@kungfu-tech/buildchain 3.0.3-alpha.0 → 3.0.3-alpha.2

package/packages/core/release-propagation.js

@@ -5,6 +5,7 @@ import path from "node:path";
 export const RELEASE_PROPAGATION_GRAPH_CONTRACT = "kungfu-buildchain-release-propagation-graph";
 export const RELEASE_PROPAGATION_PLAN_CONTRACT = "kungfu-buildchain-release-propagation-plan";
 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"]);
@@ -31,6 +32,49 @@ function sha256Json(value) {
   return crypto.createHash("sha256").update(stableJson(value)).digest("hex");
 }
 
+function releaseVersion(upstreamRelease) {
+  return upstreamRelease.package?.version || upstreamRelease.publicationArtifact?.version || "";
+}
+
+function safeBranchPart(value) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9._-]+/g, "-")
+    .replaceAll(/^-+|-+$/g, "");
+  if (!normalized) {
+    throw new Error(`release propagation branch component is empty: ${value}`);
+  }
+  return normalized;
+}
+
+function releaseIdentity(upstreamRelease) {
+  const version = releaseVersion(upstreamRelease);
+  if (!version) {
+    throw new Error("upstream release does not expose a package or publication version");
+  }
+  return {
+    repository: upstreamRelease.repository,
+    version,
+    channel: upstreamRelease.channel,
+  };
+}
+
+function propagationIdentity({ upstreamRelease, targetNode }) {
+  return {
+    release: releaseIdentity(upstreamRelease),
+    downstreamRepository: targetNode.repository,
+  };
+}
+
+function propagationBranch({ upstreamRelease, targetNode }) {
+  const identity = propagationIdentity({ upstreamRelease, targetNode });
+  const digest = sha256Json(identity).slice(0, 12);
+  const repository = safeBranchPart(upstreamRelease.repository.replace("/", "-"));
+  const version = safeBranchPart(releaseVersion(upstreamRelease));
+  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`);
@@ -305,6 +349,8 @@ export function createReleasePropagationLock({
   upstreamRelease,
   downstreamChannel,
 } = {}) {
+  const identity = propagationIdentity({ upstreamRelease, targetNode });
+  const propagationKey = sha256Json(identity);
   const lock = {
     schemaVersion: 1,
     contract: RELEASE_PROPAGATION_LOCK_CONTRACT,
@@ -331,6 +377,9 @@ export function createReleasePropagationLock({
       edge: edge.id,
       channelPolicy: edge.channelPolicy,
       channelMap: edge.channelMap,
+      releaseIdentity: identity.release,
+      propagationKey,
+      branch: propagationBranch({ upstreamRelease, targetNode }),
       exact: true,
       floatingTags: false,
     },
@@ -374,6 +423,8 @@ export function planReleasePropagation({ graph: graphInput, upstreamRelease: rel
       channel: downstreamChannel,
       baseRef: lock.downstream.baseRef,
       lockPath: lock.downstream.lockPath,
+      propagationKey: lock.propagation.propagationKey,
+      branch: lock.propagation.branch,
       lock,
     });
   }
@@ -387,6 +438,7 @@ export function planReleasePropagation({ graph: graphInput, upstreamRelease: rel
       targetCount: targets.length,
       channels: [...new Set(targets.map((target) => target.channel))],
       repositories: targets.map((target) => target.repository),
+      releaseIdentity: releaseIdentity(upstreamRelease),
     },
   };
 }
@@ -411,13 +463,135 @@ export function writeReleasePropagationLock({ plan, target = "", cwd = process.c
   }
   const selected = matches[0];
   const outputPath = path.resolve(cwd, output || selected.lockPath);
+  const rendered = stableJson(selected.lock);
+  const previous = fs.existsSync(outputPath) ? fs.readFileSync(outputPath, "utf8") : "";
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-  fs.writeFileSync(outputPath, stableJson(selected.lock));
+  if (previous !== rendered) {
+    fs.writeFileSync(outputPath, rendered);
+  }
   return {
     target: selected.target,
     repository: selected.repository,
     channel: selected.channel,
     path: outputPath,
     lockSha256: selected.lock.lockSha256,
+    propagationKey: selected.propagationKey || selected.lock.propagation?.propagationKey || "",
+    branch: selected.branch || selected.lock.propagation?.branch || "",
+    status: previous === rendered ? "reused" : "written",
+    changed: previous !== rendered,
+  };
+}
+
+const RECEIPT_VISIBILITY_STATES = new Set(["pending", "visible", "failed", "not-requested"]);
+const RECEIPT_PR_STATES = new Set(["planned", "created", "updated", "reused", "no-change", "failed"]);
+
+function receiptVisibilityState(value, label) {
+  const state = optionalString(value) || "pending";
+  if (!RECEIPT_VISIBILITY_STATES.has(state)) {
+    throw new Error(`${label} must be pending, visible, failed, or not-requested`);
+  }
+  return state;
+}
+
+function receiptPrOutcome(value = {}) {
+  const outcome = assertPlainObject(value, "release propagation PR outcome");
+  const state = optionalString(outcome.state) || "planned";
+  if (!RECEIPT_PR_STATES.has(state)) {
+    throw new Error("release propagation PR outcome state is unsupported");
+  }
+  return {
+    state,
+    number: outcome.number === undefined || outcome.number === null || outcome.number === ""
+      ? null
+      : Number(outcome.number),
+    url: optionalString(outcome.url),
+    branch: assertString(outcome.branch, "release propagation PR outcome branch"),
+  };
+}
+
+export function createReleasePropagationReceipt({
+  plan,
+  target = "",
+  lockResult,
+  prOutcome,
+  stagingState = "pending",
+  productionState = "not-requested",
+  observedAt = "",
+} = {}) {
+  const selectedPlan = assertPlainObject(plan, "plan");
+  const matches = selectedPlan.targets.filter((entry) =>
+    !target || entry.target === target || entry.repository === target);
+  if (matches.length !== 1) {
+    throw new Error(`expected exactly one propagation target, found ${matches.length}`);
+  }
+  const selected = matches[0];
+  const result = assertPlainObject(lockResult, "release propagation lock result");
+  if (result.lockSha256 !== selected.lock.lockSha256) {
+    throw new Error("release propagation receipt lock result does not match the plan");
+  }
+  const propagationKey = selected.propagationKey || selected.lock.propagation?.propagationKey || "";
+  if (result.propagationKey && result.propagationKey !== propagationKey) {
+    throw new Error("release propagation receipt key does not match the lock result");
+  }
+  const branch = selected.branch || selected.lock.propagation?.branch || "";
+  const normalizedPr = receiptPrOutcome({ ...prOutcome, branch: prOutcome?.branch || branch });
+  if (normalizedPr.branch !== branch) {
+    throw new Error("release propagation PR branch does not match the exact plan");
+  }
+  const upstreamRelease = selectedPlan.upstreamRelease;
+  const release = releaseIdentity(upstreamRelease);
+  const states = {
+    "package-published": {
+      state: upstreamRelease.package ? "complete" : "not-applicable",
+      evidence: upstreamRelease.package
+        ? {
+            name: upstreamRelease.package.name,
+            version: upstreamRelease.package.version,
+            integrity: upstreamRelease.package.integrity,
+          }
+        : null,
+    },
+    "alpha-complete": {
+      state: release.channel === "alpha" ? "complete" : "not-applicable",
+      evidence: release.channel === "alpha"
+        ? {
+            releasePassportSha256: upstreamRelease.releasePassport.sha256,
+            tag: upstreamRelease.tag,
+          }
+        : null,
+    },
+    "staging-visible": {
+      state: receiptVisibilityState(stagingState, "stagingState"),
+    },
+    "production-visible": {
+      state: receiptVisibilityState(productionState, "productionState"),
+    },
+  };
+  const body = {
+    schemaVersion: 1,
+    contract: RELEASE_PROPAGATION_RECEIPT_CONTRACT,
+    propagationKey,
+    observedAt: optionalString(observedAt),
+    release,
+    upstream: {
+      repository: upstreamRelease.repository,
+      tag: upstreamRelease.tag,
+      sourceSha: upstreamRelease.sourceSha,
+      releasePassport: upstreamRelease.releasePassport,
+    },
+    downstream: {
+      repository: selected.repository,
+      channel: selected.channel,
+      baseRef: selected.baseRef,
+      lockPath: selected.lockPath,
+      lockSha256: result.lockSha256,
+      lockWriteState: result.status || (result.changed === false ? "reused" : "written"),
+      pullRequest: normalizedPr,
+    },
+    states,
+  };
+  return {
+    ...body,
+    receiptSha256: sha256Json(body),
   };
 }

package/scripts/auditable-demo.mjs

@@ -423,6 +423,38 @@ function copyFile(source, target) {
   fs.copyFileSync(source, target);
 }
 
+function parseAdapterArguments(value = "[]") {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    invariant(false, "adapter arguments must be valid JSON");
+  }
+  invariant(
+    Array.isArray(parsed) && parsed.length <= 32,
+    "adapter arguments must be an array with at most 32 entries",
+  );
+  const reserved = new Set([
+    "--artifact-root",
+    "--output",
+    "--source-coordinate",
+  ]);
+  for (const [index, argument] of parsed.entries()) {
+    invariant(
+      typeof argument === "string"
+        && argument.length > 0
+        && argument.length <= 256
+        && !/[\0\r\n]/.test(argument),
+      `adapter argument ${index} is invalid`,
+    );
+    invariant(
+      !reserved.has(argument),
+      `adapter argument ${index} attempts to override a reserved coordinate`,
+    );
+  }
+  return parsed;
+}
+
 function runAdapter(values) {
   const sourceRoot = path.resolve(required(values, "--source-root"));
   const artifactRoot = path.resolve(required(values, "--artifact-root"));
@@ -430,6 +462,9 @@ function runAdapter(values) {
   const diagnostics = path.resolve(required(values, "--diagnostics"));
   const sourceCoordinate = path.resolve(required(values, "--source-coordinate"));
   const adapterRelative = required(values, "--adapter");
+  const adapterArguments = parseAdapterArguments(
+    values["--adapter-arguments-json"] || "[]",
+  );
   const adapter = resolveInside(sourceRoot, adapterRelative, "adapter path");
   const metadata = fs.lstatSync(adapter);
   invariant(metadata.isFile() && !metadata.isSymbolicLink(), "adapter must be a regular non-symlink file");
@@ -456,7 +491,15 @@ function runAdapter(values) {
   try {
     const result = spawnSync(
       adapter,
-      ["--artifact-root", artifactRoot, "--output", output, "--source-coordinate", sourceCoordinate],
+      [
+        "--artifact-root",
+        artifactRoot,
+        "--output",
+        output,
+        "--source-coordinate",
+        sourceCoordinate,
+        ...adapterArguments,
+      ],
       { cwd: sourceRoot, env: environment, encoding: "utf8", maxBuffer: 4 * 1024 * 1024 },
     );
     fs.writeFileSync(path.join(diagnostics, "adapter.stdout.log"), result.stdout || "");
@@ -473,6 +516,8 @@ function runAdapter(values) {
       schema: "buildchain.auditable-demo-adapter-execution/v1",
       path: adapterRelative,
       sha256: sha256(readRegular(adapter, "adapter", 4 * 1024 * 1024)),
+      arguments: adapterArguments,
+      argumentsRoot: sha256(Buffer.from(stableJson(adapterArguments))),
       exitCode: 0,
     });
   } finally {
@@ -490,8 +535,8 @@ function prepareSmoke(values) {
   const scene = {
     schema: "build-images.demo-scene/v1",
     id: identifier,
-    width: 640,
-    height: 360,
+    width: 1280,
+    height: 720,
     fps: 5,
     durationMs: 1000,
     title: `${normalized.scene.title.slice(0, 96)} gate smoke`,
@@ -838,6 +883,38 @@ function constraintsForAdditionalRendition(entry, policy) {
   throw new Error(`additional rendition MIME type is not allowed: ${entry.mimeType}`);
 }
 
+function expectedRenditionDimensions(rule, scene) {
+  if (rule.dimensions === undefined) {
+    return {
+      policy: "scene-exact",
+      width: scene.width,
+      height: scene.height,
+    };
+  }
+  exactKeys(
+    rule.dimensions,
+    ["policy", "width", "height"],
+    [],
+    `${rule.path}.dimensions`,
+  );
+  invariant(
+    rule.dimensions.policy === "exact-downscale-same-aspect",
+    `${rule.path} dimension policy is unsupported`,
+  );
+  const width = integer(rule.dimensions.width, 1, 16384, `${rule.path}.dimensions.width`);
+  const height = integer(rule.dimensions.height, 1, 16384, `${rule.path}.dimensions.height`);
+  invariant(width <= scene.width && height <= scene.height, `${rule.path} dimensions would upscale the scene`);
+  invariant(
+    width * scene.height === height * scene.width,
+    `${rule.path} dimensions drift from the scene aspect ratio`,
+  );
+  return {
+    policy: rule.dimensions.policy,
+    width,
+    height,
+  };
+}
+
 function qualifyRendererOutput(renderOutput, manifest, scene, profileId, inspectMedia, inspectionRoot = "") {
   const loaded = loadMediaProfile(profileId);
   const { profile, catalog } = loaded;
@@ -887,12 +964,16 @@ function qualifyRendererOutput(renderOutput, manifest, scene, profileId, inspect
     }
     const facts = profile.mode === "web-delivery" ? inspectMedia(target) : {};
     if (profile.mode === "web-delivery") {
+      const expectedDimensions = expectedRenditionDimensions(rule, scene);
       invariant(facts && typeof facts === "object", `${rule.path} inspection is missing`);
       invariant(facts.container === rule.container, `${rule.path} container mismatch`);
       invariant(facts.videoCodec === rule.videoCodec, `${rule.path} video codec mismatch`);
       if (rule.pixelFormat) invariant(facts.pixelFormat === rule.pixelFormat, `${rule.path} pixel format mismatch`);
       invariant(facts.audioStreams === rule.audioStreams, `${rule.path} audio stream policy failed`);
-      invariant(facts.width === scene.width && facts.height === scene.height, `${rule.path} dimensions mismatch`);
+      invariant(
+        facts.width === expectedDimensions.width && facts.height === expectedDimensions.height,
+        `${rule.path} dimensions mismatch`,
+      );
       if (facts.durationMs > 0) {
         invariant(
           Math.abs(facts.durationMs - scene.durationMs) <= catalog.qualification.durationToleranceMs,
@@ -916,6 +997,9 @@ function qualifyRendererOutput(renderOutput, manifest, scene, profileId, inspect
       root: declared.root,
       bytes: declared.bytes,
       maximumBytes: rule.maximumBytes || 0,
+      dimensionPolicy: profile.mode === "web-delivery"
+        ? expectedRenditionDimensions(rule, scene).policy
+        : "not-qualified",
       ...facts,
     });
   }
@@ -986,12 +1070,28 @@ function finalizeGate(values) {
   const rendererImage = required(values, "--renderer-image");
   const adapterRelative = required(values, "--adapter");
   const sourceSha = required(values, "--source-sha");
+  const mediaProfile = values["--media-profile"] || "archive-v1";
   invariant(/^[0-9a-f]{40}$/.test(sourceSha), "source SHA must be exact");
   const normalized = validateAdapterOutput(adapterOutput);
-  verifyRendererOutput(smokeOutput, rendererImage, {
+  const selectedProfile = loadMediaProfile(mediaProfile).profile;
+  const mediaInspectionPath = values["--media-inspection"]
+    ? path.resolve(values["--media-inspection"])
+    : "";
+  const mediaInspection = selectedProfile.mode === "web-delivery"
+    ? loadMediaInspection(
+      required({ "--media-inspection": mediaInspectionPath }, "--media-inspection"),
+      smokeOutput,
+      rendererImage,
+    )
+    : null;
+  const verifiedSmoke = verifyRendererOutput(smokeOutput, rendererImage, {
     scene: path.join(smokeInput, "scene.json"),
     transcript: path.join(smokeInput, "complete-transcript.txt"),
     projection: path.join(smokeInput, "public-projection.json"),
+  }, {
+    mediaProfile,
+    inspectMedia: mediaInspection?.inspectMedia,
+    inspectionRoot: mediaInspection?.inspectionRoot || "",
   });
   const sourceCoordinate = validateSourceCoordinate(readJson(sourceCoordinatePath, "source artifact coordinate"));
   invariant(sourceCoordinate.sourceSha === sourceSha, "source artifact coordinate SHA mismatch");
@@ -1025,10 +1125,16 @@ function finalizeGate(values) {
     adapter: {
       path: adapterRelative,
       sha256: readJson(path.join(diagnostics, "adapter.json"), "adapter execution").sha256,
+      argumentsRoot: readJson(
+        path.join(diagnostics, "adapter.json"),
+        "adapter execution",
+      ).argumentsRoot,
     },
     renderer: {
       image: rendererImage,
       smokeManifestRoot: sha256(readRegular(path.join(smokeOutput, "manifest.json"), "smoke manifest")),
+      mediaProfile,
+      mediaQualificationRoot: verifiedSmoke.qualification.qualificationRoot,
     },
     qualifiedInputs: {
       transcript: sha256(readRegular(path.join(output, "complete-transcript.txt"), "transcript")),
@@ -1060,12 +1166,18 @@ function verifyGate(values) {
   const expectedRoot = required(values, "--expected-root");
   const expectedImage = required(values, "--renderer-image");
   const expectedSourceSha = required(values, "--source-sha");
+  const expectedMediaProfile = values["--media-profile"] || "archive-v1";
   invariant(DIGEST_PATTERN.test(expectedRoot), "expected gate root must be sha256");
   invariant(verifyChecksums(bundle) === expectedRoot, "gate bundle root mismatch");
   const receipt = readJson(path.join(bundle, "gate-receipt.json"), "gate receipt");
   invariant(receipt.schema === "buildchain.auditable-demo-gate/v1" && receipt.status === "passed", "gate did not pass");
   invariant(receipt.sourceSha === expectedSourceSha, "gate source SHA mismatch");
   invariant(receipt.renderer?.image === expectedImage, "gate renderer image mismatch");
+  invariant(receipt.renderer?.mediaProfile === expectedMediaProfile, "gate media profile mismatch");
+  invariant(
+    DIGEST_PATTERN.test(receipt.renderer?.mediaQualificationRoot || ""),
+    "gate media qualification root is invalid",
+  );
   const normalized = validateAdapterOutput(bundle, false);
   invariant(
     receipt.qualifiedInputs?.transcript === sha256(readRegular(path.join(bundle, "complete-transcript.txt"), "transcript"))
@@ -1113,6 +1225,7 @@ function finalizeMedia(values) {
     "--expected-root": gateRoot,
     "--renderer-image": rendererImage,
     "--source-sha": sourceSha,
+    "--media-profile": mediaProfile,
   });
   const terminalCapturePath = path.join(gateBundle, "terminal-capture.json");
   const verifiedRenderer = verifyRendererOutput(renderOutput, rendererImage, {
@@ -1199,6 +1312,7 @@ export {
   inspectIsoBmffFastStart,
   inspectMediaFile,
   inspectRendererMedia,
+  parseAdapterArguments,
   qualifyMediaFixture,
   prepareSmoke,
   runAdapter,