@kungfu-tech/buildchain 4.0.1-alpha.2 → 4.0.1-alpha.4

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 (78) hide show
  1. package/architecture/decisions/0003-two-phase-delivery-warrant.md +152 -0
  2. package/architecture/internal-capabilities.json +94 -0
  3. package/architecture/maintainability-policy.json +75 -8
  4. package/architecture/v3-core-mechanism-inventory.json +2 -0
  5. package/architecture/v4-delivery-authority-parity.json +250 -0
  6. package/architecture/v4-delivery-warrant-shadow-fixtures.json +41 -9
  7. package/bin/buildchain.mjs +9 -1
  8. package/contracts/dev-delivery-authority-v2.schema.json +662 -0
  9. package/dist/site/agent-index.json +1 -0
  10. package/dist/site/artifact-schemas.json +2 -0
  11. package/dist/site/buildchain-contract.json +91 -8
  12. package/dist/site/buildchain-site.json +169 -18
  13. package/dist/site/capability-registry.json +2 -2
  14. package/dist/site/cli-registry.json +46 -2
  15. package/dist/site/kfd-claims.json +43 -9
  16. package/dist/site/kfd-upstream-aggregate.json +1 -1
  17. package/dist/site/manual-registry.json +3 -3
  18. package/dist/site/node-api-registry.json +1694 -165
  19. package/dist/site/page-registry.json +162 -11
  20. package/dist/site/public-surface-audit.json +367 -7
  21. package/dist/site/publication-registry.json +4 -4
  22. package/dist/site/release-provenance.json +2 -0
  23. package/dist/site/schemas/dev-delivery-authority-v2.schema.json +662 -0
  24. package/dist/site/site-manifest.json +7 -7
  25. package/dist/site/workflow-registry.json +22 -6
  26. package/docs/MAP.md +1 -0
  27. package/docs/cli-reference.md +211 -13
  28. package/docs/dev-delivery-qualification-landing-adr.md +251 -0
  29. package/docs/dev-delivery-warrant.md +330 -38
  30. package/docs/node-api-reference.md +113 -53
  31. package/package.json +5 -1
  32. package/packages/core/buildchain-contract.js +3 -2
  33. package/packages/core/dev-delivery-authority-candidate.js +270 -0
  34. package/packages/core/dev-delivery-authority-evidence.js +146 -0
  35. package/packages/core/dev-delivery-authority-landing.js +461 -0
  36. package/packages/core/dev-delivery-authority-observation.js +48 -0
  37. package/packages/core/dev-delivery-authority-qualification.js +591 -0
  38. package/packages/core/dev-delivery-authority-settlement.js +213 -0
  39. package/packages/core/dev-delivery-authority-state.js +583 -0
  40. package/packages/core/dev-delivery-candidate-identity.js +13 -0
  41. package/packages/core/dev-delivery-contract-surface.js +76 -0
  42. package/packages/core/dev-delivery-execution-failure.js +133 -0
  43. package/packages/core/dev-delivery-execution-transfer.js +572 -0
  44. package/packages/core/dev-delivery-landing-admission-core.js +119 -0
  45. package/packages/core/dev-delivery-landing-readback.js +598 -0
  46. package/packages/core/dev-delivery-landing-terminal-evidence.js +271 -0
  47. package/packages/core/dev-delivery-landing-testing-port.js +6 -0
  48. package/packages/core/dev-delivery-native-execution.js +110 -0
  49. package/packages/core/dev-delivery-native-proof.js +546 -0
  50. package/packages/core/dev-delivery-process-boundary.js +550 -0
  51. package/packages/core/dev-delivery-provider-attempt.js +127 -0
  52. package/packages/core/dev-delivery-provider-heartbeat.js +370 -0
  53. package/packages/core/dev-delivery-warrant-cancellation.js +1 -0
  54. package/packages/core/dev-delivery-warrant-qualification.js +145 -0
  55. package/packages/core/dev-delivery-warrant-settlement.js +237 -36
  56. package/packages/core/dev-delivery-warrant-state.js +564 -0
  57. package/packages/core/dev-delivery-warrant.js +321 -368
  58. package/scripts/buildchain-cli-help.mjs +11 -2
  59. package/scripts/check-v4-floating-consumer-policy-contract.mjs +1 -1
  60. package/scripts/dev-delivery-authority-command-adapters.mjs +206 -0
  61. package/scripts/dev-delivery-authority-provider.mjs +28 -0
  62. package/scripts/dev-delivery-authority.mjs +490 -0
  63. package/scripts/dev-delivery-native-run.mjs +177 -0
  64. package/scripts/dev-delivery-process-boundary.mjs +260 -0
  65. package/scripts/dev-delivery-proof.mjs +67 -2
  66. package/scripts/dev-delivery-provider-heartbeat.mjs +215 -0
  67. package/scripts/dev-delivery-two-phase-resume.mjs +345 -0
  68. package/scripts/dev-delivery-two-phase.mjs +573 -0
  69. package/scripts/dev-delivery-warrant-options.mjs +266 -0
  70. package/scripts/dev-delivery-warrant-store.mjs +227 -0
  71. package/scripts/dev-delivery-warrant.mjs +227 -193
  72. package/scripts/dev-pr-auto-merge.mjs +1 -1
  73. package/scripts/dev-pr-delivery-warrant.mjs +10 -0
  74. package/scripts/generate-site-bundle.mjs +26 -4
  75. package/scripts/npm-publish-transaction.mjs +2 -2
  76. package/scripts/release-train-self-dogfood.mjs +94 -92
  77. package/scripts/site-capability-metadata.mjs +12 -0
  78. package/templates/native-dev-delivery.yml +143 -0
