@kungfu-tech/buildchain 4.0.1-alpha.9 → 4.0.2-alpha.0

package/architecture/ci-lane-change-budget.json

@@ -183,5 +183,74 @@
       ".github/workflows/verify.yml#stage-capsule-checkpoints"
     ]
   },
-  "declarations": []
+  "declarations": [
+    {
+      "laneId": ".github/workflows/.release-candidate-promote.yml#legacy-promote",
+      "authorityClass": "release",
+      "triggerClass": "reusable",
+      "concurrencyPolicy": {
+        "mode": "none",
+        "cancelInProgress": false
+      },
+      "expectedRunnerMinutes": 45,
+      "cancellationBehavior": "finish-started",
+      "sloImpact": {
+        "mergeCritical": false,
+        "metric": "protected release completion latency",
+        "expectedContributionSeconds": 0,
+        "rationale": "This is the existing v3 promotion lane under an explicit legacy identity, not an added execution path."
+      }
+    },
+    {
+      "laneId": ".github/workflows/.release-candidate-promote.yml#v4-declarative-promote",
+      "authorityClass": "release",
+      "triggerClass": "reusable",
+      "concurrencyPolicy": {
+        "mode": "none",
+        "cancelInProgress": false
+      },
+      "expectedRunnerMinutes": 30,
+      "cancellationBehavior": "finish-started",
+      "sloImpact": {
+        "mergeCritical": false,
+        "metric": "protected release completion latency",
+        "expectedContributionSeconds": 0,
+        "rationale": "The v4 provider lane replaces consumer tail execution only for release invocations and is outside merge-critical CI."
+      }
+    },
+    {
+      "laneId": ".github/workflows/v4-declarative-release-tail-dogfood.yml#publish",
+      "authorityClass": "release",
+      "triggerClass": "manual",
+      "concurrencyPolicy": {
+        "mode": "none",
+        "cancelInProgress": false
+      },
+      "expectedRunnerMinutes": 35,
+      "cancellationBehavior": "finish-started",
+      "sloImpact": {
+        "mergeCritical": false,
+        "metric": "manual dogfood release completion latency",
+        "expectedContributionSeconds": 0,
+        "rationale": "The explicit dogfood run proves hosted provider publication and checkpoint resume without joining pull-request checks."
+      }
+    },
+    {
+      "laneId": ".github/workflows/v4-adopter-delivery.yml#qualification",
+      "authorityClass": "evidence",
+      "triggerClass": "mixed",
+      "concurrencyPolicy": {
+        "mode": "none",
+        "cancelInProgress": false
+      },
+      "expectedRunnerMinutes": 5,
+      "cancellationBehavior": "finish-started",
+      "sloImpact": {
+        "mergeCritical": false,
+        "metric": "public adopter qualification completion latency",
+        "expectedContributionSeconds": 0,
+        "rationale": "The lane only reconciles already-produced rooted platform reports and grants no provider, release, or stable publication authority."
+      }
+    }
+  ]
 }

package/architecture/decisions/0004-v4-declarative-release-tail.md

