@kungfu-tech/buildchain 3.0.5-alpha.8 → 3.0.6-alpha.0

package/docs/dev-qualification-patrol.md

@@ -0,0 +1,108 @@
+---
+status: preview
+period: ongoing
+theme: dev-qualification-patrol
+doc_type: architecture-and-usage
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-08-03
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-03
+  visible_context: Existing Buildchain Shifu Gate receipts, Kungfu Dev Patrol, Alpha preflight, candidate patrol, and GitHub failed-job rerun semantics.
+  invisible_context_boundary: No credentials, private logs, or private configuration were used.
+---
+
+# Dev Qualification Patrol
+
+Buildchain provides a reusable controller for repositories whose development
+branch advances faster than a heavy cross-platform qualification workflow can
+settle. The controller keeps no external queue. On every wakeup it derives the
+only pending item from the current source-branch head and maintains these
+states:
+
+- `qualified`: the current source SHA already has a successful Dev run;
+- `running`: one Dev run is active, with a different current SHA retained as
+  the implicit latest pending item;
+- `waiting-preflight`: the current SHA has not passed its lightweight exact-SHA
+  preflight;
+- `waiting-priority`: a declared Alpha or release workflow is queued or active;
+- `dispatch-ready`: the latest SHA is preflight-qualified and no Dev or
+  priority run is active;
+- `retry-ready`: the latest exact-SHA Dev run failed only at a classified
+  external boundary and remains inside the attempt limit; or
+- `blocked`: the failure was deterministic, unknown, or exhausted its bounded
+  retry policy.
+
+This is an event-driven, coalescing controller rather than a FIFO build queue.
+If ten commits arrive during one slow Dev run, the next reconciliation observes
+only the newest branch head. Intermediate unqualified SHAs are superseded
+without consuming the shared native runners.
+
+## Exact-source and priority contract
+
+Call `.github/workflows/dev-qualification-patrol.yml` from a thin consumer
+workflow after the lightweight preflight, Dev Patrol, and declared priority
+workflows complete. Add an offset schedule as recovery for delayed or missed
+GitHub events. Repeated wakeups are idempotent.
+
+The controller requires a successful preflight whose `head_sha` equals the
+current source head. It dispatches the heavy workflow on the source branch and
+adds a controller-owned `source-sha` input. The consumer must reject the run
+before qualification if that input differs from the workflow event SHA. This
+closes the race where the branch advances between observation and workflow
+startup. The heavy reusable Gate workflow then receives the exact SHA as its
+`source-ref`, so every platform receipt remains source-bound.
+
+`priority-workflows-json` is a JSON array of workflow paths. Any queued,
+waiting, pending, requested, or in-progress run in those workflows prevents a
+new Dev dispatch or automatic retry. This lets Alpha and release work keep
+priority on shared self-hosted runners. A successful current Dev result remains
+qualified even when priority work is active; priority only governs new heavy
+work.
+
+## Bounded local retry
+
+The controller uses GitHub's failed-jobs rerun endpoint, not a fresh workflow
+dispatch, for classified transient failures. Successful matrix jobs and their
+exact-source receipts remain in the same workflow-run transaction. Failed jobs
+and dependent aggregation run again. The Shifu Gate profile uploads platform,
+diagnostic, aggregate, and controller artifacts with overwrite enabled so a
+later attempt can replace only the same-run artifact names.
+
+Automatic retry is deliberately narrow:
+
+- whole-run `cancelled`, `timed_out`, or `startup_failure` conclusions qualify;
+- checkout, setup, toolchain, download, upload, environment exposure, and
+  runner-workspace reset steps qualify;
+- Gate execution, Gate enforcement, aggregation, and controller-receipt
+  failures never qualify; and
+- an unknown failing step fails closed.
+
+`max-attempts` counts the original attempt. The default `2` therefore permits
+at most one automatic failed-jobs rerun. This policy reduces retry friction for
+network, runner, and provider failures without laundering a product or Gate
+failure into an infrastructure retry.
+
+## Permission and mutation boundary
+
+The reusable workflow always performs `observe` with Actions and contents read
+permissions. The separate `mutate` job runs only when the observation proposes
+`dispatch` or `rerun-failed-jobs`, `mutation-authorized` is true, and `dry-run`
+is false. Before writing, it re-resolves the branch and all workflow state and
+requires the action and source SHA to match the read-only observation. A race
+fails closed and the next event recomputes from current truth.
+
+Start a consumer in dry-run mode. Its observation and mutation decisions are
+retained as exact-source artifacts with a canonical decision root. Enabling
+mutation requires a repository token that can write Actions; no contents,
+pull-request, tag, release, package, or publication permission is used.
+
+The controller does not merge a PR, publish an Alpha, create a tag, create a
+release, or settle a Release Passport. Once Dev and Alpha preflight evidence
+both succeed for one SHA, the separate
+[Dev to Alpha Candidate Patrol](dev-alpha-candidate-patrol.md) may select it.

package/docs/node-api-reference.md

@@ -24,7 +24,7 @@ Signatures and source locations are mechanical. JavaScript return types remain c
 
 ## `@kungfu-tech/buildchain`
 
-Target: `./packages/core/index.js`. Public symbols: 547.
+Target: `./packages/core/index.js`. Public symbols: 558.
 
 | Symbol | Kind and signature | Parameters | Return | Errors | Side effects | Example | Source |
 | --- | --- | --- | --- | --- | --- | --- | --- |
