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

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 (157) hide show
  1. package/AGENTS.md +10 -1
  2. package/CONTRIBUTING.md +24 -0
  3. package/README.md +2 -2
  4. package/actions/promote-buildchain-ref/README.md +1 -1
  5. package/actions/v4-release-candidate-promote/README.md +28 -0
  6. package/architecture/agent-change-map.md +64 -7
  7. package/architecture/ci-lane-change-budget.json +366 -0
  8. package/architecture/internal-capabilities.json +53 -8
  9. package/architecture/maintainability-debt.json +147 -93
  10. package/architecture/maintainability-policy.json +32 -28
  11. package/architecture/release-tail-contract-inventory.json +6 -6
  12. package/architecture/v4-architecture-constitution.md +23 -20
  13. package/architecture/v4-cross-platform-adopter-qualification.json +1 -1
  14. package/architecture/v4-delivery-authority-parity.json +2 -2
  15. package/architecture/v4-delivery-warrant-shadow-bootstrap-plan.json +1 -1
  16. package/architecture/v4-floating-consumer-policy.json +2 -2
  17. package/architecture/v4-next-development-parity.json +5 -5
  18. package/architecture/v4-partial-mutation-recovery-qualification.json +4 -1
  19. package/architecture/v4-platform-stage-checkpoints.json +1 -1
  20. package/architecture/v4-provider-operation-journal-contract.json +5 -2
  21. package/architecture/v4-publication-facade-patches.json +64 -0
  22. package/architecture/v4-release-activation-shadow-domain.json +5 -2
  23. package/architecture/v4-release-topology.json +74 -39
  24. package/architecture/v4-rust-wasm-production-authority.json +58 -0
  25. package/architecture/v4-stable-publication-fence.json +5 -2
  26. package/architecture/v4-stage-capsule-qualification.json +2 -2
  27. package/architecture/v4-tail-reseal-parity.json +8 -6
  28. package/architecture/v4-universal-workflow-bootstrap.json +171 -0
  29. package/architecture/v4-universal-workflow-fault-campaign.json +72 -0
  30. package/architecture/v4-universal-workflow-train-admission.json +40 -0
  31. package/architecture/workflow-taxonomy.json +1451 -0
  32. package/bin/buildchain.mjs +7 -7
  33. package/contracts/buildchain-v2-residuals-v1.json +57 -48
  34. package/contracts/dev-delivery-authority-v2.schema.json +16 -2
  35. package/contracts/fixtures/v4-tail-reseal-v1/valid.json +1 -1
  36. package/contracts/v4-canonical-contracts-v1.schema.json +1 -0
  37. package/dist/site/buildchain-contract.json +93 -48
  38. package/dist/site/buildchain-site.json +222 -69
  39. package/dist/site/capability-registry.json +4 -4
  40. package/dist/site/controller-registry.json +50 -13
  41. package/dist/site/kfd-claims.json +2585 -1000
  42. package/dist/site/kfd-upstream-aggregate.json +1 -1
  43. package/dist/site/manual-registry.json +13 -13
  44. package/dist/site/node-api-registry.json +120 -115
  45. package/dist/site/page-registry.json +204 -51
  46. package/dist/site/public-surface-audit.json +3205 -1219
  47. package/dist/site/publication-authority-registry.json +1124 -362
  48. package/dist/site/publication-registry.json +4 -4
  49. package/dist/site/schemas/dev-delivery-authority-v2.schema.json +16 -2
  50. package/dist/site/site-manifest.json +17 -17
  51. package/dist/site/workflow-registry.json +5061 -1659
  52. package/docs/MAP.md +1 -0
  53. package/docs/auditable-demo.md +1 -1
  54. package/docs/cli.md +21 -8
  55. package/docs/dev-delivery-warrant.md +1 -1
  56. package/docs/engineering-housekeeper.md +3 -3
  57. package/docs/kfd-support.md +26 -2
  58. package/docs/next-development-transition.md +2 -2
  59. package/docs/node-api-reference.md +190 -190
  60. package/docs/publication-authority.md +2 -2
  61. package/docs/release-candidate.md +3 -3
  62. package/docs/release-flow.md +67 -19
  63. package/docs/release-governance.md +8 -8
  64. package/docs/release-passport.md +27 -2
  65. package/docs/reusable-build-surface.md +16 -0
  66. package/docs/v4-adopter-delivery.md +2 -2
  67. package/docs/v4-production-release.md +71 -8
  68. package/docs/v4-rust-wasm-production-authority.md +58 -0
  69. package/docs/v4-stage-capsule.md +2 -2
  70. package/docs/v4-tail-reseal.md +1 -1
  71. package/docs/workflow-catalog.md +154 -0
  72. package/docs/workflow-path-migration.md +109 -0
  73. package/package.json +10 -6
  74. package/packages/core/artifact-verification-envelope.js +5 -5
  75. package/packages/core/buildchain-contract.js +1 -1
  76. package/packages/core/buildchain-kfd-claims.js +2 -2
  77. package/packages/core/buildchain-publication-authority.js +42 -26
  78. package/packages/core/buildchain-v4-domain.wasm +0 -0
  79. package/packages/core/ci-lane-change-budget.js +14 -1
  80. package/packages/core/controller-evidence.js +4 -1
  81. package/packages/core/dev-delivery-candidate-identity.js +40 -6
  82. package/packages/core/dev-delivery-warrant-state.js +3 -4
  83. package/packages/core/dev-delivery-warrant.js +12 -2
  84. package/packages/core/github-governance-authority.js +4 -4
  85. package/packages/core/kfd-adopter-manifest.js +46 -47
  86. package/packages/core/next-development-projection.js +2 -2
  87. package/packages/core/paper-agent-entry.js +30 -4
  88. package/packages/core/paper-fleet.js +1 -1
  89. package/packages/core/paper-runtime-channels.js +348 -0
  90. package/packages/core/paper-scaffold-content.js +10 -0
  91. package/packages/core/paper.js +37 -71
  92. package/packages/core/release-line-dry-run.js +1 -1
  93. package/packages/core/release-passport-contract.js +5 -5
  94. package/packages/core/release-passport.js +5 -4
  95. package/packages/core/release-tail-provider-plane.js +68 -1048
  96. package/packages/core/v4-canonical-contracts.js +10 -75
  97. package/packages/core/v4-domain-wasm-artifact.js +7 -0
  98. package/packages/core/v4-domain-wasm.js +216 -0
  99. package/packages/core/v4-floating-consumer-evidence.js +1 -1
  100. package/packages/core/v4-floating-consumer-policy.js +1 -1
  101. package/packages/core/v4-partial-mutation-recovery-qualification.js +9 -386
  102. package/packages/core/v4-product-publication.js +19 -349
  103. package/packages/core/v4-protected-publication-source.js +19 -21
  104. package/packages/core/v4-provider-operation-journal.js +18 -487
  105. package/packages/core/v4-provider-readback-idempotency.js +12 -97
  106. package/packages/core/v4-release-activation-shadow.js +13 -500
  107. package/packages/core/v4-release-invocation.js +28 -389
  108. package/packages/core/v4-stable-publication-fence.js +13 -342
  109. package/packages/core/v4-universal-workflow-bootstrap.js +586 -0
  110. package/scripts/binary-publication-evidence.mjs +135 -0
  111. package/scripts/build-contract-core.mjs +1 -14
  112. package/scripts/build-v4-domain-wasm.mjs +189 -0
  113. package/scripts/check-action-bundles.mjs +12 -2
  114. package/scripts/check-ci-lane-change-budget.mjs +4 -1
  115. package/scripts/check-core-mechanism-inventory.mjs +4 -3
  116. package/scripts/check-inventory.mjs +35 -44
  117. package/scripts/check-maintainability.mjs +16 -113
  118. package/scripts/check-v4-floating-consumer-policy-contract.mjs +2 -2
  119. package/scripts/check-v4-public-dogfood-contract.mjs +22 -9
  120. package/scripts/check-v4-release-topology.mjs +90 -33
  121. package/scripts/check-v4-runtime-semantic-closure.mjs +4 -1
  122. package/scripts/check-v4-universal-workflow-bootstrap.mjs +266 -0
  123. package/scripts/check-workflow-taxonomy.mjs +6 -0
  124. package/scripts/copy-v4-domain-wasm.mjs +14 -0
  125. package/scripts/dev-delivery-authority-command-adapters.mjs +1 -1
  126. package/scripts/dev-delivery-authority.mjs +8 -8
  127. package/scripts/dev-delivery-source-proof-reuse.mjs +2 -1
  128. package/scripts/dev-delivery-warrant-options.mjs +14 -9
  129. package/scripts/dev-delivery-warrant-store.mjs +73 -7
  130. package/scripts/dev-delivery-warrant-transition.mjs +109 -0
  131. package/scripts/dev-delivery-warrant.mjs +76 -99
  132. package/scripts/dev-pr-auto-merge.mjs +15 -15
  133. package/scripts/generate-channel-build-workflow.mjs +7 -2
  134. package/scripts/generate-channel-promotion-workflow.mjs +7 -5
  135. package/scripts/generate-site-bundle.mjs +11 -11
  136. package/scripts/generate-v4-universal-workflow-facades.mjs +458 -0
  137. package/scripts/generate-workflow-taxonomy.mjs +25 -0
  138. package/scripts/github-output.mjs +31 -0
  139. package/scripts/maintainability-metrics.mjs +16 -5
  140. package/scripts/maintainability-public-surface.mjs +115 -0
  141. package/scripts/next-development-review.mjs +307 -0
  142. package/scripts/paper-work-fleet-cli.mjs +2 -0
  143. package/scripts/release-asset-client.mjs +91 -0
  144. package/scripts/release-candidate-resolver.mjs +9 -9
  145. package/scripts/source-verification-evidence.mjs +344 -0
  146. package/scripts/stable-candidate-qualification.mjs +1 -1
  147. package/scripts/universal-facade-maintainability.mjs +82 -0
  148. package/scripts/v4-product-publication-intent.mjs +13 -6
  149. package/scripts/v4-publication-settlement.mjs +211 -0
  150. package/scripts/v4-universal-workflow-backflow.mjs +212 -0
  151. package/scripts/v4-universal-workflow-engine.mjs +618 -0
  152. package/scripts/v4-universal-workflow-self-dogfood.mjs +205 -0
  153. package/scripts/verify-version-state-delta.mjs +173 -0
  154. package/scripts/workflow-taxonomy.mjs +507 -0
  155. package/templates/native-dev-delivery.yml +4 -7
  156. package/templates/universal-buildchain-bootstrap-recovery.yml +282 -0
  157. package/templates/universal-buildchain-bootstrap.yml +28 -0
