@kungfu-tech/buildchain 3.0.6 → 3.0.7-alpha.1

package/scripts/resume-from-candidate-run.mjs

@@ -95,12 +95,18 @@ function findFiles(root, predicate) {
   return collectFiles(root).filter((file) => predicate(file.path, file.absolutePath));
 }
 
+export function recoveredArtifactPathsByBasename(downloads, filename) {
+  return downloads.flatMap((download) => download.files
+    .filter((file) => path.basename(file.path) === filename)
+    .map((file) => outputPath(file.absolutePath)));
+}
+
 function readOnlyJson(files, label) {
   if (files.length !== 1) throw new Error(`expected exactly one ${label}, found ${files.length}`);
   return JSON.parse(fs.readFileSync(files[0].absolutePath, "utf8"));
 }
 
-async function readExistingTransaction({ repoInfo, apiUrl, token, fetchImpl, version }) {
+export async function readExistingTransaction({ repoInfo, apiUrl, token, fetchImpl, version }) {
   const stateRef = releaseTransactionStateRef(version);
   const response = await githubJson({
     apiUrl,
@@ -110,10 +116,31 @@ async function readExistingTransaction({ repoInfo, apiUrl, token, fetchImpl, ver
     path: `/repos/${repoInfo.owner}/${repoInfo.repo}/contents/state.json?ref=${encodeURIComponent(stateRef)}`,
   });
   if (!response) return undefined;
-  if (response.type !== "file" || response.encoding !== "base64" || !response.content) {
-    throw new Error(`durable transaction ${stateRef} did not expose a base64 state.json file`);
+  if (response.type !== "file") {
+    throw new Error(`durable transaction ${stateRef} did not expose a state.json file`);
+  }
+  let encoded = response.encoding === "base64" && response.content
+    ? response
+    : undefined;
+  if (!encoded) {
+    const blobSha = String(response.sha || "").trim();
+    if (!/^[0-9a-f]{40}$/i.test(blobSha)) {
+      throw new Error(`durable transaction ${stateRef} did not expose inline content or an exact blob identity`);
+    }
+    encoded = await githubJson({
+      apiUrl,
+      token,
+      fetchImpl,
+      path: `/repos/${repoInfo.owner}/${repoInfo.repo}/git/blobs/${blobSha}`,
+    });
+    if (String(encoded?.sha || "").trim() !== blobSha) {
+      throw new Error(`durable transaction ${stateRef} blob identity drifted from ${blobSha}`);
+    }
+  }
+  if (encoded?.encoding !== "base64" || !encoded.content) {
+    throw new Error(`durable transaction ${stateRef} did not expose base64 state.json content`);
   }
-  return JSON.parse(Buffer.from(String(response.content).replace(/\s/g, ""), "base64").toString("utf8"));
+  return JSON.parse(Buffer.from(String(encoded.content).replace(/\s/g, ""), "base64").toString("utf8"));
 }
 
 function outputPath(filePath) {
@@ -180,6 +207,7 @@ function candidateArtifactNames({ passport, selected, artifacts, artifactPattern
 
 export function normalizePlatformManifests(downloads, passport) {
   const manifests = [];
+  const paths = [];
   const evidenceByArtifact = new Map();
   const platformById = new Map((passport.platformMatrix || []).map((entry) => [String(entry.platformId || ""), entry]));
   const seenPlatformIds = new Set();
@@ -208,6 +236,7 @@ export function normalizePlatformManifests(downloads, passport) {
       manifest.artifactName = expectedPlatform.artifactName;
       seenPlatformIds.add(platformId);
       manifests.push(manifest);
+      paths.push(file.absolutePath);
       addEvidence(manifest.artifactName, download.record.files);
     }
     if (String(download.artifact.name).includes("-diagnostics-")) {
@@ -222,7 +251,7 @@ export function normalizePlatformManifests(downloads, passport) {
     artifactName,
     files: [...files.values()].sort((left, right) => left.path.localeCompare(right.path)),
   }));
-  return { manifests, evidence };
+  return { manifests, paths, evidence };
 }
 
 function normalizeControllerReceipts(downloads, passport) {
@@ -268,16 +297,53 @@ export function createRecoveredPublicationCandidate({
   return { ...payload, candidateDigest: publicationArtifactCandidateDigest(payload) };
 }
 
+export function deduplicateReleaseAssets(files = []) {
+  const assets = new Map();
+  for (const file of files) {
+    const name = path.basename(file.path);
+    const existing = assets.get(name);
+    if (!existing) {
+      assets.set(name, file);
+      continue;
+    }
+    const digest = String(file.sha256 || "").replace(/^sha256:/, "");
+    const existingDigest = String(existing.sha256 || "").replace(/^sha256:/, "");
+    if (digest !== existingDigest || Number(file.size) !== Number(existing.size)) {
+      throw new Error(
+        `recovered GitHub Release asset basename collision: ${name} maps to different sealed bytes`,
+      );
+    }
+    if (
+      String(file.path).length < String(existing.path).length ||
+      (String(file.path).length === String(existing.path).length &&
+        String(file.path).localeCompare(String(existing.path)) < 0)
+    ) {
+      assets.set(name, file);
+    }
+  }
+  return [...assets.values()].sort((left, right) =>
+    path.basename(left.path).localeCompare(path.basename(right.path)),
+  );
+}
+
 export function createRecoveredPublication({ downloads, bundleRoot, repository, passport, candidateRuntimeSha, publishArtifactKind, publishPackageMain, releasePatterns, platformManifests }) {
   const allFiles = downloads.flatMap((download) => download.files.map((file) => ({
     path: path.relative(bundleRoot, file.absolutePath).split(path.sep).join("/"),
     size: file.size,
     sha256: file.sha256.replace(/^sha256:/, ""),
     absolutePath: file.absolutePath,
+    artifactName: String(download.artifact?.name || ""),
   }))).sort((left, right) => left.path.localeCompare(right.path));
   const kind = String(publishArtifactKind || "npm");
   const releaseMatchers = splitPatterns(releasePatterns).map(patternMatcher);
-  const releaseAssets = allFiles.filter((file) => releaseMatchers.some((matcher) => matcher.test(path.basename(file.path))));
+  const platformArtifactNames = new Set(
+    platformManifests.map((manifest) => String(manifest.artifactName || "")).filter(Boolean),
+  );
+  const releaseAssetFiles = kind !== "npm" && platformArtifactNames.size > 0
+    ? allFiles.filter((file) => platformArtifactNames.has(file.artifactName))
+    : allFiles;
+  const releaseAssets = deduplicateReleaseAssets(releaseAssetFiles.filter((file) =>
+    releaseMatchers.some((matcher) => matcher.test(path.basename(file.path)))));
   if (kind !== "npm") {
     createRecoveredPublicationCandidate({ allFiles, repository, passport, candidateRuntimeSha });
     const version = String(passport.target?.version || "").trim();
@@ -367,6 +433,42 @@ async function recoverCandidateEvidence({
   };
 }
 
+export function exposeRecoveredPayloadRoot({ resolvedOutput, bundleRoot }) {
+  const recoveredPayloadRoot = path.join(bundleRoot, "artifacts");
+  if (!fs.existsSync(recoveredPayloadRoot) || !fs.statSync(recoveredPayloadRoot).isDirectory()) {
+    throw new Error(`recovered candidate payload root is missing: ${recoveredPayloadRoot}`);
+  }
+  const compatibilityRoot = path.join(resolvedOutput, "payloads");
+  try {
+    fs.lstatSync(compatibilityRoot);
+    if (fs.realpathSync(compatibilityRoot) !== fs.realpathSync(recoveredPayloadRoot)) {
+      throw new Error(`recovered candidate payload compatibility path is already occupied: ${compatibilityRoot}`);
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+    fs.symlinkSync(path.relative(resolvedOutput, recoveredPayloadRoot), compatibilityRoot, "dir");
+  }
+  return compatibilityRoot;
+}
+
+export function exposeRecoveredPassportPath({ resolvedOutput, recoveredPassportPath }) {
+  if (!fs.existsSync(recoveredPassportPath) || !fs.statSync(recoveredPassportPath).isFile()) {
+    throw new Error(`recovered candidate passport is missing: ${recoveredPassportPath}`);
+  }
+  const recoveredPassportRoot = path.dirname(recoveredPassportPath);
+  const compatibilityRoot = path.join(resolvedOutput, "passport");
+  try {
+    fs.lstatSync(compatibilityRoot);
+    if (fs.realpathSync(compatibilityRoot) !== fs.realpathSync(recoveredPassportRoot)) {
+      throw new Error(`recovered candidate passport compatibility path is already occupied: ${compatibilityRoot}`);
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+    fs.symlinkSync(path.relative(resolvedOutput, recoveredPassportRoot), compatibilityRoot, "dir");
+  }
+  return path.join(compatibilityRoot, path.basename(recoveredPassportPath));
+}
+
 async function resolveTargetAdvance({ observedTargetSha, targetSha, transactionId, existingTransaction, repoInfo, apiUrl, token, fetchImpl }) {
   if (observedTargetSha === targetSha || !transactionId || existingTransaction?.id !== transactionId) return undefined;
   const comparison = await githubJson({ apiUrl, token, fetchImpl, path: `/repos/${repoInfo.owner}/${repoInfo.repo}/compare/${targetSha}...${observedTargetSha}` });
@@ -494,7 +596,16 @@ export async function resumeFromCandidateRun({
     if (publication.manifest) fs.writeFileSync(sealedManifestPath, `${JSON.stringify(publication.manifest, null, 2)}\n`);
     const publishRequiredArtifacts = publication.publishRequiredArtifacts;
     fs.writeFileSync(requiredArtifactsPath, `${JSON.stringify(publishRequiredArtifacts, null, 2)}\n`);
+    const payloadRoot = exposeRecoveredPayloadRoot({ resolvedOutput, bundleRoot });
+    const recoveredPassportPath = initialDownloads[0].files.find(
+      (file) => path.basename(file.path) === "release-candidate-passport.json",
+    ).absolutePath;
+    const passportPath = exposeRecoveredPassportPath({ resolvedOutput, recoveredPassportPath });
     const tarballs = publication.npmArtifacts.map((entry) => outputPath(entry.file.absolutePath));
+    const githubArtifactAttestationPolicies = recoveredArtifactPathsByBasename(
+      downloads,
+      "github-artifact-attestation-policy.json",
+    );
     return {
       enabled: true,
       action: "reused",
@@ -507,10 +618,11 @@ export async function resumeFromCandidateRun({
       receipt: recovery.receipt,
       publishRequiredArtifacts,
       paths: {
-        passport: outputPath(initialDownloads[0].files.find((file) => path.basename(file.path) === "release-candidate-passport.json").absolutePath),
+        passport: outputPath(passportPath),
         buildSummary: outputPath(initialDownloads[1].files.find((file) => path.basename(file.path) === "build-summary.json").absolutePath),
-        payloads: outputPath(path.join(bundleRoot, "artifacts")),
-        platformManifests: downloads.flatMap((download) => download.files.filter((file) => path.basename(file.path) === "manifest.json").map((file) => outputPath(file.absolutePath))),
+        payloads: outputPath(payloadRoot),
+        platformManifests: platformManifestEvidence.paths.map(outputPath),
+        githubArtifactAttestationPolicies,
         npmTarballs: tarballs,
         releaseAssets: publication.releaseAssets.map((asset) => outputPath(asset.absolutePath)),
         publishRequiredArtifacts: outputPath(requiredArtifactsPath),
@@ -560,6 +672,8 @@ export async function resumeFromCandidateRunCli() {
       "release-candidate-payload-artifacts": result.artifacts.payloads.join(","),
       "release-candidate-payload-dir": result.paths.payloads,
       "release-candidate-platform-manifest-paths": result.paths.platformManifests.join(","),
+      "release-candidate-github-artifact-attestation-policy-paths": result.paths.githubArtifactAttestationPolicies.join(","),
+      "release-candidate-github-artifact-attestation-policy-count": String(result.paths.githubArtifactAttestationPolicies.length),
       "release-candidate-npm-tarball-paths": result.paths.npmTarballs.join(","),
       "release-candidate-github-release-artifact-paths": result.paths.releaseAssets.join("\n"),
       "publish-required-artifacts-json": JSON.stringify(result.publishRequiredArtifacts),

package/scripts/seal-artifact-signing-requests.mjs

@@ -376,6 +376,12 @@ export function sealArtifactSigningRequests({
       signature: {
         profile: declaration.profile,
         required: declaration.required,
+        ...(declaration.entitlementsProfile !== "none"
+          ? {
+              entitlementsProfile: declaration.entitlementsProfile,
+              entitlementsPaths: declaration.entitlementsPaths,
+            }
+          : {}),
       },
     });
     const check = validateArtifactSigningRequest(request);

package/scripts/site-capability-metadata.mjs

@@ -12,6 +12,11 @@ function capabilityGroup(id) {
 export function cliCommandMeta(id) {
   const map = new Map(Object.entries({
     audit: { group: "release-passport-trust", purpose: "Inspect read-only publication authority audit commands." },
+    architecture: { group: "governance-versioning", purpose: "Inspect and qualify the Buildchain v4 capability and state-machine architecture contract." },
+    "architecture-list": { group: "governance-versioning", purpose: "Generate the Agent-readable capability list from the validated v4 architecture manifest." },
+    "architecture-qualify": { group: "governance-versioning", purpose: "Qualify an exact candidate against a distinct N-1 Git authority revision without candidate self-qualification." },
+    "architecture-show": { group: "governance-versioning", purpose: "Generate one capability and its state-machine details from the validated v4 architecture manifest." },
+    "architecture-validate": { group: "governance-versioning", purpose: "Validate v4 dependency direction, ownership, writers, budgets, recovery declarations, and exception policy." },
     "audit-publication-control-plane": { group: "release-passport-trust", purpose: "Read GitHub publication controls, bind provider-enforced npm identity, and emit a sanitized expiring receipt." },
     "audit-github-governance": { group: "governance-versioning", purpose: "Read the managed GitHub zone, aggregate native protection and ownership, and emit sanitized fail-closed governance receipts." },
     badges: { group: "distribution-indexes", purpose: "Inspect README badge command families." },
@@ -134,6 +139,7 @@ export function cliCommandMeta(id) {
     "release-line-open": { group: "governance-versioning", purpose: "Plan or write the initial version-state commit for a new minor release line." },
     "release-governance": { group: "governance-versioning", purpose: "Reconcile a managed branch's Buildchain aggregate check to an already-tested pull request SHA." },
     "release-propagation": { group: "site-and-propagation", purpose: "Route exact Paper, KFD, Buildchain, or Core Site updates through one resumable propagation Work." },
+    "release-tail": { group: "release-passport-trust", purpose: "Plan, initialize, rehearse, resume, and verify one declarative provider-owned release-tail transaction." },
     "release-transaction": { group: "release-passport-trust", purpose: "Inspect, recover, finalize, or abort durable release transactions." },
     sample: { group: "observability-diagnostics", purpose: "Inspect sampler command families." },
     "sample-process-tree": { group: "observability-diagnostics", purpose: "Sample process-tree diagnostics for a wrapped command." },
@@ -182,6 +188,8 @@ export function nodeApiMeta(exportName) {
     "./publication-control-plane-audit": { group: "release-passport-trust", summary: "Read-only publication control-plane snapshot evaluation APIs." },
     "./buildchain-publication-authority": { group: "release-passport-trust", summary: "Buildchain-owned closed-world publication authority descriptor registry." },
     "./github-governance-authority": { group: "governance-versioning", summary: "Fail-closed GitHub ownership, effective-policy, managed-zone admission, rollout-plan, and immutable receipt APIs." },
+    "./engineering-housekeeper": { group: "governance-versioning", summary: "Provider-neutral repository hygiene classification, deterministic plan and receipt, apply-time revalidation, and replay APIs." },
+    "./engineering-housekeeper-github": { group: "governance-versioning", summary: "Paginated GitHub repository hygiene inventory, default-dry-run execution, exact-head mutation fences, and rooted provider receipts." },
     "./artifact-passport": { group: "release-passport-trust", summary: "Artifact passport digest and evidence helper APIs." },
     "./artifact-verification-envelope": { group: "release-passport-trust", summary: "Sealed exact-root, lifecycle, identity, and existing KFD assessment inputs for KFX admission." },
     "./artifact-signing": { group: "reusable-build", summary: "Credential-free artifact signing declarations, source-bound requests, authority receipts, profile resolution, and fail-closed validation APIs." },
@@ -197,6 +205,11 @@ export function nodeApiMeta(exportName) {
     "./stable-candidate-ledger": { group: "governance-versioning", summary: "Immutable alpha candidate ledger, qualification, revocation, selection, and exact stable source-lock APIs." },
     "./release-propagation": { group: "site-and-propagation", summary: "Release propagation graph, plan, and exact upstream lock APIs." },
     "./release-activation-transaction": { group: "release-passport-trust", summary: "Ordered cross-repository activation, exact receipt-set binding, retry, abort, rollback, and shadow-rehearsal APIs." },
+    "./release-tail-provider-plane": { group: "release-passport-trust", summary: "Versioned declarative release-tail parsing, deterministic effect planning, durable transaction execution, readback, retry, and rooted receipt APIs." },
+    "./release-tail-provider-adapters": { group: "release-passport-trust", summary: "Buildchain-owned GitHub Release, signed-channel, activation, and released-evidence provider adapters." },
+    "./release-tail-compatibility": { group: "release-passport-trust", summary: "Bounded v3 release-hook compatibility diagnostics that reject new executable release-tail inputs." },
+    "./publication-rehearsal-runtime": { group: "release-passport-trust", summary: "Content-addressed local, replay, and provider-recording publication rehearsal over the shared release-tail core." },
+    "./publication-rehearsal-projection": { group: "release-passport-trust", summary: "Canonical generated config, workflow, and Agent projections for release local constructibility." },
     "./release-line-bootstrap": { group: "governance-versioning", summary: "Semver release-line bootstrap planning and version-state APIs." },
     "./buildchain-contract": { group: "governance-versioning", summary: "Runtime contract world and compatibility digest APIs for floating-ref drift checks." },
     "./controller-evidence": { group: "reusable-build", summary: "Project-independent controller descriptors, source/runtime-bound plans, receipts, aggregates, and validation APIs." },