@@ -113,7 +113,7 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `BUILDCHAIN_VERSION_PIN_PATH` | constant: const BUILDCHAIN_VERSION_PIN_PATH | none | value | Import does not declare a throw contract. | none-on-import | `import { BUILDCHAIN_VERSION_PIN_PATH } from "@kungfu-tech/buildchain";` | `packages/core/buildchain-layout.js:5` |
 | `BUILDCHAIN_WORKFLOW_FRICTION_ISSUE_CONTRACT` | constant: const BUILDCHAIN_WORKFLOW_FRICTION_ISSUE_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { BUILDCHAIN_WORKFLOW_FRICTION_ISSUE_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/issue-reporting.js:5` |
 | `buildchainKfdClaims` | constant: const buildchainKfdClaims | none | value | Import does not declare a throw contract. | none-on-import | `import { buildchainKfdClaims } from "@kungfu-tech/buildchain";` | `packages/core/kfd.js:896` |
-| `buildchainPublicationAuthorityDescriptors` | function: function buildchainPublicationAuthorityDescriptors() | none | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { buildchainPublicationAuthorityDescriptors } from "@kungfu-tech/buildchain";` | `packages/core/buildchain-publication-authority.js:53` |
+| `buildchainPublicationAuthorityDescriptors` | function: function buildchainPublicationAuthorityDescriptors() | none | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { buildchainPublicationAuthorityDescriptors } from "@kungfu-tech/buildchain";` | `packages/core/buildchain-publication-authority.js:54` |
 | `buildConsumerIssueReport` | function: function buildConsumerIssueReport(options = {}) | options = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { buildConsumerIssueReport } from "@kungfu-tech/buildchain";` | `packages/core/issue-reporting.js:104` |
 | `buildFactsDigest` | function: function buildFactsDigest(value) | value | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | local-filesystem-write, subprocess | `import { buildFactsDigest } from "@kungfu-tech/buildchain";` | `packages/core/build-facts.js:45` |
 | `buildWorkflowFrictionIssueReport` | function: function buildWorkflowFrictionIssueReport(options = {}) | options = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { buildWorkflowFrictionIssueReport } from "@kungfu-tech/buildchain";` | `packages/core/issue-reporting.js:199` |
@@ -126,6 +126,7 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `checkReadmeBadgeBlock` | function: function checkReadmeBadgeBlock({ readmeText, facts } = {}) | { readmeText, facts } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { checkReadmeBadgeBlock } from "@kungfu-tech/buildchain";` | `packages/core/readme-badges.js:848` |
 | `claimReleasePropagationWork` | function: function claimReleasePropagationWork({ work, expectedWorkRoot, authority, familyState, } = {}) | { work, expectedWorkRoot, authority, familyState, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { claimReleasePropagationWork } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-work-transitions.js:17` |
 | `classifyProcessCommand` | function: function classifyProcessCommand(command = "") | command = "" | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { classifyProcessCommand } from "@kungfu-tech/buildchain";` | `packages/core/diagnostics.js:1085` |
+| `classifyReleasePropagationCondition` | function: function classifyReleasePropagationCondition(condition) | condition | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { classifyReleasePropagationCondition } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-agent-entry.js:171` |
 | `codeownersForPath` | function: function codeownersForPath(source, candidatePath) | source, candidatePath | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { codeownersForPath } from "@kungfu-tech/buildchain";` | `packages/core/github-governance-authority.js:417` |
 | `collectBadgeBundleFacts` | function: async function collectBadgeBundleFacts({ cwd = process.cwd(), claims = undefined } = {}) | { cwd = process.cwd(), claims = undefined } = {} | Promise<unknown> | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectBadgeBundleFacts } from "@kungfu-tech/buildchain";` | `packages/core/readme-badges.js:790` |
 | `collectBuildchainDiagnostics` | function: function collectBuildchainDiagnostics({ cwd = process.cwd(), artifactPaths = [] } = {}) | { cwd = process.cwd(), artifactPaths = [] } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectBuildchainDiagnostics } from "@kungfu-tech/buildchain";` | `packages/core/diagnostics.js:248` |
@@ -175,7 +176,7 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `createBuildchainKfdSurfaceRegistry` | function: function createBuildchainKfdSurfaceRegistry({ root = process.cwd() } = {}) | { root = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createBuildchainKfdSurfaceRegistry } from "@kungfu-tech/buildchain";` | `packages/core/buildchain-kfd-claims.js:411` |
 | `createBuildchainLayoutDiscovery` | function: function createBuildchainLayoutDiscovery({ cwd = process.cwd(), buildchainVersion = "", } = {}) | { cwd = process.cwd(), buildchainVersion = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createBuildchainLayoutDiscovery } from "@kungfu-tech/buildchain";` | `packages/core/buildchain-layout.js:99` |
 | `createBuildchainLogger` | function: function createBuildchainLogger(options = {}) | options = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | subprocess | `import { createBuildchainLogger } from "@kungfu-tech/buildchain";` | `packages/core/logging.js:300` |
-| `createBuildchainPublicationAuthorityRegistry` | function: function createBuildchainPublicationAuthorityRegistry({ root = process.cwd() } = {}) | { root = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createBuildchainPublicationAuthorityRegistry } from "@kungfu-tech/buildchain";` | `packages/core/buildchain-publication-authority.js:78` |
+| `createBuildchainPublicationAuthorityRegistry` | function: function createBuildchainPublicationAuthorityRegistry({ root = process.cwd() } = {}) | { root = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createBuildchainPublicationAuthorityRegistry } from "@kungfu-tech/buildchain";` | `packages/core/buildchain-publication-authority.js:79` |
 | `createBuildchainPublicClaimDefinitions` | function: function createBuildchainPublicClaimDefinitions() | none | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createBuildchainPublicClaimDefinitions } from "@kungfu-tech/buildchain";` | `packages/core/buildchain-kfd-claims.js:226` |
 | `createCacheEvidenceSet` | function: function createCacheEvidenceSet({ repository, sourceCommit, sourceTree = "", runtimeCommit = "", platform, operations = [], } = {}) | { repository, sourceCommit, sourceTree = "", runtimeCommit = "", platform, operations = [], } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createCacheEvidenceSet } from "@kungfu-tech/buildchain";` | `packages/core/cache-evidence.js:244` |
 | `createCacheOperationReceipt` | function: function createCacheOperationReceipt({ operationId, operation, provider, producer, platform, cacheKey, cacheRoot, outcome, bindings = {}, metrics, evidence, } = {}) | { operationId, operation, provider, producer, platform, cacheKey, cacheRoot, outcome, bindings = {}, metrics, evidence, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createCacheOperationReceipt } from "@kungfu-tech/buildchain";` | `packages/core/cache-evidence.js:169` |
@@ -226,6 +227,7 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `createReleasePassport` | function: function createReleasePassport({ cwd = process.cwd(), repository = "", tag = "", sourceSha = "", line = "", productName = "Buildchain", packageName = "@kungfu-tech/buildchain", packageVersion = "", productMechanismPath = "product-mechanism.json", artifactEvidencePath = "artifact-evidence.json", impactPath = "impact.json", agentIndexPath = "agent-index.json", checkReportPath = "check-report.json", publishEvidencePath = "", transactionStatePath = "", assets = [], packageSet = undefined, anchorManifest = undefined, versionMaterial = undefined, publishEvidence = undefined, trustedPublishing = undefined, transaction = undefined, buildSummary = undefined, buildFacts = [], platformArtifactManifests = [], distTagPromotionEvidence = undefined, release = {}, publish = {}, impact = undefined, workflow = {}, kfd1 = undefined, kfd2Claims = [], kfd3 = undefined, kfdSupport = undefined, kfdSupportEvidencePath = "", invariantPassports = undefined, releaseEvidence = [], kfdAgentHubEvidence = undefined, kfdAgentHubEvidencePath = "", controllerReceipts = [], controllerReceiptReferences = [], githubArtifactAttestations = [], checkedAt = "", } = {}) | { cwd = process.cwd(), repository = "", tag = "", sourceSha = "", line = "", productName = "Buildchain", packageName = "@kungfu-tech/buildchain", packageVersion = "", productMechanismPath = "product-mechanism.json", artifactEvidencePath = "artifact-evidence.json", impactPath = "impact.json", agentIndexPath = "agent-index.json", checkReportPath = "check-report.json", publishEvidencePath = "", transactionStatePath = "", assets = [], packageSet = undefined, anchorManifest = undefined, versionMaterial = undefined, publishEvidence = undefined, trustedPublishing = undefined, transaction = undefined, buildSummary = undefined, buildFacts = [], platformArtifactManifests = [], distTagPromotionEvidence = undefined, release = {}, publish = {}, impact = undefined, workflow = {}, kfd1 = undefined, kfd2Claims = [], kfd3 = undefined, kfdSupport = undefined, kfdSupportEvidencePath = "", invariantPassports = undefined, releaseEvidence = [], kfdAgentHubEvidence = undefined, kfdAgentHubEvidencePath = "", controllerReceipts = [], controllerReceiptReferences = [], githubArtifactAttestations = [], checkedAt = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createReleasePassport } from "@kungfu-tech/buildchain";` | `packages/core/release-passport.js:1214` |
 | `createReleasePassportCheckManifest` | function: function createReleasePassportCheckManifest({ standards = kfdStandards } = {}) | { standards = kfdStandards } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createReleasePassportCheckManifest } from "@kungfu-tech/buildchain";` | `packages/core/release-passport-contract.js:147` |
 | `createReleasePropagationLock` | function: function createReleasePropagationLock({ graph, edge, sourceNode, targetNode, upstreamRelease, downstreamChannel, } = {}) | { graph, edge, sourceNode, targetNode, upstreamRelease, downstreamChannel, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createReleasePropagationLock } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation.js:199` |