@@ -0,0 +1,47 @@
+---
+status: accepted
+period: ongoing
+theme: buildchain-v4-declarative-release-tail
+doc_type: decision
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-08-26
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-26
+  invisible_context: unavailable
+---
+
+# ADR 0004: v4 release tails are sealed provider transactions
+
+## Decision
+
+Buildchain v4 release candidates carry a `kungfu.buildchain.v4-publication-qualification/v1` receipt. Build/Verify creates it from the candidate root, source root, typed artifact and manifest roots, floating-consumer policy digest, and a bounded freshness interval. The receipt root is written into every release-candidate Stage Capsule.
+
+`release-candidate-promote` validates that evidence before publication. It does not check out the consumer repository and does not evaluate product-owned qualification, KFD, invariant, publication, activation, or evidence commands. The v4 path accepts no non-empty `command`, `cmd`, `script`, `shell`, or `run` input. The v3 path remains available with its existing inputs and behavior.
+
+One Buildchain-owned provider transaction executes these ordered capabilities:
+
+1. `artifact.publish` creates and reads back immutable GitHub Release assets.
+2. `signed-channel.commit` commits the rooted channel document through the built-in GitHub document provider.
+3. `release.activate` commits and reads back the rooted activation document.
+4. `released-evidence.synthesize` writes receipt-only evidence from the sealed roots.
+
+Buildchain aggregates the Release Passport before the first provider mutation. All four capabilities share one transaction root and use the existing Release Tail Provider Plane envelope, idempotency, retry, observation, and receipt contracts.
+
+## Failure and resume semantics
+
+The transaction state is checkpointed after every observation and effect. A retry reads the same state, verifies its declaration and plan roots, and starts at the first capability without a settled receipt. A provider result lost after mutation is recovered by readback. Conflicting or partially matching public state enters `repair-required` without another mutation.
+
+The dogfood-only `provider-failure-after-capability` input interrupts after a durable capability checkpoint. The workflow immediately invokes the same built-in provider action against the same state path, proving local tail-only continuation and retaining the state, receipts, candidate evidence, and Release Passport as workflow artifacts.
+
+## Consequences
+
+- Consumers declare evidence and provider targets; they do not inject release-tail programs.
+- Candidate, source, artifact, and policy mismatch, tampering, missing evidence, and stale evidence fail before provider mutation.
+- Adding a new provider capability requires changing Buildchain's fixed capability registry and schema; arbitrary executable extension points are not a compatibility mechanism.
+- v3 consumers are not forced onto the v4 evidence contract.

