@kungfu-tech/buildchain 3.0.4-alpha.0 → 3.0.4-alpha.10

package/packages/core/release-propagation.js

@@ -1,37 +1,23 @@
-import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import {
+  assertPlainObject,
+  assertString,
+  RELEASE_PROPAGATION_PLAN_CONTRACT,
+  normalizeChannel,
+  optionalString,
+  sha256Json,
+  stableJson,
+} from "./release-propagation-common.js";
+import { normalizeExecutionProfile } from "./release-propagation-execution-profile.js";
+import { normalizeUpstreamRelease } from "./release-propagation-release.js";
 
 export const RELEASE_PROPAGATION_GRAPH_CONTRACT = "kungfu-buildchain-release-propagation-graph";
-export const RELEASE_PROPAGATION_PLAN_CONTRACT = "kungfu-buildchain-release-propagation-plan";
+export { RELEASE_PROPAGATION_PLAN_CONTRACT };
 export const RELEASE_PROPAGATION_LOCK_CONTRACT = "kungfu-buildchain-release-propagation-lock";
 export const RELEASE_PROPAGATION_RECEIPT_CONTRACT = "kungfu-buildchain-release-propagation-receipt";
-
-const SUPPORTED_CHANNELS = new Set(["alpha", "release"]);
 const SUPPORTED_CHANNEL_POLICIES = new Set(["preserve", "explicit"]);
 
-function stableJson(value) {
-  return `${JSON.stringify(sortJson(value), null, 2)}\n`;
-}
-
-function sortJson(value) {
-  if (Array.isArray(value)) {
-    return value.map(sortJson);
-  }
-  if (!value || typeof value !== "object") {
-    return value;
-  }
-  return Object.fromEntries(
-    Object.entries(value)
-      .sort(([left], [right]) => left.localeCompare(right))
-      .map(([key, entry]) => [key, sortJson(entry)]),
-  );
-}
-
-function sha256Json(value) {
-  return crypto.createHash("sha256").update(stableJson(value)).digest("hex");
-}
-
 function releaseVersion(upstreamRelease) {
   return upstreamRelease.package?.version || upstreamRelease.publicationArtifact?.version || "";
 }
@@ -75,32 +61,6 @@ function propagationBranch({ upstreamRelease, targetNode }) {
   return `buildchain/release-propagation/${repository}/${version}-${upstreamRelease.channel}-${digest}`;
 }
 
