PDKKit

Canonical process-design-kit discovery, identity, asset integrity and validation contracts.

Status

The PDKKit-owned contract layer is complete and executable for deterministic manifest-driven discovery, validation, retained corpus evaluation and parser-backed standard-view inspection, detailed numeric semantics, immutable CircuiteFoundation artifact provenance and oracle comparison. The PDK stage slice is also executable by a flow host with immutable artifacts, scope-bound tool evidence, human approval and resume coverage. The larger platform goal requires separate provider evidence and foundry approval; PDKKit represents unsupported vendor-specific constructs as explicit blocked results. External standard-view and rule-deck backends can now return the same typed domain results as the local inspectors. External providers fail closed on result schema, run, asset, format, source-reference and PDK-digest mismatches; they do not execute or qualify an external process by themselves. The workspace now provides typed process-qualification and release-eligibility contracts in ToolQualification, ReleaseEngine and Xcircuite, but this package does not manufacture the independent evidence required to pass those gates.

Products

Product	Responsibility
PDKCore	PDK identity and immutable manifest reference
PDKDiscovery	Deterministic local PDK discovery without qualification claims
PDKValidation	Manifest, input, asset, digest, parser-backed cross-view and retained corpus validation
PDKStandardViews	Canonical standard-view and rule-deck inspection, local/external result providers, manifest binding and immutable oracle comparison
PDKKit	Umbrella API and public contract version (2)
PDKKitCLICore / pdkkit-cli	Deterministic JSON inspection, discovery, validation, corpus, standard-view, rule-deck and oracle CLI

Contract

Every executing product uses protocol-first dependency injection, typed request records, immutable artifact identities from CircuiteFoundation, and explicit completed, blocked, failed and cancelled states. Each domain result carries its own payload, diagnostics, immutable artifact references and ExecutionProvenance. The domain protocols refine CircuiteFoundation.Engine directly, and their result types conform to ArtifactProducing, DiagnosticReporting and EvidenceProviding without a facade or parallel execution contract.

The artifact boundary has two representations with different authority:

flowchart LR
  Intent["PDKAssetReference\nartifact intent"] --> Locator["CircuiteFoundation\nArtifactLocator"]
  Locator --> Referencer["LocalArtifactReferencer\nstreaming SHA-256"]
  Referencer --> Identity["ArtifactReference\nimmutable verified identity"]
  Identity --> Result["PDK domain result\nwith provenance"]

Loading

ArtifactReference is the integrity source of truth inside PDKCore. Requests carry locators while completed domain results retain the same canonical identity and provenance, so every PDKKit-owned artifact consumer observes one integrity boundary.

External providers conform to PDKExternalStandardViewResultProviding or PDKExternalRuleDeckResultProviding and return JSON-encoded domain results. ExternalPDKStandardViewInspector and ExternalPDKRuleDeckInspector validate the corresponding typed result before it is consumed by manifest binding or downstream evidence. Source references must match the requested digest-bearing input artifacts. Provider process execution, tool discovery and process-scoped qualification remain owned by Xcircuite/SignoffToolSupport and ToolQualification.

Xcircuite integration

Xcircuite resolves a PDKReference before constructing downstream stage requests. Every physical or electrical stage records the same PDK digest.

The library does not depend on a flow runtime. A flow host owns stage execution, artifact persistence, qualification gates, repair loops and human approval.

The flow host can expose discovery, validation, retained-corpus, standard-view and oracle stages through its own executor implementation. Each stage persists the complete domain result as an immutable run artifact and maps completed, blocked, failed and cancelled states to flow gates. Qualification evidence is accepted only when the ToolQualification scope matches the requested implementation, binary, algorithm, process and deck; integration tests also cover human approval followed by resume.

Relative artifact references are resolved against an explicit project root and cannot escape it. Callers pass the project root into PDKKit, so a persisted run remains reproducible even when its inputs are stored as project-relative references.

Manifest contract

PDKManifest is the canonical process-scoped source of truth. It contains:

• process identity and version;
• immutable asset references and expected SHA-256/byte count when required by a production profile;
• manufacturing layer and purpose semantics;
• device terminals and extraction recognition;
• PVT, RC, electromigration and reliability corner mappings;
• cross-view mappings for layer map, LEF/GDSII/OASIS, SPICE and Liberty views.

The current manifest schema and canonical field names are required. Unsupported, incomplete, or malformed schemas produce typed errors.

Raw asset presence is not treated as semantic proof. Missing mappings, missing assets, digest mismatches and unavailable semantics produce structured blocked diagnostics instead of a false pass.

