@kungfu-tech/buildchain 4.0.2-alpha.42 → 4.0.2-alpha.43

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

@@ -10929,8 +10929,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "fbc23073bbae240489a2f826b2c26daadc58e704050c5f8df366509f5c5a1c3e",
-    "workflowRegistryDigest": "0143633ac365cc3bbd4b8c3aead36b3fa336375acc56d10bff0292866f46dda4",
-    "pageRegistryDigest": "77db2ba380ab0206b07b6db59a702a995077b5570732c9851caec15c65b717be"
+    "workflowRegistryDigest": "b3235d2cfb6220c9f349cfaffa8a1f1309444798266a70e2fd020effc3f11ff2",
+    "pageRegistryDigest": "48da222775d48a130d729ea7951446259b5cd4db7d4c0bd3234a02f77d5719d9"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-09-06T11:33:49.000Z",
-  "publishedAt": "2026-09-06T11:33:49.000Z",
+  "generatedAt": "2026-09-06T12:32:13.000Z",
+  "publishedAt": "2026-09-06T12:32:13.000Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "9c053766731017a319479923df0ae6cc6de1a54f",
+  "sourceRevision": "2c34aaf899b3921588f53023b350565b63914dce",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.2-alpha.42",
+    "version": "4.0.2-alpha.43",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-09-06T11:33:49.000Z",
-  "publishedAt": "2026-09-06T11:33:49.000Z",
+  "generatedAt": "2026-09-06T12:32:13.000Z",
+  "publishedAt": "2026-09-06T12:32:13.000Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "9c053766731017a319479923df0ae6cc6de1a54f",
+  "sourceRevision": "2c34aaf899b3921588f53023b350565b63914dce",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.2-alpha.42",
+    "version": "4.0.2-alpha.43",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -237,7 +237,7 @@
       "path": "docs/cli.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:b90266a341f7c7f904e5a5a8df7dd669ba30e6934633889ef221288ce698f784"
