@kungfu-tech/buildchain 3.0.9-alpha.8 → 4.0.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (255) hide show
  1. package/AGENTS.md +39 -0
  2. package/README.md +17 -13
  3. package/actions/promote-buildchain-ref/README.md +0 -10
  4. package/actions/release-tail/README.md +6 -10
  5. package/architecture/internal-capabilities.json +502 -0
  6. package/architecture/maintainability-baseline.json +59 -0
  7. package/architecture/maintainability-policy.json +1384 -0
  8. package/architecture/release-tail-contract-inventory.json +587 -0
  9. package/architecture/v3-core-mechanism-inventory.json +1043 -0
  10. package/architecture/v3-core-mechanism-inventory.md +67 -0
  11. package/architecture/v4-adopter-delivery-parity.json +47 -0
  12. package/architecture/v4-architecture-constitution.md +210 -0
  13. package/architecture/v4-bootstrap-authority.json +56 -0
  14. package/architecture/v4-canonical-contract-fixtures.json +105 -0
  15. package/architecture/v4-capability-state-machine-manifest.json +480 -0
  16. package/architecture/v4-capability-state-machine-manifest.schema.json +202 -0
  17. package/architecture/v4-delivery-warrant-shadow-bootstrap-plan.json +830 -0
  18. package/architecture/v4-delivery-warrant-shadow-bootstrap-plan.md +223 -0
  19. package/architecture/v4-delivery-warrant-shadow-bootstrap-plan.schema.json +318 -0
  20. package/architecture/v4-delivery-warrant-shadow-fixtures.json +227 -0
  21. package/architecture/v4-delivery-warrant-shadow-fixtures.schema.json +67 -0
  22. package/architecture/v4-exception-ledger.json +5 -0
  23. package/architecture/v4-exception-ledger.schema.json +56 -0
  24. package/architecture/v4-partial-mutation-recovery-qualification.json +65 -0
  25. package/architecture/v4-platform-stage-checkpoints.json +97 -0
  26. package/architecture/v4-provider-operation-journal-contract.json +113 -0
  27. package/architecture/v4-release-activation-shadow-domain.json +61 -0
  28. package/architecture/v4-release-train-parity.json +68 -0
  29. package/architecture/v4-rust-libnode-bridge-evaluation.json +107 -0
  30. package/architecture/v4-rust-libnode-bridge-spike.md +85 -0
  31. package/architecture/v4-stable-publication-fence.json +66 -0
  32. package/architecture/v4-stage-capsule-contract.json +90 -0
  33. package/architecture/v4-stage-capsule-qualification.json +99 -0
  34. package/architecture/v4-stage-capsule-resume-planner.json +52 -0
  35. package/architecture/v4-stage-capsule-store-contract.json +72 -0
  36. package/bin/buildchain.mjs +15 -6
  37. package/contracts/auditable-demo-scenario-v1.schema.json +1 -1
  38. package/contracts/buildchain-v2-residuals-v1.json +2 -2
  39. package/contracts/fixtures/v4-delivery-warrant-trace-v1/golden.json +158 -0
  40. package/contracts/fixtures/v4-delivery-warrant-trace-v1/property.json +380 -0
  41. package/contracts/fixtures/v4-delivery-warrant-trace-v1/replay.json +163 -0
  42. package/contracts/fixtures/v4-partial-mutation-recovery-v1/shared.json +155 -0
  43. package/contracts/fixtures/v4-provider-operation-journal-v1/shared.json +457 -0
  44. package/contracts/fixtures/v4-provider-readback-idempotency-v1/shared.json +682 -0
  45. package/contracts/fixtures/v4-release-activation-shadow-v1/shared.json +53 -0
  46. package/contracts/fixtures/v4-stable-publication-fence-v1/shared.json +56 -0
  47. package/contracts/fixtures/v4-stage-capsule-resume-v1/late-platform-failure.json +176 -0
  48. package/contracts/fixtures/v4-stage-capsule-store-v1/shared.json +132 -0
  49. package/contracts/fixtures/v4-stage-capsule-v1/shared.json +111 -0
  50. package/contracts/v4-canonical-contracts-v1.schema.json +182 -0
  51. package/contracts/v4-delivery-warrant-semantic-diff-report-v1.schema.json +284 -0
  52. package/contracts/v4-delivery-warrant-trace-v1.schema.json +215 -0
  53. package/contracts/v4-host-contract-v1.schema.json +135 -0
  54. package/contracts/v4-partial-mutation-recovery-v1.schema.json +168 -0
  55. package/contracts/v4-provider-operation-journal-v1.schema.json +381 -0
  56. package/contracts/v4-release-activation-shadow-v1.schema.json +186 -0
  57. package/contracts/v4-stable-publication-fence-v1.schema.json +125 -0
  58. package/contracts/v4-stage-capsule-resume-v1.schema.json +225 -0
  59. package/contracts/v4-stage-capsule-store-v1.schema.json +154 -0
  60. package/contracts/v4-stage-capsule-v1.schema.json +178 -0
  61. package/crates/buildchain-v4-bridge/Cargo.lock +213 -0
  62. package/crates/buildchain-v4-bridge/Cargo.toml +12 -0
  63. package/crates/buildchain-v4-bridge/src/main.rs +495 -0
  64. package/dist/site/agent-index.json +0 -3
  65. package/dist/site/artifact-schemas.json +0 -6
  66. package/dist/site/buildchain-contract.json +103 -397
  67. package/dist/site/buildchain-site.json +302 -270
  68. package/dist/site/capability-registry.json +9 -11
  69. package/dist/site/cli-registry.json +8 -30
  70. package/dist/site/controller-registry.json +48 -8
  71. package/dist/site/kfd-claims.json +129 -142
  72. package/dist/site/kfd-upstream-aggregate.json +9 -9
  73. package/dist/site/manual-registry.json +18 -49
  74. package/dist/site/node-api-registry.json +1882 -4118
  75. package/dist/site/page-registry.json +278 -230
  76. package/dist/site/public-surface-audit.json +87 -185
  77. package/dist/site/publication-authority-registry.json +11 -1
  78. package/dist/site/publication-registry.json +4 -4
  79. package/dist/site/release-provenance.json +3 -7
  80. package/dist/site/schemas/kfd-support-projection-v1.schema.json +106 -0
  81. package/dist/site/site-manifest.json +22 -38
  82. package/dist/site/workflow-registry.json +80 -35
  83. package/docs/MAP.md +8 -4
  84. package/docs/auditable-demo.md +2 -2
  85. package/docs/aws-us-elastic-runner-burst-plane.md +7 -59
  86. package/docs/cli-reference.md +15 -92
  87. package/docs/cli.md +14 -14
  88. package/docs/dev-alpha-candidate-patrol.md +3 -11
  89. package/docs/dev-delivery-warrant.md +28 -100
  90. package/docs/engineering-housekeeper.md +12 -4
  91. package/docs/getting-started.md +1 -1
  92. package/docs/install.md +5 -5
  93. package/docs/kfd-support.md +2 -7
  94. package/docs/lifecycle-protocol.md +2 -4
  95. package/docs/node-api-reference.md +414 -523
  96. package/docs/release-flow.md +31 -31
  97. package/docs/release-governance.md +16 -28
  98. package/docs/release-passport.md +2 -15
  99. package/docs/release-tail-contract.md +13 -6
  100. package/docs/release-tail-provider-plane.md +13 -19
  101. package/docs/release-train.md +4 -4
  102. package/docs/reusable-build-surface.md +14 -27
  103. package/docs/site-bundle-contract.md +1 -5
  104. package/docs/stable-candidate-patrol.md +7 -7
  105. package/docs/v4-canonical-contracts.md +92 -0
  106. package/docs/v4-delivery-warrant-read-candidate.md +73 -0
  107. package/docs/v4-delivery-warrant-semantic-diff.md +75 -0
  108. package/docs/v4-production-release.md +63 -0
  109. package/docs/v4-stage-capsule.md +193 -0
  110. package/docs/versioning.md +3 -3
  111. package/package.json +19 -17
  112. package/packages/core/adopter-delivery-gate.js +576 -0
  113. package/packages/core/adopter-delivery-json.js +66 -0
  114. package/packages/core/artifact-signing.js +0 -61
  115. package/packages/core/artifact-verification-envelope.js +5 -5
  116. package/packages/core/build-facts.js +12 -4
  117. package/packages/core/buildchain-agent-manuals.js +0 -2
  118. package/packages/core/buildchain-config.js +4 -69
  119. package/packages/core/buildchain-contract.js +232 -46
  120. package/packages/core/buildchain-kfd-claims.js +1 -1
  121. package/packages/core/channel-candidate.js +0 -8
  122. package/packages/core/channel-promotion-baseline.js +0 -52
  123. package/packages/core/controller-evidence.js +3 -4
  124. package/packages/core/dev-alpha-candidate-selection.js +2 -10
  125. package/packages/core/dev-delivery-warrant-cancellation.js +0 -1
  126. package/packages/core/dev-delivery-warrant-settlement.js +1 -5
  127. package/packages/core/dev-delivery-warrant.js +12 -52
  128. package/packages/core/diagnostics.js +3 -8
  129. package/packages/core/github-governance-authority.js +3 -1
  130. package/packages/core/kfd-adopter-category-driver.js +167 -0
  131. package/packages/core/kfd-adopter-manifest.js +47 -46
  132. package/packages/core/kfd-gate.js +15 -45
  133. package/packages/core/paper-agent-entry.js +7 -16
  134. package/packages/core/paper-fleet.js +2 -2
  135. package/packages/core/paper-repository.js +2 -3
  136. package/packages/core/paper-scaffold-content.js +2 -23
  137. package/packages/core/paper.js +11 -43
  138. package/packages/core/publication-reproducibility.js +4 -4
  139. package/packages/core/release-line-bootstrap.js +21 -8
  140. package/packages/core/release-passport-contract.js +5 -5
  141. package/packages/core/release-passport.js +20 -131
  142. package/packages/core/self-dogfood-version.js +48 -35
  143. package/packages/core/spawn-command.js +232 -8
  144. package/packages/core/v4-adopter-delivery-parity.js +219 -0
  145. package/packages/core/v4-canonical-contracts.js +284 -0
  146. package/packages/core/v4-delivery-warrant-fixture-runner.js +371 -0
  147. package/packages/core/v4-delivery-warrant-read-candidate.js +279 -0
  148. package/packages/core/v4-delivery-warrant-semantic-diff-gate.js +352 -0
  149. package/packages/core/v4-delivery-warrant-shadow-adapter.js +447 -0
  150. package/packages/core/v4-partial-mutation-recovery-qualification.js +395 -0
  151. package/packages/core/v4-platform-stage-checkpoints.js +471 -0
  152. package/packages/core/v4-provider-operation-journal.js +531 -0
  153. package/packages/core/v4-provider-readback-idempotency.js +394 -0
  154. package/packages/core/v4-release-activation-shadow.js +519 -0
  155. package/packages/core/v4-stable-publication-fence.js +357 -0
  156. package/packages/core/v4-stage-capsule-local-store.js +426 -0
  157. package/packages/core/v4-stage-capsule-qualification-campaign.js +512 -0
  158. package/packages/core/v4-stage-capsule-qualification.js +456 -0
  159. package/packages/core/v4-stage-capsule-resume-planner.js +397 -0
  160. package/packages/core/v4-stage-capsule-store.js +401 -0
  161. package/packages/core/v4-stage-capsule.js +319 -0
  162. package/scripts/assemble-self-publication-admission.mjs +1 -1
  163. package/scripts/audit-publication-control-plane.mjs +5 -5
  164. package/scripts/auditable-demo-bundle-verification.mjs +3 -2
  165. package/scripts/auditable-demo-platform.mjs +2 -2
  166. package/scripts/auditable-demo-renditions.mjs +1 -1
  167. package/scripts/auditable-demo.mjs +2 -2
  168. package/scripts/aws-macos-jit-controller-core.mjs +13 -346
  169. package/scripts/aws-macos-jit-controller-runtime.mjs +2 -210
  170. package/scripts/aws-macos-jit-controller.mjs +37 -275
  171. package/scripts/aws-macos-jit-core.mjs +3 -41
  172. package/scripts/aws-macos-jit.mjs +0 -12
  173. package/scripts/aws-windows-jit-campaign.mjs +2 -2
  174. package/scripts/aws-windows-jit-controller-core.mjs +1 -1
  175. package/scripts/aws-windows-jit-controller.mjs +3 -3
  176. package/scripts/build-contract-core.mjs +3 -8
  177. package/scripts/build-standalone-binary.mjs +3 -14
  178. package/scripts/buildchain-channel-router.mjs +4 -0
  179. package/scripts/buildchain-cli-help.mjs +7 -13
  180. package/scripts/buildchain-contract-lock.mjs +0 -6
  181. package/scripts/check-action-bundles.mjs +3 -4
  182. package/scripts/check-internal-architecture.mjs +7 -6
  183. package/scripts/check-inventory.mjs +30 -25
  184. package/scripts/check-v4-public-dogfood-contract.mjs +270 -0
  185. package/scripts/create-release-bundle.mjs +8 -4
  186. package/scripts/dev-alpha-candidate-patrol.mjs +1 -22
  187. package/scripts/dev-delivery-proof.mjs +2 -54
  188. package/scripts/dev-delivery-warrant.mjs +59 -77
  189. package/scripts/dev-pr-auto-merge.mjs +4 -30
  190. package/scripts/dev-pr-delivery-warrant.mjs +0 -55
  191. package/scripts/dispatch-artifact-signing-authority.mjs +7 -4
  192. package/scripts/generate-buildchain-kfd-witnesses.mjs +94 -88
  193. package/scripts/generate-channel-build-workflow.mjs +54 -24
  194. package/scripts/generate-channel-promotion-workflow.mjs +15 -6
  195. package/scripts/generate-site-bundle.mjs +5 -21
  196. package/scripts/git-fetch-process-tree.mjs +34 -1
  197. package/scripts/init-repo.mjs +64 -159
  198. package/scripts/inspect-artifact-signing-requests.mjs +0 -6
  199. package/scripts/locked-source-checkout.mjs +3 -4
  200. package/scripts/maintainability-metrics.mjs +8 -2
  201. package/scripts/npm-publish-dry-run.mjs +2 -2
  202. package/scripts/npm-publish-transaction.mjs +2 -2
  203. package/scripts/publication-commit-evidence.mjs +23 -69
  204. package/scripts/release-candidate-resolver.mjs +11 -17
  205. package/scripts/release-tail.mjs +3 -49
  206. package/scripts/resume-from-candidate-run.mjs +9 -123
  207. package/scripts/run-lifecycle-core.mjs +12 -13
  208. package/scripts/seal-artifact-signing-requests.mjs +17 -21
  209. package/scripts/site-capability-metadata.mjs +2 -7
  210. package/scripts/stable-candidate-qualification.mjs +10 -10
  211. package/scripts/v4-architecture.mjs +12 -2
  212. package/scripts/v4-bridge-bootstrap.mjs +141 -0
  213. package/scripts/v4-bridge-evidence.mjs +141 -0
  214. package/scripts/v4-host-adapter.mjs +182 -0
  215. package/scripts/v4-platform-stage-checkpoint-rehearsal.mjs +207 -0
  216. package/scripts/v4-stage-capsule-qualification.mjs +528 -0
  217. package/scripts/v4-stage-capsule-resume-rehearsal.mjs +57 -0
  218. package/scripts/v4-warrant-shadow-plan.mjs +601 -0
  219. package/scripts/verify-golden-path.mjs +5 -5
  220. package/scripts/web-surface-cloudfront-rewrite.mjs +15 -15
  221. package/scripts/web-surface-core.mjs +2 -8
  222. package/scripts/workflow-call-contract.mjs +5 -184
  223. package/contracts/fixtures/kfd-adopter-release-v1/kfd-4-perspective.json +0 -16
  224. package/contracts/fixtures/kfd-adopter-release-v1/kfd-4-replay.json +0 -57
  225. package/contracts/fixtures/next-development-transition-v1/anchored-manual-waiting.json +0 -47
  226. package/contracts/fixtures/next-development-transition-v1/semver-auto-planned.json +0 -47
  227. package/contracts/fixtures/next-development-transition-v1/version-model-cases.json +0 -40
  228. package/contracts/next-development-request-v1.schema.json +0 -66
  229. package/contracts/next-development-transition-v1.schema.json +0 -292
  230. package/contracts/publication-rehearsal-capsule-v1.schema.json +0 -173
  231. package/dist/site/schemas/publication-rehearsal-capsule-v1.schema.json +0 -269
  232. package/dist/site/schemas/release-tail-capabilities-v1.schema.json +0 -353
  233. package/dist/site/schemas/release-tail-provider-bindings-v1.schema.json +0 -94
  234. package/docs/next-development-transition.md +0 -119
  235. package/docs/publication-rehearsal.md +0 -94
  236. package/packages/core/buildchain-compatibility-proof.js +0 -631
  237. package/packages/core/dev-delivery-native-proof.js +0 -333
  238. package/packages/core/dev-delivery-warrant-shadow.js +0 -502
  239. package/packages/core/next-development-candidate-reservation.js +0 -186
  240. package/packages/core/next-development-controller.js +0 -726
  241. package/packages/core/next-development-projection.js +0 -288
  242. package/packages/core/next-development-transition.js +0 -738
  243. package/packages/core/publication-rehearsal-projection.js +0 -173
  244. package/packages/core/publication-rehearsal-runtime.js +0 -921
  245. package/scripts/aws-macos-jit-instance-rehydrate.mjs +0 -260
  246. package/scripts/aws-macos-jit-source-rebind.mjs +0 -724
  247. package/scripts/dev-delivery-native-run.mjs +0 -187
  248. package/scripts/dev-delivery-two-phase.mjs +0 -598
  249. package/scripts/generate-next-development-guidance.mjs +0 -49
  250. package/scripts/materialize-self-release-candidate-version.mjs +0 -137
  251. package/scripts/next-development-self-dogfood-harness.mjs +0 -409
  252. package/scripts/next-development-self-dogfood.mjs +0 -532
  253. package/scripts/next-development-transition.mjs +0 -47
  254. package/scripts/release-candidate-tail-reseal.mjs +0 -426
  255. package/templates/native-dev-delivery.yml +0 -82
