@kungfu-tech/buildchain 3.0.2 → 3.0.3-alpha.1

package/scripts/auditable-demo.mjs

@@ -22,6 +22,19 @@ const REQUIRED_ADAPTER_FILES = [
   "public-projection.json",
   "scene.json",
 ];
+const OPTIONAL_ADAPTER_FILES = ["terminal-capture.json"];
+const MAX_TERMINAL_CAPTURE_BYTES = 4 * 1024 * 1024;
+const MAX_TERMINAL_CAPTURE_EVENTS = 10_000;
+const TERMINAL_CAPTURE_NON_AUTHORITIES = [
+  "first-party-identity",
+  "system-identity",
+  "kfd-compliance",
+  "product-system-metadata",
+  "package-metadata",
+  "registry-history",
+  "scan-output",
+  "standalone-generation",
+];
 
 function invariant(condition, message) {
   if (!condition) throw new Error(message);
@@ -155,6 +168,19 @@ function text(value, minimum, maximum, label) {
   return value;
 }
 
+function decodeBase64(value, label) {
+  invariant(
+    typeof value === "string"
+      && value.length > 0
+      && value.length <= MAX_TERMINAL_CAPTURE_BYTES * 2
+      && /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value),
+    `${label} must be canonical base64`,
+  );
+  const decoded = Buffer.from(value, "base64");
+  invariant(decoded.toString("base64") === value, `${label} must be canonical base64`);
+  return decoded;
+}
+
 function validateScene(value) {
   exactKeys(
     value,
@@ -223,6 +249,81 @@ function validateProjection(value, scene, transcriptLineCount) {
   };
 }
 
+function validateTerminalCapture(value, scene) {
+  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 <= MAX_TERMINAL_CAPTURE_EVENTS,
+    `terminalCapture.events must contain 1 through ${MAX_TERMINAL_CAPTURE_EVENTS} 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 <= MAX_TERMINAL_CAPTURE_BYTES, "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"
+      && DIGEST_PATTERN.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;
+}
+
 function validateSourceCoordinate(value) {
   exactKeys(
     value,
@@ -276,11 +377,21 @@ function validateAdapterOutput(output, strict = true) {
     scene,
     lines.length,
   );
+  const terminalCapturePath = path.join(output, "terminal-capture.json");
+  const terminalCapture = fs.existsSync(terminalCapturePath)
+    ? validateTerminalCapture(readJson(terminalCapturePath, "terminal capture"), scene)
+    : null;
   if (strict) {
-    const allowed = new Set(REQUIRED_ADAPTER_FILES);
+    const allowed = new Set([...REQUIRED_ADAPTER_FILES, ...OPTIONAL_ADAPTER_FILES]);
     for (const member of listFiles(output)) invariant(allowed.has(member), `undeclared adapter output: ${member}`);
   }
-  return { transcript: transcript.endsWith("\n") ? transcript : `${transcript}\n`, lines, scene, projection };
+  return {
+    transcript: transcript.endsWith("\n") ? transcript : `${transcript}\n`,
+    lines,
+    scene,
+    projection,
+    terminalCapture,
+  };
 }
 
 function parseArguments(argv) {
@@ -312,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"));
@@ -319,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");
@@ -345,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 || "");
@@ -355,10 +509,15 @@ function runAdapter(values) {
     fs.writeFileSync(path.join(output, "complete-transcript.txt"), normalized.transcript);
     writeJson(path.join(output, "scene.json"), normalized.scene);
     writeJson(path.join(output, "public-projection.json"), normalized.projection);
+    if (normalized.terminalCapture) {
+      writeJson(path.join(output, "terminal-capture.json"), normalized.terminalCapture);
+    }
     writeJson(path.join(diagnostics, "adapter.json"), {
       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 {
@@ -376,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`,
@@ -724,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;
@@ -773,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,
@@ -802,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,
     });
   }
@@ -872,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");
@@ -885,6 +1099,12 @@ function finalizeGate(values) {
   fs.writeFileSync(path.join(output, "complete-transcript.txt"), normalized.transcript);
   writeJson(path.join(output, "scene.json"), normalized.scene);
   writeJson(path.join(output, "public-projection.json"), normalized.projection);
+  if (normalized.terminalCapture) {
+    copyFile(
+      path.join(adapterOutput, "terminal-capture.json"),
+      path.join(output, "terminal-capture.json"),
+    );
+  }
   copyFile(sourceCoordinatePath, path.join(output, "source-artifact.json"));
   copyFile(path.join(diagnostics, "adapter.json"), path.join(output, "adapter.json"));
   for (const name of listFiles(smokeOutput)) {
@@ -905,15 +1125,29 @@ 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")),
       projection: sha256(readRegular(path.join(output, "public-projection.json"), "projection")),
       scene: sha256(readRegular(path.join(output, "scene.json"), "scene")),
+      ...(normalized.terminalCapture
+        ? {
+          terminalCapture: {
+            schema: normalized.terminalCapture.schema,
+            root: sha256(readRegular(path.join(output, "terminal-capture.json"), "terminal capture")),
+          },
+        }
+        : {}),
       evidenceClass: normalized.projection.evidenceClass,
       claimBoundary: normalized.projection.claimBoundary,
     },
@@ -932,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"))
@@ -945,6 +1185,19 @@ function verifyGate(values) {
       && receipt.qualifiedInputs?.scene === sha256(readRegular(path.join(bundle, "scene.json"), "scene")),
     "gate qualified input roots mismatch",
   );
+  const qualifiedCapture = receipt.qualifiedInputs?.terminalCapture;
+  invariant(
+    Boolean(qualifiedCapture) === Boolean(normalized.terminalCapture),
+    "gate terminal capture presence drifted",
+  );
+  if (normalized.terminalCapture) {
+    invariant(
+      qualifiedCapture.schema === normalized.terminalCapture.schema
+        && qualifiedCapture.root
+          === sha256(readRegular(path.join(bundle, "terminal-capture.json"), "terminal capture")),
+      "gate terminal capture root mismatch",
+    );
+  }
   invariant(receipt.qualifiedInputs.evidenceClass === normalized.projection.evidenceClass, "gate evidence class drifted");
 }
 
@@ -972,11 +1225,16 @@ 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, {
     scene: path.join(gateBundle, "scene.json"),
     transcript: path.join(gateBundle, "complete-transcript.txt"),
     projection: path.join(gateBundle, "public-projection.json"),
+    ...(fs.existsSync(terminalCapturePath)
+      ? { terminalCapture: terminalCapturePath }
+      : {}),
   }, {
     mediaProfile,
     inspectMedia: mediaInspection?.inspectMedia,
@@ -1054,6 +1312,7 @@ export {
   inspectIsoBmffFastStart,
   inspectMediaFile,
   inspectRendererMedia,
+  parseAdapterArguments,
   qualifyMediaFixture,
   prepareSmoke,
   runAdapter,