package/architecture/internal-capabilities.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "coverageRoots": [
     "actions/promote-buildchain-ref/internal",
     "bin/buildchain.mjs",
@@ -42,6 +42,7 @@
     "scripts/paper-work-fleet-cli.mjs",
     "scripts/run-lifecycle-core.mjs",
     "scripts/resolve-artifact-transfer-mode.mjs",
+    "scripts/resolve-build-summary-names.sh",
     "scripts/release-propagation.mjs",
     "scripts/engineering-housekeeper-workflow.mjs",
     "scripts/release-tail.mjs",
@@ -75,6 +76,7 @@
     "packages/core/dev-delivery-warrant.js",
     "packages/core/dev-delivery-warrant-state.js",
     "packages/core/dev-delivery-warrant-qualification.js",
+    "packages/core/dev-delivery-warrant-legacy-recovery.js",
     "packages/core/dev-delivery-native-proof.js",
     "packages/core/dev-delivery-native-execution.js",
     "packages/core/dev-delivery-execution-failure.js",
@@ -129,9 +131,17 @@
     "packages/core/published-delivery-authority.js",
     "packages/core/v4-adopter-delivery.js",
     "packages/core/v4-adopter-delivery-parity.js",
+    "packages/core/v4-cross-platform-adopter-qualification.js",
+    "scripts/v4-cross-platform-adopter-qualification.mjs",
     "crates/buildchain-v4-contracts/src/adopter_delivery.rs",
     "crates/buildchain-v4-contracts/src/compatibility_facts.rs",
-    "crates/buildchain-v4-contracts/src/compatibility_facts"
+    "crates/buildchain-v4-contracts/src/compatibility_facts",
+    "scripts/check-internal-architecture.mjs",
+    "scripts/check-maintainability.mjs",
+    "scripts/maintainability-metrics.mjs",
+    "scripts/generate-agent-change-map.mjs",
+    "scripts/maintainability-domain-metrics.mjs",
+    "scripts/maintainability-governance.mjs"
   ],
   "ownershipRules": [
     {
@@ -209,13 +219,16 @@
       "contracts": [
         "actions/promote-buildchain-ref/action.yml",
         "actions/promote-buildchain-ref/lib.js"
+      ],
+      "generatedOutputs": ["actions/promote-buildchain-ref/dist/index.js"],
+      "validationCommands": [
+        "node --test tests/promote-buildchain-ref.test.mjs tests/promote-buildchain-ref-governance.test.mjs tests/promotion-responsibilities.test.mjs"
       ]
     },
     {
       "id": "promotion-version-state",
       "owner": "Buildchain maintainers",
       "implementation": [
-        "actions/promote-buildchain-ref/internal/existing-version-state.js",
         "actions/promote-buildchain-ref/internal/version-state.js",
         "actions/promote-buildchain-ref/internal/version-state-operations.js"
       ],
@@ -227,6 +240,10 @@
       "contracts": [
         ".buildchain/release-impact.json",
         "actions/promote-buildchain-ref/lib.js"
+      ],
+      "generatedOutputs": ["actions/promote-buildchain-ref/dist/index.js"],
+      "validationCommands": [
+        "node --test tests/promote-buildchain-ref.test.mjs tests/promote-buildchain-ref-recovery.test.mjs tests/release-impact-contract.test.mjs"
       ]
     },
     {
@@ -235,14 +252,19 @@
       "implementation": [
         "actions/promote-buildchain-ref/internal/durable-transaction-store.js",
         "actions/promote-buildchain-ref/internal/durable-transaction-operations.js",
-        "actions/promote-buildchain-ref/internal/github-adapter.js"
+        "actions/promote-buildchain-ref/internal/github-adapter.js",
+        "actions/promote-buildchain-ref/internal/promotion-operations.js"
       ],
       "tests": [
         "tests/promote-buildchain-ref.test.mjs",
         "tests/promote-buildchain-ref-recovery.test.mjs",
         "tests/promotion-responsibilities.test.mjs"
       ],
-      "contracts": ["actions/promote-buildchain-ref/lib.js"]
+      "contracts": ["actions/promote-buildchain-ref/lib.js"],
+      "generatedOutputs": ["actions/promote-buildchain-ref/dist/index.js"],
+      "validationCommands": [
+        "node --test tests/promote-buildchain-ref.test.mjs tests/promote-buildchain-ref-recovery.test.mjs tests/promotion-responsibilities.test.mjs"
+      ]
     },
     {
       "id": "promotion-channel-orchestration",
@@ -261,6 +283,10 @@
       "contracts": [
         "actions/promote-buildchain-ref/action.yml",
         "actions/promote-buildchain-ref/lib.js"
+      ],
+      "generatedOutputs": ["actions/promote-buildchain-ref/dist/index.js"],
+      "validationCommands": [
+        "node --test tests/promote-buildchain-ref.test.mjs tests/promote-buildchain-ref-recovery.test.mjs tests/promote-buildchain-ref-governance.test.mjs tests/promotion-responsibilities.test.mjs"
       ]
     },
     {
@@ -275,7 +301,11 @@
         "bin/internal/trust-release-verification-handlers.mjs"
       ],
       "tests": ["tests/cli.test.mjs", "tests/public-surface-audit.test.mjs"],
-      "contracts": ["bin/buildchain.mjs", "docs/cli.md"]
+      "contracts": ["bin/buildchain.mjs", "docs/cli.md"],
+      "generatedOutputs": [],
+      "validationCommands": [
+        "node --test tests/cli.test.mjs tests/public-surface-audit.test.mjs"
+      ]
     },
     {
       "id": "release-workflow-promotion-routing",
@@ -292,6 +322,10 @@
       "contracts": [
         ".github/workflows/.release-candidate-promote.yml",
         ".github/workflows/release-candidate-promote.yml"
+      ],
+      "generatedOutputs": [".github/workflows/release-candidate-promote.yml"],
+      "validationCommands": [
+        "node --test tests/promotion-routing-evidence.test.mjs tests/build-surface.test.mjs tests/build-surface-promotion.test.mjs"
       ]
     },
     {
@@ -305,6 +339,10 @@
       "contracts": [
         "docs/release-passport.md",
         "dist/site/release-passport-check-manifest.json"
+      ],
+      "generatedOutputs": ["dist/site/release-passport-check-manifest.json"],
+      "validationCommands": [
+        "node --test tests/release-passport.test.mjs tests/release-passport-contract.test.mjs"
       ]
     },
     {
@@ -315,7 +353,11 @@
         "bin/internal/command-registry.mjs"
       ],
       "tests": ["tests/command-registry.test.mjs", "tests/cli.test.mjs"],