+| `createReleasePropagationPushPlan` | function: function createReleasePropagationPushPlan({ work: workInput, expectedWorkRoot, repositoryState: stateInput, } = {}) | { work: workInput, expectedWorkRoot, repositoryState: stateInput, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | subprocess | `import { createReleasePropagationPushPlan } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-push.js:77` |
 | `createReleasePropagationReceipt` | function: function createReleasePropagationReceipt({ plan, target = "", lockResult, prOutcome, stagingState = "pending", productionState = "not-requested", observedAt = "", } = {}) | { plan, target = "", lockResult, prOutcome, stagingState = "pending", productionState = "not-requested", observedAt = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createReleasePropagationReceipt } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation.js:371` |
 | `createReleasePropagationStageReceipt` | function: function createReleasePropagationStageReceipt({ work, stage, outcome = "success", observedAt, actor, summary, evidence, failure = null, } = {}) | { work, stage, outcome = "success", observedAt, actor, summary, evidence, failure = null, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createReleasePropagationStageReceipt } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-work.js:214` |
 | `createReleasePropagationWork` | function: function createReleasePropagationWork({ plan, target = "", workContext, expectedDownstreamBaseSha, } = {}) | { plan, target = "", workContext, expectedDownstreamBaseSha, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createReleasePropagationWork } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-work.js:111` |
@@ -266,6 +268,7 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `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:2840` |
 | `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` |
 | `explainArtifactPassport` | function: async function explainArtifactPassport(options = {}) | options = {} | Promise<unknown> | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { explainArtifactPassport } from "@kungfu-tech/buildchain";` | `packages/core/artifact-passport.js:827` |
 | `explainKfdAgentHub` | function: function explainKfdAgentHub({ cwd = process.cwd(), declarationPath = KFD_AGENT_HUB_DECLARATION, kfdRoot = "" } = {}) | { cwd = process.cwd(), declarationPath = KFD_AGENT_HUB_DECLARATION, kfdRoot = "" } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { explainKfdAgentHub } from "@kungfu-tech/buildchain";` | `packages/core/kfd-agent-hub.js:470` |
 | `explainReleaseLineDryRun` | function: function explainReleaseLineDryRun({ cwd = process.cwd(), targetRef, sha = "", sourceRef = "", tags, publishTransaction = false, publishCommand = "", } = {}) | { cwd = process.cwd(), targetRef, sha = "", sourceRef = "", tags, publishTransaction = false, publishCommand = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { explainReleaseLineDryRun } from "@kungfu-tech/buildchain";` | `packages/core/release-line-dry-run.js:127` |
@@ -303,6 +306,7 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `IMPACT_LEDGER_CONTRACT` | constant: const IMPACT_LEDGER_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { IMPACT_LEDGER_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/release-passport.js:30` |
 | `initKfdAgentHub` | function: function initKfdAgentHub({ cwd = process.cwd(), declarationPath = KFD_AGENT_HUB_DECLARATION, write = false, force = false } = {}) | { cwd = process.cwd(), declarationPath = KFD_AGENT_HUB_DECLARATION, write = false, force = false } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { initKfdAgentHub } from "@kungfu-tech/buildchain";` | `packages/core/kfd-agent-hub.js:363` |
 | `inspectKfdAgentHub` | function: function inspectKfdAgentHub({ cwd = process.cwd(), declarationPath = KFD_AGENT_HUB_DECLARATION, kfdRoot = "" } = {}) | { cwd = process.cwd(), declarationPath = KFD_AGENT_HUB_DECLARATION, kfdRoot = "" } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { inspectKfdAgentHub } from "@kungfu-tech/buildchain";` | `packages/core/kfd-agent-hub.js:384` |
+| `inspectReleasePropagationPushState` | function: function inspectReleasePropagationPushState({ work: workInput, cwd = process.cwd(), remote = "origin", } = {}) | { work: workInput, cwd = process.cwd(), remote = "origin", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | subprocess | `import { inspectReleasePropagationPushState } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-push.js:174` |
 | `KFD_AGENT_HUB_ADOPTION_CONTRACT` | constant: const KFD_AGENT_HUB_ADOPTION_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { KFD_AGENT_HUB_ADOPTION_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/kfd-agent-hub.js:9` |
 | `KFD_AGENT_HUB_ADOPTION_SCHEMA` | constant: const KFD_AGENT_HUB_ADOPTION_SCHEMA | none | value | Import does not declare a throw contract. | none-on-import | `import { KFD_AGENT_HUB_ADOPTION_SCHEMA } from "@kungfu-tech/buildchain";` | `packages/core/kfd-agent-hub.js:12` |
 | `KFD_AGENT_HUB_DECLARATION` | constant: const KFD_AGENT_HUB_DECLARATION | none | value | Import does not declare a throw contract. | none-on-import | `import { KFD_AGENT_HUB_DECLARATION } from "@kungfu-tech/buildchain";` | `packages/core/kfd-agent-hub.js:7` |
@@ -370,6 +374,7 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `normalizeManualUpstreamPickupConfig` | function: function normalizeManualUpstreamPickupConfig(input) | input | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { normalizeManualUpstreamPickupConfig } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-pickup.js:118` |
 | `normalizePackageReleasePropagationConfig` | function: function normalizePackageReleasePropagationConfig(input) | input | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { normalizePackageReleasePropagationConfig } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-capture.js:63` |
 | `normalizeReleasePropagationGraph` | function: function normalizeReleasePropagationGraph(input) | input | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { normalizeReleasePropagationGraph } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation.js:163` |
+| `normalizeSiteUpstreamIntent` | function: function normalizeSiteUpstreamIntent(value) | value | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { normalizeSiteUpstreamIntent } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-agent-entry.js:77` |
 | `normalizeStableCandidateLedger` | function: function normalizeStableCandidateLedger(input, expected = {}) | input, expected = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { normalizeStableCandidateLedger } from "@kungfu-tech/buildchain";` | `packages/core/stable-candidate-ledger.js:76` |
 | `PACKAGE_RELEASE_PROPAGATION_CONFIG_CONTRACT` | constant: const PACKAGE_RELEASE_PROPAGATION_CONFIG_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { PACKAGE_RELEASE_PROPAGATION_CONFIG_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-capture.js:17` |
 | `PAPER_ALPHA_PLAN_CONTRACT` | constant: const PAPER_ALPHA_PLAN_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { PAPER_ALPHA_PLAN_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:90` |
@@ -396,6 +401,7 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `planPaperScaffold` | function: function planPaperScaffold({ cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", name = path.basename(path.resolve(cwd)), title = "", packageName = "", repository = "", version = "0.1.0-alpha.0", siteBaseUrl = "", } = {}) | { cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", name = path.basename(path.resolve(cwd)), title = "", packageName = "", repository = "", version = "0.1.0-alpha.0", siteBaseUrl = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { planPaperScaffold } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:702` |
 | `planReleaseLineBootstrap` | function: function planReleaseLineBootstrap({ cwd = process.cwd(), major, minor, sourceRef = "", initialVersion = "", requiredStatusCheck = "check", setDefault = true, createAlphaPr = true, approvalCount = 1, bootstrapBranch = "", } = {}) | { cwd = process.cwd(), major, minor, sourceRef = "", initialVersion = "", requiredStatusCheck = "check", setDefault = true, createAlphaPr = true, approvalCount = 1, bootstrapBranch = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { planReleaseLineBootstrap } from "@kungfu-tech/buildchain";` | `packages/core/release-line-bootstrap.js:140` |
 | `planReleasePropagation` | function: function planReleasePropagation({ graph: graphInput, upstreamRelease: releaseInput, sourceNode = "" } = {}) | { graph: graphInput, upstreamRelease: releaseInput, sourceNode = "" } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { planReleasePropagation } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation.js:249` |
+| `planSiteUpstreamAgentEntry` | function: function planSiteUpstreamAgentEntry({ sourceId: sourceInput, channel = "", handoffWork = null, } = {}) | { sourceId: sourceInput, channel = "", handoffWork = null, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { planSiteUpstreamAgentEntry } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-agent-entry.js:134` |
 | `planTransactionRecovery` | function: function planTransactionRecovery({ transaction, evidence, validation, explicitOverride = false, } = {}) | { transaction, evidence, validation, explicitOverride = false, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { planTransactionRecovery } from "@kungfu-tech/buildchain";` | `packages/core/publish-transaction.js:769` |
 | `prepareGitHubArtifactAttestation` | function: function prepareGitHubArtifactAttestation({ subjectPath, platformManifestPath, releasePassportPath, policy, expectedBuildchainRef = "", expectedCallerRepository = "", expectedSourceSha = "", } = {}) | { subjectPath, platformManifestPath, releasePassportPath, policy, expectedBuildchainRef = "", expectedCallerRepository = "", expectedSourceSha = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { prepareGitHubArtifactAttestation } from "@kungfu-tech/buildchain";` | `packages/core/github-artifact-attestation.js:250` |
 | `preparePublicationNpmPackage` | function: function preparePublicationNpmPackage({ cwd = process.cwd(), outputDir = ".buildchain/publication/npm-package", packageName = "", } = {}) | { cwd = process.cwd(), outputDir = ".buildchain/publication/npm-package", packageName = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | local-filesystem-write | `import { preparePublicationNpmPackage } from "@kungfu-tech/buildchain";` | `packages/core/publication-package.js:120` |
@@ -456,9 +462,13 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `RELEASE_PASSPORT_CONTRACT` | constant: const RELEASE_PASSPORT_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PASSPORT_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/release-passport.js:28` |
 | `RELEASE_PASSPORT_SCHEMA` | constant: const RELEASE_PASSPORT_SCHEMA | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PASSPORT_SCHEMA } from "@kungfu-tech/buildchain";` | `packages/core/release-passport-contract.js:16` |
 | `RELEASE_PASSPORT_SCHEMA_ID` | constant: const RELEASE_PASSPORT_SCHEMA_ID | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PASSPORT_SCHEMA_ID } from "@kungfu-tech/buildchain";` | `packages/core/release-passport-contract.js:7` |
+| `RELEASE_PROPAGATION_FAILURE_MATRIX` | constant: const RELEASE_PROPAGATION_FAILURE_MATRIX | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_FAILURE_MATRIX } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-agent-entry.js:66` |
+| `RELEASE_PROPAGATION_FAILURE_MATRIX_CONTRACT` | constant: const RELEASE_PROPAGATION_FAILURE_MATRIX_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_FAILURE_MATRIX_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-agent-entry.js:11` |
 | `RELEASE_PROPAGATION_GRAPH_CONTRACT` | constant: const RELEASE_PROPAGATION_GRAPH_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_GRAPH_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation.js:15` |
 | `RELEASE_PROPAGATION_LOCK_CONTRACT` | constant: const RELEASE_PROPAGATION_LOCK_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_LOCK_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation.js:17` |
 | `RELEASE_PROPAGATION_PLAN_CONTRACT` | value: RELEASE_PROPAGATION_PLAN_CONTRACT | none | unknown | No narrower error contract was mechanically discoverable. | unknown | `import { RELEASE_PROPAGATION_PLAN_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation.js:1` |
+| `RELEASE_PROPAGATION_PUSH_PLAN_CONTRACT` | constant: const RELEASE_PROPAGATION_PUSH_PLAN_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_PUSH_PLAN_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-push.js:14` |
+| `RELEASE_PROPAGATION_PUSH_RESULT_CONTRACT` | constant: const RELEASE_PROPAGATION_PUSH_RESULT_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_PUSH_RESULT_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-push.js:16` |
 | `RELEASE_PROPAGATION_RECEIPT_CONTRACT` | constant: const RELEASE_PROPAGATION_RECEIPT_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_RECEIPT_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation.js:18` |
 | `RELEASE_PROPAGATION_STAGE_RECEIPT_CONTRACT` | constant: const RELEASE_PROPAGATION_STAGE_RECEIPT_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_STAGE_RECEIPT_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-work-constants.js:2` |
 | `RELEASE_PROPAGATION_WORK_CONTRACT` | constant: const RELEASE_PROPAGATION_WORK_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_WORK_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-work-constants.js:1` |
@@ -505,6 +515,7 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `sha512IntegrityFile` | function: function sha512IntegrityFile(filePath) | filePath | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { sha512IntegrityFile } from "@kungfu-tech/buildchain";` | `packages/core/artifact-passport.js:38` |
 | `shellJoin` | function: function shellJoin(command) | command | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { shellJoin } from "@kungfu-tech/buildchain";` | `packages/core/package-manager.js:114` |
 | `signDetachedArtifactRequest` | function: function signDetachedArtifactRequest({ request, privateKey, keyId, authority = {}, } = {}) | { request, privateKey, keyId, authority = {}, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { signDetachedArtifactRequest } from "@kungfu-tech/buildchain";` | `packages/core/detached-artifact-signature.js:36` |
+| `SITE_UPSTREAM_AGENT_ENTRY_CONTRACT` | constant: const SITE_UPSTREAM_AGENT_ENTRY_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { SITE_UPSTREAM_AGENT_ENTRY_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-agent-entry.js:9` |
 | `STABLE_CANDIDATE_LEDGER_CONTRACT` | constant: const STABLE_CANDIDATE_LEDGER_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { STABLE_CANDIDATE_LEDGER_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/stable-candidate-ledger.js:1` |
 | `STABLE_CANDIDATE_STATES` | constant: const STABLE_CANDIDATE_STATES | none | value | Import does not declare a throw contract. | none-on-import | `import { STABLE_CANDIDATE_STATES } from "@kungfu-tech/buildchain";` | `packages/core/stable-candidate-ledger.js:2` |
 | `stableCandidatePromotionRefs` | function: function stableCandidatePromotionRefs(candidateInput, targetBranch) | candidateInput, targetBranch | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { stableCandidatePromotionRefs } from "@kungfu-tech/buildchain";` | `packages/core/stable-candidate-ledger.js:264` |
@@ -624,7 +635,7 @@ Target: `./packages/core/build-facts.js`. Public symbols: 15.
 
 ## `@kungfu-tech/buildchain/core`
 
-Target: `./packages/core/index.js`. Public symbols: 547.
+Target: `./packages/core/index.js`. Public symbols: 558.
 
 | Symbol | Kind and signature | Parameters | Return | Errors | Side effects | Example | Source |
 | --- | --- | --- | --- | --- | --- | --- | --- |
@@ -713,7 +724,7 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `BUILDCHAIN_VERSION_PIN_PATH` | constant: const BUILDCHAIN_VERSION_PIN_PATH | none | value | Import does not declare a throw contract. | none-on-import | `import { BUILDCHAIN_VERSION_PIN_PATH } from "@kungfu-tech/buildchain/core";` | `packages/core/buildchain-layout.js:5` |
 | `BUILDCHAIN_WORKFLOW_FRICTION_ISSUE_CONTRACT` | constant: const BUILDCHAIN_WORKFLOW_FRICTION_ISSUE_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { BUILDCHAIN_WORKFLOW_FRICTION_ISSUE_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/issue-reporting.js:5` |
 | `buildchainKfdClaims` | constant: const buildchainKfdClaims | none | value | Import does not declare a throw contract. | none-on-import | `import { buildchainKfdClaims } from "@kungfu-tech/buildchain/core";` | `packages/core/kfd.js:896` |
-| `buildchainPublicationAuthorityDescriptors` | function: function buildchainPublicationAuthorityDescriptors() | none | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { buildchainPublicationAuthorityDescriptors } from "@kungfu-tech/buildchain/core";` | `packages/core/buildchain-publication-authority.js:53` |
+| `buildchainPublicationAuthorityDescriptors` | function: function buildchainPublicationAuthorityDescriptors() | none | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { buildchainPublicationAuthorityDescriptors } from "@kungfu-tech/buildchain/core";` | `packages/core/buildchain-publication-authority.js:54` |
 | `buildConsumerIssueReport` | function: function buildConsumerIssueReport(options = {}) | options = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { buildConsumerIssueReport } from "@kungfu-tech/buildchain/core";` | `packages/core/issue-reporting.js:104` |
 | `buildFactsDigest` | function: function buildFactsDigest(value) | value | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | local-filesystem-write, subprocess | `import { buildFactsDigest } from "@kungfu-tech/buildchain/core";` | `packages/core/build-facts.js:45` |
 | `buildWorkflowFrictionIssueReport` | function: function buildWorkflowFrictionIssueReport(options = {}) | options = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { buildWorkflowFrictionIssueReport } from "@kungfu-tech/buildchain/core";` | `packages/core/issue-reporting.js:199` |
@@ -726,6 +737,7 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `checkReadmeBadgeBlock` | function: function checkReadmeBadgeBlock({ readmeText, facts } = {}) | { readmeText, facts } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { checkReadmeBadgeBlock } from "@kungfu-tech/buildchain/core";` | `packages/core/readme-badges.js:848` |
 | `claimReleasePropagationWork` | function: function claimReleasePropagationWork({ work, expectedWorkRoot, authority, familyState, } = {}) | { work, expectedWorkRoot, authority, familyState, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { claimReleasePropagationWork } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-work-transitions.js:17` |
 | `classifyProcessCommand` | function: function classifyProcessCommand(command = "") | command = "" | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { classifyProcessCommand } from "@kungfu-tech/buildchain/core";` | `packages/core/diagnostics.js:1085` |
+| `classifyReleasePropagationCondition` | function: function classifyReleasePropagationCondition(condition) | condition | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { classifyReleasePropagationCondition } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-agent-entry.js:171` |
 | `codeownersForPath` | function: function codeownersForPath(source, candidatePath) | source, candidatePath | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { codeownersForPath } from "@kungfu-tech/buildchain/core";` | `packages/core/github-governance-authority.js:417` |
 | `collectBadgeBundleFacts` | function: async function collectBadgeBundleFacts({ cwd = process.cwd(), claims = undefined } = {}) | { cwd = process.cwd(), claims = undefined } = {} | Promise<unknown> | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectBadgeBundleFacts } from "@kungfu-tech/buildchain/core";` | `packages/core/readme-badges.js:790` |
 | `collectBuildchainDiagnostics` | function: function collectBuildchainDiagnostics({ cwd = process.cwd(), artifactPaths = [] } = {}) | { cwd = process.cwd(), artifactPaths = [] } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectBuildchainDiagnostics } from "@kungfu-tech/buildchain/core";` | `packages/core/diagnostics.js:248` |
@@ -775,7 +787,7 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `createBuildchainKfdSurfaceRegistry` | function: function createBuildchainKfdSurfaceRegistry({ root = process.cwd() } = {}) | { root = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createBuildchainKfdSurfaceRegistry } from "@kungfu-tech/buildchain/core";` | `packages/core/buildchain-kfd-claims.js:411` |
 | `createBuildchainLayoutDiscovery` | function: function createBuildchainLayoutDiscovery({ cwd = process.cwd(), buildchainVersion = "", } = {}) | { cwd = process.cwd(), buildchainVersion = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createBuildchainLayoutDiscovery } from "@kungfu-tech/buildchain/core";` | `packages/core/buildchain-layout.js:99` |
 | `createBuildchainLogger` | function: function createBuildchainLogger(options = {}) | options = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | subprocess | `import { createBuildchainLogger } from "@kungfu-tech/buildchain/core";` | `packages/core/logging.js:300` |
-| `createBuildchainPublicationAuthorityRegistry` | function: function createBuildchainPublicationAuthorityRegistry({ root = process.cwd() } = {}) | { root = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createBuildchainPublicationAuthorityRegistry } from "@kungfu-tech/buildchain/core";` | `packages/core/buildchain-publication-authority.js:78` |
+| `createBuildchainPublicationAuthorityRegistry` | function: function createBuildchainPublicationAuthorityRegistry({ root = process.cwd() } = {}) | { root = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createBuildchainPublicationAuthorityRegistry } from "@kungfu-tech/buildchain/core";` | `packages/core/buildchain-publication-authority.js:79` |
 | `createBuildchainPublicClaimDefinitions` | function: function createBuildchainPublicClaimDefinitions() | none | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createBuildchainPublicClaimDefinitions } from "@kungfu-tech/buildchain/core";` | `packages/core/buildchain-kfd-claims.js:226` |
 | `createCacheEvidenceSet` | function: function createCacheEvidenceSet({ repository, sourceCommit, sourceTree = "", runtimeCommit = "", platform, operations = [], } = {}) | { repository, sourceCommit, sourceTree = "", runtimeCommit = "", platform, operations = [], } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createCacheEvidenceSet } from "@kungfu-tech/buildchain/core";` | `packages/core/cache-evidence.js:244` |
 | `createCacheOperationReceipt` | function: function createCacheOperationReceipt({ operationId, operation, provider, producer, platform, cacheKey, cacheRoot, outcome, bindings = {}, metrics, evidence, } = {}) | { operationId, operation, provider, producer, platform, cacheKey, cacheRoot, outcome, bindings = {}, metrics, evidence, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createCacheOperationReceipt } from "@kungfu-tech/buildchain/core";` | `packages/core/cache-evidence.js:169` |
@@ -826,6 +838,7 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `createReleasePassport` | function: function createReleasePassport({ cwd = process.cwd(), repository = "", tag = "", sourceSha = "", line = "", productName = "Buildchain", packageName = "@kungfu-tech/buildchain", packageVersion = "", productMechanismPath = "product-mechanism.json", artifactEvidencePath = "artifact-evidence.json", impactPath = "impact.json", agentIndexPath = "agent-index.json", checkReportPath = "check-report.json", publishEvidencePath = "", transactionStatePath = "", assets = [], packageSet = undefined, anchorManifest = undefined, versionMaterial = undefined, publishEvidence = undefined, trustedPublishing = undefined, transaction = undefined, buildSummary = undefined, buildFacts = [], platformArtifactManifests = [], distTagPromotionEvidence = undefined, release = {}, publish = {}, impact = undefined, workflow = {}, kfd1 = undefined, kfd2Claims = [], kfd3 = undefined, kfdSupport = undefined, kfdSupportEvidencePath = "", invariantPassports = undefined, releaseEvidence = [], kfdAgentHubEvidence = undefined, kfdAgentHubEvidencePath = "", controllerReceipts = [], controllerReceiptReferences = [], githubArtifactAttestations = [], checkedAt = "", } = {}) | { cwd = process.cwd(), repository = "", tag = "", sourceSha = "", line = "", productName = "Buildchain", packageName = "@kungfu-tech/buildchain", packageVersion = "", productMechanismPath = "product-mechanism.json", artifactEvidencePath = "artifact-evidence.json", impactPath = "impact.json", agentIndexPath = "agent-index.json", checkReportPath = "check-report.json", publishEvidencePath = "", transactionStatePath = "", assets = [], packageSet = undefined, anchorManifest = undefined, versionMaterial = undefined, publishEvidence = undefined, trustedPublishing = undefined, transaction = undefined, buildSummary = undefined, buildFacts = [], platformArtifactManifests = [], distTagPromotionEvidence = undefined, release = {}, publish = {}, impact = undefined, workflow = {}, kfd1 = undefined, kfd2Claims = [], kfd3 = undefined, kfdSupport = undefined, kfdSupportEvidencePath = "", invariantPassports = undefined, releaseEvidence = [], kfdAgentHubEvidence = undefined, kfdAgentHubEvidencePath = "", controllerReceipts = [], controllerReceiptReferences = [], githubArtifactAttestations = [], checkedAt = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createReleasePassport } from "@kungfu-tech/buildchain/core";` | `packages/core/release-passport.js:1214` |
 | `createReleasePassportCheckManifest` | function: function createReleasePassportCheckManifest({ standards = kfdStandards } = {}) | { standards = kfdStandards } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createReleasePassportCheckManifest } from "@kungfu-tech/buildchain/core";` | `packages/core/release-passport-contract.js:147` |
 | `createReleasePropagationLock` | function: function createReleasePropagationLock({ graph, edge, sourceNode, targetNode, upstreamRelease, downstreamChannel, } = {}) | { graph, edge, sourceNode, targetNode, upstreamRelease, downstreamChannel, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createReleasePropagationLock } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation.js:199` |
+| `createReleasePropagationPushPlan` | function: function createReleasePropagationPushPlan({ work: workInput, expectedWorkRoot, repositoryState: stateInput, } = {}) | { work: workInput, expectedWorkRoot, repositoryState: stateInput, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | subprocess | `import { createReleasePropagationPushPlan } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-push.js:77` |
 | `createReleasePropagationReceipt` | function: function createReleasePropagationReceipt({ plan, target = "", lockResult, prOutcome, stagingState = "pending", productionState = "not-requested", observedAt = "", } = {}) | { plan, target = "", lockResult, prOutcome, stagingState = "pending", productionState = "not-requested", observedAt = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createReleasePropagationReceipt } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation.js:371` |
 | `createReleasePropagationStageReceipt` | function: function createReleasePropagationStageReceipt({ work, stage, outcome = "success", observedAt, actor, summary, evidence, failure = null, } = {}) | { work, stage, outcome = "success", observedAt, actor, summary, evidence, failure = null, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createReleasePropagationStageReceipt } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-work.js:214` |
 | `createReleasePropagationWork` | function: function createReleasePropagationWork({ plan, target = "", workContext, expectedDownstreamBaseSha, } = {}) | { plan, target = "", workContext, expectedDownstreamBaseSha, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createReleasePropagationWork } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-work.js:111` |
@@ -866,6 +879,7 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `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:2840` |
 | `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` |
 | `explainArtifactPassport` | function: async function explainArtifactPassport(options = {}) | options = {} | Promise<unknown> | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { explainArtifactPassport } from "@kungfu-tech/buildchain/core";` | `packages/core/artifact-passport.js:827` |
 | `explainKfdAgentHub` | function: function explainKfdAgentHub({ cwd = process.cwd(), declarationPath = KFD_AGENT_HUB_DECLARATION, kfdRoot = "" } = {}) | { cwd = process.cwd(), declarationPath = KFD_AGENT_HUB_DECLARATION, kfdRoot = "" } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { explainKfdAgentHub } from "@kungfu-tech/buildchain/core";` | `packages/core/kfd-agent-hub.js:470` |
 | `explainReleaseLineDryRun` | function: function explainReleaseLineDryRun({ cwd = process.cwd(), targetRef, sha = "", sourceRef = "", tags, publishTransaction = false, publishCommand = "", } = {}) | { cwd = process.cwd(), targetRef, sha = "", sourceRef = "", tags, publishTransaction = false, publishCommand = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { explainReleaseLineDryRun } from "@kungfu-tech/buildchain/core";` | `packages/core/release-line-dry-run.js:127` |
@@ -903,6 +917,7 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `IMPACT_LEDGER_CONTRACT` | constant: const IMPACT_LEDGER_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { IMPACT_LEDGER_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/release-passport.js:30` |
 | `initKfdAgentHub` | function: function initKfdAgentHub({ cwd = process.cwd(), declarationPath = KFD_AGENT_HUB_DECLARATION, write = false, force = false } = {}) | { cwd = process.cwd(), declarationPath = KFD_AGENT_HUB_DECLARATION, write = false, force = false } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { initKfdAgentHub } from "@kungfu-tech/buildchain/core";` | `packages/core/kfd-agent-hub.js:363` |
 | `inspectKfdAgentHub` | function: function inspectKfdAgentHub({ cwd = process.cwd(), declarationPath = KFD_AGENT_HUB_DECLARATION, kfdRoot = "" } = {}) | { cwd = process.cwd(), declarationPath = KFD_AGENT_HUB_DECLARATION, kfdRoot = "" } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { inspectKfdAgentHub } from "@kungfu-tech/buildchain/core";` | `packages/core/kfd-agent-hub.js:384` |
+| `inspectReleasePropagationPushState` | function: function inspectReleasePropagationPushState({ work: workInput, cwd = process.cwd(), remote = "origin", } = {}) | { work: workInput, cwd = process.cwd(), remote = "origin", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | subprocess | `import { inspectReleasePropagationPushState } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-push.js:174` |
 | `KFD_AGENT_HUB_ADOPTION_CONTRACT` | constant: const KFD_AGENT_HUB_ADOPTION_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { KFD_AGENT_HUB_ADOPTION_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/kfd-agent-hub.js:9` |
 | `KFD_AGENT_HUB_ADOPTION_SCHEMA` | constant: const KFD_AGENT_HUB_ADOPTION_SCHEMA | none | value | Import does not declare a throw contract. | none-on-import | `import { KFD_AGENT_HUB_ADOPTION_SCHEMA } from "@kungfu-tech/buildchain/core";` | `packages/core/kfd-agent-hub.js:12` |
 | `KFD_AGENT_HUB_DECLARATION` | constant: const KFD_AGENT_HUB_DECLARATION | none | value | Import does not declare a throw contract. | none-on-import | `import { KFD_AGENT_HUB_DECLARATION } from "@kungfu-tech/buildchain/core";` | `packages/core/kfd-agent-hub.js:7` |
@@ -970,6 +985,7 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `normalizeManualUpstreamPickupConfig` | function: function normalizeManualUpstreamPickupConfig(input) | input | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { normalizeManualUpstreamPickupConfig } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-pickup.js:118` |
 | `normalizePackageReleasePropagationConfig` | function: function normalizePackageReleasePropagationConfig(input) | input | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { normalizePackageReleasePropagationConfig } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-capture.js:63` |
 | `normalizeReleasePropagationGraph` | function: function normalizeReleasePropagationGraph(input) | input | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { normalizeReleasePropagationGraph } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation.js:163` |
+| `normalizeSiteUpstreamIntent` | function: function normalizeSiteUpstreamIntent(value) | value | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { normalizeSiteUpstreamIntent } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-agent-entry.js:77` |
 | `normalizeStableCandidateLedger` | function: function normalizeStableCandidateLedger(input, expected = {}) | input, expected = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { normalizeStableCandidateLedger } from "@kungfu-tech/buildchain/core";` | `packages/core/stable-candidate-ledger.js:76` |
 | `PACKAGE_RELEASE_PROPAGATION_CONFIG_CONTRACT` | constant: const PACKAGE_RELEASE_PROPAGATION_CONFIG_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { PACKAGE_RELEASE_PROPAGATION_CONFIG_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-capture.js:17` |
 | `PAPER_ALPHA_PLAN_CONTRACT` | constant: const PAPER_ALPHA_PLAN_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { PAPER_ALPHA_PLAN_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:90` |
@@ -996,6 +1012,7 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `planPaperScaffold` | function: function planPaperScaffold({ cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", name = path.basename(path.resolve(cwd)), title = "", packageName = "", repository = "", version = "0.1.0-alpha.0", siteBaseUrl = "", } = {}) | { cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", name = path.basename(path.resolve(cwd)), title = "", packageName = "", repository = "", version = "0.1.0-alpha.0", siteBaseUrl = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { planPaperScaffold } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:702` |
 | `planReleaseLineBootstrap` | function: function planReleaseLineBootstrap({ cwd = process.cwd(), major, minor, sourceRef = "", initialVersion = "", requiredStatusCheck = "check", setDefault = true, createAlphaPr = true, approvalCount = 1, bootstrapBranch = "", } = {}) | { cwd = process.cwd(), major, minor, sourceRef = "", initialVersion = "", requiredStatusCheck = "check", setDefault = true, createAlphaPr = true, approvalCount = 1, bootstrapBranch = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { planReleaseLineBootstrap } from "@kungfu-tech/buildchain/core";` | `packages/core/release-line-bootstrap.js:140` |
 | `planReleasePropagation` | function: function planReleasePropagation({ graph: graphInput, upstreamRelease: releaseInput, sourceNode = "" } = {}) | { graph: graphInput, upstreamRelease: releaseInput, sourceNode = "" } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { planReleasePropagation } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation.js:249` |
+| `planSiteUpstreamAgentEntry` | function: function planSiteUpstreamAgentEntry({ sourceId: sourceInput, channel = "", handoffWork = null, } = {}) | { sourceId: sourceInput, channel = "", handoffWork = null, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { planSiteUpstreamAgentEntry } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-agent-entry.js:134` |
 | `planTransactionRecovery` | function: function planTransactionRecovery({ transaction, evidence, validation, explicitOverride = false, } = {}) | { transaction, evidence, validation, explicitOverride = false, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { planTransactionRecovery } from "@kungfu-tech/buildchain/core";` | `packages/core/publish-transaction.js:769` |
 | `prepareGitHubArtifactAttestation` | function: function prepareGitHubArtifactAttestation({ subjectPath, platformManifestPath, releasePassportPath, policy, expectedBuildchainRef = "", expectedCallerRepository = "", expectedSourceSha = "", } = {}) | { subjectPath, platformManifestPath, releasePassportPath, policy, expectedBuildchainRef = "", expectedCallerRepository = "", expectedSourceSha = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { prepareGitHubArtifactAttestation } from "@kungfu-tech/buildchain/core";` | `packages/core/github-artifact-attestation.js:250` |
 | `preparePublicationNpmPackage` | function: function preparePublicationNpmPackage({ cwd = process.cwd(), outputDir = ".buildchain/publication/npm-package", packageName = "", } = {}) | { cwd = process.cwd(), outputDir = ".buildchain/publication/npm-package", packageName = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | local-filesystem-write | `import { preparePublicationNpmPackage } from "@kungfu-tech/buildchain/core";` | `packages/core/publication-package.js:120` |
@@ -1056,9 +1073,13 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `RELEASE_PASSPORT_CONTRACT` | constant: const RELEASE_PASSPORT_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PASSPORT_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/release-passport.js:28` |
 | `RELEASE_PASSPORT_SCHEMA` | constant: const RELEASE_PASSPORT_SCHEMA | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PASSPORT_SCHEMA } from "@kungfu-tech/buildchain/core";` | `packages/core/release-passport-contract.js:16` |
 | `RELEASE_PASSPORT_SCHEMA_ID` | constant: const RELEASE_PASSPORT_SCHEMA_ID | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PASSPORT_SCHEMA_ID } from "@kungfu-tech/buildchain/core";` | `packages/core/release-passport-contract.js:7` |
+| `RELEASE_PROPAGATION_FAILURE_MATRIX` | constant: const RELEASE_PROPAGATION_FAILURE_MATRIX | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_FAILURE_MATRIX } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-agent-entry.js:66` |
+| `RELEASE_PROPAGATION_FAILURE_MATRIX_CONTRACT` | constant: const RELEASE_PROPAGATION_FAILURE_MATRIX_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_FAILURE_MATRIX_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-agent-entry.js:11` |
 | `RELEASE_PROPAGATION_GRAPH_CONTRACT` | constant: const RELEASE_PROPAGATION_GRAPH_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_GRAPH_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation.js:15` |
 | `RELEASE_PROPAGATION_LOCK_CONTRACT` | constant: const RELEASE_PROPAGATION_LOCK_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_LOCK_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation.js:17` |
 | `RELEASE_PROPAGATION_PLAN_CONTRACT` | value: RELEASE_PROPAGATION_PLAN_CONTRACT | none | unknown | No narrower error contract was mechanically discoverable. | unknown | `import { RELEASE_PROPAGATION_PLAN_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation.js:1` |
+| `RELEASE_PROPAGATION_PUSH_PLAN_CONTRACT` | constant: const RELEASE_PROPAGATION_PUSH_PLAN_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_PUSH_PLAN_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-push.js:14` |
+| `RELEASE_PROPAGATION_PUSH_RESULT_CONTRACT` | constant: const RELEASE_PROPAGATION_PUSH_RESULT_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_PUSH_RESULT_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-push.js:16` |
 | `RELEASE_PROPAGATION_RECEIPT_CONTRACT` | constant: const RELEASE_PROPAGATION_RECEIPT_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_RECEIPT_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation.js:18` |
 | `RELEASE_PROPAGATION_STAGE_RECEIPT_CONTRACT` | constant: const RELEASE_PROPAGATION_STAGE_RECEIPT_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_STAGE_RECEIPT_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-work-constants.js:2` |
 | `RELEASE_PROPAGATION_WORK_CONTRACT` | constant: const RELEASE_PROPAGATION_WORK_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_WORK_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-work-constants.js:1` |
@@ -1105,6 +1126,7 @@ Target: `./packages/core/index.js`. Public symbols: 547.
 | `sha512IntegrityFile` | function: function sha512IntegrityFile(filePath) | filePath | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { sha512IntegrityFile } from "@kungfu-tech/buildchain/core";` | `packages/core/artifact-passport.js:38` |
 | `shellJoin` | function: function shellJoin(command) | command | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { shellJoin } from "@kungfu-tech/buildchain/core";` | `packages/core/package-manager.js:114` |
 | `signDetachedArtifactRequest` | function: function signDetachedArtifactRequest({ request, privateKey, keyId, authority = {}, } = {}) | { request, privateKey, keyId, authority = {}, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { signDetachedArtifactRequest } from "@kungfu-tech/buildchain/core";` | `packages/core/detached-artifact-signature.js:36` |
+| `SITE_UPSTREAM_AGENT_ENTRY_CONTRACT` | constant: const SITE_UPSTREAM_AGENT_ENTRY_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { SITE_UPSTREAM_AGENT_ENTRY_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-agent-entry.js:9` |
 | `STABLE_CANDIDATE_LEDGER_CONTRACT` | constant: const STABLE_CANDIDATE_LEDGER_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { STABLE_CANDIDATE_LEDGER_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/stable-candidate-ledger.js:1` |
 | `STABLE_CANDIDATE_STATES` | constant: const STABLE_CANDIDATE_STATES | none | value | Import does not declare a throw contract. | none-on-import | `import { STABLE_CANDIDATE_STATES } from "@kungfu-tech/buildchain/core";` | `packages/core/stable-candidate-ledger.js:2` |
 | `stableCandidatePromotionRefs` | function: function stableCandidatePromotionRefs(candidateInput, targetBranch) | candidateInput, targetBranch | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { stableCandidatePromotionRefs } from "@kungfu-tech/buildchain/core";` | `packages/core/stable-candidate-ledger.js:264` |
@@ -1765,8 +1787,8 @@ Target: `./packages/core/buildchain-publication-authority.js`. Public symbols: 2
 
 | Symbol | Kind and signature | Parameters | Return | Errors | Side effects | Example | Source |
 | --- | --- | --- | --- | --- | --- | --- | --- |
-| `buildchainPublicationAuthorityDescriptors` | function: function buildchainPublicationAuthorityDescriptors() | none | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { buildchainPublicationAuthorityDescriptors } from "@kungfu-tech/buildchain/buildchain-publication-authority";` | `packages/core/buildchain-publication-authority.js:53` |
-| `createBuildchainPublicationAuthorityRegistry` | function: function createBuildchainPublicationAuthorityRegistry({ root = process.cwd() } = {}) | { root = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createBuildchainPublicationAuthorityRegistry } from "@kungfu-tech/buildchain/buildchain-publication-authority";` | `packages/core/buildchain-publication-authority.js:78` |
+| `buildchainPublicationAuthorityDescriptors` | function: function buildchainPublicationAuthorityDescriptors() | none | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { buildchainPublicationAuthorityDescriptors } from "@kungfu-tech/buildchain/buildchain-publication-authority";` | `packages/core/buildchain-publication-authority.js:54` |
+| `createBuildchainPublicationAuthorityRegistry` | function: function createBuildchainPublicationAuthorityRegistry({ root = process.cwd() } = {}) | { root = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createBuildchainPublicationAuthorityRegistry } from "@kungfu-tech/buildchain/buildchain-publication-authority";` | `packages/core/buildchain-publication-authority.js:79` |
 
 ## `@kungfu-tech/buildchain/github-governance-authority`
 
@@ -1897,31 +1919,41 @@ Target: `./packages/core/release-passport-contract.js`. Public symbols: 5.
 
 ## `@kungfu-tech/buildchain/release-propagation`
 
-Target: `./packages/core/release-propagation.js`. Public symbols: 31.
+Target: `./packages/core/release-propagation.js`. Public symbols: 42.
 
 | Symbol | Kind and signature | Parameters | Return | Errors | Side effects | Example | Source |
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | `claimReleasePropagationWork` | function: function claimReleasePropagationWork({ work, expectedWorkRoot, authority, familyState, } = {}) | { work, expectedWorkRoot, authority, familyState, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { claimReleasePropagationWork } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-work-transitions.js:17` |
+| `classifyReleasePropagationCondition` | function: function classifyReleasePropagationCondition(condition) | condition | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { classifyReleasePropagationCondition } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-agent-entry.js:171` |
 | `completeReleasePropagationWork` | function: function completeReleasePropagationWork({ work, expectedWorkRoot, receipt, completionDecision, } = {}) | { work, expectedWorkRoot, receipt, completionDecision, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { completeReleasePropagationWork } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-work-transitions.js:110` |
 | `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/release-propagation";` | `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/release-propagation";` | `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/release-propagation";` | `packages/core/release-propagation-capture.js:101` |
 | `createReleasePropagationLock` | function: function createReleasePropagationLock({ graph, edge, sourceNode, targetNode, upstreamRelease, downstreamChannel, } = {}) | { graph, edge, sourceNode, targetNode, upstreamRelease, downstreamChannel, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createReleasePropagationLock } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation.js:199` |
+| `createReleasePropagationPushPlan` | function: function createReleasePropagationPushPlan({ work: workInput, expectedWorkRoot, repositoryState: stateInput, } = {}) | { work: workInput, expectedWorkRoot, repositoryState: stateInput, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | subprocess | `import { createReleasePropagationPushPlan } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-push.js:77` |
 | `createReleasePropagationReceipt` | function: function createReleasePropagationReceipt({ plan, target = "", lockResult, prOutcome, stagingState = "pending", productionState = "not-requested", observedAt = "", } = {}) | { plan, target = "", lockResult, prOutcome, stagingState = "pending", productionState = "not-requested", observedAt = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createReleasePropagationReceipt } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation.js:371` |
 | `createReleasePropagationStageReceipt` | function: function createReleasePropagationStageReceipt({ work, stage, outcome = "success", observedAt, actor, summary, evidence, failure = null, } = {}) | { work, stage, outcome = "success", observedAt, actor, summary, evidence, failure = null, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createReleasePropagationStageReceipt } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-work.js:214` |
 | `createReleasePropagationWork` | function: function createReleasePropagationWork({ plan, target = "", workContext, expectedDownstreamBaseSha, } = {}) | { plan, target = "", workContext, expectedDownstreamBaseSha, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createReleasePropagationWork } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-work.js:111` |
+| `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/release-propagation";` | `packages/core/release-propagation-push.js:231` |
+| `inspectReleasePropagationPushState` | function: function inspectReleasePropagationPushState({ work: workInput, cwd = process.cwd(), remote = "origin", } = {}) | { work: workInput, cwd = process.cwd(), remote = "origin", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | subprocess | `import { inspectReleasePropagationPushState } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-push.js:174` |
 | `MANUAL_UPSTREAM_PICKUP_CONFIG_CONTRACT` | constant: const MANUAL_UPSTREAM_PICKUP_CONFIG_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { MANUAL_UPSTREAM_PICKUP_CONFIG_CONTRACT } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-pickup.js:16` |
 | `MANUAL_UPSTREAM_PICKUP_PLAN_CONTRACT` | constant: const MANUAL_UPSTREAM_PICKUP_PLAN_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { MANUAL_UPSTREAM_PICKUP_PLAN_CONTRACT } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-pickup.js:18` |
 | `normalizeManualUpstreamPickupConfig` | function: function normalizeManualUpstreamPickupConfig(input) | input | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { normalizeManualUpstreamPickupConfig } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-pickup.js:118` |
 | `normalizePackageReleasePropagationConfig` | function: function normalizePackageReleasePropagationConfig(input) | input | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { normalizePackageReleasePropagationConfig } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-capture.js:63` |
 | `normalizeReleasePropagationGraph` | function: function normalizeReleasePropagationGraph(input) | input | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { normalizeReleasePropagationGraph } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation.js:163` |
+| `normalizeSiteUpstreamIntent` | function: function normalizeSiteUpstreamIntent(value) | value | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { normalizeSiteUpstreamIntent } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-agent-entry.js:77` |
 | `PACKAGE_RELEASE_PROPAGATION_CONFIG_CONTRACT` | constant: const PACKAGE_RELEASE_PROPAGATION_CONFIG_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { PACKAGE_RELEASE_PROPAGATION_CONFIG_CONTRACT } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-capture.js:17` |
 | `planReleasePropagation` | function: function planReleasePropagation({ graph: graphInput, upstreamRelease: releaseInput, sourceNode = "" } = {}) | { graph: graphInput, upstreamRelease: releaseInput, sourceNode = "" } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { planReleasePropagation } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation.js:249` |
+| `planSiteUpstreamAgentEntry` | function: function planSiteUpstreamAgentEntry({ sourceId: sourceInput, channel = "", handoffWork = null, } = {}) | { sourceId: sourceInput, channel = "", handoffWork = null, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { planSiteUpstreamAgentEntry } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-agent-entry.js:134` |
 | `readReleasePropagationJson` | function: function readReleasePropagationJson(value, { cwd = process.cwd(), label = "json" } = {}) | value, { cwd = process.cwd(), label = "json" } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { readReleasePropagationJson } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation.js:305` |
 | `recordReleasePropagationStage` | function: function recordReleasePropagationStage({ work, expectedWorkRoot, receipt } = {}) | { work, expectedWorkRoot, receipt } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | may-write-or-invoke-external-actions | `import { recordReleasePropagationStage } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-work-transitions.js:45` |
+| `RELEASE_PROPAGATION_FAILURE_MATRIX` | constant: const RELEASE_PROPAGATION_FAILURE_MATRIX | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_FAILURE_MATRIX } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-agent-entry.js:66` |
+| `RELEASE_PROPAGATION_FAILURE_MATRIX_CONTRACT` | constant: const RELEASE_PROPAGATION_FAILURE_MATRIX_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_FAILURE_MATRIX_CONTRACT } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-agent-entry.js:11` |
 | `RELEASE_PROPAGATION_GRAPH_CONTRACT` | constant: const RELEASE_PROPAGATION_GRAPH_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_GRAPH_CONTRACT } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation.js:15` |
 | `RELEASE_PROPAGATION_LOCK_CONTRACT` | constant: const RELEASE_PROPAGATION_LOCK_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_LOCK_CONTRACT } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation.js:17` |
 | `RELEASE_PROPAGATION_PLAN_CONTRACT` | value: RELEASE_PROPAGATION_PLAN_CONTRACT | none | unknown | No narrower error contract was mechanically discoverable. | unknown | `import { RELEASE_PROPAGATION_PLAN_CONTRACT } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation.js:1` |
+| `RELEASE_PROPAGATION_PUSH_PLAN_CONTRACT` | constant: const RELEASE_PROPAGATION_PUSH_PLAN_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_PUSH_PLAN_CONTRACT } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-push.js:14` |
+| `RELEASE_PROPAGATION_PUSH_RESULT_CONTRACT` | constant: const RELEASE_PROPAGATION_PUSH_RESULT_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_PUSH_RESULT_CONTRACT } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-push.js:16` |
 | `RELEASE_PROPAGATION_RECEIPT_CONTRACT` | constant: const RELEASE_PROPAGATION_RECEIPT_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_RECEIPT_CONTRACT } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation.js:18` |
 | `RELEASE_PROPAGATION_STAGE_RECEIPT_CONTRACT` | constant: const RELEASE_PROPAGATION_STAGE_RECEIPT_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_STAGE_RECEIPT_CONTRACT } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-work-constants.js:2` |
 | `RELEASE_PROPAGATION_WORK_CONTRACT` | constant: const RELEASE_PROPAGATION_WORK_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_WORK_CONTRACT } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-work-constants.js:1` |
@@ -1930,6 +1962,7 @@ Target: `./packages/core/release-propagation.js`. Public symbols: 31.
 | `resolveNpmRegistryRelease` | function: function resolveNpmRegistryRelease({ source: sourceInput, channel, packageMetadata, attestations, }) | { source: sourceInput, channel, packageMetadata, attestations, } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { resolveNpmRegistryRelease } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-pickup.js:167` |
 | `resolvePropagationChannel` | function: function resolvePropagationChannel(edge, upstreamChannel) | edge, upstreamChannel | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { resolvePropagationChannel } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation.js:190` |
 | `resumeReleasePropagationWork` | function: function resumeReleasePropagationWork(work) | work | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { resumeReleasePropagationWork } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-work.js:518` |
+| `SITE_UPSTREAM_AGENT_ENTRY_CONTRACT` | constant: const SITE_UPSTREAM_AGENT_ENTRY_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { SITE_UPSTREAM_AGENT_ENTRY_CONTRACT } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-agent-entry.js:9` |
 | `verifyReleasePropagationWork` | function: function verifyReleasePropagationWork(input) | input | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { verifyReleasePropagationWork } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation-work.js:486` |
 | `writeReleasePropagationLock` | function: function writeReleasePropagationLock({ plan, target = "", cwd = process.cwd(), output = "" } = {}) | { plan, target = "", cwd = process.cwd(), output = "" } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | local-filesystem-write | `import { writeReleasePropagationLock } from "@kungfu-tech/buildchain/release-propagation";` | `packages/core/release-propagation.js:317` |