@@ -0,0 +1,61 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "contract": "kungfu-buildchain-v4-release-activation-production-architecture",
4
+ "schemaAuthority": "contracts/v4-release-activation-shadow-v1.schema.json",
5
+ "fixtureAuthority": "contracts/fixtures/v4-release-activation-shadow-v1/shared.json",
6
+ "journalAuthority": "architecture/v4-provider-operation-journal-contract.json",
7
+ "mode": "production",
8
+ "authority": {
9
+ "productionWriter": "v4-domain",
10
+ "productionWriterCount": 1,
11
+ "planAndFoldAuthority": "rust-v4-core",
12
+ "planAndFoldWriterCount": 1,
13
+ "typescript": "byte-equivalent-provider-adapter",
14
+ "productionWriteChange": true
15
+ },
16
+ "implementations": {
17
+ "rustDomain": "crates/buildchain-v4-contracts/src/release_activation_shadow.rs",
18
+ "rustModel": "crates/buildchain-v4-contracts/src/release_activation_shadow/model.rs",
19
+ "rustJournalMaterializer": "crates/buildchain-v4-contracts/src/release_activation_shadow/journal.rs",
20
+ "typescript": "packages/core/v4-release-activation-shadow.js"
21
+ },
22
+ "roots": [
23
+ "release-activation-step",
24
+ "release-activation-plan",
25
+ "release-activation-state"
26
+ ],
27
+ "resumePolicy": {
28
+ "confirmed": "never-replay",
29
+ "attempting": "readback-before-any-retry",
30
+ "observed": "readback-before-any-retry",
31
+ "confirmable": "readback-before-any-retry",
32
+ "planned": "eligible-only-after-confirmed-dependencies",
33
+ "retryable": "eligible-only-after-confirmed-dependencies",
34
+ "rejected": "block-plan",
35
+ "terminal": "block-plan"
36
+ },
37
+ "foldRejects": [
38
+ "missing-qualification",
39
+ "dependency-cycle",
40
+ "unknown-or-self-dependency",
41
+ "logical-operation-conflict",
42
+ "coordinate-or-authority-mismatch",
43
+ "conflicting-event-ordinal",
44
+ "event-ordinal-gap",
45
+ "provider-journal-impossible-transition"
46
+ ],
47
+ "budgets": {
48
+ "schemaAuthorities": 1,
49
+ "planAndFoldWriters": 1,
50
+ "secondStateFoldWriters": 0,
51
+ "providerSdkImportsInContracts": 0,
52
+ "providerSdkImportsInRustDomain": 0,
53
+ "liveProviderMutations": 0,
54
+ "productionWriteAuthorityChanges": 1,
55
+ "v3ConsumerBehaviorChanges": 0
56
+ },
57
+ "successors": [
58
+ "stable-candidate-publication-fencing-shadow",
59
+ "partial-mutation-recovery-qualification"
60
+ ]
61
+ }
@@ -0,0 +1,68 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "contract": "kungfu-buildchain-v4-release-train-parity",
4
+ "sourceAuthority": {
5
+ "branch": "dev/v3/v3.0",
6
+ "familyStateRoot": "sha256:212c90214e34f41de5720452c048f342ecfd04f31e732491b51069ae52ff61f9",
7
+ "portableSealRoot": "sha256:dbdaa70e23bd853d865ff0c90aefa6f74bb8e043feab4faac1d486381e116261",
8
+ "commits": [
9
+ "71bf3f64f4766a339592ca35463800be19fdec2d",
10
+ "81455e922eb50ebbb88ac6c1fb6c051047ba36ad",
11
+ "ce1ca498f01c702bc70d6ac5a7788ed0c1da2ab4",
12
+ "590eaf9de7d9db6df341c435d42dfb616bd70bc1"
13
+ ]
14
+ },
15
+ "target": {
16
+ "branch": "dev/v4/v4.0",
17
+ "capturedBase": "7149037df66555c083cf51ee5055301917026047",
18
+ "implementation": "exact-shared-javascript-semantics"
19
+ },
20
+ "normativeVectors": [
21
+ {
22
+ "path": "tests/release-train.test.mjs",
23
+ "count": 11,
24
+ "result": "exact"
25
+ },
26
+ {
27
+ "path": "tests/dev-alpha-candidate-patrol.test.mjs",
28
+ "count": 37,
29
+ "result": "exact"
30
+ },
31
+ {
32
+ "path": "tests/release-blocker-priority.test.mjs",
33
+ "count": 3,
34
+ "result": "exact"
35
+ },
36
+ {
37
+ "path": "tests/release-train-self-dogfood.test.mjs",
38
+ "count": 5,
39
+ "result": "exact"
40
+ }
41
+ ],
42
+ "adapterDifferences": [
43
+ {
44
+ "surface": "branch-coordinates",
45
+ "source": "dev/v3/v3.0 -> alpha/v3/v3.0",
46
+ "target": "dev/v4/v4.0 -> alpha/v4/v4.0",
47
+ "semanticImpact": "none"
48
+ },
49
+ {
50
+ "surface": "candidate-patrol-runtime-ref",
51
+ "source": "v3-alpha",
52
+ "target": "v4-alpha",
53
+ "semanticImpact": "none"
54
+ },
55
+ {
56
+ "surface": "architecture-projection",
57
+ "source": "architecture/v3-core-mechanism-inventory.json",
58
+ "target": "architecture/v4-release-train-parity.json",
59
+ "semanticImpact": "evidence-only"
60
+ }
61
+ ],
62
+ "forbidden": [
63
+ "v4-first-redesign",
64
+ "production-authority-cutover",
65
+ "alpha2-migration",
66
+ "provider-gate-bypass"
67
+ ]
68
+ }
@@ -0,0 +1,107 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "contract": "kungfu-buildchain-v4-rust-libnode-bridge-evaluation",
4
+ "observedAt": "2026-08-07T05:50:58.385Z",
5
+ "baseline": {
6
+ "buildchainRevision": "95e7c1060cae94a38b72c5ac3d7b79cce0ad662b",
7
+ "libnodeRepository": "kungfu-systems/libnode",
8
+ "libnodeRevision": "4bef69b88a441f22024fa9f3d7bfd76a89963e8a"
9
+ },
10
+ "selection": {
11
+ "id": "rust-trunk-node-subprocess-host-v1",
12
+ "status": "selected-for-wave-0",
13
+ "replaceable": true,
14
+ "productionWriterAuthority": "typescript-v3",
15
+ "contract": "contracts/v4-host-contract-v1.schema.json"
16
+ },
17
+ "contractBoundary": {
18
+ "protocolVersion": "1.0",
19
+ "requestFields": [
20
+ "command identity",
21
+ "arguments",
22
+ "canonical base64 input bytes",
23
+ "required capabilities",
24
+ "timeout"
25
+ ],
26
+ "responseFields": [
27
+ "structured result",
28
+ "byte-exact stdout and stderr",
29
+ "diagnostics",
30
+ "exit code and signal",
31
+ "host capabilities"
32
+ ],
33
+ "explicitUnsupportedStatus": "unsupported",
34
+ "credentialSerialization": "forbidden-by-closed-request",
35
+ "privateRuntimeLayouts": "absent"
36
+ },
37
+ "options": [
38
+ {
39
+ "id": "rust-process-direct-libnode-cxx-api",
40
+ "status": "rejected-for-wave-0",
41
+ "prototypeDisposition": "source-grounded-infeasibility",
42
+ "build": "requires a new C++ shim and platform-specific Node/V8 link graph",
43
+ "runtime": "one process but one Node isolate and event-loop lifecycle inside the Rust host",
44
+ "packaging": "must ship a 110302336-byte observed dylib plus a Rust/C++ ABI-matched shim on darwin-arm64",
45
+ "lifecycle": "must bind InitializeOncePerProcess, CommonEnvironmentSetup, SpinEventLoop, Stop, and teardown",
46
+ "failure": "C++ exceptions, fatal V8 failures, and process-global initialization share the Rust failure domain",
47
+ "cancellation": "requires cross-thread node::Stop and isolate lifecycle ownership",
48
+ "portability": "separate linker and loader work is required for dylib, so, and dll targets",
49
+ "falsifiableReconsideration": "reconsider when libnode publishes a versioned C ABI shim that owns initialization, cancellation, teardown, and byte-oriented request-response semantics",
50
+ "evidence": [
51
+ "kungfu-systems/libnode@4bef69b88a441f22024fa9f3d7bfd76a89963e8a:README.md exposes only libpath and include compiler coordinates",
52
+ "kungfu-systems/libnode@4bef69b88a441f22024fa9f3d7bfd76a89963e8a:src/cpp/link.cc exports an empty N-API module, not an embedder C ABI",
53
+ "kungfu-systems/libnode@4bef69b88a441f22024fa9f3d7bfd76a89963e8a:node/src/node.h exposes the C++ embedding lifecycle"
54
+ ]
55
+ },
56
+ {
57
+ "id": "rust-trunk-node-subprocess-host-v1",
58
+ "status": "selected-for-wave-0",
59
+ "prototypeDisposition": "implemented-and-tested",
60
+ "build": "one bounded Rust binary plus an existing Node-compatible MJS host",
61
+ "runtime": "one child per request; no daemon, shared database, or second authority",
62
+ "packaging": "Rust source, lockfile, contract, and MJS host are included in the npm dry-run package",
63
+ "lifecycle": "Rust owns spawn, bounded input-output, timeout, termination, and reap",
64
+ "failure": "invalid response, host crash, controlled command failure, and unsupported capability are distinct",
65
+ "cancellation": "timeout and SIGINT terminate and reap the host before returning a structured cancellation",
66
+ "portability": "uses std::process plus the repository Node runtime; darwin-arm64 is executed and Linux/Windows remain bounded validation targets",
67
+ "replacementMechanism": "BUILDCHAIN_V4_HOST_COMMAND and BUILDCHAIN_V4_HOST_SCRIPT replace the host without changing the Rust domain contract",
68
+ "evidence": [
69
+ "tests/v4-bridge.test.mjs",
70
+ "crates/buildchain-v4-bridge/src/main.rs",
71
+ "scripts/v4-host-adapter.mjs"
72
+ ]
73
+ }
74
+ ],
75
+ "retainedFixtures": [
76
+ "architecture.list read-only JSON command",
77
+ "architecture.show structured JSON command",
78
+ "controlled failure with partial stdout, stderr, and exit 42",
79
+ "512 KiB canonical byte echo",
80
+ "unsupported capability",
81
+ "host crash before response",
82
+ "timeout cancellation",
83
+ "SIGINT cancellation and reap",
84
+ "credential field rejection"
85
+ ],
86
+ "observedMeasurements": {
87
+ "environment": {
88
+ "platform": "darwin",
89
+ "architecture": "arm64",
90
+ "node": "v24.16.0",
91
+ "rustc": "rustc 1.95.0 (59807616e 2026-04-14) (Homebrew)"
92
+ },
93
+ "iterations": 7,
94
+ "directNodeHostColdStartMedianMs": 39.215,
95
+ "rustSubprocessBridgeColdStartMedianMs": 58.608,
96
+ "rustSubprocessBridgeColdStartRangeMs": [49.582, 523.831],
97
+ "rustReleaseBinaryBytes": 768544,
98
+ "observedLibnodeArtifactBytes": 110302336,
99
+ "interpretation": "The subprocess boundary adds about 19.4 ms at the median in this bounded local probe; the seven-sample maximum shows cold-start variance and is not a final ABI benchmark."
100
+ },
101
+ "nonClaims": [
102
+ "No production state-machine writer moved from TypeScript v3.",
103
+ "No daemon, service database, credential broker, or second process authority was introduced.",
104
+ "The selected Wave 0 host is replaceable and is not the final v4 ABI.",
105
+ "Linux and Windows runtime parity is not claimed by the darwin-arm64 measurement."
106
+ ]
107
+ }
@@ -0,0 +1,85 @@
1
+ ---
2
+ status: draft
3
+ period: 2026-08-07
4
+ theme: buildchain-v4-rust-libnode-bridge
5
+ doc_type: architecture-evaluation
6
+ source_level: local-files + protected-git-evidence
7
+ confidence: high
8
+ sensitivity: public
9
+ evidence_grade: A
10
+ review_state: unreviewed
11
+ last_reviewed: 2026-08-07
12
+ ai_provenance:
13
+ model_family: GPT-5
14
+ product: Codex
15
+ generated_at: 2026-08-07
16
+ boundary: Uses repository source, executable fixtures, and a local darwin-arm64 measurement; it does not claim unexecuted platform parity or a final v4 ABI.
17
+ ---
18
+
19
+ # Buildchain v4 Rust/libnode bridge spike
20
+
21
+ ## Decision
22
+
23
+ Wave 0 selects a Rust-trunk to Node-compatible subprocess host behind the
24
+ closed, versioned
25
+ [`v4-host-contract-v1.schema.json`](../contracts/v4-host-contract-v1.schema.json).
26
+ The Rust trunk owns transport bounds, correlation, timeout, cancellation,
27
+ child cleanup, crash classification, and compatibility output. The MJS adapter
28
+ continues to call the existing read-only TypeScript implementation. All
29
+ production writers remain TypeScript v3.
30
+
31
+ The host is replaceable through explicit executable and adapter coordinates;
32
+ the Rust code does not import libnode, Node, V8, provider SDK, or private
33
+ runtime types. The exact option matrix, retained fixtures, source revisions,
34
+ and captured measurements are machine-readable in
35
+ [`v4-rust-libnode-bridge-evaluation.json`](v4-rust-libnode-bridge-evaluation.json).
36
+
37
+ ## Contract
38
+
39
+ Requests carry only a command identity, string arguments, canonical base64
40
+ input bytes, required capabilities, a timeout, and a correlation id. Responses
41
+ carry a structured result, byte-exact stdout and stderr, typed diagnostics,
42
+ exit code and signal semantics, and the capabilities actually offered by the
43
+ host. Both documents are closed objects. Credential fields and private runtime
44
+ layouts therefore fail before host execution.
45
+
46
+ Unsupported commands, capabilities, and protocol versions are explicit rather
47
+ than silently downgraded. `compat` mode unwraps the response and reproduces the
48
+ legacy process stdout, stderr, and exit code; `exchange` mode returns the full
49
+ structured response.
50
+
51
+ ## Compared boundaries
52
+
53
+ | Boundary | Wave 0 result | Evidence |
54
+ | --- | --- | --- |
55
+ | Rust process directly embeds libnode's C++ API | Rejected for Wave 0 | The exact libnode source exposes compiler `libpath`/`include` coordinates and Node's C++ embedding lifecycle, but no versioned C ABI that owns initialization, event-loop execution, cancellation, and teardown. A new shim would bind Rust to Node/V8 ABI and failure-domain details. |
56
+ | Rust process spawns a Node-compatible contract host | Selected | Implemented with bounded pipes and a closed protocol; the retained suite proves CLI/JSON parity, structured results, controlled failure, large input, unsupported behavior, timeout, signal cancellation, cleanup, and host crash classification. |
57
+
58
+ The in-process result is falsifiable: reconsider it when libnode publishes a
59
+ versioned C ABI shim that owns the complete lifecycle and accepts and returns
60
+ only the frozen byte-oriented host contract. A benchmark alone is insufficient
61
+ because it would not remove the ABI, teardown, crash-domain, and portability
62
+ risks.
63
+
64
+ ## Reproduce
65
+
66
+ ```bash
67
+ pnpm bridge:v4:build
68
+ pnpm bridge:v4:run -- architecture.list -- --json
69
+ pnpm run bridge:v4:evidence -- --iterations 7
70
+ pnpm run check:v4-bridge
71
+ node --test tests/v4-bridge.test.mjs
72
+ ```
73
+
74
+ Set `BUILDCHAIN_LIBNODE_ROOT` only when collecting optional local libnode
75
+ revision and artifact-size evidence. Its path is never written into the
76
+ contract or committed evaluation.
77
+
78
+ ## Limits
79
+
80
+ The darwin-arm64 probe observed a roughly 19.4 ms median increment over direct
81
+ Node host startup and a 768,544-byte release Rust binary. These seven samples
82
+ are a boundary cost observation, not a final performance or ABI decision.
83
+ Linux and Windows remain required validation targets before any consumer or
84
+ writer migration. This spike creates no daemon, credential broker, mutable
85
+ cross-machine store, or second state authority.
@@ -0,0 +1,66 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "contract": "kungfu-buildchain-v4-stable-publication-fence-architecture",
4
+ "schemaAuthority": "contracts/v4-stable-publication-fence-v1.schema.json",
5
+ "fixtureAuthority": "contracts/fixtures/v4-stable-publication-fence-v1/shared.json",
6
+ "activationPredecessor": "architecture/v4-release-activation-shadow-domain.json",
7
+ "mode": "production",
8
+ "authority": {
9
+ "productionWriter": "v4-domain",
10
+ "productionWriterCount": 1,
11
+ "fenceAuthority": "rust-v4-core",
12
+ "fenceWriterCount": 1,
13
+ "typescript": "byte-equivalent-provider-adapter",
14
+ "candidateSelfQualification": false,
15
+ "productionWriteChange": true
16
+ },
17
+ "qualificationPolicies": {
18
+ "n-minus-one": "authority-generation-must-immediately-precede-candidate",
19
+ "independent-seal": "qualifier-authority-must-differ-from-publisher-authority",
20
+ "candidateRoot": "exact-content-root",
21
+ "coordinates": [
22
+ "source-root",
23
+ "metadata-root",
24
+ "journal-root",
25
+ "protected-ancestry-root",
26
+ "provider-confirmation-roots"
27
+ ]
28
+ },
29
+ "publicationTargets": ["stable-ref", "npm-tag", "oci-tag", "github-release"],
30
+ "implementations": {
31
+ "rustDomain": "crates/buildchain-v4-contracts/src/stable_publication_fence.rs",
32
+ "typescript": "packages/core/v4-stable-publication-fence.js"
33
+ },
34
+ "roots": [
35
+ "stable-publication-candidate",
36
+ "stable-publication-qualification",
37
+ "stable-publication-target",
38
+ "stable-publication-plan",
39
+ "stable-publication-fence"
40
+ ],
41
+ "rejects": [
42
+ "candidate-self-qualification",
43
+ "candidate-root-mismatch",
44
+ "qualification-publication-authority-collision",
45
+ "protected-ancestry-mismatch",
46
+ "source-mismatch",
47
+ "metadata-mismatch",
48
+ "journal-mismatch",
49
+ "provider-confirmation-mismatch",
50
+ "conflicting-publication-target"
51
+ ],
52
+ "budgets": {
53
+ "schemaAuthorities": 1,
54
+ "fenceWriters": 1,
55
+ "secondStateFoldWriters": 0,
56
+ "providerSdkImportsInContracts": 0,
57
+ "providerSdkImportsInRustDomain": 0,
58
+ "liveProviderMutations": 0,
59
+ "networkWrites": 0,
60
+ "credentialReads": 0,
61
+ "publicOrProtectedRefChanges": 0,
62
+ "productionWriteAuthorityChanges": 1,
63
+ "v3ConsumerBehaviorChanges": 0
64
+ },
65
+ "successor": "partial-mutation-recovery-qualification"
66
+ }
@@ -0,0 +1,90 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "contract": "kungfu-buildchain-v4-stage-capsule-architecture",
4
+ "schemaAuthority": "contracts/v4-stage-capsule-v1.schema.json",
5
+ "fixtureAuthority": "contracts/fixtures/v4-stage-capsule-v1/shared.json",
6
+ "storeSuccessor": "architecture/v4-stage-capsule-store-contract.json",
7
+ "authority": {
8
+ "writer": "typescript-v3",
9
+ "writerCount": 1,
10
+ "rust": "validation-only",
11
+ "productionWriteChange": false
12
+ },
13
+ "roots": {
14
+ "identity": "stage-capsule-identity",
15
+ "capsule": "stage-capsule",
16
+ "availability": "stage-capsule-availability"
17
+ },
18
+ "identityIncludes": [
19
+ "sourceRoot",
20
+ "platform",
21
+ "platformRoot",
22
+ "stage",
23
+ "toolchainRoots",
24
+ "runtimeRoot",
25
+ "policyRoot",
26
+ "declaredInputs",
27
+ "transformationRoot",
28
+ "outputManifestRoot",
29
+ "qualificationRoot",
30
+ "observationRoots"
31
+ ],
32
+ "identityExcludes": [
33
+ "providerRunId",
34
+ "providerArtifactId",
35
+ "runnerPath",
36
+ "credential",
37
+ "ambientClock",
38
+ "networkObservation",
39
+ "transportLocation",
40
+ "currentAvailability"
41
+ ],
42
+ "templateGuidance": {
43
+ "source": "contracts/fixtures/v4-stage-capsule-v1/shared.json",
44
+ "requiredRootOnlyFields": [
45
+ "toolchainRoots",
46
+ "declaredInputs",
47
+ "observationRoots",
48
+ "transports"
49
+ ],
50
+ "forbiddenRawFields": [
51
+ "providerRunId",
52
+ "providerArtifactId",
53
+ "runnerPath",
54
+ "credential",
55
+ "ambientClock",
56
+ "networkObservation"
57
+ ]
58
+ },
59
+ "reuse": {
60
+ "explicitEvaluationClock": true,
61
+ "failClosedStatuses": [
62
+ "missing",
63
+ "expired",
64
+ "partial",
65
+ "corrupt",
66
+ "quarantined",
67
+ "root-mismatch"
68
+ ],
69
+ "requiresExactRoots": [
70
+ "capsuleRoot",
71
+ "outputManifestRoot",
72
+ "qualificationRoot"
73
+ ]
74
+ },
75
+ "budgets": {
76
+ "schemaAuthorities": 1,
77
+ "writers": 1,
78
+ "secondWriters": 0,
79
+ "providerSdkImportsInContracts": 0,
80
+ "providerSdkImportsInRustDomain": 0,
81
+ "productionWriteAuthorityChanges": 0,
82
+ "v3ConsumerBehaviorChanges": 0
83
+ },
84
+ "successors": [
85
+ "store-retention",
86
+ "platform-stage-checkpoints",
87
+ "resume-planner",
88
+ "qualification-reconciliation"
89
+ ]
90
+ }
@@ -0,0 +1,99 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "contract": "kungfu-buildchain-v4-stage-capsule-qualification",
4
+ "capsuleAuthority": "architecture/v4-stage-capsule-contract.json",
5
+ "storeAuthority": "architecture/v4-stage-capsule-store-contract.json",
6
+ "checkpointAuthority": "architecture/v4-platform-stage-checkpoints.json",
7
+ "resumeAuthority": "architecture/v4-stage-capsule-resume-planner.json",
8
+ "implementation": "packages/core/v4-stage-capsule-qualification.js",
9
+ "rehearsal": "scripts/v4-stage-capsule-qualification.mjs",
10
+ "mode": "shadow-only",
11
+ "productionAuthority": "v3",
12
+ "campaign": {
13
+ "platforms": ["linux-x64", "macos-arm64", "windows-x64"],
14
+ "processRuns": ["seed", "resume"],
15
+ "consumers": ["buildchain"],
16
+ "requiredComparisons": [
17
+ "artifact-manifest-root",
18
+ "content-root",
19
+ "campaign-profile-root",
20
+ "planner-decision",
21
+ "retained-byte-cost",
22
+ "restore-overhead",
23
+ "rollback"
24
+ ]
25
+ },
26
+ "publicConsumerDogfood": {
27
+ "callerWorkflow": ".github/workflows/v4-public-consumer-dogfood.yml",
28
+ "reusableWorkflow": "kungfu-systems/buildchain/.github/workflows/v4-stage-capsule-canary.yml",
29
+ "validationRef": "4178776bf635d0738cb1917e449076d64883218c",
30
+ "invocation": "workflow_call",
31
+ "runtimeBinding": "job.workflow_sha",
32
+ "consumerSourceBinding": "github.sha",
33
+ "configPath": ".buildchain/buildchain.toml",
34
+ "executableStages": ["install", "build", "verify"],
35
+ "dependencies": {
36
+ "install": [],
37
+ "build": ["install"],
38
+ "verify": ["build"]
39
+ },
40
+ "excludedStages": {
41
+ "version-state": "source-mutation",
42
+ "publish": "provider-mutation"
43
+ },
44
+ "runners": ["ubuntu-24.04", "macos-15", "windows-2025"],
45
+ "consumerOrchestrationCopied": false,
46
+ "relativeOrSelfInvocationAllowed": false,
47
+ "directQualificationInvocationAllowed": false,
48
+ "candidateBranchOverrideAllowed": false,
49
+ "recursionRecovery": "public-train-ref-only"
50
+ },
51
+ "faultCampaign": [
52
+ "corrupt",
53
+ "cross-platform",
54
+ "cross-stage",
55
+ "expired",
56
+ "missing",
57
+ "partial",
58
+ "policy-drift",
59
+ "root-mismatch",
60
+ "source-drift",
61
+ "stale-writer",
62
+ "toolchain-drift"
63
+ ],
64
+ "qualification": {
65
+ "freshAndResumedRootsMustMatch": true,
66
+ "falseReuseMaximum": 0,
67
+ "falseRebuildMaximum": 0,
68
+ "allFaultsMustPass": true,
69
+ "threePlatformAggregateRequired": true,
70
+ "fiveNativeTerminalChildrenRequired": true,
71
+ "protectedDeliveryMustBeDrained": true
72
+ },
73
+ "rollback": {
74
+ "switch": "stage-capsule-mode=v3",
75
+ "migrationRequired": false,
76
+ "retainedStateDestroyed": false
77
+ },
78
+ "authority": {
79
+ "providerEffects": false,
80
+ "productionWrites": false,
81
+ "productionReuse": false,
82
+ "releaseEffects": false,
83
+ "credentials": false,
84
+ "aws": false,
85
+ "selfHostedRunners": false,
86
+ "ambientEnvironment": false,
87
+ "ambientClock": false,
88
+ "v3BehaviorChange": false
89
+ },
90
+ "budgets": {
91
+ "qualificationImplementations": 1,
92
+ "canonicalQualificationRoots": 1,
93
+ "providerSdkImports": 0,
94
+ "productionStageSkippingChanges": 0,
95
+ "productionWriteAuthorityChanges": 0,
96
+ "v3ConsumerBehaviorChanges": 0,
97
+ "publicConsumerDogfoodWorkflows": 1
98
+ }
99
+ }
@@ -0,0 +1,52 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "contract": "kungfu-buildchain-v4-stage-capsule-resume-planner",
4
+ "schemaAuthority": "contracts/v4-stage-capsule-resume-v1.schema.json",
5
+ "fixtureAuthority": "contracts/fixtures/v4-stage-capsule-resume-v1/late-platform-failure.json",
6
+ "capsuleAuthority": "architecture/v4-stage-capsule-contract.json",
7
+ "checkpointAuthority": "architecture/v4-platform-stage-checkpoints.json",
8
+ "mode": "shadow-only",
9
+ "productionAuthority": "v3",
10
+ "planner": {
11
+ "rust": "pure-domain-authority",
12
+ "typescript": "byte-identical-projection",
13
+ "ambientClock": false,
14
+ "filesystem": false,
15
+ "network": false,
16
+ "environment": false
17
+ },
18
+ "decisions": ["reuse", "rebuild", "reject"],
19
+ "rebuildCauses": [
20
+ "source-changed",
21
+ "platform-changed",
22
+ "toolchain-changed",
23
+ "runtime-changed",
24
+ "policy-changed",
25
+ "input-changed",
26
+ "transformation-changed",
27
+ "output-manifest-changed",
28
+ "retention-changed"
29
+ ],
30
+ "failClosedCauses": [
31
+ "cross-platform",
32
+ "stage-mismatch",
33
+ "partial",
34
+ "corrupt",
35
+ "quarantined",
36
+ "root-mismatch",
37
+ "evidence-insufficient"
38
+ ],
39
+ "effects": {
40
+ "separateFromCapsuleReuse": true,
41
+ "providerReadbackRequired": true,
42
+ "plannerMutation": false
43
+ },
44
+ "budgets": {
45
+ "plannerImplementations": 2,
46
+ "canonicalPlanRoots": 1,
47
+ "providerSdkImportsInPlanner": 0,
48
+ "plannerSideEffects": 0,
49
+ "productionStageSkippingChanges": 0,
50
+ "v3AuthorityChanges": 0
51
+ }
52
+ }