-      "contracts": ["docs/cli.md", "dist/site/cli-registry.json"]
+      "contracts": ["docs/cli.md", "dist/site/cli-registry.json"],
+      "generatedOutputs": ["dist/site/cli-registry.json"],
+      "validationCommands": [
+        "node --test tests/command-registry.test.mjs tests/cli.test.mjs"
+      ]
     },
     {
       "id": "reusable-build-orchestration",
@@ -323,10 +365,13 @@
       "implementation": [
         "scripts/generate-channel-build-workflow.mjs",
         "scripts/resolve-artifact-transfer-mode.mjs",
+        "scripts/resolve-build-summary-names.sh",
         "scripts/run-lifecycle-core.mjs"
       ],
       "tests": [
         "tests/artifact-transfer-mode.test.mjs",
+        "tests/resolve-build-summary-names.test.mjs",
+        "tests/build-surface-reusable-build-artifacts.test.mjs",
         "tests/build-surface.test.mjs",
         "tests/build-surface-promotion.test.mjs",
         "tests/controller-evidence.test.mjs"
@@ -334,6 +379,13 @@
       "contracts": [
         ".github/workflows/.build.yml",
         ".github/workflows/build.yml"
+      ],
+      "generatedOutputs": [
+        ".github/workflows/build.yml",
+        "actions/run-lifecycle/dist/index.js"
+      ],
+      "validationCommands": [
+        "node --test tests/artifact-transfer-mode.test.mjs tests/resolve-build-summary-names.test.mjs tests/build-surface-reusable-build-artifacts.test.mjs tests/build-surface.test.mjs tests/build-surface-promotion.test.mjs tests/controller-evidence.test.mjs"
       ]
     },
     {
@@ -348,7 +400,11 @@
         "tests/web-surface.test.mjs",
         "tests/web-surface-publication-authority.test.mjs"
       ],
-      "contracts": [".github/workflows/.web-surface.yml"]
+      "contracts": [".github/workflows/.web-surface.yml"],
+      "generatedOutputs": [],
+      "validationCommands": [
+        "node --test tests/web-surface.test.mjs tests/web-surface-publication-authority.test.mjs"
+      ]
     },
     {
       "id": "shared-build-contract",
@@ -365,6 +421,10 @@
       "contracts": [
         "dist/site/buildchain-contract.json",
         "docs/runtime-train-validation.md"
+      ],
+      "generatedOutputs": ["dist/site/buildchain-contract.json"],
+      "validationCommands": [
+        "node --test tests/buildchain-contract.test.mjs tests/build-surface.test.mjs tests/build-surface-promotion.test.mjs"
       ]
     },
     {
@@ -379,14 +439,22 @@
         "tests/workflow-call-contract.test.mjs",
         "tests/public-surface-audit.test.mjs"
       ],