@@ -46,6 +46,10 @@ import {
46
46
  const SITE_BUNDLE_CONTRACT = "kungfu-buildchain-site-bundle";
47
47
  const PUBLICATION_RELEASE_REGISTRY_CONTRACT = "kungfu-buildchain-publication-release-registry";
48
48
  const README_PATH = "README.md";
49
+ const DEV_DELIVERY_AUTHORITY_SCHEMA =
50
+ "schemas/dev-delivery-authority-v2.schema.json";
51
+ const DEV_DELIVERY_AUTHORITY_SCHEMA_SOURCE =
52
+ "contracts/dev-delivery-authority-v2.schema.json";
49
53
  const root = path.resolve(import.meta.dirname, "..");
50
54
  const outputDir = path.join(root, "dist", "site");
51
55
  const requireFromHere = createRequire(import.meta.url);
@@ -73,6 +77,18 @@ function stableJson(value) {
73
77
  return `${JSON.stringify(value, null, 2)}\n`;
74
78
  }
75
79
 
80
+ function siteFileBytes(name, value) {
81
+ return name === DEV_DELIVERY_AUTHORITY_SCHEMA
82
+ ? readText(DEV_DELIVERY_AUTHORITY_SCHEMA_SOURCE)
83
+ : stableJson(value);
84
+ }
85
+
86
+ function writeSiteFile(name, value) {
87
+ const filePath = path.join(outputDir, name);
88
+ fs.mkdirSync(path.dirname(filePath), { recursive: true });
89
+ fs.writeFileSync(filePath, siteFileBytes(name, value));
90
+ }
91
+
76
92
  function env(name) {
77
93
  return String(process.env[name] || "").trim();
78
94
  }
@@ -931,6 +947,7 @@ function buildSiteBundle() {
931
947
  "schemas/release-passport-v1.schema.json",
932
948
  "schemas/kfd-agent-hub-adoption.schema.json",
933
949
  "schemas/kfd-product-gate-input-v1.schema.json",
950
+ "schemas/dev-delivery-authority-v2.schema.json",
934
951
  "kfd-support.json",
935
952
  "artifact-evidence.json",
936
953
  "product-mechanism.json",
@@ -965,6 +982,7 @@ function buildSiteBundle() {
965
982
  "schemas/release-passport-v1.schema.json",
966
983
  "schemas/kfd-agent-hub-adoption.schema.json",
967
984
  "schemas/kfd-product-gate-input-v1.schema.json",
985
+ "schemas/dev-delivery-authority-v2.schema.json",
968
986
  "buildchain-contract.json",
969
987
  "kfd-claims.json",
970
988
  "product-mechanism.json",
@@ -1095,6 +1113,7 @@ function buildSiteBundle() {
1095
1113
  "schemas/release-passport-v1.schema.json",
1096
1114
  "schemas/kfd-agent-hub-adoption.schema.json",
1097
1115
  "schemas/kfd-product-gate-input-v1.schema.json",
1116
+ "schemas/dev-delivery-authority-v2.schema.json",
1098
1117
  "buildchain-contract.json",
1099
1118
  "kfd-upstream-aggregate.json",
1100
1119
  "kfd-claims.json",
@@ -1269,6 +1288,9 @@ function buildSiteBundle() {
1269
1288
  "schemas/release-passport-v1.schema.json": RELEASE_PASSPORT_SCHEMA,
1270
1289
  "schemas/kfd-agent-hub-adoption.schema.json": KFD_AGENT_HUB_ADOPTION_SCHEMA,
1271
1290
  "schemas/kfd-product-gate-input-v1.schema.json": KFD_PRODUCT_GATE_INPUT_SCHEMA,
1291
+ [DEV_DELIVERY_AUTHORITY_SCHEMA]: readJson(
1292
+ DEV_DELIVERY_AUTHORITY_SCHEMA_SOURCE,
1293
+ ),
1272
1294
  "badge-endpoint-registry.json": badgeEndpointRegistry,
1273
1295
  "publication-registry.json": publicationRegistry,
1274
1296
  "buildchain-contract.json": createBuildchainContractWorld({ root, controllerRegistry }),
@@ -1288,7 +1310,7 @@ export function writeSiteBundle({ check = false } = {}) {
1288
1310
  const mismatches = [];
1289
1311
  for (const [name, value] of Object.entries(files)) {
1290
1312
  const filePath = path.join(outputDir, name);
1291
- const next = stableJson(value);
1313
+ const next = siteFileBytes(name, value);
1292
1314
  if (check) {
1293
1315
  if (existingJson(filePath) !== next) {
1294
1316
  mismatches.push(path.relative(root, filePath));
@@ -1301,11 +1323,11 @@ export function writeSiteBundle({ check = false } = {}) {
1301
1323
  if (!check) {
1302
1324
  for (let iteration = 0; iteration < 5; iteration += 1) {
1303
1325
  for (const [name, value] of Object.entries(files)) {
1304
- writeJson(path.join(outputDir, name), value);
1326
+ writeSiteFile(name, value);
1305
1327
  }
1306
1328
  const nextFiles = buildSiteBundle();
1307
1329
  const stable = Object.entries(nextFiles).every(([name, value]) => (
1308
- existingJson(path.join(outputDir, name)) === stableJson(value)
1330
+ existingJson(path.join(outputDir, name)) === siteFileBytes(name, value)
1309
1331
  ));
1310
1332
  files = nextFiles;
1311
1333
  if (stable) {
@@ -1316,7 +1338,7 @@ export function writeSiteBundle({ check = false } = {}) {
1316
1338
  }
1317
1339
  }
1318
1340
  for (const [name, value] of Object.entries(files)) {
1319
- writeJson(path.join(outputDir, name), value);
1341
+ writeSiteFile(name, value);
1320
1342
  }
1321
1343
  }
1322
1344
  return {
@@ -128,8 +128,8 @@ function parseNpmView(stdout) {
128
128
  const parsed = JSON.parse(raw);
129
129
  const dist = parsed?.dist || parsed;
130
130
  return {
131
- integrity: dist?.integrity || "",
132
- shasum: dist?.shasum || "",
131
+ integrity: dist?.integrity || parsed?.["dist.integrity"] || "",
132
+ shasum: dist?.shasum || parsed?.["dist.shasum"] || "",
133
133
  };
134
134
  }
135
135
 
@@ -6,7 +6,11 @@ import fs from "node:fs";
6
6
  import {
7
7
  closeDevDeliveryWarrant,
8
8
  createDevDeliveryQueue,
9
+ createNativeCommandContract,
10
+ createNativeProofReuseDecision,
11
+ createNativeQualificationProof,
9
12
  createReleaseBlockerPriorityClaim,
13
+ qualifyDevDeliveryWarrant,
10
14
  selectDevDeliveryWarrant,
11
15
  submitDevDeliveryCandidate,
12
16
  } from "../packages/core/dev-delivery-warrant.js";
@@ -81,9 +85,12 @@ function branch(value, label) {
81
85
  return normalized;
82
86
  }
83
87
 
84
- function at(recordedAt, seconds) {
85
- return new Date(Date.parse(recordedAt) + seconds * 1000).toISOString();
86
- }
88
+ const at = (recordedAt, seconds) => new Date(Date.parse(recordedAt) + seconds * 1000).toISOString();
89
+
90
+ const normalizeFields = (input, fields, normalizer, prefix = "") =>
91
+ Object.fromEntries(fields.map((field) => [field, normalizer(input?.[field], `${prefix}${field}`)]));
92
+
93
+ const requireEvidence = (condition, message) => { if (!condition) throw new Error(message); };
87
94
 
88
95
  function normalizeDelivery(input, expected) {
89
96
  const delivery = {
@@ -92,59 +99,44 @@ function normalizeDelivery(input, expected) {
92
99
  "delivery.pullRequestNumber",
93
100
  ),
94
101
  baseBranch: branch(input?.baseBranch, "delivery.baseBranch"),
95
- headSha: sha(input?.headSha, "delivery.headSha"),
96
- headTreeSha: sha(input?.headTreeSha, "delivery.headTreeSha"),
97
- state: text(input?.state, "delivery.state"),
98
- reviewState: text(input?.reviewState, "delivery.reviewState"),
99
- reviewHeadSha: sha(input?.reviewHeadSha, "delivery.reviewHeadSha"),
100
- mergeSha: sha(input?.mergeSha, "delivery.mergeSha"),
101
- mergeTreeSha: sha(input?.mergeTreeSha, "delivery.mergeTreeSha"),
102
- ciHeadSha: sha(input?.ciHeadSha, "delivery.ciHeadSha"),
103
- ciConclusion: text(input?.ciConclusion, "delivery.ciConclusion"),
104
- reviewRoot: root(input?.reviewRoot, "delivery.reviewRoot"),
105
- ciRoot: root(input?.ciRoot, "delivery.ciRoot"),
106
- mergeRoot: root(input?.mergeRoot, "delivery.mergeRoot"),
107
- artifactRoot: root(input?.artifactRoot, "delivery.artifactRoot"),
108
- installedProductRoot: root(
109
- input?.installedProductRoot,
110
- "delivery.installedProductRoot",
102
+ ...normalizeFields(
103
+ input,
104
+ ["headSha", "headTreeSha", "reviewHeadSha", "mergeSha", "mergeTreeSha", "ciHeadSha"],
105
+ sha,
106
+ "delivery.",
107
+ ),
108
+ ...normalizeFields(input, ["state", "reviewState", "ciConclusion"], text, "delivery."),
109
+ ...normalizeFields(
110
+ input,
111
+ ["reviewRoot", "ciRoot", "mergeRoot", "artifactRoot", "installedProductRoot"],
112
+ root,
113
+ "delivery.",
111
114
  ),
112
115
  };
113
- if (delivery.baseBranch !== expected.sourceBranch) {
114
- throw new Error(
115
- "protected delivery base does not match the Release Cut source branch",
116
- );
117
- }
118
- if (
119
- delivery.state !== "MERGED" ||
120
- delivery.reviewState !== "APPROVED" ||
121
- delivery.ciConclusion !== "success"
122
- ) {
123
- throw new Error(
124
- "protected delivery is not merged, approved, and CI-successful",
125
- );
126
- }
127
- if (
128
- delivery.headSha !== expected.devLandingSha ||
129
- delivery.reviewHeadSha !== delivery.headSha
130
- ) {
131
- throw new Error(
132
- "protected delivery review does not bind the exact repaired head",
133
- );
134
- }
135
- if (
136
- delivery.headTreeSha !== expected.cutCandidateTreeSha ||
137
- delivery.mergeTreeSha !== delivery.headTreeSha
138
- ) {
139
- throw new Error(
140
- "protected delivery merge tree does not equal the repaired candidate tree",
141
- );
142
- }
143
- if (delivery.ciHeadSha !== delivery.mergeSha) {
144
- throw new Error(
145
- "protected delivery CI does not bind the merge-group result",
146
- );
147
- }
116
+ requireEvidence(
117
+ delivery.baseBranch === expected.sourceBranch,
118
+ "protected delivery base does not match the Release Cut source branch",
119
+ );
120
+ requireEvidence(
121
+ delivery.state === "MERGED" &&
122
+ delivery.reviewState === "APPROVED" &&
123
+ delivery.ciConclusion === "success",
124
+ "protected delivery is not merged, approved, and CI-successful",
125
+ );
126
+ requireEvidence(
127
+ delivery.headSha === expected.devLandingSha &&
128
+ delivery.reviewHeadSha === delivery.headSha,
129
+ "protected delivery review does not bind the exact repaired head",
130
+ );
131
+ requireEvidence(
132
+ delivery.headTreeSha === expected.cutCandidateTreeSha &&
133
+ delivery.mergeTreeSha === delivery.headTreeSha,
134
+ "protected delivery merge tree does not equal the repaired candidate tree",
135
+ );
136
+ requireEvidence(
137
+ delivery.ciHeadSha === delivery.mergeSha,
138
+ "protected delivery CI does not bind the merge-group result",
139
+ );
148
140
  return delivery;
149
141
  }
150
142
 
@@ -153,50 +145,32 @@ function normalizeInput(input = {}) {
153
145
  repository: repository(input.repository),
154
146
  sourceBranch: branch(input.sourceBranch, "sourceBranch"),
155
147
  targetBranch: branch(input.targetBranch, "targetBranch"),
156
- assignmentRoot: root(input.assignmentRoot, "assignmentRoot"),
157
- initiativeRoot: root(input.initiativeRoot, "initiativeRoot"),
158
- dependencyProofRoot: root(input.dependencyProofRoot, "dependencyProofRoot"),
159
- originDevSha: sha(input.originDevSha, "originDevSha"),
160
- candidateSha: sha(input.candidateSha, "candidateSha"),
161
- candidateTreeSha: sha(input.candidateTreeSha, "candidateTreeSha"),
162
- alphaBaseSha: sha(input.alphaBaseSha, "alphaBaseSha"),
163
- buildchainRuntimeSha: sha(
164
- input.buildchainRuntimeSha,
165
- "buildchainRuntimeSha",
166
- ),
167
- observedDevSha: sha(input.observedDevSha, "observedDevSha"),
168
- blockerRoot: root(input.blockerRoot, "blockerRoot"),
169
- patchRoot: root(input.patchRoot, "patchRoot"),
170
- cutCandidateSha: sha(input.cutCandidateSha, "cutCandidateSha"),
171
- cutCandidateTreeSha: sha(input.cutCandidateTreeSha, "cutCandidateTreeSha"),
172
- cutLandingEvidenceRoot: root(
173
- input.cutLandingEvidenceRoot,
174
- "cutLandingEvidenceRoot",
148
+ ...normalizeFields(
149
+ input,
150
+ ["assignmentRoot", "initiativeRoot", "dependencyProofRoot", "environmentRoot", "blockerRoot", "patchRoot", "cutLandingEvidenceRoot", "devConflictEvidenceRoot", "devLandingEvidenceRoot"],
151
+ root,
175
152
  ),
176
- devBaseSha: sha(input.devBaseSha, "devBaseSha"),
177
- devLandingSha: sha(input.devLandingSha, "devLandingSha"),
178
- devConflictEvidenceRoot: root(
179
- input.devConflictEvidenceRoot,
180
- "devConflictEvidenceRoot",
181
- ),
182
- devLandingEvidenceRoot: root(
183
- input.devLandingEvidenceRoot,
184
- "devLandingEvidenceRoot",
153
+ ...normalizeFields(
154
+ input,
155
+ ["originDevSha", "candidateSha", "candidateTreeSha", "alphaBaseSha", "buildchainRuntimeSha", "observedDevSha", "cutCandidateSha", "cutCandidateTreeSha", "devBaseSha", "devLandingSha"],
156
+ sha,
185
157
  ),
158
+ nativeCommand: text(input.nativeCommand, "nativeCommand"),
159
+ nativeExecutionReceipt: structuredClone(input.nativeExecutionReceipt || {}),
186
160
  ordinaryPullRequestNumber: positiveInteger(
187
161
  input.ordinaryPullRequestNumber,
188
162
  "ordinaryPullRequestNumber",
189
163
  ),
190
164
  recordedAt: timestamp(input.recordedAt, "recordedAt"),
191
165
  };
192
- if (normalized.observedDevSha === normalized.originDevSha) {
193
- throw new Error(
194
- "self-dogfood requires dev to advance beyond the frozen origin",
195
- );
196
- }
197
- if (normalized.cutCandidateSha === normalized.candidateSha) {
198
- throw new Error("self-dogfood requires a successor repair candidate");
199
- }
166
+ requireEvidence(
167
+ normalized.observedDevSha !== normalized.originDevSha,
168
+ "self-dogfood requires dev to advance beyond the frozen origin",
169
+ );
170
+ requireEvidence(
171
+ normalized.cutCandidateSha !== normalized.candidateSha,
172
+ "self-dogfood requires a successor repair candidate",
173
+ );
200
174
  normalized.delivery = normalizeDelivery(input.delivery, normalized);
201
175
  return normalized;
202
176
  }
@@ -214,6 +188,10 @@ function deliveryCandidate(input, deliveryClass = "release") {
214
188
  closureRoot: input.closureRoot,
215
189
  dependencyRoot: input.dependencyRoot,
216
190
  toolchainRoot: input.toolchainRoot,
191
+ ...(input.environmentRoot ? { environmentRoot: input.environmentRoot } : {}),
192
+ ...(input.nativeCommand
193
+ ? { nativeCommandContract: createNativeCommandContract(input.nativeCommand) }
194
+ : {}),
217
195
  deliveryClass,
218
196
  priority: "ordinary",
219
197
  ...(input.releaseBlockerPriority
@@ -366,7 +344,7 @@ function runQueueCampaign(value, repaired, priorityClaim) {
366
344
  dependencyRoot: value.dependencyProofRoot,
367
345
  toolchainRoot: value.dependencyProofRoot,
368
346
  },
369
- "native-proof-required",
347
+ "non-native-fast",
370
348
  );
371
349
  queue = submitDevDeliveryCandidate(queue, ordinary, {
372
350
  now: at(value.recordedAt, 6),
@@ -388,6 +366,8 @@ function runQueueCampaign(value, repaired, priorityClaim) {
388
366
  closureRoot: value.delivery.mergeRoot,
389
367
  dependencyRoot: value.dependencyProofRoot,
390
368
  toolchainRoot: value.delivery.installedProductRoot,
369
+ environmentRoot: value.environmentRoot,
370
+ nativeCommand: value.nativeCommand,
391
371
  releaseBlockerPriority: priorityClaim,
392
372
  });
393
373
  const submitted = submitDevDeliveryCandidate(queue, blocker, {
@@ -426,7 +406,29 @@ function runQueueCampaign(value, repaired, priorityClaim) {
426
406
  "eligible release blocker did not receive bounded priority",
427
407
  );
428
408
  }
429
- const closed = closeDevDeliveryWarrant(selected.queue, selected.warrant, {
409
+ const nativeCommandRoot = createNativeCommandContract(value.nativeCommand).commandRoot;
410
+ const proof = createNativeQualificationProof({
411
+ ...selected.warrant,
412
+ repository: value.repository,
413
+ protectedBase: value.sourceBranch,
414
+ qualifiedBase: value.devBaseSha,
415
+ nativeCommandRoot,
416
+ nativeExecutionReceipt: value.nativeExecutionReceipt,
417
+ affectedPaths: [], shardEvidenceRoots: [],
418
+ qualifiedAt: at(value.recordedAt, 12),
419
+ });
420
+ const current = {
421
+ ...selected.warrant,
422
+ nativeCommandRoot,
423
+ currentBase: value.devBaseSha,
424
+ graphKnown: true, attributionComplete: true,
425
+ changedPaths: [], renames: [],
426
+ };
427
+ const reuseDecision = createNativeProofReuseDecision({ proof, current });
428
+ const qualified = qualifyDevDeliveryWarrant(selected.queue, selected.warrant, {
429
+ nativeProof: proof, reuseDecision, current, now: at(value.recordedAt, 12),
430
+ });
431
+ const closed = closeDevDeliveryWarrant(qualified.queue, qualified.warrant, {
430
432
  outcome: "merged",
431
433
  evidenceRoot: value.delivery.mergeRoot,
432
434
  now: at(value.recordedAt, 13),
@@ -92,6 +92,17 @@ export function cliCommandMeta(id) {
92
92
  "kfd-upstream-roles": { group: "kfd-trust", purpose: "List Buildchain-managed KFD upstream role values and inference policy." },
93
93
  lifecycle: { group: "reusable-build", purpose: "Run configured lifecycle commands and write deterministic artifact manifests." },
94
94
  dev: { group: "governance-versioning", purpose: "Inspect protected development-channel governance command families." },
95
+ "dev-authority-admit-merge-group": { group: "governance-versioning", purpose: "Verify that one exact candidate holds the exclusive Landing Warrant before merge_group admission." },
96
+ "dev-authority-complete-qualification": { group: "governance-versioning", purpose: "Bind qualification evidence and release one bounded Qualification Lease without granting landing authority." },
97
+ "dev-authority-heartbeat-landing": { group: "governance-versioning", purpose: "Extend the exact fenced Landing Warrant while final landing work remains live." },
98
+ "dev-authority-heartbeat-qualification": { group: "governance-versioning", purpose: "Extend one exact fenced Qualification Lease while qualification work remains live." },
99
+ "dev-authority-lease-landing": { group: "governance-versioning", purpose: "Issue or retain the single exclusive Landing Warrant for a qualified candidate." },
100
+ "dev-authority-lease-qualification": { group: "governance-versioning", purpose: "Issue one qualification-only lease within the configured bounded lane count." },
101
+ "dev-authority-migrate": { group: "governance-versioning", purpose: "Migrate one exact v1 Warrant state into v2 without rewriting candidate or fencing evidence." },
102
+ "dev-authority-observe": { group: "governance-versioning", purpose: "Read bounded Qualification Leases and the exclusive Landing Warrant without mutating authority." },
103
+ "dev-authority-recover": { group: "governance-versioning", purpose: "Recover expired qualification or Landing authority and emit one rooted wake instruction." },
104
+ "dev-authority-settle": { group: "governance-versioning", purpose: "Settle terminal candidate evidence idempotently and release held qualification or Landing authority immediately." },
105
+ "dev-authority-submit": { group: "governance-versioning", purpose: "Submit an exact candidate to the opt-in bounded-qualification authority state." },
95
106
  "dev-proof-classify": { group: "governance-versioning", purpose: "Classify source-qualified candidate changes against a current integration base." },
96
107
  "dev-proof-integration": { group: "governance-versioning", purpose: "Seal final exact integration delivery proof for a warranted candidate." },
97
108
  "dev-proof-replay": { group: "governance-versioning", purpose: "Replay source qualification against a Project Cut without rewriting candidate source." },
@@ -174,6 +185,7 @@ export function nodeApiMeta(exportName) {
174
185
  "./build-facts": { group: "observability-diagnostics", summary: "Git source, version, module output, product artifact, and legacy Kungfu build fact APIs." },
175
186
  "./candidate-timeline": { group: "observability-diagnostics", summary: "Source-bound candidate event normalization, per-attempt critical-path-safe aggregation, and compact reporting APIs." },
176
187
  "./channel-candidate": { group: "governance-versioning", summary: "Exact-source channel candidate decisions, same-SHA workflow evidence validation, and deterministic source-lock reference APIs." },
188
+ "./dev-delivery-authority": { group: "governance-versioning", summary: "Opt-in bounded Qualification Lease, exclusive Landing Warrant, provider-attempt admission and heartbeat readback, terminal sealing, and expired-Landing verification APIs." },
177
189
  "./dev-delivery-warrant": { group: "governance-versioning", summary: "Durable fair Dev Delivery Warrant queue, fenced lease, and split source and integration proof APIs." },
178
190
  "./cache-evidence": { group: "observability-diagnostics", summary: "Content-addressed cache operation receipts and source/platform-bound evidence-set verification APIs." },
179
191
  "./diagnostics": { group: "observability-diagnostics", summary: "Native diagnostics collection, summarization, cache, compiler, and process-sampler APIs." },
@@ -0,0 +1,143 @@
1
+ name: Protected Dev Delivery
2
+
3
+ on:
4
+ repository_dispatch:
5
+ types: [buildchain-dev-delivery-wake]
6
+ workflow_dispatch:
7
+ inputs:
8
+ buildchain-ref:
9
+ description: "Buildchain runtime selector: v4, v4-alpha, or a trusted train/v4/v4.0/<capability>"
10
+ required: false
11
+ default: "v4-alpha"
12
+ target-branch:
13
+ description: "Protected dev/vN/vN.M branch"
14
+ required: true
15
+ expected-pr-number:
16
+ description: "Exact ready and approved PR number"
17
+ required: true
18
+ type: number
19
+ expected-head-sha:
20
+ description: "Exact immutable PR head"
21
+ required: true
22
+ source-workflow-run-id:
23
+ description: "Exact successful source workflow run"
24
+ required: false
25
+ type: number
26
+ default: 0
27
+ legacy-active-owner-binding-json:
28
+ description: "Explicit legacy-safe phase-less owner binding JSON"
29
+ required: false
30
+ default: ""
31
+ source-workflow-id:
32
+ description: "Pull-request workflow used only to recover a historical active owner with no recorded run"
33
+ required: false
34
+ default: ""
35
+ source-identity-root:
36
+ description: "Semantic source identity root"
37
+ required: true
38
+ source-patch-root:
39
+ description: "Semantic patch root"
40
+ required: true
41
+ assignment-root:
42
+ description: "Native Assignment root"
43
+ required: true
44
+ initiative-root:
45
+ description: "Parent Initiative root"
46
+ required: true
47
+ plan-root:
48
+ description: "Native qualification plan root"
49
+ required: true
50
+ closure-root:
51
+ description: "Affected closure root"
52
+ required: true
53
+ dependency-root:
54
+ description: "Dependency graph root"
55
+ required: true
56
+ toolchain-root:
57
+ description: "Native toolchain root"
58
+ required: true
59
+ environment-root:
60
+ description: "Exact native execution environment contract root bound before native spawn"
61
+ required: false
62
+ default: ""
63
+ affected-paths-json:
64
+ description: "JSON array representing the affected closure"
65
+ required: true
66
+ shard-evidence-roots-json:
67
+ description: "JSON array of exact native shard evidence roots"
68
+ required: false
69
+ default: "[]"
70
+ release-blocker-priority-json:
71
+ description: "Optional exact rooted release-blocker priority claim"
72
+ required: false
73
+ default: ""
74
+ native-proof-json:
75
+ description: "Optional reusable native proof"
76
+ required: false
77
+ default: ""
78
+ native-command:
79
+ description: "Slow native qualification command"
80
+ required: false
81
+ default: ""
82
+ native-command-root:
83
+ description: "Optional exact native command contract root"
84
+ required: false
85
+ default: ""
86
+ native-heartbeat-seconds:
87
+ description: "Heartbeat cadence while native qualification runs"
88
+ required: false
89
+ type: number
90
+ default: 300
91
+ delivery-class:
92
+ description: "Bounded delivery class"
93
+ required: false
94
+ default: "native-proof-required"
95
+ delivery-priority:
96
+ description: "Reviewed delivery priority"
97
+ required: false
98
+ default: "ordinary"
99
+
100
+ permissions:
101
+ actions: write
102
+ contents: write
103
+ pull-requests: write
104
+ checks: read
105
+ statuses: write
106
+
107
+ jobs:
108
+ deliver:
109
+ uses: kungfu-systems/buildchain/.github/workflows/dev-pr-auto-merge.yml@v4-alpha
110
+ with:
111
+ buildchain-ref: ${{ inputs.buildchain-ref || 'v4-alpha' }}
112
+ target-branch: ${{ github.event.client_payload.candidate.targetBranch || inputs.target-branch }}
113
+ expected-pr-number: ${{ github.event.client_payload.candidate.pullRequestNumber || inputs.expected-pr-number }}
114
+ expected-head-sha: ${{ github.event.client_payload.candidate.sourceHead || inputs.expected-head-sha }}
115
+ source-workflow-run-id: ${{ github.event.client_payload.candidate.sourceWorkflowRunId || inputs.source-workflow-run-id || github.run_id }}
116
+ legacy-active-owner-binding-json: ${{ inputs.legacy-active-owner-binding-json || '' }}
117
+ delivery-warrant-mode: required
118
+ handoff-workflow-id: native-dev-delivery.yml
119
+ source-workflow-id: ${{ inputs.source-workflow-id || '' }}
120
+ assignment-root: ${{ github.event.client_payload.candidate.assignmentRoot || inputs.assignment-root }}
121
+ initiative-root: ${{ github.event.client_payload.candidate.initiativeRoot || inputs.initiative-root }}
122
+ source-identity-root: ${{ github.event.client_payload.candidate.sourceIdentityRoot || inputs.source-identity-root }}
123
+ source-patch-root: ${{ github.event.client_payload.candidate.sourcePatchRoot || inputs.source-patch-root }}
124
+ plan-root: ${{ github.event.client_payload.candidate.planRoot || inputs.plan-root }}
125
+ closure-root: ${{ github.event.client_payload.candidate.closureRoot || inputs.closure-root }}
126
+ dependency-root: ${{ github.event.client_payload.candidate.dependencyRoot || inputs.dependency-root }}
127
+ toolchain-root: ${{ github.event.client_payload.candidate.toolchainRoot || inputs.toolchain-root }}
128
+ environment-root: ${{ github.event.client_payload.candidate.environmentRoot || inputs.environment-root }}
129
+ affected-paths-json: ${{ github.event_name == 'repository_dispatch' && toJSON(github.event.client_payload.candidate.affectedPaths) || inputs.affected-paths-json }}
130
+ shard-evidence-roots-json: ${{ github.event_name == 'repository_dispatch' && toJSON(github.event.client_payload.candidate.shardEvidenceRoots) || inputs.shard-evidence-roots-json || '[]' }}
131
+ release-blocker-priority-json: ${{ github.event_name == 'repository_dispatch' && toJSON(github.event.client_payload.candidate.releaseBlockerPriority) || inputs.release-blocker-priority-json || '' }}
132
+ native-proof-json: ${{ inputs.native-proof-json || '' }}
133
+ native-command: ${{ github.event.client_payload.candidate.nativeCommandContract.command || inputs.native-command || '' }}
134
+ native-command-root: ${{ github.event.client_payload.candidate.nativeCommandContract.commandRoot || inputs.native-command-root || '' }}
135
+ native-heartbeat-seconds: ${{ inputs.native-heartbeat-seconds || 300 }}
136
+ delivery-class: ${{ github.event.client_payload.candidate.deliveryClass || inputs.delivery-class || 'native-proof-required' }}
137
+ delivery-priority: ${{ github.event.client_payload.candidate.priority || inputs.delivery-priority || 'ordinary' }}
138
+ queue-admission-context: Queue admission lease
139
+ active-lease-context: Queue family lease/exact
140
+ landing-mode: queue
141
+ dry-run: false
142
+ secrets:
143
+ github-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}