@kungfu-tech/buildchain 2.11.0 → 2.11.1-alpha.2

package/dist/site/public-surface-audit.json

@@ -7,7 +7,7 @@
     "workflowCount": 36,
     "actionCount": 4,
     "sitePageCount": 45,
-    "docCommandRefCount": 227,
+    "docCommandRefCount": 229,
     "failureCount": 0
   },
   "enumerated": {
@@ -70,7 +70,7 @@
       {
         "id": "explain-artifact",
         "source": "bin/buildchain.mjs",
-        "usage": "buildchain explain artifact <subject> [--passport <file-or-url>] [--for human|agent] [--json]"
+        "usage": "buildchain explain artifact <subject> [--passport <file-or-url>] [--npm-registry <url>] [--for human|agent] [--json]"
       },
       {
         "id": "explain-release",
@@ -120,7 +120,7 @@
       {
         "id": "inspect-artifact",
         "source": "bin/buildchain.mjs",
-        "usage": "buildchain inspect artifact <subject> [--passport <file-or-url>] [--json]"
+        "usage": "buildchain inspect artifact <subject> [--passport <file-or-url>] [--npm-registry <url>] [--json]"
       },
       {
         "id": "inspect-release",
@@ -1937,6 +1937,11 @@
         "path": "docs/kfd-support.md",
         "command": "buildchain kfd migrate-layout --write"
       },
+      {
+        "id": "kfd-migrate-layout",
+        "path": "docs/kfd-support.md",
+        "command": "buildchain kfd migrate-layout --write"
+      },
       {
         "id": "kfd-schema-list",
         "path": "docs/cli.md",
@@ -2332,6 +2337,11 @@
         "path": "docs/cli.md",
         "command": "buildchain verify artifact"
       },
+      {
+        "id": "verify-artifact",
+        "path": "docs/cli.md",
+        "command": "buildchain verify artifact npm"
+      },
       {
         "id": "verify-artifact",
         "path": "docs/release-passport.md",
@@ -2438,9 +2448,9 @@
     "cliRegistryPath": "dist/site/cli-registry.json",
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
-    "cliRegistryDigest": "1f7e1f7707a089f067175030fde6712b69ceece3df1b811eb542b0b4c8c1d4a9",
+    "cliRegistryDigest": "53833f92021caa7cc5feaff5d21f38b0a77317ace11a43795be180d1dec3699f",
     "workflowRegistryDigest": "67572429a83124370b9ffd46f56923aa2b252873c9624ded39a26675fb0ee815",
-    "pageRegistryDigest": "eca33e2ed1e0dbffe8ce7f8f5ee5b4fdc34ef7b2daad7091a2be192ab70b80db"
+    "pageRegistryDigest": "14b3d852445462c23c9c48d786844353a8c3e2764092323fabe60dcab9e39aae"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-09T04:23:24.659Z",
-  "publishedAt": "2026-07-09T04:23:24.659Z",
+  "generatedAt": "2026-07-09T10:17:37.497Z",
+  "publishedAt": "2026-07-09T10:17:37.497Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "290544db8afeaa9c1af5220adabeff932764fab7",
+  "sourceRevision": "85d3b04ebed5b161f019095bdb5ff5e18d4513db",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.11.0",
+    "version": "2.11.1-alpha.2",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:a57f131080254b3f7a0950b5bdd580b256ecb29047a0e1ee16e8385d61a44b81"
+      "digest": "sha256:795464d3d84af5698b19a26821dbd16040c258b708e070daaaba6d55e6ad81f7"
     },
     {
       "id": "install",
@@ -69,7 +69,7 @@
       "path": "docs/release-passport.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:332f058d9a016cc31c709a3447a56dc43ffd0c5e6cdbcd15f9a62f61bb16eb15"
+      "digest": "sha256:f278f148e36f508f7217ad0e41501fa1cf5fe4d0a54d81dfbab867b3d35465c7"
     },
     {
       "id": "release-candidate",
@@ -77,7 +77,7 @@
       "path": "docs/release-candidate.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:391f14569c7d2a43dd9986c6a29462d674a77338dac6a4ac89c79a4c3d6c4947"
+      "digest": "sha256:841d6f3281ba6dfe80527e4f149807bdbd05d41f9e94afe1c446fcd6d29e307c"
     },
     {
       "id": "release-propagation",
@@ -173,7 +173,7 @@
       "path": "docs/cli.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:d77b7d5e4006e952235f6d68daff01bcc4cf87d81b874c57e447caabdaf0acaa"
+      "digest": "sha256:4b31f7ff5330cde8ab32b237f533c7af76463cce570d67dd14669c3a14c83c84"
     },
     {
       "id": "build-facts",
@@ -189,7 +189,7 @@
       "path": "docs/kfd-support.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:4bcf5d1ce63555072130eae90c739555b11658d1d796a3fcea770b90841c4afd"
+      "digest": "sha256:ce1bbf5c085a69649ee2e6ae76a52419eef94304e59efc0d0dcd4466c714709e"
     },
     {
       "id": "lifecycle-protocol",

package/docs/MAP.md

@@ -42,7 +42,7 @@ workflow, action, and Node API export also carries a `capabilityGroup`,
 | Capability-grouped KFD navigation | `dist/site/capability-registry.json`, `dist/site/page-registry.json`, `dist/site/manual-registry.json`, `dist/site/cli-registry.json`, `dist/site/node-api-registry.json` | this map, [`site-bundle-contract.md`](site-bundle-contract.md), [`kfd-support.md`](kfd-support.md) |
 | KFD-1 / KFD-2 / KFD-3 release-passport gates | `dist/site/kfd-claims.json`, `dist/site/buildchain-contract.json`, `dist/site/artifact-schemas.json` | [`release-passport.md`](release-passport.md) |
 | KFD-3 public surface reverse audit | `dist/site/public-surface-audit.json`, `dist/site/cli-registry.json`, `dist/site/workflow-registry.json`, `dist/site/page-registry.json` | [`cli.md`](cli.md), [`site-bundle-contract.md`](site-bundle-contract.md) |
-| KFD-1 / KFD-2 / KFD-3 first-class CLI and Node API | `.buildchain/kfd/kfd-3-surfaces.json`, `dist/site/kfd-claims.json`, `buildchain.release.json`, KFD schemas from `@kungfu-tech/kfd` | [`kfd-support.md`](kfd-support.md), [`cli.md`](cli.md#commands) |
+| KFD-1 / KFD-2 / KFD-3 first-class CLI and Node API | `.buildchain/kfd/kfd-3/surfaces.json`, `dist/site/kfd-claims.json`, `buildchain.release.json`, KFD schemas from `@kungfu-tech/kfd` | [`kfd-support.md`](kfd-support.md), [`cli.md`](cli.md#commands) |
 | Floating `@v2` drift detection and compatibility issues | `dist/site/buildchain-contract.json` | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) |
 | npm publish transactions, evidence, dist-tags, and recovery | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`publish-transaction.md`](publish-transaction.md) |
 | Git/source/version/module/product build facts | `dist/site/node-api-registry.json`, `dist/site/cli-registry.json`, `kungfu-buildchain-module-build-facts`, `kungfu-buildchain-product-build-facts` | [`build-facts.md`](build-facts.md) |

package/docs/cli.md

@@ -104,7 +104,10 @@ Supported presets:
   plans by default, and only configured `[infra.commands]` hooks can execute.
 - `--type publication-artifact` for papers, reports, specifications, and other
   publication repositories that produce PDFs, metadata, source bundles, and
-  site-consumable manifests without becoming web-surface repositories.
+  site-consumable manifests without becoming web-surface repositories. The
+  scaffold uses Buildchain's pinned
+  `ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0` toolchain for
+  LaTeX PDF builds.
 - `--type distribution-index` for Homebrew taps and other index repositories
   whose files are projections of upstream release passport evidence.
 - `--type anchored-package` for packages whose version is anchored to an
@@ -219,7 +222,7 @@ buildchain kfd schema show kfd-3 --json
 buildchain kfd 3 detect --kind node-api --kind cli --json
 buildchain kfd 3 register node-api --product Buildchain
 buildchain kfd 3 audit --json
-buildchain kfd 3 witness --kind prebuild --output .buildchain/kfd-3/collaboration-interface.prebuild.json
+buildchain kfd 3 witness --kind prebuild --output .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json
 buildchain kfd 3 query buildchain --json
 buildchain kfd 4 schema --json
 ```
@@ -400,7 +403,7 @@ The command writes `.buildchain/publication/publication-artifact.json`,
 and, when `[publication.archive]` is configured,
 `.buildchain/publication/publication-registry.json` by default. See
 [`publication-artifacts.md`](publication-artifacts.md) for the repository
-contract and reusable workflow.
+contract, pinned LaTeX builder, and reusable workflow.
 
 Generate, check, or update the managed README badge block:
 
@@ -477,9 +480,9 @@ buildchain collect github-release \
   --platform-manifest-json .buildchain/artifacts/darwin-arm64/manifest.json \
   --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \
   --dist-tag-evidence-json .buildchain/release-evidence/v2.3.2/dist-tag-evidence.json \
-  --kfd-1-witness-json .buildchain/kfd-1/contract-world.witness.json \
-  --kfd-2-claim-json .buildchain/kfd-2/release-claims.json \
-  --kfd-3-prebuild-witness-json .buildchain/kfd-3/collaboration-interface.prebuild.json \
+  --kfd-1-witness-json .buildchain/kfd/kfd-1/contract-world.witness.json \
+  --kfd-2-claim-json .buildchain/kfd/kfd-2/release-claims.json \
+  --kfd-3-prebuild-witness-json .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json \
   --kfd-3-artifact-verify-cmd "kungfu agent verify --json" \
   --release-extra-json '{"channel":"release","targetRef":"release/v2/v2.3"}' \
   --output-dir .buildchain/release-passport
@@ -576,6 +579,10 @@ Verify a published artifact by subject:
 buildchain verify artifact ./Kungfu-2.8.0-windows-x64.exe
 buildchain inspect artifact ./Kungfu-2.8.0-windows-x64.exe --json
 buildchain explain artifact ./Kungfu-2.8.0-windows-x64.exe --for agent --json
+buildchain verify artifact npm:@kungfu-tech/libnode@22.22.3-kf.3-alpha.18 \
+  --repository kungfu-systems/libnode \
+  --tag v22.22.3-kf.3-alpha.18 \
+  --json
 ```
 
 `verify artifact` computes or obtains the subject digest, discovers the
@@ -583,6 +590,10 @@ detached release passport, verifies the passport, then requires that the
 subject digest appears in the passport's release assets, package set, publish
 evidence, or artifact evidence. Outcomes are explicit: `pass`, `fail`, or
 `unverifiable`. A filename is only a hint; trust comes from digest equality.
+For `npm:<name>@<version>` subjects, Buildchain resolves `dist.integrity` from
+the npm registry before matching passport evidence. Use `--npm-registry <url>`
+to verify packages from a custom registry; otherwise Buildchain uses
+`npm_config_registry` or `https://registry.npmjs.org/`.
 
 Discovery is fail-closed and ordered:
 

package/docs/kfd-support.md

@@ -10,14 +10,16 @@ facts, not as README prose. The machine-readable sources are:
 - `buildchain.release.json` for release-specific KFD-1, KFD-2, and KFD-3
   passport results;
 - `.buildchain/buildchain.toml` for repository-owned Buildchain configuration;
-- `.buildchain/kfd/kfd-3-surfaces.json` for product-owned KFD-3 surface
+- `.buildchain/kfd/kfd-3/surfaces.json` for product-owned KFD-3 surface
   registration;
 - `.buildchain/contract-lock.json` for accepted floating runtime contracts.
 
 Buildchain still reads the legacy root files `buildchain.toml`,
-`buildchain.contract-lock.json`, and `buildchain.kfd3.json` so existing
-consumers do not break, but new repositories should keep repo-owned Buildchain
-files under `.buildchain/`.
+`buildchain.contract-lock.json`, `buildchain.kfd3.json`, and the historical
+`.buildchain/kfd/kfd-3-surfaces.json` registry so existing consumers can run
+`buildchain kfd migrate-layout --write`. New repositories should keep
+repo-owned Buildchain files under `.buildchain/`, with all KFD evidence under
+`.buildchain/kfd/`.
 
 ## Unified Namespace
 
@@ -145,9 +147,9 @@ package = "@kungfu-tech/kfd"
 repository = "kungfu-systems/kfd"
 evidence = [
   "package:kfd.release.json",
-  "package:.buildchain/kfd-1/contract-world.witness.json",
-  "package:.buildchain/kfd-2/public-release-trust.claim.json",
-  "package:.buildchain/kfd-3/collaboration-interface.json",
+  "package:.buildchain/kfd/kfd-1/contract-world.witness.json",
+  "package:.buildchain/kfd/kfd-2/release-claims.json",
+  "package:.buildchain/kfd/kfd-3/collaboration-interface.json",
   "package:standards.json",
 ]
 ```
@@ -251,7 +253,7 @@ KFD-3 surface registration uses three states.
 | State | Meaning |
 | --- | --- |
 | `detected` | Buildchain found a candidate public surface from package metadata, wheel metadata, CLI bins, binary artifacts, docs, or site bundle facts. |
-| `declared` | The product owner accepted that candidate into `.buildchain/kfd/kfd-3-surfaces.json`. |
+| `declared` | The product owner accepted that candidate into `.buildchain/kfd/kfd-3/surfaces.json`. |
 | `enforced` | The product has promoted a declared surface to a hard release boundary. Missing enforced surfaces fail release verification. |
 
 Detection does not silently become product intent. `register` is the boundary
@@ -298,7 +300,7 @@ Generate a witness for release passport collection:
 ```bash
 buildchain kfd 3 witness \
   --kind prebuild \
-  --output .buildchain/kfd-3/collaboration-interface.prebuild.json
+  --output .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json
 ```
 
 Query capability facts for agents or downstream sites:

package/docs/publication-artifacts.md

@@ -46,8 +46,8 @@ registry_path = ".buildchain/publication/publication-registry.json"
 
 [publication.toolchain]
 type = "latex-docker"
-image = "ghcr.io/kungfu-systems/latex"
-digest = "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+image = "ghcr.io/kungfu-systems/build-images/latex-pdf-builder"
+digest = "sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8"
 command = "latexmk -pdf -outdir=_build paper/main.tex"
 
 [lifecycle.build]
@@ -82,11 +82,14 @@ if PDF, source bundle, route, metadata, or toolchain evidence changes for an
 existing version, Buildchain fails before the registry is rewritten.
 
 `publication.toolchain` makes the source-to-PDF transformation part of the
-machine-readable contract. `latex-docker` is the preferred LaTeX profile: the
-workflow pulls the declared image by digest and runs the declared command in
-that pinned container. `custom-command` remains available for compatibility,
-but the passport records it as lower trust because Buildchain can record the
-command boundary without proving the compiler or LaTeX distribution digest.
+machine-readable contract. `latex-docker` is the preferred LaTeX profile. The
+Buildchain paper scaffold and reusable workflow default to
+`ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0`, pinned by the
+digest above. The workflow pulls the declared image by digest and runs the
+declared command in that pinned container. `custom-command` remains available
+for compatibility, but the passport records it as lower trust because
+Buildchain can record the command boundary without proving the compiler or
+LaTeX distribution digest.
 
 ## Reusable Workflow
 
@@ -109,8 +112,8 @@ The workflow:
   any paper build runs;
 - resolves the declared publication toolchain from `[publication.toolchain]` or
   workflow inputs;
-- for `latex-docker`, pulls the pinned image digest and runs the declared
-  command in the container;
+- for `latex-docker`, pulls the pinned build-images LaTeX builder digest and
+  runs the declared command in the container;
 - for `custom-command`, runs the declared command and records the lower-trust
   boundary in the passport;
 - runs the verify command;

package/docs/release-candidate.md

@@ -105,9 +105,9 @@ jobs:
     with:
       channel: alpha
       artifact-name: libnode
-      release-passport-kfd-1-witness-jsons: .buildchain/kfd-1/standard-contract.witness.json
-      release-passport-kfd-2-claim-jsons: .buildchain/kfd-2/release-claims.json
-      release-passport-kfd-3-prebuild-witness-jsons: .buildchain/kfd-3/collaboration-interface.prebuild.json
+      release-passport-kfd-1-witness-jsons: .buildchain/kfd/kfd-1/standard-contract.witness.json
+      release-passport-kfd-2-claim-jsons: .buildchain/kfd/kfd-2/release-claims.json
+      release-passport-kfd-3-prebuild-witness-jsons: .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json
       release-passport-kfd-3-artifact-verify-command: kungfu agent verify --json
 ```
 

package/docs/release-passport.md

@@ -109,8 +109,8 @@ buildchain collect github-release \
   --platform-manifest-json .buildchain/artifacts/darwin-arm64/manifest.json \
   --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \
   --dist-tag-evidence-json .buildchain/release-evidence/v2.2.0/dist-tag-evidence.json \
-  --kfd-1-witness-json .buildchain/kfd-1/contract-world.witness.json \
-  --kfd-2-claim-json .buildchain/kfd-2/release-claims.json \
+  --kfd-1-witness-json .buildchain/kfd/kfd-1/contract-world.witness.json \
+  --kfd-2-claim-json .buildchain/kfd/kfd-2/release-claims.json \
   --output-dir .buildchain/release-passport
 ```
 
@@ -279,7 +279,7 @@ pre-build witness:
 
 ```bash
 kungfu sdk collaboration-interface witness --json \
-  > .buildchain/kfd-3/collaboration-interface.prebuild.json
+  > .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json
 ```
 
 That witness must contain, or point to, the product-owned KFD-3 collaboration
@@ -292,7 +292,7 @@ either as a JSON file or a command:
 
 ```bash
 buildchain collect github-release \
-  --kfd-3-prebuild-witness-json .buildchain/kfd-3/collaboration-interface.prebuild.json \
+  --kfd-3-prebuild-witness-json .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json \
   --kfd-3-artifact-verify-cmd "kungfu agent verify --json"
 ```
 
@@ -376,6 +376,11 @@ appears in the passport's artifacts, package set, publish evidence, or artifact
 evidence. The command returns `pass`, `fail`, or `unverifiable`; missing
 passports and digest mismatches fail closed.
 
+For npm subjects, Buildchain treats the registry as the package digest source:
+`npm:<name>@<version>` resolves `dist.integrity` and matches it against
+`packageSet.main.digest`, `packageSet.platforms[].digest`, and publish evidence.
+Use `--npm-registry <url>` when the package comes from a non-default registry.
+
 Discovery is ordered and auditable:
 
 1. explicit `--passport`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.11.0",
+  "version": "2.11.1-alpha.2",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/packages/core/README.md

@@ -69,7 +69,9 @@ writeBuildFacts({ fact, output: ".buildchain/facts/native-core.json" });
 Publication repositories can produce site-consumable paper/report facts without
 becoming web-surface repositories. When `[publication.archive]` is configured,
 the same API also maintains the append-only publication registry used by site
-repositories for latest and historical version pages:
+repositories for latest and historical version pages. The preferred
+`latex-docker` toolchain records the pinned build-images LaTeX builder digest in
+the publication artifact passport:
 
 ```js
 import { writePublicationArtifact } from "@kungfu-tech/buildchain/publication-artifact";

package/packages/core/artifact-passport.js

@@ -8,6 +8,7 @@ import { readJsonFromLocation, sha256File, verifyReleasePassport } from "./relea
 export const ARTIFACT_VERIFICATION_CONTRACT = "kungfu-buildchain-artifact-verification";
 export const ARTIFACT_PASSPORT_POINTER_CONTRACT = "kungfu-buildchain-artifact-passport-pointer";
 export const ARTIFACT_PASSPORT_LOCATOR_CONTRACT = "kungfu-buildchain-artifact-passport-locator";
+export const DEFAULT_NPM_REGISTRY_BASE_URL = "https://registry.npmjs.org/";
 
 function optionalString(value) {
   return value === undefined || value === null ? "" : String(value);
@@ -118,6 +119,45 @@ function parseNpmSubject(subject) {
   return { name: spec.slice(0, atIndex), version: spec.slice(atIndex + 1) };
 }
 
+function normalizeNpmRegistryBaseUrl(value = "") {
+  const registry = optionalString(value || process.env.npm_config_registry || DEFAULT_NPM_REGISTRY_BASE_URL).trim();
+  return registry.endsWith("/") ? registry : `${registry}/`;
+}
+
+function npmRegistryPackageMetadataUrl(name, registryBaseUrl = "") {
+  return new URL(encodeURIComponent(name), normalizeNpmRegistryBaseUrl(registryBaseUrl)).toString();
+}
+
+async function resolveNpmSubjectDigest({ name, version, registryBaseUrl = "" } = {}) {
+  if (!name || !version) {
+    return { status: "skipped", reason: "missing-name-or-version" };
+  }
+  const metadataUrl = npmRegistryPackageMetadataUrl(name, registryBaseUrl);
+  const metadata = await readJsonFromLocation(metadataUrl);
+  const versionMetadata = metadata?.versions?.[version];
+  if (!versionMetadata) {
+    return {
+      status: "missing",
+      reason: "version-not-found",
+      registry: normalizeNpmRegistryBaseUrl(registryBaseUrl),
+      metadataUrl,
+    };
+  }
+  const integrity = optionalString(versionMetadata.dist?.integrity);
+  const shasum = optionalString(versionMetadata.dist?.shasum);
+  const digest = integrity || (shasum ? `sha1:${shasum}` : "");
+  return {
+    status: digest ? "resolved" : "missing",
+    reason: digest ? "" : "dist-integrity-missing",
+    registry: normalizeNpmRegistryBaseUrl(registryBaseUrl),
+    metadataUrl,
+    digest,
+    integrity,
+    shasum,
+    tarball: optionalString(versionMetadata.dist?.tarball),
+  };
+}
+
 function parseGitHubReleaseSubject(subject) {
   const value = subject.replace(/^github-release:/, "");
   const match = value.match(/^([^/]+\/[^@/]+)@([^/]+)\/(.+)$/);
@@ -328,6 +368,7 @@ export async function resolveArtifactSubject(subject, {
   cwd = process.cwd(),
   subjectDigest = "",
   subjectKind = "",
+  npmRegistryBaseUrl = "",
 } = {}) {
   const input = optionalString(subject).trim();
   if (!input) {
@@ -335,12 +376,38 @@ export async function resolveArtifactSubject(subject, {
   }
   if (/^npm:/i.test(input)) {
     const parsed = parseNpmSubject(input);
+    let npmDigest = {};
+    if (!subjectDigest) {
+      try {
+        npmDigest = await resolveNpmSubjectDigest({
+          name: parsed.name,
+          version: parsed.version,
+          registryBaseUrl: npmRegistryBaseUrl,
+        });
+      } catch (error) {
+        npmDigest = {
+          status: "error",
+          registry: normalizeNpmRegistryBaseUrl(npmRegistryBaseUrl),
+          error: error.message,
+        };
+      }
+    }
+    const digest = subjectDigest || npmDigest.digest || "";
     return {
       input,
       kind: subjectKind || "npm-package",
       name: parsed.name,
       version: parsed.version,
-      digest: subjectDigest,
+      digest,
+      integrity: npmDigest.integrity || (digest.startsWith("sha512-") ? digest : ""),
+      shasum: npmDigest.shasum || "",
+      registry: npmDigest.registry || normalizeNpmRegistryBaseUrl(npmRegistryBaseUrl),
+      npm: {
+        digestResolution: npmDigest.status || (subjectDigest ? "provided" : "skipped"),
+        metadataUrl: npmDigest.metadataUrl || "",
+        tarball: npmDigest.tarball || "",
+        error: npmDigest.error || "",
+      },
       localPath: "",
     };
   }
@@ -640,8 +707,9 @@ export async function verifyArtifactPassport({
   githubReleaseBaseUrl = "",
   subjectDigest = "",
   subjectKind = "",
+  npmRegistryBaseUrl = "",
 } = {}) {
-  const resolvedSubject = await resolveArtifactSubject(subject, { cwd, subjectDigest, subjectKind });
+  const resolvedSubject = await resolveArtifactSubject(subject, { cwd, subjectDigest, subjectKind, npmRegistryBaseUrl });
   const issues = [];
   if (resolvedSubject.missing) {
     issues.push(issue("error", "subject.missing", "artifact subject does not exist locally", { subject: resolvedSubject.input }));

package/packages/core/buildchain-layout.js

@@ -6,8 +6,27 @@ export const BUILDCHAIN_CONFIG_PATH = ".buildchain/buildchain.toml";
 export const LEGACY_BUILDCHAIN_CONFIG_PATH = "buildchain.toml";
 export const BUILDCHAIN_CONTRACT_LOCK_PATH = ".buildchain/contract-lock.json";
 export const LEGACY_BUILDCHAIN_CONTRACT_LOCK_PATH = "buildchain.contract-lock.json";
-export const BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATH = ".buildchain/kfd/kfd-3-surfaces.json";
+export const BUILDCHAIN_KFD_ROOT = ".buildchain/kfd";
+export const BUILDCHAIN_KFD1_DIR = ".buildchain/kfd/kfd-1";
+export const BUILDCHAIN_KFD2_DIR = ".buildchain/kfd/kfd-2";
+export const BUILDCHAIN_KFD3_DIR = ".buildchain/kfd/kfd-3";
+export const BUILDCHAIN_KFD4_DIR = ".buildchain/kfd/kfd-4";
+export const BUILDCHAIN_KFD1_CONTRACT_WORLD_WITNESS_PATH = ".buildchain/kfd/kfd-1/contract-world.witness.json";
+export const BUILDCHAIN_KFD1_RELEASE_GATE_PATH = ".buildchain/kfd/kfd-1/release-gate.json";
+export const BUILDCHAIN_KFD1_VERIFY_RESULT_PATH = ".buildchain/kfd/kfd-1/verify-result.json";
+export const BUILDCHAIN_KFD2_RELEASE_CLAIMS_PATH = ".buildchain/kfd/kfd-2/release-claims.json";
+export const BUILDCHAIN_KFD2_CLAIM_ARGS_PATH = ".buildchain/kfd/kfd-2/buildchain-claim-args.txt";
+export const BUILDCHAIN_KFD2_CLAIMS_DIR = ".buildchain/kfd/kfd-2/claims";
+export const BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATH = ".buildchain/kfd/kfd-3/surfaces.json";
+export const BUILDCHAIN_KFD3_COLLABORATION_INTERFACE_PATH = ".buildchain/kfd/kfd-3/collaboration-interface.json";
+export const BUILDCHAIN_KFD3_PREBUILD_WITNESS_PATH = ".buildchain/kfd/kfd-3/collaboration-interface.prebuild.json";
+export const BUILDCHAIN_KFD3_ARTIFACT_WITNESS_PATH = ".buildchain/kfd/kfd-3/collaboration-interface.artifact.json";
+export const BUILDCHAIN_KFD3_CAPABILITY_QUERY_PATH = ".buildchain/kfd/kfd-3/capability-query.json";
 export const LEGACY_BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATH = "buildchain.kfd3.json";
+export const LEGACY_BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATHS = Object.freeze([
+  ".buildchain/kfd/kfd-3-surfaces.json",
+  LEGACY_BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATH,
+]);
 export const BUILDCHAIN_RELEASE_PASSPORT_PATH = ".buildchain/release-passport/buildchain.release.json";
 export const LEGACY_BUILDCHAIN_RELEASE_PASSPORT_PATH = "buildchain.release.json";
 
@@ -59,7 +78,7 @@ export function resolveBuildchainContractLockPath(cwd = process.cwd()) {
 export function resolveKfd3SurfaceRegistryPath(cwd = process.cwd()) {
   return firstExistingRepoPath(cwd, [
     BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATH,
-    LEGACY_BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATH,
+    ...LEGACY_BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATHS,
   ]);
 }
 
@@ -87,7 +106,79 @@ export function discoverBuildchainRepoFiles(cwd = process.cwd()) {
     {
       kind: "kfd-3-surface-registry",
       canonical: BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATH,
-      legacy: LEGACY_BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATH,
+      legacy: LEGACY_BUILDCHAIN_KFD3_SURFACE_REGISTRY_PATHS,
+      tracked: true,
+    },
+    {
+      kind: "kfd-1-contract-world-witness",
+      canonical: BUILDCHAIN_KFD1_CONTRACT_WORLD_WITNESS_PATH,
+      legacy: [
+        ".buildchain/kfd-1/contract-world.witness.json",
+        ".buildchain/kfd/buildchain-kfd-1-witness.json",
+      ],
+      tracked: true,
+    },
+    {
+      kind: "kfd-1-release-gate",
+      canonical: BUILDCHAIN_KFD1_RELEASE_GATE_PATH,
+      legacy: [".buildchain/kfd-1/release-gate.json"],
+      tracked: true,
+    },
+    {
+      kind: "kfd-1-verify-result",
+      canonical: BUILDCHAIN_KFD1_VERIFY_RESULT_PATH,
+      legacy: [".buildchain/kfd-1/verify-result.json"],
+      tracked: false,
+    },
+    {
+      kind: "kfd-2-release-claims",
+      canonical: BUILDCHAIN_KFD2_RELEASE_CLAIMS_PATH,
+      legacy: [
+        ".buildchain/kfd-2/release-claims.json",
+        ".buildchain/kfd-2/public-release-trust.claim.json",
+      ],
+      tracked: true,
+    },
+    {
+      kind: "kfd-2-claim-args",
+      canonical: BUILDCHAIN_KFD2_CLAIM_ARGS_PATH,
+      legacy: [".buildchain/kfd-2/buildchain-claim-args.txt"],
+      tracked: true,
+    },
+    {
+      kind: "kfd-2-claims",
+      canonical: BUILDCHAIN_KFD2_CLAIMS_DIR,
+      legacy: [".buildchain/kfd/kfd-2-claims", ".buildchain/kfd-2/claims"],
+      tracked: false,
+    },
+    {
+      kind: "kfd-3-collaboration-interface",
+      canonical: BUILDCHAIN_KFD3_COLLABORATION_INTERFACE_PATH,
+      legacy: [".buildchain/kfd-3/collaboration-interface.json"],
+      tracked: true,
+    },
+    {
+      kind: "kfd-3-prebuild-witness",
+      canonical: BUILDCHAIN_KFD3_PREBUILD_WITNESS_PATH,
+      legacy: [
+        ".buildchain/kfd-3/collaboration-interface.prebuild.json",
+        ".buildchain/kfd/buildchain-kfd-3-prebuild-witness.json",
+      ],
+      tracked: true,
+    },
+    {
+      kind: "kfd-3-artifact-witness",
+      canonical: BUILDCHAIN_KFD3_ARTIFACT_WITNESS_PATH,
+      legacy: [
+        ".buildchain/kfd-3/collaboration-interface.artifact.json",
+        ".buildchain/kfd/buildchain-kfd-3-artifact-witness.json",
+      ],
+      tracked: true,
+    },
+    {
+      kind: "kfd-3-capability-query",
+      canonical: BUILDCHAIN_KFD3_CAPABILITY_QUERY_PATH,
+      legacy: [".buildchain/kfd-3/capability-query.json"],
       tracked: true,
     },
     {
@@ -99,12 +190,16 @@ export function discoverBuildchainRepoFiles(cwd = process.cwd()) {
   ];
   return files.map((entry) => {
     const canonicalExists = fs.existsSync(repoPath(cwd, entry.canonical));
-    const legacyExists = fs.existsSync(repoPath(cwd, entry.legacy));
+    const legacyPaths = Array.isArray(entry.legacy) ? entry.legacy : [entry.legacy].filter(Boolean);
+    const existingLegacyPaths = legacyPaths.filter((legacy) => fs.existsSync(repoPath(cwd, legacy)));
+    const legacyExists = existingLegacyPaths.length > 0;
     return {
       ...entry,
+      legacy: legacyPaths,
       canonicalExists,
       legacyExists,
-      activePath: canonicalExists ? entry.canonical : legacyExists ? entry.legacy : entry.canonical,
+      existingLegacyPaths,
+      activePath: canonicalExists ? entry.canonical : legacyExists ? existingLegacyPaths[0] : entry.canonical,
       migrationNeeded: !canonicalExists && legacyExists,
     };
   });
@@ -114,12 +209,12 @@ export function planBuildchainLayoutMigration({ cwd = process.cwd() } = {}) {
   const entries = discoverBuildchainRepoFiles(cwd);
   const moves = entries
     .filter((entry) => entry.migrationNeeded)
-    .map((entry) => ({
+    .flatMap((entry) => entry.existingLegacyPaths.map((legacy) => ({
       kind: entry.kind,
-      from: entry.legacy,
+      from: legacy,
       to: entry.canonical,
       tracked: entry.tracked,
-    }));
+    })));
   return {
     schemaVersion: 1,
     contract: "kungfu-buildchain-repository-layout-migration",