-      "contracts": ["docs/release-governance.md"]
+      "contracts": ["docs/release-governance.md"],
+      "generatedOutputs": [],
+      "validationCommands": [
+        "node --test tests/workflow-call-contract.test.mjs tests/public-surface-audit.test.mjs"
+      ]
     },
     {
       "id": "promotion-runtime-override-authorization",
       "owner": "Buildchain release governance maintainers",
       "implementation": ["scripts/authorize-promotion-runtime-override.cjs"],
       "tests": ["tests/authorize-promotion-runtime-override.test.mjs"],
-      "contracts": [".github/workflows/release-candidate-promote.yml"]
+      "contracts": [".github/workflows/release-candidate-promote.yml"],
+      "generatedOutputs": [],
+      "validationCommands": [
+        "node --test tests/authorize-promotion-runtime-override.test.mjs"
+      ]
     },
     {
       "id": "paper-fleet-golden-path",
@@ -411,6 +479,13 @@
       "contracts": [
         "dist/site/cli-registry.json",
         "dist/site/node-api-registry.json"
+      ],
+      "generatedOutputs": [
+        "dist/site/cli-registry.json",
+        "dist/site/node-api-registry.json"
+      ],
+      "validationCommands": [
+        "node --test tests/cli.test.mjs tests/paper.test.mjs tests/public-surface-audit.test.mjs"
       ]
     },
     {
@@ -431,6 +506,13 @@
         "docs/release-propagation.md",
         "dist/site/cli-registry.json",
         "dist/site/node-api-registry.json"
+      ],
+      "generatedOutputs": [
+        "dist/site/cli-registry.json",
+        "dist/site/node-api-registry.json"
+      ],
+      "validationCommands": [
+        "node --test tests/release-propagation.test.mjs tests/release-propagation-pickup.test.mjs"
       ]
     },
     {
@@ -451,6 +533,10 @@
         "contracts/engineering-housekeeper-v1.schema.json",
         "contracts/fixtures/engineering-housekeeper-v1/cases.json",
         "docs/engineering-housekeeper.md"
+      ],
+      "generatedOutputs": [],
+      "validationCommands": [
+        "node --test tests/engineering-housekeeper.test.mjs tests/engineering-housekeeper-github.test.mjs tests/engineering-housekeeper-workflow.test.mjs"
       ]
     },
     {
@@ -473,6 +559,10 @@
         ".github/workflows/release-tail.yml",
         "actions/release-tail/action.yml",
         "docs/release-tail-provider-plane.md"
+      ],
+      "generatedOutputs": ["actions/release-tail/dist/index.js"],
+      "validationCommands": [
+        "node --test tests/release-tail-provider-plane.test.mjs tests/release-tail-contract.test.mjs"
       ]
     },
     {
@@ -489,6 +579,10 @@
         "contracts/v4-publication-rehearsal-capsule-v1.schema.json",
         ".github/workflows/v4-publication-rehearsal-dogfood.yml",
         "docs/v4-publication-rehearsal.md"
+      ],
+      "generatedOutputs": [],
+      "validationCommands": [
+        "node --test tests/v4-publication-rehearsal.test.mjs"
       ]
     },
     {
@@ -498,6 +592,7 @@
         "packages/core/dev-delivery-warrant.js",
         "packages/core/dev-delivery-warrant-state.js",
         "packages/core/dev-delivery-warrant-qualification.js",
+        "packages/core/dev-delivery-warrant-legacy-recovery.js",
         "packages/core/dev-delivery-native-proof.js",
         "packages/core/dev-delivery-native-execution.js",
         "packages/core/dev-delivery-execution-failure.js",
@@ -531,6 +626,7 @@
       "tests": [
         "tests/dev-delivery-warrant.test.mjs",
         "tests/dev-delivery-warrant-command.test.mjs",
+        "tests/dev-delivery-warrant-legacy-recovery.test.mjs",
         "tests/dev-delivery-two-phase.test.mjs",
         "tests/dev-delivery-two-phase-run.test.mjs",
         "tests/dev-delivery-native-run.test.mjs",
@@ -551,6 +647,12 @@
         "templates/native-dev-delivery.yml",
         "docs/dev-delivery-warrant.md",
         "docs/dev-delivery-qualification-landing-adr.md"
+      ],
+      "generatedOutputs": [
+        "dist/site/schemas/dev-delivery-authority-v2.schema.json"
+      ],
+      "validationCommands": [
+        "node --test tests/dev-delivery-warrant.test.mjs tests/dev-delivery-warrant-command.test.mjs tests/dev-delivery-warrant-legacy-recovery.test.mjs tests/dev-delivery-two-phase.test.mjs tests/dev-delivery-two-phase-run.test.mjs tests/dev-delivery-native-run.test.mjs tests/dev-delivery-process-boundary.test.mjs tests/dev-delivery-process-boundary-negative.test.mjs tests/dev-delivery-provider-heartbeat.test.mjs tests/dev-delivery-authority.test.mjs tests/build-surface.test.mjs tests/v4-delivery-authority-parity.test.mjs"
       ]
     },
     {
@@ -575,6 +677,12 @@
         "contracts/fixtures/v4-compatibility-facts-v1/shared.json",
         "dist/site/schemas/v4-compatibility-facts-v1.schema.json",
         "docs/v4-compatibility-facts.md"
+      ],
+      "generatedOutputs": [
+        "dist/site/schemas/v4-compatibility-facts-v1.schema.json"
+      ],
+      "validationCommands": [
+        "node --test tests/v4-compatibility-facts.test.mjs"
       ]
     },
     {
@@ -593,14 +701,19 @@
         "packages/core/published-delivery-authority.js",
         "packages/core/v4-adopter-delivery.js",
         "packages/core/v4-adopter-delivery-parity.js",
+        "packages/core/v4-cross-platform-adopter-qualification.js",
+        "scripts/v4-cross-platform-adopter-qualification.mjs",
         "crates/buildchain-v4-contracts/src/adopter_delivery.rs"
       ],
       "tests": [
         "tests/v4-adopter-delivery.test.mjs",
-        "tests/v4-adopter-delivery-parity.test.mjs"
+        "tests/v4-adopter-delivery-parity.test.mjs",
+        "tests/v4-cross-platform-adopter-qualification.test.mjs",
+        "tests/non-kfd-specification-driver-clean-room.test.mjs"
       ],
       "contracts": [
         "architecture/v4-adopter-delivery-parity.json",
+        "architecture/v4-cross-platform-adopter-qualification.json",
         "contracts/v4-adopter-delivery-v1.schema.json",
         "contracts/fixtures/v4-adopter-delivery-v1/archive-template.json",
         "contracts/fixtures/v4-adopter-delivery-v1/bootstrap-positive.json",
@@ -610,6 +723,10 @@
         ".github/workflows/v4-adopter-delivery.yml",
         ".github/workflows/v4-adopter-delivery-dogfood.yml",
         "docs/v4-adopter-delivery.md"
+      ],
+      "generatedOutputs": [],
+      "validationCommands": [
+        "node --test tests/v4-adopter-delivery.test.mjs tests/v4-adopter-delivery-parity.test.mjs tests/v4-cross-platform-adopter-qualification.test.mjs tests/non-kfd-specification-driver-clean-room.test.mjs"
       ]
     },
     {
@@ -708,6 +825,37 @@
         "docs/v4-stage-capsule.md",
         "docs/v4-runtime-ref-resume-authority.md",
         "docs/v4-tail-reseal.md"
+      ],
+      "generatedOutputs": [],
+      "validationCommands": [
+        "node --test tests/v4-architecture.test.mjs tests/v4-bridge.test.mjs tests/v4-provider-operation-journal.test.mjs tests/v4-provider-readback-idempotency.test.mjs tests/v4-release-activation-shadow.test.mjs tests/v4-stable-publication-fence.test.mjs tests/v4-partial-mutation-recovery-qualification.test.mjs tests/v4-stage-capsule.test.mjs tests/v4-stage-capsule-store.test.mjs tests/v4-platform-stage-checkpoints.test.mjs tests/v4-stage-capsule-qualification.test.mjs tests/v4-runtime-ref-resume-authority.test.mjs tests/v4-tail-reseal.test.mjs tests/v4-tail-reseal-parity.test.mjs"
+      ]
+    },
+    {
+      "id": "maintainability-governance",
+      "owner": "Buildchain architecture maintainers",
+      "implementation": [
+        "scripts/check-internal-architecture.mjs",
+        "scripts/check-maintainability.mjs",
+        "scripts/maintainability-metrics.mjs",
+        "scripts/generate-agent-change-map.mjs",
+        "scripts/maintainability-domain-metrics.mjs",
+        "scripts/maintainability-governance.mjs"
+      ],
+      "tests": [
+        "tests/internal-architecture.test.mjs",
+        "tests/maintainability.test.mjs",
+        "tests/maintainability-governance.test.mjs"
+      ],
+      "contracts": [
+        "architecture/internal-capabilities.json",
+        "architecture/maintainability-debt.json",
+        "architecture/maintainability-policy.json"
+      ],
+      "generatedOutputs": ["architecture/agent-change-map.md"],
+      "validationCommands": [
+        "node --test tests/internal-architecture.test.mjs tests/maintainability.test.mjs tests/maintainability-governance.test.mjs",
+        "node scripts/generate-agent-change-map.mjs"
       ]
     }
   ]