@@ -1,9 +1,5 @@
1
- import {
2
- V4ContractFault,
3
- v4ContentRoot,
4
- validateV4Clock,
5
- validateV4Root,
6
- } from "./v4-canonical-contracts.js";
1
+ import { V4ContractFault } from "./v4-canonical-contracts.js";
2
+ import { V4DomainWasmFault, invokeV4DomainWasm } from "./v4-domain-wasm.js";
7
3
 
8
4
  export const V4_STABLE_PUBLICATION_REQUEST_CONTRACT =
9
5
  "buildchain-v4-stable-publication-request/v1";
@@ -12,346 +8,21 @@ export const V4_STABLE_PUBLICATION_PLAN_CONTRACT =
12
8
  export const V4_STABLE_PUBLICATION_FENCE_CONTRACT =
13
9
  "buildchain-v4-stable-publication-fence/v1";
14
10
 
15
- const TOKEN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
16
- const COMMIT = /^[0-9a-f]{40}$/u;
17
- const TARGET_KINDS = new Set([
18
- "stable-ref",
19
- "npm-tag",
20
- "oci-tag",
21
- "github-release",
22
- ]);
23
-
24
- function fault(code, path, message) {
25
- throw new V4ContractFault(code, path, message);
26
- }
27
-
28
- function exactKeys(value, expected, path) {
29
- if (!value || typeof value !== "object" || Array.isArray(value))
30
- fault(
31
- "invalid-stable-publication-shape",
32
- path,
33
- `${path} must be an object`,
34
- );
35
- const actual = Object.keys(value).sort();
36
- const canonical = [...expected].sort();
37
- if (
38
- actual.length !== canonical.length ||
39
- actual.some((key, index) => key !== canonical[index])
40
- )
41
- fault(
42
- "invalid-stable-publication-shape",
43
- path,
44
- `${path} keys do not match the closed publication fence contract`,
45
- );
46
- }
47
-
48
- function asciiCompare(left, right) {
49
- return left < right ? -1 : left > right ? 1 : 0;
50
- }
51
-
52
- function validateToken(value, path) {
53
- if (typeof value !== "string" || !TOKEN.test(value))
54
- fault(
55
- "invalid-stable-publication-token",
56
- path,
57
- `${path} must be an ASCII token`,
58
- );
59
- }
60
-
61
- function validateGeneration(value, path) {
62
- if (!Number.isSafeInteger(value) || value < 1)
63
- fault(
64
- "invalid-stable-publication-generation",
65
- path,
66
- `${path} must be a positive safe integer`,
67
- );
68
- }
69
-
70
- function normalizeRoots(values, path) {
71
- if (!Array.isArray(values) || values.length === 0)
72
- fault(
73
- "stable-publication-provider-confirmation-mismatch",
74
- path,
75
- `${path} must contain rooted provider confirmations`,
76
- );
77
- for (const [index, value] of values.entries())
78
- validateV4Root(value, `${path}/${index}`);
79
- const sorted = [...values].sort(asciiCompare);
80
- if (new Set(sorted).size !== sorted.length)
81
- fault(
82
- "stable-publication-provider-confirmation-mismatch",
83
- path,
84
- `${path} must not contain duplicate roots`,
85
- );
86
- return sorted;
87
- }
88
-
89
- function validateCandidate(candidate) {
90
- exactKeys(
91
- candidate,
92
- [
93
- "generation",
94
- "commit",
95
- "sourceRoot",
96
- "metadataRoot",
97
- "journalRoot",
98
- "protectedAncestryRoot",
99
- ],
100
- "$/candidate",
101
- );
102
- validateGeneration(candidate.generation, "$/candidate/generation");
103
- if (typeof candidate.commit !== "string" || !COMMIT.test(candidate.commit))
104
- fault(
105
- "invalid-stable-publication-commit",
106
- "$/candidate/commit",
107
- "candidate commit must be a lowercase 40-byte Git object id",
108
- );
109
- for (const field of [
110
- "sourceRoot",
111
- "metadataRoot",
112
- "journalRoot",
113
- "protectedAncestryRoot",
114
- ])
115
- validateV4Root(candidate[field], `$/candidate/${field}`);
116
- return structuredClone(candidate);
117
- }
118
-
119
- function normalizeTargets(targets) {
120
- if (!Array.isArray(targets) || targets.length === 0)
121
- fault(
122
- "invalid-stable-publication-target",
123
- "$/targets",
124
- "at least one shadow publication target is required",
125
- );
126
- const normalized = targets.map((target, index) => {
127
- const path = `$/targets/${index}`;
128
- exactKeys(
129
- target,
130
- ["id", "kind", "desired", "providerConfirmationRoot"],
131
- path,
132
- );
133
- validateToken(target.id, `${path}/id`);
134
- if (!TARGET_KINDS.has(target.kind))
135
- fault(
136
- "invalid-stable-publication-target",
137
- `${path}/kind`,
138
- "publication target kind is unsupported",
139
- );
140
- if (
141
- typeof target.desired !== "string" ||
142
- target.desired.length === 0 ||
143
- target.desired.length > 200 ||
144
- [...target.desired].some((character) => {
145
- const code = character.codePointAt(0);
146
- return code < 0x21 || code > 0x7e;
147
- })
148
- )
149
- fault(
150
- "invalid-stable-publication-target",
151
- `${path}/desired`,
152
- "desired target must be non-empty printable ASCII without whitespace",
153
- );
154
- validateV4Root(
155
- target.providerConfirmationRoot,
156
- `${path}/providerConfirmationRoot`,
157
- );
158
- const payload = structuredClone(target);
159
- return {
160
- ...payload,
161
- targetRoot: v4ContentRoot("stable-publication-target", payload),
162
- };
163
- });
164
- normalized.sort((left, right) => asciiCompare(left.id, right.id));
165
- if (
166
- new Set(normalized.map(({ id }) => id)).size !== normalized.length ||
167
- new Set(normalized.map(({ kind }) => kind)).size !== normalized.length
168
- )
169
- fault(
170
- "conflicting-stable-publication-target",
171
- "$/targets",
172
- "publication target ids and kinds must be unique",
173
- );
174
- return normalized;
175
- }
176
-
177
- function validateQualification(request, candidate, candidateRoot, targets) {
178
- const qualification = request.qualification;
179
- exactKeys(
180
- qualification,
181
- [
182
- "mode",
183
- "authorityGeneration",
184
- "qualifiedCandidateRoot",
185
- "qualifierAuthorityRoot",
186
- "sealRoot",
187
- "sourceRoot",
188
- "metadataRoot",
189
- "journalRoot",
190
- "protectedAncestryRoot",
191
- "providerConfirmationRoots",
192
- ],
193
- "$/qualification",
194
- );
195
- if (!new Set(["n-minus-one", "independent-seal"]).has(qualification.mode))
196
- fault(
197
- "invalid-stable-publication-qualification",
198
- "$/qualification/mode",
199
- "qualification mode is unsupported",
200
- );
201
- validateGeneration(
202
- qualification.authorityGeneration,
203
- "$/qualification/authorityGeneration",
204
- );
205
- for (const field of [
206
- "qualifiedCandidateRoot",
207
- "qualifierAuthorityRoot",
208
- "sealRoot",
209
- "sourceRoot",
210
- "metadataRoot",
211
- "journalRoot",
212
- "protectedAncestryRoot",
213
- ])
214
- validateV4Root(qualification[field], `$/qualification/${field}`);
215
- if (qualification.qualifiedCandidateRoot !== candidateRoot)
216
- fault(
217
- "stable-publication-candidate-root-mismatch",
218
- "$/qualification/qualifiedCandidateRoot",
219
- "qualification must bind the exact candidate root",
220
- );
221
- if (
222
- qualification.mode === "n-minus-one" &&
223
- qualification.authorityGeneration + 1 !== candidate.generation
224
- )
225
- fault(
226
- "stable-publication-self-qualification",
227
- "$/qualification/authorityGeneration",
228
- "N-1 qualification must come from the immediately preceding generation",
229
- );
230
- if (
231
- qualification.mode === "independent-seal" &&
232
- qualification.authorityGeneration > candidate.generation
233
- )
234
- fault(
235
- "stable-publication-self-qualification",
236
- "$/qualification/authorityGeneration",
237
- "independent sealed authority cannot come from a future generation",
238
- );
239
- if (qualification.qualifierAuthorityRoot === request.publisherAuthorityRoot)
240
- fault(
241
- "stable-publication-authority-mismatch",
242
- "$/qualification/qualifierAuthorityRoot",
243
- "qualification and publication authorities must be independent",
244
- );
245
- const coordinateFaults = [
246
- ["sourceRoot", "stable-publication-source-mismatch"],
247
- ["metadataRoot", "stable-publication-metadata-mismatch"],
248
- ["journalRoot", "stable-publication-journal-mismatch"],
249
- ["protectedAncestryRoot", "stable-publication-ancestry-mismatch"],
250
- ];
251
- for (const [field, code] of coordinateFaults)
252
- if (qualification[field] !== candidate[field])
253
- fault(
254
- code,
255
- `$/qualification/${field}`,
256
- `qualification ${field} must match the exact candidate coordinate`,
257
- );
258
- const qualifiedConfirmations = normalizeRoots(
259
- qualification.providerConfirmationRoots,
260
- "$/qualification/providerConfirmationRoots",
261
- );
262
- const targetConfirmations = targets
263
- .map(({ providerConfirmationRoot }) => providerConfirmationRoot)
264
- .sort(asciiCompare);
265
- if (
266
- qualifiedConfirmations.length !== targetConfirmations.length ||
267
- qualifiedConfirmations.some(
268
- (root, index) => root !== targetConfirmations[index],
269
- )
270
- )
271
- fault(
272
- "stable-publication-provider-confirmation-mismatch",
273
- "$/qualification/providerConfirmationRoots",
274
- "qualification must bind every exact provider confirmation and no others",
275
- );
276
- const payload = {
277
- ...structuredClone(qualification),
278
- providerConfirmationRoots: qualifiedConfirmations,
279
- };
280
- return {
281
- ...payload,
282
- qualificationRoot: v4ContentRoot(
283
- "stable-publication-qualification",
284
- payload,
285
- ),
286
- };
11
+ function project(request) {
12
+ try {
13
+ return invokeV4DomainWasm("stable-publication", request);
14
+ } catch (error) {
15
+ if (error instanceof V4DomainWasmFault) {
16
+ throw new V4ContractFault(error.code, error.path, error.message);
17
+ }
18
+ throw error;
19
+ }
287
20
  }
288
21
 
289
22
  export function planV4StablePublication(request) {
290
- exactKeys(
291
- request,
292
- [
293
- "schema",
294
- "declaredAt",
295
- "candidate",
296
- "qualification",
297
- "publisherAuthorityRoot",
298
- "targets",
299
- ],
300
- "$",
301
- );
302
- if (request.schema !== V4_STABLE_PUBLICATION_REQUEST_CONTRACT)
303
- fault(
304
- "unsupported-stable-publication-version",
305
- "$/schema",
306
- "stable publication request version is unsupported",
307
- );
308
- validateV4Clock(request.declaredAt, "$/declaredAt");
309
- validateV4Root(request.publisherAuthorityRoot, "$/publisherAuthorityRoot");
310
- const candidate = validateCandidate(request.candidate);
311
- const candidateRoot = v4ContentRoot(
312
- "stable-publication-candidate",
313
- candidate,
314
- );
315
- const targets = normalizeTargets(request.targets);
316
- const qualification = validateQualification(
317
- request,
318
- candidate,
319
- candidateRoot,
320
- targets,
321
- );
322
- const payload = {
323
- schema: V4_STABLE_PUBLICATION_PLAN_CONTRACT,
324
- mode: "production",
325
- productionAuthority: "v4",
326
- declaredAt: request.declaredAt,
327
- candidate,
328
- candidateRoot,
329
- qualification,
330
- publisherAuthorityRoot: request.publisherAuthorityRoot,
331
- targets,
332
- };
333
- return {
334
- ...payload,
335
- planRoot: v4ContentRoot("stable-publication-plan", payload),
336
- };
23
+ return project(request).plan;
337
24
  }
338
25
 
339
26
  export function projectV4StablePublication(request) {
340
- const plan = planV4StablePublication(request);
341
- const payload = {
342
- schema: V4_STABLE_PUBLICATION_FENCE_CONTRACT,
343
- decision: "allow-publication",
344
- effectCount: plan.targets.length,
345
- candidateRoot: plan.candidateRoot,
346
- qualificationMode: plan.qualification.mode,
347
- qualificationRoot: plan.qualification.qualificationRoot,
348
- planRoot: plan.planRoot,
349
- };
350
- return {
351
- plan,
352
- fence: {
353
- ...payload,
354
- fenceRoot: v4ContentRoot("stable-publication-fence", payload),
355
- },
356
- };
27
+ return project(request);
357
28
  }