PDKValidationRequest keeps discovery and production validation explicit. requiredCornerIDs requires every locked process corner to exist, while requireAssetIdentity requires each production-required asset to declare both SHA-256 and byte count before its materialized bytes are compared. These checks establish reproducible process input identity; they do not issue a ToolQualification trust decision.

pdkkit-cli validate now executes every declared LEF, GDSII/OASIS, SPICE and Liberty mapping through the same manifest-bound inspectors used by inspect-view. The payload retains one standardViewResults entry per mapped view, including parser provenance, canonical facts, binding findings and the completed/blocked/failed status. This makes manifest validation and standalone inspection consume the same cross-view evidence.

Declared rule-deck assets are validated through ruleDeckResults: the deck must be readable UTF-8 text, contain statements, have a ruleDeck layer mapping and identify every mapped layer by name, alias or manufacturing number. Use --no-standard-views or --no-rule-decks only when an agent explicitly needs to isolate a contract layer during diagnosis.

PDKRuleDeckInspectionRequest and PDKRuleDeckInspectionPayload are the standalone protocol-first form of that check. LocalPDKRuleDeckInspector and pdkkit-cli inspect-rule-deck exposes the same immutable reference, mapped-layer evidence and structured findings without requiring a full manifest validation run. The inspector intentionally reports grammar limitations instead of claiming complete vendor-specific DRC rule semantics.

The public package and CLI contract version is 2. The rule-deck stage is identified as pdk.inspect-rule-deck; request schema evolution is independent from the manifest schema.

PDKCorpusSuite and LocalPDKCorpusValidator retain expected valid, blocked and failed cases. Corpus success is evidence of the declared local validator and failed cases, including manifest-bound standard-view and rule-deck checks. Rule-deck corpus results retain expected/observed outcomes and finding codes so the artifact can be reviewed or resumed by an agent. Corpus success is evidence of the declared local validator contract only; it does not establish trust.

PDKOracleExpectation binds canonical standard-view facts, numeric SPICE model parameters, Liberty timing tables and unit declarations to a manifest digest. LocalPDKOracleComparator returns structured field mismatches. PDKKit emits evidence only; ToolQualification owns every trust and qualification decision.

CLI

swift run pdkkit-cli inspect --manifest <path> --pretty
swift run pdkkit-cli discover --root <path> [--root <path> ...] --process-id <id>
swift run pdkkit-cli validate --manifest <path> --required-role layerMap --required-corner <id> --require-asset-identity --pretty
swift run pdkkit-cli corpus --suite <path> --root <path> --pretty
swift run pdkkit-cli inspect-view --manifest <path> --asset-id <id> --format <lef|gdsii|oasis|spice|liberty> --pretty
swift run pdkkit-cli inspect-rule-deck --manifest <path> --asset-id <id> --pretty
swift run pdkkit-cli oracle --manifest <path> --oracle <path> --pretty

The CLI writes deterministic sorted-key JSON to stdout. Domain blockers use exit code 2; argument, read and decode errors use exit code 1 and a single structured diagnostic object on stderr.

The executable product is named pdkkit-cli so its Xcode build directory does not collide case-insensitively with the public PDKKit library module on default macOS filesystems.

Build

swift build

Test

perl -e 'alarm shift; exec @ARGV' 30 xcodebuild -quiet test -scheme PDKKit-Package -destination 'platform=macOS'

The repository's current verification result is 59 tests in 6 Swift Testing suites. The detailed standard-view suite passes 12 tests with xcodebuild test-without-building after an Xcode build-for-testing build. The Xcircuite PDK integration slice passes 6 tests in 1 suite with xcodebuild; the release-stage composition slice passes 5 tests in 1 suite. The Xcode command may print environment-specific IDE warnings while still returning success.

Evidence boundary

Manifest + standard views
          |
          v
Local inspection -> retained corpus -> immutable oracle comparison
                                             |
                                             v
                                      oracleCorrelated

oracleCorrelated is the highest state this package emits. A process-scoped processQualified result requires an independent ToolProcessQualificationEvidence record with matching PDK scope, followed by release approval outside this package. This boundary is intentional: a local parser or retained fixture cannot establish manufacturing-process trust by itself.

SPICE model parameters with unsupported expressions, missing .end markers, Liberty timing tables with non-numeric values or inconsistent dimensions, and timing tables without a declared time_unit are blocked. This is a supported numeric-semantic subset, not a claim of complete vendor-specific language coverage.

Validation requests use schema version 3 and require explicit cross-view controls. Schema version 2 remains decodable with non-production defaults for retained runs. Manifest-bound standard-view requests include project-root resolution whenever it is part of their reproducibility contract.

See MILESTONES.md, CAPABILITY_REPORT.md, DESIGN.md, INTERFACES.md and IMPLEMENTATION_PLAN.md for the implementation boundary and qualification limitations.