+      "digest": "sha256:cd4e6144d45f4f01b733a728695a9f22acdd7124bd4aba18c6b0146d27f57c44"
     },
     {
       "id": "cli-reference",
@@ -253,7 +253,7 @@
       "path": "docs/node-api-reference.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:3b4b475408bb16915854aa2d7969cc9db4faecdfdc0f2f6af5174e7d91188cf2"
+      "digest": "sha256:df79569e33023c30fe010a88acecb45caf769970cda1e83c5fc2657986fa9e33"
     },
     {
       "id": "build-facts",

package/dist/site/workflow-registry.json

@@ -2746,7 +2746,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.42",
+      "introducedVersion": "4.0.2-alpha.43",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -3943,7 +3943,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.42",
+      "introducedVersion": "4.0.2-alpha.43",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -5970,7 +5970,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.42",
+      "introducedVersion": "4.0.2-alpha.43",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -6001,7 +6001,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.42",
+      "introducedVersion": "4.0.2-alpha.43",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -6032,7 +6032,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.42",
+      "introducedVersion": "4.0.2-alpha.43",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",

package/docs/cli.md

@@ -8,11 +8,11 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-07-31
+last_reviewed: 2026-09-06
 ai_provenance:
-  model_family: GPT-5
+  model_family: GPT-6
   product: Codex
-  generated_at: 2026-07-31
+  generated_at: 2026-09-06
   invisible_context: not asserted
 ---
 
@@ -182,6 +182,10 @@ The safety and authority boundary is explicit:
   the pull-request source and target from GitHub context and fails closed on a
   non-work source branch or a target other than the configured development
   line.
+- Installed npm runtimes resolve their source from registry `gitHead`, or from
+  the official exact version tag when that field is absent. Missing, malformed,
+  duplicate, or unexpected tag results fail closed; floating tags are never
+  used as the installed package's source identity.
 - `work start` derives the protected development branch from the configured
   publication semver line and creates a safe local work branch only when the
   worktree is clean, the sole `origin` is the canonical `kungfu-systems`

package/docs/node-api-reference.md

@@ -150,8 +150,8 @@ Target: `./packages/core/index.js`. Public symbols: 636.
 | `collectModuleBuildFacts` | function: function collectModuleBuildFacts({ cwd = process.cwd(), moduleId = "", moduleRoot = "", scope = "", versionSource = undefined, versionSourceId = "", outputs = [], lifecycle = "", platform = currentPlatform(), dependencies = [], now = nowIso(), } = {}) | { cwd = process.cwd(), moduleId = "", moduleRoot = "", scope = "", versionSource = undefined, versionSourceId = "", outputs = [], lifecycle = "", platform = currentPlatform(), dependencies = [], now = nowIso(), } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectModuleBuildFacts } from "@kungfu-tech/buildchain";` | `packages/core/build-facts.js:310` |
 | `collectNativeDiagnostics` | function: function collectNativeDiagnostics({ cwd = process.cwd(), profile = undefined, runCommand = defaultDiagnosticCommandRunner, } = {}) | { cwd = process.cwd(), profile = undefined, runCommand = defaultDiagnosticCommandRunner, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectNativeDiagnostics } from "@kungfu-tech/buildchain";` | `packages/core/diagnostics.js:295` |
 | `collectPaperFleetAudit` | function: function collectPaperFleetAudit({ root = process.cwd(), repositories = [], buildchainRoot = process.cwd(), buildchainVersion = "", buildchainSha = "", governance = {}, } = {}) | { root = process.cwd(), repositories = [], buildchainRoot = process.cwd(), buildchainVersion = "", buildchainSha = "", governance = {}, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperFleetAudit } from "@kungfu-tech/buildchain";` | `packages/core/paper-fleet.js:158` |
-| `collectPaperPreflight` | function: function collectPaperPreflight({ cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {}) | { cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperPreflight } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2041` |
-| `collectPaperStatus` | function: function collectPaperStatus({ cwd = process.cwd() } = {}) | { cwd = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperStatus } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:1140` |
+| `collectPaperPreflight` | function: function collectPaperPreflight({ cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {}) | { cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperPreflight } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2025` |
+| `collectPaperStatus` | function: function collectPaperStatus({ cwd = process.cwd() } = {}) | { cwd = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperStatus } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:1124` |
 | `collectProcessTreeSnapshot` | function: function collectProcessTreeSnapshot({ rootPid = process.pid, cwd = process.cwd(), platform = process.platform, runCommand = defaultDiagnosticCommandRunner, } = {}) | { rootPid = process.pid, cwd = process.cwd(), platform = process.platform, runCommand = defaultDiagnosticCommandRunner, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectProcessTreeSnapshot } from "@kungfu-tech/buildchain";` | `packages/core/diagnostics.js:1029` |
 | `collectPublicationArtifact` | function: function collectPublicationArtifact({ cwd = process.cwd(), sourceSha = "", sourceBundle = true, sourceBundlePath = "", generatedAt = "", manifestPath = "", passportPath = "", } = {}) | { cwd = process.cwd(), sourceSha = "", sourceBundle = true, sourceBundlePath = "", generatedAt = "", manifestPath = "", passportPath = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | local-filesystem-write | `import { collectPublicationArtifact } from "@kungfu-tech/buildchain";` | `packages/core/publication-artifact.js:271` |
 | `collectPublicationPackageFacts` | function: function collectPublicationPackageFacts({ cwd = process.cwd(), packageName = "", outputDir = ".buildchain/publication/npm-package", } = {}) | { cwd = process.cwd(), packageName = "", outputDir = ".buildchain/publication/npm-package", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { collectPublicationPackageFacts } from "@kungfu-tech/buildchain";` | `packages/core/publication-package.js:74` |
@@ -219,9 +219,9 @@ Target: `./packages/core/index.js`. Public symbols: 636.
 | `createManualUpstreamPickupCapture` | function: function createManualUpstreamPickupCapture({ plan, expectedDownstreamBaseSha, }) | { plan, expectedDownstreamBaseSha, } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createManualUpstreamPickupCapture } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-pickup.js:361` |
 | `createManualUpstreamPickupPlan` | function: function createManualUpstreamPickupPlan({ config: configInput, sourceId, channel, currentVersion, upstreamRelease, }) | { config: configInput, sourceId, channel, currentVersion, upstreamRelease, } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createManualUpstreamPickupPlan } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-pickup.js:303` |
 | `createPackageReleasePropagationCapture` | function: function createPackageReleasePropagationCapture({ config: configInput, upstreamRelease: upstreamReleaseInput, expectedBaseShas = {}, } = {}) | { config: configInput, upstreamRelease: upstreamReleaseInput, expectedBaseShas = {}, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPackageReleasePropagationCapture } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-capture.js:101` |
-| `createPaperAlphaPlan` | function: function createPaperAlphaPlan({ cwd = process.cwd(), sourceRef = "", targetRef = "", } = {}) | { cwd = process.cwd(), sourceRef = "", targetRef = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperAlphaPlan } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2283` |
-| `createPaperBuildPlan` | function: function createPaperBuildPlan({ cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {}) | { cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperBuildPlan } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2220` |
-| `createPaperResumePlan` | function: function createPaperResumePlan({ cwd = process.cwd(), buildchainRef = "", } = {}) | { cwd = process.cwd(), buildchainRef = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | local-filesystem-write | `import { createPaperResumePlan } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2341` |
+| `createPaperAlphaPlan` | function: function createPaperAlphaPlan({ cwd = process.cwd(), sourceRef = "", targetRef = "", } = {}) | { cwd = process.cwd(), sourceRef = "", targetRef = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperAlphaPlan } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2267` |
+| `createPaperBuildPlan` | function: function createPaperBuildPlan({ cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {}) | { cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperBuildPlan } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2204` |
+| `createPaperResumePlan` | function: function createPaperResumePlan({ cwd = process.cwd(), buildchainRef = "", } = {}) | { cwd = process.cwd(), buildchainRef = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | local-filesystem-write | `import { createPaperResumePlan } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2325` |
 | `createPaperWorkStartPlan` | function: function createPaperWorkStartPlan({ cwd = process.cwd(), topic = "", branch = "", buildchainSha = "", } = {}) | { cwd = process.cwd(), topic = "", branch = "", buildchainSha = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createPaperWorkStartPlan } from "@kungfu-tech/buildchain";` | `packages/core/paper-work.js:41` |
 | `createPaperWorkSubmitPlan` | function: function createPaperWorkSubmitPlan({ cwd = process.cwd(), pullRequests = [], pullRequestObservation = { ok: true }, buildchainSha = "", } = {}) | { cwd = process.cwd(), pullRequests = [], pullRequestObservation = { ok: true }, buildchainSha = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createPaperWorkSubmitPlan } from "@kungfu-tech/buildchain";` | `packages/core/paper-work.js:207` |
 | `createPortableDevCachePlan` | function: function createPortableDevCachePlan(manifest) | manifest | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createPortableDevCachePlan } from "@kungfu-tech/buildchain";` | `packages/core/portable-dev-cache.js:172` |
@@ -293,7 +293,7 @@ Target: `./packages/core/index.js`. Public symbols: 636.
 | `evaluateGithubGovernanceSnapshot` | function: function evaluateGithubGovernanceSnapshot({ descriptor = createBuildchainGithubGovernanceAuthority(), repository, targetRef, organizationPlan, codeowners, effectivePolicy, memberships, apiEvidence = {}, observedAt, expiresAt, verifier = {}, } = {}) | { descriptor = createBuildchainGithubGovernanceAuthority(), repository, targetRef, organizationPlan, codeowners, effectivePolicy, memberships, apiEvidence = {}, observedAt, expiresAt, verifier = {}, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { evaluateGithubGovernanceSnapshot } from "@kungfu-tech/buildchain";` | `packages/core/github-governance-authority.js:697` |
 | `evaluateKfdProductGate` | function: async function evaluateKfdProductGate({ cwd = process.cwd(), input, expectedSourceSha = "", checkedAt = new Date().toISOString(), } = {}) | { cwd = process.cwd(), input, expectedSourceSha = "", checkedAt = new Date().toISOString(), } = {} | Promise<unknown> | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { evaluateKfdProductGate } from "@kungfu-tech/buildchain";` | `packages/core/kfd-product-gates.js:419` |
 | `evaluatePublicationControlPlaneSnapshot` | function: function evaluatePublicationControlPlaneSnapshot({ repository, workflowPath, publisherWorkflowPath = workflowPath, environment, branch, packageName, publisherMode = "npm-trusted-publisher", requiredStatusCheck = "check", snapshot, observedAt, expiresAt, } = {}) | { repository, workflowPath, publisherWorkflowPath = workflowPath, environment, branch, packageName, publisherMode = "npm-trusted-publisher", requiredStatusCheck = "check", snapshot, observedAt, expiresAt, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { evaluatePublicationControlPlaneSnapshot } from "@kungfu-tech/buildchain";` | `packages/core/publication-control-plane-audit.js:245` |
-| `executePaperNpmBootstrap` | function: function executePaperNpmBootstrap(options = {}) | options = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperNpmBootstrap } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2468` |
+| `executePaperNpmBootstrap` | function: function executePaperNpmBootstrap(options = {}) | options = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperNpmBootstrap } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2452` |
 | `executePaperWorkStart` | function: function executePaperWorkStart(plan) | plan | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperWorkStart } from "@kungfu-tech/buildchain";` | `packages/core/paper-work.js:169` |
 | `executePaperWorkSubmitPush` | function: function executePaperWorkSubmitPush(plan) | plan | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperWorkSubmitPush } from "@kungfu-tech/buildchain";` | `packages/core/paper-work.js:357` |
 | `executeReleasePropagationPush` | function: function executeReleasePropagationPush({ work, expectedWorkRoot, cwd = process.cwd(), remote = "origin", } = {}) | { work, expectedWorkRoot, cwd = process.cwd(), remote = "origin", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | may-write-or-invoke-external-actions | `import { executeReleasePropagationPush } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-push.js:231` |
@@ -839,8 +839,8 @@ Target: `./packages/core/index.js`. Public symbols: 636.
 | `collectModuleBuildFacts` | function: function collectModuleBuildFacts({ cwd = process.cwd(), moduleId = "", moduleRoot = "", scope = "", versionSource = undefined, versionSourceId = "", outputs = [], lifecycle = "", platform = currentPlatform(), dependencies = [], now = nowIso(), } = {}) | { cwd = process.cwd(), moduleId = "", moduleRoot = "", scope = "", versionSource = undefined, versionSourceId = "", outputs = [], lifecycle = "", platform = currentPlatform(), dependencies = [], now = nowIso(), } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectModuleBuildFacts } from "@kungfu-tech/buildchain/core";` | `packages/core/build-facts.js:310` |
 | `collectNativeDiagnostics` | function: function collectNativeDiagnostics({ cwd = process.cwd(), profile = undefined, runCommand = defaultDiagnosticCommandRunner, } = {}) | { cwd = process.cwd(), profile = undefined, runCommand = defaultDiagnosticCommandRunner, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectNativeDiagnostics } from "@kungfu-tech/buildchain/core";` | `packages/core/diagnostics.js:295` |
 | `collectPaperFleetAudit` | function: function collectPaperFleetAudit({ root = process.cwd(), repositories = [], buildchainRoot = process.cwd(), buildchainVersion = "", buildchainSha = "", governance = {}, } = {}) | { root = process.cwd(), repositories = [], buildchainRoot = process.cwd(), buildchainVersion = "", buildchainSha = "", governance = {}, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperFleetAudit } from "@kungfu-tech/buildchain/core";` | `packages/core/paper-fleet.js:158` |
-| `collectPaperPreflight` | function: function collectPaperPreflight({ cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {}) | { cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperPreflight } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2041` |
-| `collectPaperStatus` | function: function collectPaperStatus({ cwd = process.cwd() } = {}) | { cwd = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperStatus } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:1140` |
+| `collectPaperPreflight` | function: function collectPaperPreflight({ cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {}) | { cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperPreflight } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2025` |
+| `collectPaperStatus` | function: function collectPaperStatus({ cwd = process.cwd() } = {}) | { cwd = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperStatus } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:1124` |
 | `collectProcessTreeSnapshot` | function: function collectProcessTreeSnapshot({ rootPid = process.pid, cwd = process.cwd(), platform = process.platform, runCommand = defaultDiagnosticCommandRunner, } = {}) | { rootPid = process.pid, cwd = process.cwd(), platform = process.platform, runCommand = defaultDiagnosticCommandRunner, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectProcessTreeSnapshot } from "@kungfu-tech/buildchain/core";` | `packages/core/diagnostics.js:1029` |
 | `collectPublicationArtifact` | function: function collectPublicationArtifact({ cwd = process.cwd(), sourceSha = "", sourceBundle = true, sourceBundlePath = "", generatedAt = "", manifestPath = "", passportPath = "", } = {}) | { cwd = process.cwd(), sourceSha = "", sourceBundle = true, sourceBundlePath = "", generatedAt = "", manifestPath = "", passportPath = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | local-filesystem-write | `import { collectPublicationArtifact } from "@kungfu-tech/buildchain/core";` | `packages/core/publication-artifact.js:271` |
 | `collectPublicationPackageFacts` | function: function collectPublicationPackageFacts({ cwd = process.cwd(), packageName = "", outputDir = ".buildchain/publication/npm-package", } = {}) | { cwd = process.cwd(), packageName = "", outputDir = ".buildchain/publication/npm-package", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { collectPublicationPackageFacts } from "@kungfu-tech/buildchain/core";` | `packages/core/publication-package.js:74` |
@@ -908,9 +908,9 @@ Target: `./packages/core/index.js`. Public symbols: 636.
 | `createManualUpstreamPickupCapture` | function: function createManualUpstreamPickupCapture({ plan, expectedDownstreamBaseSha, }) | { plan, expectedDownstreamBaseSha, } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createManualUpstreamPickupCapture } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-pickup.js:361` |
 | `createManualUpstreamPickupPlan` | function: function createManualUpstreamPickupPlan({ config: configInput, sourceId, channel, currentVersion, upstreamRelease, }) | { config: configInput, sourceId, channel, currentVersion, upstreamRelease, } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createManualUpstreamPickupPlan } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-pickup.js:303` |
 | `createPackageReleasePropagationCapture` | function: function createPackageReleasePropagationCapture({ config: configInput, upstreamRelease: upstreamReleaseInput, expectedBaseShas = {}, } = {}) | { config: configInput, upstreamRelease: upstreamReleaseInput, expectedBaseShas = {}, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPackageReleasePropagationCapture } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-capture.js:101` |
-| `createPaperAlphaPlan` | function: function createPaperAlphaPlan({ cwd = process.cwd(), sourceRef = "", targetRef = "", } = {}) | { cwd = process.cwd(), sourceRef = "", targetRef = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperAlphaPlan } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2283` |
-| `createPaperBuildPlan` | function: function createPaperBuildPlan({ cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {}) | { cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperBuildPlan } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2220` |
-| `createPaperResumePlan` | function: function createPaperResumePlan({ cwd = process.cwd(), buildchainRef = "", } = {}) | { cwd = process.cwd(), buildchainRef = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | local-filesystem-write | `import { createPaperResumePlan } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2341` |
+| `createPaperAlphaPlan` | function: function createPaperAlphaPlan({ cwd = process.cwd(), sourceRef = "", targetRef = "", } = {}) | { cwd = process.cwd(), sourceRef = "", targetRef = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperAlphaPlan } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2267` |
+| `createPaperBuildPlan` | function: function createPaperBuildPlan({ cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {}) | { cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperBuildPlan } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2204` |
+| `createPaperResumePlan` | function: function createPaperResumePlan({ cwd = process.cwd(), buildchainRef = "", } = {}) | { cwd = process.cwd(), buildchainRef = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | local-filesystem-write | `import { createPaperResumePlan } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2325` |
 | `createPaperWorkStartPlan` | function: function createPaperWorkStartPlan({ cwd = process.cwd(), topic = "", branch = "", buildchainSha = "", } = {}) | { cwd = process.cwd(), topic = "", branch = "", buildchainSha = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createPaperWorkStartPlan } from "@kungfu-tech/buildchain/core";` | `packages/core/paper-work.js:41` |
 | `createPaperWorkSubmitPlan` | function: function createPaperWorkSubmitPlan({ cwd = process.cwd(), pullRequests = [], pullRequestObservation = { ok: true }, buildchainSha = "", } = {}) | { cwd = process.cwd(), pullRequests = [], pullRequestObservation = { ok: true }, buildchainSha = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createPaperWorkSubmitPlan } from "@kungfu-tech/buildchain/core";` | `packages/core/paper-work.js:207` |
 | `createPortableDevCachePlan` | function: function createPortableDevCachePlan(manifest) | manifest | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createPortableDevCachePlan } from "@kungfu-tech/buildchain/core";` | `packages/core/portable-dev-cache.js:172` |
@@ -982,7 +982,7 @@ Target: `./packages/core/index.js`. Public symbols: 636.
 | `evaluateGithubGovernanceSnapshot` | function: function evaluateGithubGovernanceSnapshot({ descriptor = createBuildchainGithubGovernanceAuthority(), repository, targetRef, organizationPlan, codeowners, effectivePolicy, memberships, apiEvidence = {}, observedAt, expiresAt, verifier = {}, } = {}) | { descriptor = createBuildchainGithubGovernanceAuthority(), repository, targetRef, organizationPlan, codeowners, effectivePolicy, memberships, apiEvidence = {}, observedAt, expiresAt, verifier = {}, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { evaluateGithubGovernanceSnapshot } from "@kungfu-tech/buildchain/core";` | `packages/core/github-governance-authority.js:697` |
 | `evaluateKfdProductGate` | function: async function evaluateKfdProductGate({ cwd = process.cwd(), input, expectedSourceSha = "", checkedAt = new Date().toISOString(), } = {}) | { cwd = process.cwd(), input, expectedSourceSha = "", checkedAt = new Date().toISOString(), } = {} | Promise<unknown> | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { evaluateKfdProductGate } from "@kungfu-tech/buildchain/core";` | `packages/core/kfd-product-gates.js:419` |
 | `evaluatePublicationControlPlaneSnapshot` | function: function evaluatePublicationControlPlaneSnapshot({ repository, workflowPath, publisherWorkflowPath = workflowPath, environment, branch, packageName, publisherMode = "npm-trusted-publisher", requiredStatusCheck = "check", snapshot, observedAt, expiresAt, } = {}) | { repository, workflowPath, publisherWorkflowPath = workflowPath, environment, branch, packageName, publisherMode = "npm-trusted-publisher", requiredStatusCheck = "check", snapshot, observedAt, expiresAt, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { evaluatePublicationControlPlaneSnapshot } from "@kungfu-tech/buildchain/core";` | `packages/core/publication-control-plane-audit.js:245` |
-| `executePaperNpmBootstrap` | function: function executePaperNpmBootstrap(options = {}) | options = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperNpmBootstrap } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2468` |
+| `executePaperNpmBootstrap` | function: function executePaperNpmBootstrap(options = {}) | options = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperNpmBootstrap } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2452` |
 | `executePaperWorkStart` | function: function executePaperWorkStart(plan) | plan | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperWorkStart } from "@kungfu-tech/buildchain/core";` | `packages/core/paper-work.js:169` |
 | `executePaperWorkSubmitPush` | function: function executePaperWorkSubmitPush(plan) | plan | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperWorkSubmitPush } from "@kungfu-tech/buildchain/core";` | `packages/core/paper-work.js:357` |
 | `executeReleasePropagationPush` | function: function executeReleasePropagationPush({ work, expectedWorkRoot, cwd = process.cwd(), remote = "origin", } = {}) | { work, expectedWorkRoot, cwd = process.cwd(), remote = "origin", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | may-write-or-invoke-external-actions | `import { executeReleasePropagationPush } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-push.js:231` |
@@ -2327,17 +2327,17 @@ Target: `./packages/core/paper.js`. Public symbols: 48.
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | `collectPaperAgentEntry` | function: function collectPaperAgentEntry({ cwd = process.cwd(), buildchainSha = "", mode = "contract", env = process.env, runtimeAdmission, } = {}) | { cwd = process.cwd(), buildchainSha = "", mode = "contract", env = process.env, runtimeAdmission, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperAgentEntry } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:255` |
 | `collectPaperFleetAudit` | function: function collectPaperFleetAudit({ root = process.cwd(), repositories = [], buildchainRoot = process.cwd(), buildchainVersion = "", buildchainSha = "", governance = {}, } = {}) | { root = process.cwd(), repositories = [], buildchainRoot = process.cwd(), buildchainVersion = "", buildchainSha = "", governance = {}, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperFleetAudit } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-fleet.js:158` |
-| `collectPaperPreflight` | function: function collectPaperPreflight({ cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {}) | { cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperPreflight } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2041` |
-| `collectPaperStatus` | function: function collectPaperStatus({ cwd = process.cwd() } = {}) | { cwd = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperStatus } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:1140` |
+| `collectPaperPreflight` | function: function collectPaperPreflight({ cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {}) | { cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperPreflight } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2025` |
+| `collectPaperStatus` | function: function collectPaperStatus({ cwd = process.cwd() } = {}) | { cwd = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperStatus } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:1124` |
 | `createPaperAgentEntry` | function: function createPaperAgentEntry({ buildchainVersion, buildchainSha, developmentRef, }) | { buildchainVersion, buildchainSha, developmentRef, } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperAgentEntry } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:95` |
-| `createPaperAlphaPlan` | function: function createPaperAlphaPlan({ cwd = process.cwd(), sourceRef = "", targetRef = "", } = {}) | { cwd = process.cwd(), sourceRef = "", targetRef = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperAlphaPlan } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2283` |
-| `createPaperBuildPlan` | function: function createPaperBuildPlan({ cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {}) | { cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperBuildPlan } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2220` |
-| `createPaperProvisioningAuthority` | function: function createPaperProvisioningAuthority({ repository, packageName, buildchainVersion, buildchainSha, contractLock, buildWorkflow, verifyWorkflow, releaseWorkflow, agentEntry, agentInstructions, environment = "", }) | { repository, packageName, buildchainVersion, buildchainSha, contractLock, buildWorkflow, verifyWorkflow, releaseWorkflow, agentEntry, agentInstructions, environment = "", } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperProvisioningAuthority } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:527` |
-| `createPaperResumePlan` | function: function createPaperResumePlan({ cwd = process.cwd(), buildchainRef = "", } = {}) | { cwd = process.cwd(), buildchainRef = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | local-filesystem-write | `import { createPaperResumePlan } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2341` |
+| `createPaperAlphaPlan` | function: function createPaperAlphaPlan({ cwd = process.cwd(), sourceRef = "", targetRef = "", } = {}) | { cwd = process.cwd(), sourceRef = "", targetRef = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperAlphaPlan } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2267` |
+| `createPaperBuildPlan` | function: function createPaperBuildPlan({ cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {}) | { cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperBuildPlan } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2204` |
+| `createPaperProvisioningAuthority` | function: function createPaperProvisioningAuthority({ repository, packageName, buildchainVersion, buildchainSha, contractLock, buildWorkflow, verifyWorkflow, releaseWorkflow, agentEntry, agentInstructions, environment = "", }) | { repository, packageName, buildchainVersion, buildchainSha, contractLock, buildWorkflow, verifyWorkflow, releaseWorkflow, agentEntry, agentInstructions, environment = "", } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperProvisioningAuthority } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:511` |
+| `createPaperResumePlan` | function: function createPaperResumePlan({ cwd = process.cwd(), buildchainRef = "", } = {}) | { cwd = process.cwd(), buildchainRef = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | local-filesystem-write | `import { createPaperResumePlan } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2325` |
 | `createPaperWorkStartPlan` | function: function createPaperWorkStartPlan({ cwd = process.cwd(), topic = "", branch = "", buildchainSha = "", } = {}) | { cwd = process.cwd(), topic = "", branch = "", buildchainSha = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createPaperWorkStartPlan } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-work.js:41` |
 | `createPaperWorkSubmitPlan` | function: function createPaperWorkSubmitPlan({ cwd = process.cwd(), pullRequests = [], pullRequestObservation = { ok: true }, buildchainSha = "", } = {}) | { cwd = process.cwd(), pullRequests = [], pullRequestObservation = { ok: true }, buildchainSha = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createPaperWorkSubmitPlan } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-work.js:207` |
 | `discoverPaperFleet` | function: function discoverPaperFleet(root = process.cwd()) | root = process.cwd() | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { discoverPaperFleet } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-fleet.js:23` |
-| `executePaperNpmBootstrap` | function: function executePaperNpmBootstrap(options = {}) | options = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperNpmBootstrap } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2468` |
+| `executePaperNpmBootstrap` | function: function executePaperNpmBootstrap(options = {}) | options = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperNpmBootstrap } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2452` |
 | `executePaperWorkStart` | function: function executePaperWorkStart(plan) | plan | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperWorkStart } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-work.js:169` |
 | `executePaperWorkSubmitPush` | function: function executePaperWorkSubmitPush(plan) | plan | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperWorkSubmitPush } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-work.js:357` |
 | `mergePaperAgentEntryInstructions` | function: function mergePaperAgentEntryInstructions(current = "", { developmentRef }) | current = "", { developmentRef } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { mergePaperAgentEntryInstructions } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:63` |

package/package.json

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

package/packages/core/paper-runtime-channels.js

@@ -8,6 +8,7 @@ import {
   sha256Json,
 } from "./buildchain-contract.js";
 import {
+  commandResult,
   gitValue,
   readJson,
   sha256Text,
@@ -16,6 +17,70 @@ import {
 
 export const PAPER_ALPHA_LOCK = ".buildchain/alpha-contract-lock.json";
 
+export function resolvePaperNpmRuntimeSha(cwd, identity) {
+  if (!identity.version) return "";
+  const observed = commandResult(
+    "npm",
+    [
+      "view",
+      `${identity.name}@${identity.version}`,
+      "gitHead",
+      "--json",
+      "--registry=https://registry.npmjs.org",
+    ],
+    { cwd },
+  );
+  if (!observed.ok) return "";
+  let parsed;
+  try {
+    parsed = JSON.parse(observed.stdout || "null");
+  } catch {
+    return "";
+  }
+  const gitHead =
+    typeof parsed === "string" ? parsed : String(parsed?.gitHead || "");
+  return /^[0-9a-f]{40}$/i.test(gitHead)
+    ? gitHead
+    : resolvePaperPublishedTagSha(cwd, identity);
+}
+
+function resolvePaperPublishedTagSha(cwd, identity) {
+  if (
+    identity.name !== "@kungfu-tech/buildchain" ||
+    !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(
+      identity.version,
+    )
+  )
+    return "";
+  const ref = `refs/tags/v${identity.version}`;
+  const observed = commandResult(
+    "git",
+    [
+      "ls-remote",
+      "--exit-code",
+      "https://github.com/kungfu-systems/buildchain.git",
+      ref,
+      `${ref}^{}`,
+    ],
+    { cwd },
+  );
+  if (!observed.ok || !observed.stdout) return "";
+  const refs = new Map();
+  for (const line of observed.stdout.split(/\r?\n/)) {
+    const [sha, name, extra] = line.split(/\s+/);
+    if (
+      !/^[0-9a-f]{40}$/.test(sha) ||
+      ![ref, `${ref}^{}`].includes(name) ||
+      extra ||
+      refs.has(name)
+    )
+      return "";
+    refs.set(name, sha);
+  }
+  if (!refs.has(ref)) return "";
+  return refs.get(`${ref}^{}`) || refs.get(ref);
+}
+
 function fileDigestMatches(cwd, relative, digest) {
   if (!relative || !/^sha256:[0-9a-f]{64}$/.test(digest || "")) return false;
   const absolute = path.resolve(cwd, relative);

package/packages/core/paper.js

@@ -1,5 +1,5 @@
 import crypto from "node:crypto";
-import { bindPaperV4Authority, paperV4Channels, selectPaperRuntime, paperRuntimeLockPath, paperProvisioningWorkflowErrors } from "./paper-runtime-channels.js";
+import { bindPaperV4Authority, paperV4Channels, selectPaperRuntime, paperRuntimeLockPath, paperProvisioningWorkflowErrors, resolvePaperNpmRuntimeSha } from "./paper-runtime-channels.js";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -257,23 +257,7 @@ export function resolvePaperRuntimeGitSha(
   const value = resolvePaperBuildchainSha(buildchainRoot);
   if (GIT_SHA_PATTERN.test(value)) return value;
   const identity = buildchainPackageIdentity(buildchainRoot, buildchainVersion);
-  if (!identity.version) return "";
-  const observed = commandResult(
-    "npm",
-    [
-      "view",
-      `${identity.name}@${identity.version}`,
-      "gitHead",
-      "--json",
-      `--registry=${NPM_REGISTRY}`,
-    ],
-    { cwd: buildchainRoot },
-  );
-  if (!observed.ok) return "";
-  const parsed = safeParseJson(observed.stdout);
-  const gitHead =
-    typeof parsed === "string" ? parsed : String(parsed?.gitHead || "");
-  return GIT_SHA_PATTERN.test(gitHead) ? gitHead : "";
+  return resolvePaperNpmRuntimeSha(buildchainRoot, identity);
 }
 
 function runtimeAcceptedAt(buildchainRoot, sha, buildchainVersion = "") {