-function assertPlainObject(value, label) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`${label} must be an object`);
-  }
-  return value;
-}
-
-function assertString(value, label) {
-  if (typeof value !== "string" || value.trim() === "") {
-    throw new Error(`${label} must be a non-empty string`);
-  }
-  return value.trim();
-}
-
-function optionalString(value) {
-  return value === undefined || value === null ? "" : String(value).trim();
-}
-
-function normalizeChannel(value, label) {
-  const channel = assertString(value, label);
-  if (!SUPPORTED_CHANNELS.has(channel)) {
-    throw new Error(`${label} must be alpha or release`);
-  }
-  return channel;
-}
-
 function normalizeChannelMap(edge, label) {
   const policy = edge.channelPolicy || "preserve";
   if (!SUPPORTED_CHANNEL_POLICIES.has(policy)) {
@@ -130,6 +90,7 @@ function normalizeNode(node, index) {
     lockPath: optionalString(node.lockPath || node.lock_path),
     baseRef: optionalString(node.baseRef || node.base_ref),
     workflow: optionalString(node.workflow),
+    executionProfile: normalizeExecutionProfile(node.executionProfile || node.execution_profile, `nodes[${index}].executionProfile`),
   };
   if (!/^[^/\s]+\/[^/\s]+$/.test(normalized.repository)) {
     throw new Error(`nodes[${index}].repository must be owner/repo`);
@@ -235,112 +196,6 @@ export function resolvePropagationChannel(edge, upstreamChannel) {
   return downstreamChannel ? normalizeChannel(downstreamChannel, `edge ${edge.id} downstream channel`) : "";
 }
 
-function normalizeReleasePassport(passport = {}) {
-  if (!passport || typeof passport !== "object" || Array.isArray(passport)) {
-    throw new Error("upstreamRelease.releasePassport must be an object");
-  }
-  return {
-    url: assertString(passport.url, "upstreamRelease.releasePassport.url"),
-    sha256: assertString(passport.sha256 || passport.digest, "upstreamRelease.releasePassport.sha256"),
-  };
-}
-
-function normalizePackageFact(pkg = {}) {
-  if (!pkg || typeof pkg !== "object" || Array.isArray(pkg)) {
-    throw new Error("upstreamRelease.package must be an object");
-  }
-  return {
-    name: assertString(pkg.name, "upstreamRelease.package.name"),
-    version: assertString(pkg.version, "upstreamRelease.package.version"),
-    integrity: assertString(pkg.integrity, "upstreamRelease.package.integrity"),
-  };
-}
-
-function normalizeDigestUrlFact(value = {}, label) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`${label} must be an object`);
-  }
-  return {
-    url: assertString(value.url, `${label}.url`),
-    sha256: assertString(value.sha256 || value.digest, `${label}.sha256`),
-  };
-}
-
-function normalizeOptionalPathDigestUrlFact(value = undefined, label) {
-  if (value === undefined || value === null) {
-    return undefined;
-  }
-  const normalized = normalizeDigestUrlFact(value, label);
-  return {
-    path: optionalString(value.path),
-    bytes: value.bytes === undefined ? undefined : Number(value.bytes),
-    ...normalized,
-  };
-}
-
-function normalizePublicationArtifactFact(value = undefined) {
-  if (value === undefined || value === null) {
-    return undefined;
-  }
-  const artifact = assertPlainObject(value, "upstreamRelease.publicationArtifact");
-  return {
-    id: optionalString(artifact.id),
-    kind: optionalString(artifact.kind),
-    version: assertString(artifact.version, "upstreamRelease.publicationArtifact.version"),
-    canonicalUrl: assertString(
-      artifact.canonicalUrl || artifact.canonical_url,
-      "upstreamRelease.publicationArtifact.canonicalUrl",
-    ),
-    latestUrl: assertString(
-      artifact.latestUrl || artifact.latest_url,
-      "upstreamRelease.publicationArtifact.latestUrl",
-    ),
-    latestEvidenceUrl: optionalString(artifact.latestEvidenceUrl || artifact.latest_evidence_url),
-    immutableVersionUrl: assertString(
-      artifact.immutableVersionUrl || artifact.immutable_version_url || artifact.immutableVersionPrefix || artifact.immutable_version_prefix,
-      "upstreamRelease.publicationArtifact.immutableVersionUrl",
-    ),
-    immutableVersionPrefix: optionalString(artifact.immutableVersionPrefix || artifact.immutable_version_prefix),
-    registry: normalizeDigestUrlFact(artifact.registry, "upstreamRelease.publicationArtifact.registry"),
-    manifest: normalizeDigestUrlFact(artifact.manifest, "upstreamRelease.publicationArtifact.manifest"),
-    passport: normalizeDigestUrlFact(artifact.passport, "upstreamRelease.publicationArtifact.passport"),
-    primaryArtifact: normalizeOptionalPathDigestUrlFact(
-      artifact.primaryArtifact || artifact.primary_artifact,
-      "upstreamRelease.publicationArtifact.primaryArtifact",
-    ),
-    sourceBundle: normalizeOptionalPathDigestUrlFact(
-      artifact.sourceBundle || artifact.source_bundle,
-      "upstreamRelease.publicationArtifact.sourceBundle",
-    ),
-  };
-}
-
-function normalizeUpstreamRelease(input) {
-  const release = assertPlainObject(input, "upstreamRelease");
-  const publicationArtifact = normalizePublicationArtifactFact(release.publicationArtifact || release.publication_artifact);
-  const packageFact = release.package === undefined ? undefined : normalizePackageFact(release.package);
-  if (!packageFact && !publicationArtifact) {
-    throw new Error("upstreamRelease requires package or publicationArtifact");
-  }
-  return {
-    repository: assertString(release.repository, "upstreamRelease.repository"),
-    channel: normalizeChannel(release.channel, "upstreamRelease.channel"),
-    tag: assertString(release.tag, "upstreamRelease.tag"),
-    sourceSha: assertString(release.sourceSha || release.source_sha, "upstreamRelease.sourceSha"),
-    package: packageFact,
-    publicationArtifact,
-    releasePassport: normalizeReleasePassport(release.releasePassport || release.release_passport),
-    siteBundle: release.siteBundle || release.site_bundle
-      ? {
-        manifestSha256: assertString(
-          release.siteBundle?.manifestSha256 || release.site_bundle?.manifest_sha256,
-          "upstreamRelease.siteBundle.manifestSha256",
-        ),
-      }
-      : undefined,
-  };
-}
-
 export function createReleasePropagationLock({
   graph,
   edge,
@@ -359,6 +214,7 @@ export function createReleasePropagationLock({
       repository: upstreamRelease.repository,
       channel: upstreamRelease.channel,
       tag: upstreamRelease.tag,
+      tagTargetSha: upstreamRelease.tagTargetSha,
       sourceSha: upstreamRelease.sourceSha,
       package: upstreamRelease.package,
       publicationArtifact: upstreamRelease.publicationArtifact,
@@ -371,6 +227,7 @@ export function createReleasePropagationLock({
       channel: downstreamChannel,
       baseRef: edge.prBaseRef || targetNode.baseRef,
       lockPath: edge.lockPath || targetNode.lockPath || ".buildchain/upstream-release.lock.json",
+      executionProfile: targetNode.executionProfile,
     },
     propagation: {
       graphContract: graph.contract,
@@ -423,6 +280,7 @@ export function planReleasePropagation({ graph: graphInput, upstreamRelease: rel
       channel: downstreamChannel,
       baseRef: lock.downstream.baseRef,
       lockPath: lock.downstream.lockPath,
+      executionProfile: lock.downstream.executionProfile,
       propagationKey: lock.propagation.propagationKey,
       branch: lock.propagation.branch,
       lock,
@@ -548,6 +406,7 @@ export function createReleasePropagationReceipt({
             name: upstreamRelease.package.name,
             version: upstreamRelease.package.version,
             integrity: upstreamRelease.package.integrity,
+            gitHead: upstreamRelease.package.gitHead,
           }
         : null,
     },
@@ -576,6 +435,7 @@ export function createReleasePropagationReceipt({
     upstream: {
       repository: upstreamRelease.repository,
       tag: upstreamRelease.tag,
+      tagTargetSha: upstreamRelease.tagTargetSha,
       sourceSha: upstreamRelease.sourceSha,
       releasePassport: upstreamRelease.releasePassport,
     },
@@ -595,3 +455,19 @@ export function createReleasePropagationReceipt({
     receiptSha256: sha256Json(body),
   };
 }
+
+export {
+  RELEASE_PROPAGATION_STAGE_RECEIPT_CONTRACT,
+  RELEASE_PROPAGATION_WORK_CONTRACT,
+  RELEASE_PROPAGATION_WORK_STAGES,
+  createReleasePropagationStageReceipt,
+  createReleasePropagationWork,
+  resumeReleasePropagationWork,
+  verifyReleasePropagationWork,
+} from "./release-propagation-work.js";
+export {
+  claimReleasePropagationWork,
+  completeReleasePropagationWork,
+  recordReleasePropagationStage,
+  repairReleasePropagationWork,
+} from "./release-propagation-work-transitions.js";

package/scripts/aggregate-build-summary.mjs

@@ -8,6 +8,51 @@ function readEnv(name, fallback = "") {
   return process.env[name] || fallback;
 }
 
+function parsePlatformIds(name) {
+  const raw = readEnv(name, "").trim();
+  if (!raw) return [];
+  const parsed = JSON.parse(raw);
+  if (!Array.isArray(parsed)) {
+    throw new Error(`${name} must be a JSON array`);
+  }
+  const ids = parsed.map((entry) => String(
+    typeof entry === "string" ? entry : entry?.id || "",
+  ).trim());
+  if (ids.some((id) => !id)) {
+    throw new Error(`${name} entries must declare non-empty platform ids`);
+  }
+  if (new Set(ids).size !== ids.length) {
+    throw new Error(`${name} must not contain duplicate platform ids`);
+  }
+  return ids;
+}
+
+function readManifest(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function selectPlatformManifests({ inputRoot, expectedPlatformIds }) {
+  const candidates = findJsonFiles(inputRoot)
+    .filter((file) => path.basename(file) === "manifest.json")
+    .sort()
+    .map((file) => ({ file, manifest: readManifest(file) }))
+    .filter(({ manifest }) => manifest?.contract === "kungfu-buildchain-artifact");
+  if (expectedPlatformIds.length === 0) return candidates;
+  return expectedPlatformIds.map((platformId) => {
+    const matches = candidates.filter(({ manifest }) => manifest.platform?.id === platformId);
+    if (matches.length !== 1) {
+      throw new Error(
+        `expected exactly one platform manifest for ${platformId}, found ${matches.length} under ${inputRoot}`,
+      );
+    }
+    return matches[0];
+  });
+}
+
 export function aggregateBuildSummaryCli() {
   const inputRoot = path.resolve(readEnv("BUILDCHAIN_SUMMARY_INPUT", ".buildchain/downloaded-manifests"));
   const outputPath = path.resolve(readEnv("BUILDCHAIN_SUMMARY_OUTPUT", ".buildchain/artifacts/build-summary.json"));
@@ -18,10 +63,28 @@ export function aggregateBuildSummaryCli() {
     throw new Error("BUILDCHAIN_ADDITIONAL_PLATFORM_COUNT must be a non-negative integer");
   }
   const expectedManifestCount = expectedPlatformCount + additionalPlatformCount;
-  const manifestFiles = findJsonFiles(inputRoot)
-    .filter((file) => path.basename(file) === "manifest.json")
-    .sort();
-  const manifests = manifestFiles.map((file) => JSON.parse(fs.readFileSync(file, "utf8")));
+  const platformIds = parsePlatformIds("BUILDCHAIN_EXPECTED_PLATFORMS_JSON");
+  const additionalPlatformIds = parsePlatformIds("BUILDCHAIN_ADDITIONAL_PLATFORM_IDS_JSON");
+  if (platformIds.length > 0 && platformIds.length !== expectedPlatformCount) {
+    throw new Error(
+      `BUILDCHAIN_EXPECTED_PLATFORMS_JSON declares ${platformIds.length} platforms, expected ${expectedPlatformCount}`,
+    );
+  }
+  if (additionalPlatformIds.length !== additionalPlatformCount) {
+    throw new Error(
+      `BUILDCHAIN_ADDITIONAL_PLATFORM_IDS_JSON declares ${additionalPlatformIds.length} platforms, expected ${additionalPlatformCount}`,
+    );
+  }
+  const expectedPlatformIds = [...platformIds, ...additionalPlatformIds];
+  if (new Set(expectedPlatformIds).size !== expectedPlatformIds.length) {
+    throw new Error("declared platform ids must be unique across primary and additional platforms");
+  }
+  const selected = selectPlatformManifests({
+    inputRoot,
+    expectedPlatformIds,
+  });
+  const manifestFiles = selected.map(({ file }) => file);
+  const manifests = selected.map(({ manifest }) => manifest);
   if (expectedManifestCount > 0 && manifests.length !== expectedManifestCount) {
     throw new Error(
       `expected ${expectedManifestCount} platform manifests, found ${manifests.length} under ${inputRoot}`,

package/scripts/auditable-demo-renditions.mjs

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const TERMINAL_CAPTURE_NON_AUTHORITIES = [
+  "first-party-identity",
+  "system-identity",
+  "kfd-compliance",
+  "product-system-metadata",
+  "package-metadata",
+  "registry-history",
+  "scan-output",
+  "standalone-generation",
+];
+const RENDITION_SET_NON_AUTHORITIES = [
+  "publication-authority",
+  "runtime-authority",
+  ...TERMINAL_CAPTURE_NON_AUTHORITIES,
+];
+
+export function validateTerminalCapture(value, scene, helpers) {
+  const { decodeBase64, digestPattern, exactKeys, integer, invariant, maxBytes, maxEvents, text } = helpers;
+  exactKeys(
+    value,
+    ["schema", "command", "dimensions", "durationMs", "encoding", "events", "completion", "exitCode", "authority"],
+    [],
+    "terminalCapture",
+  );
+  invariant(value.schema === "kungfu.terminal-capture/v1", "unsupported terminal capture schema");
+  text(value.command, 1, 160, "terminalCapture.command");
+  exactKeys(value.dimensions, ["columns", "rows"], [], "terminalCapture.dimensions");
+  integer(value.dimensions.columns, 80, 200, "terminalCapture.dimensions.columns");
+  integer(value.dimensions.rows, 24, 80, "terminalCapture.dimensions.rows");
+  const durationMs = integer(value.durationMs, 500, 60000, "terminalCapture.durationMs");
+  invariant(
+    durationMs <= scene.durationMs && scene.durationMs - durationMs <= 2000,
+    "terminal capture duration must end within two seconds of the scene",
+  );
+  invariant(value.encoding === "base64", "terminalCapture.encoding must be base64");
+  invariant(
+    Array.isArray(value.events) && value.events.length > 0 && value.events.length <= maxEvents,
+    `terminalCapture.events must contain 1 through ${maxEvents} events`,
+  );
+  let previousAtMs = -1;
+  let totalBytes = 0;
+  for (const [index, event] of value.events.entries()) {
+    exactKeys(event, ["atMs", "data"], [], `terminalCapture.events[${index}]`);
+    const atMs = integer(event.atMs, 0, durationMs - 1, `terminalCapture.events[${index}].atMs`);
+    invariant(atMs >= previousAtMs, "terminal capture event timestamps must be monotonic");
+    invariant(index > 0 || atMs === 0, "the first terminal capture event must start at zero");
+    previousAtMs = atMs;
+    totalBytes += decodeBase64(event.data, `terminalCapture.events[${index}].data`).length;
+    invariant(totalBytes <= maxBytes, "terminal capture exceeds the 4 MiB byte bound");
+  }
+  exactKeys(value.completion, ["schema", "status", "reportRoot", "eventCount"], [], "terminalCapture.completion");
+  invariant(
+    value.completion.schema === "kungfu.agent-work-lab.tui-autoplay/v1"
+      && value.completion.status === "qualified"
+      && digestPattern.test(value.completion.reportRoot),
+    "terminal capture completion sentinel is not a qualified Agent Work Lab autoplay",
+  );
+  integer(value.completion.eventCount, 1, 100_000, "terminalCapture.completion.eventCount");
+  invariant(value.exitCode === 0, "terminal capture exitCode must be zero");
+  exactKeys(value.authority, ["classification", "grants", "nonAuthorities"], [], "terminalCapture.authority");
+  invariant(value.authority.classification === "volatile-terminal-observation", "terminal capture authority classification must remain observation-only");
+  invariant(Array.isArray(value.authority.grants) && value.authority.grants.length === 0, "terminal capture must not grant authority");
+  invariant(
+    JSON.stringify(value.authority.nonAuthorities) === JSON.stringify(TERMINAL_CAPTURE_NON_AUTHORITIES),
+    "terminal capture must declare every identity and metadata non-authority",
+  );
+  return value;
+}
+
+export function validateRenditionSet(output, helpers) {
+  const { decodeUtf8, exactKeys, invariant, maxBytes, readJson, readRegular, sha256, validateProjection, validateScene } = helpers;
+  const manifestPath = path.join(output, "rendition-set.json");
+  if (!fs.existsSync(manifestPath)) return null;
+  const value = readJson(manifestPath, "rendition set");
+  exactKeys(value, ["schema", "renditions", "authority"], [], "renditionSet");
+  invariant(value.schema === "kungfu.auditable-demo.rendition-set/v1", "unsupported rendition set schema");
+  exactKeys(value.authority, ["classification", "grants", "nonAuthorities"], [], "renditionSet.authority");
+  invariant(
+    value.authority.classification === "capture-routing-metadata"
+      && Array.isArray(value.authority.grants)
+      && value.authority.grants.length === 0
+      && JSON.stringify(value.authority.nonAuthorities) === JSON.stringify(RENDITION_SET_NON_AUTHORITIES),
+    "rendition set authority boundary is invalid",
+  );
+  invariant(Array.isArray(value.renditions) && value.renditions.length === 2, "rendition set must contain exactly two captures");
+  const expected = [
+    {
+      id: "1080p", role: "primary", transcript: "complete-transcript.txt",
+      projection: "public-projection.json", scene: "scene.json", terminalCapture: "terminal-capture.json",
+      width: 1920, height: 1080,
+    },
+    {
+      id: "720p", role: "responsive", transcript: "complete-transcript-720p.txt",
+      projection: "public-projection-720p.json", scene: "scene-720p.json", terminalCapture: "terminal-capture-720p.json",
+      width: 1280, height: 720,
+    },
+  ];
+  const normalized = value.renditions.map((entry, index) => {
+    const label = `renditionSet.renditions[${index}]`;
+    exactKeys(entry, ["id", "role", "transcript", "projection", "scene", "terminalCapture", "captureRoot"], [], label);
+    const declaration = expected[index];
+    for (const key of ["id", "role", "transcript", "projection", "scene", "terminalCapture"]) {
+      invariant(entry[key] === declaration[key], `${label}.${key} is not the exact native rendition contract`);
+    }
+    const transcriptBytes = readRegular(path.join(output, entry.transcript), `${label} transcript`, 4 * 1024 * 1024);
+    const transcript = decodeUtf8(transcriptBytes, `${label} transcript`).replace(/\r\n/g, "\n");
+    invariant(transcript.trim().length > 0, `${label} transcript must not be empty`);
+    const lines = transcript.endsWith("\n") ? transcript.slice(0, -1).split("\n") : transcript.split("\n");
+    const scene = validateScene(readJson(path.join(output, entry.scene), `${label} scene`));
+    invariant(scene.width === declaration.width && scene.height === declaration.height, `${label} scene dimensions are not native`);
+    const projection = validateProjection(readJson(path.join(output, entry.projection), `${label} projection`), scene, lines.length);
+    const captureBytes = readRegular(path.join(output, entry.terminalCapture), `${label} terminal capture`, maxBytes);
+    const capture = validateTerminalCapture(JSON.parse(decodeUtf8(captureBytes, `${label} terminal capture`)), scene, helpers);
+    invariant(entry.captureRoot === sha256(captureBytes), `${label}.captureRoot mismatch`);
+    return { ...entry, transcript, lines, scene, projection, capture };
+  });
+  invariant(normalized[0].captureRoot !== normalized[1].captureRoot, "native rendition capture roots must be distinct");
+  invariant(
+    JSON.stringify(normalized[0].capture.dimensions) !== JSON.stringify(normalized[1].capture.dimensions),
+    "native rendition PTY dimensions must be distinct",
+  );
+  invariant(
+    normalized[0].projection.evidenceClass === normalized[1].projection.evidenceClass
+      && normalized[0].projection.claimBoundary === normalized[1].projection.claimBoundary,
+    "native rendition evidence boundaries must match",
+  );
+  return { schema: value.schema, renditions: normalized, authority: value.authority };
+}