v1.91.176.0 cso: ignore the compiled helpers' leading #! line in the release contract's preparationSha256 (both sides) (#3333)

* cso: ignore the compiled helpers' leading #! line in preparationSha256, on both sides of the release contract

S1 (#3312) rewrote only line 1 of lib/cso/verifier.ts and
lib/cso/preparation-container.ts. That shebang is an unused string in the
compiled helper binaries, but it moved preparationSha256, so qualify run
39535948607 refused the run-5 statements staged at 133cb36 with
STALE_RUNTIME_QUALIFICATION. Garry chose this narrow rule (option 2).

The release contract re-measures a recorded preparationSha256 that differs
from the checkout's at the staged commit (git history), accepts a record
that matches it under the current or the legacy rule, and compares and
records the current-rule value. Both release workflows fetch full history.

* test(cso): prove the release-contract fingerprint rule without git history

Free-suite checkouts are depth 1, so the tests no longer read 133cb36 or
6b2b5f3. They rebuild the staged commit in a scratch repository from this
tree with both helpers' S1 shebang reverted. Its legacy fingerprint equals
the real run-5 record (b069f7ef...), so it is 133cb36's image source byte
for byte, and the contract accepts that record under the current rule.

* v1.91.176.0 stamp

scripts/cso-requalification.ts

@@ -5,7 +5,9 @@
  * differ from the current source is older than its inputs and must be
  * requalified (or its runtimes withdrawn) before it ships.
  */
+import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { canonical, sha256 } from '../lib/cso/contracts';
 import { ISOLATION_POLICY_HASH } from '../lib/cso/docker';
@@ -31,6 +33,37 @@ export async function imageSourceFiles(root = ROOT): Promise<string[]> {
   return [...new Set([...closure, ...context])].sort();
 }
 
+/**
+ * Digest of every image source byte. A compiled helper's leading `#!` line never
+ * runs inside the image, so it is hashed as absent; every other byte counts.
+ * `legacy` hashes the shebang too, the rule staging runs recorded before this normalization (through run 39325583697).
+ */
+function preparationSha256(root: string, files: string[], legacy = false): string {
+  const helpers = new Set<string>(IMAGE_HELPER_ENTRYPOINTS);
+  return sha256(canonical(files.map(file => {
+    const bytes = fs.readFileSync(path.join(root, file));
+    if (legacy || !helpers.has(file) || bytes[0] !== 0x23 || bytes[1] !== 0x21) return [file, sha256(bytes)];
+    const newline = bytes.indexOf(0x0a);
+    return [file, sha256(newline === -1 ? Buffer.alloc(0) : bytes.subarray(newline + 1))];
+  })));
+}
+
+/** preparationSha256 of a committed tree under the current rule and the legacy rule. */
+export async function committedPreparation(commit: string, root = ROOT): Promise<{ current: string; legacy: string }> {
+  if (!/^[a-f0-9]{40}$/.test(commit)) throw new Error('INVALID_STAGED_COMMIT');
+  const archive = spawnSync('git', ['-C', root, 'archive', '--format=tar', commit], { timeout: 60_000, maxBuffer: 512 * 1024 * 1024 });
+  if (archive.status !== 0) throw new Error(`STAGED_COMMIT_UNAVAILABLE: ${commit} is not in this checkout; fetch full history`);
+  const tree = fs.mkdtempSync(path.join(os.tmpdir(), 'cso-staged-source-'));
+  try {
+    const extract = spawnSync('tar', ['-x', '-C', tree], { input: archive.stdout, timeout: 60_000 });
+    if (extract.status !== 0) throw new Error('STAGED_COMMIT_UNAVAILABLE: archive extraction failed');
+    const files = await imageSourceFiles(tree);
+    return { current: preparationSha256(tree, files), legacy: preparationSha256(tree, files, true) };
+  } finally {
+    fs.rmSync(tree, { recursive: true, force: true });
+  }
+}
+
 export async function requalificationTriggers(root = ROOT): Promise<RequalificationTriggers> {
   const files = await imageSourceFiles(root);
   const buildInputs = JSON.parse(fs.readFileSync(path.join(root, IMAGE_CONTEXT, 'build-inputs.json'), 'utf8'));
@@ -38,7 +71,7 @@ export async function requalificationTriggers(root = ROOT): Promise<Requalificat
   return {
     helperAbi: CSO_HELPER_ABI,
     isolationPolicyHash: ISOLATION_POLICY_HASH,
-    preparationSha256: sha256(canonical(files.map(file => [file, sha256(fs.readFileSync(path.join(root, file)))]))),
+    preparationSha256: preparationSha256(root, files),
     buildInputsRevision: buildInputs.revision,
   };
 }

scripts/cso-runtime-promotion.ts

@@ -18,7 +18,7 @@ import {
 } from '../lib/cso/runtime-catalog';
 import { ISOLATION_POLICY_HASH } from '../lib/cso/docker';
 import { imageBuildMatrix, type ImageBuildRow } from './cso-image-matrix';
-import { requalificationTriggers, staleRequalificationTriggers } from './cso-requalification';
+import { committedPreparation, requalificationTriggers, staleRequalificationTriggers } from './cso-requalification';
 
 const DIGEST = /^sha256:[a-f0-9]{64}$/;
 const WORKFLOW = /^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/actions\/runs\/[0-9]+$/;
@@ -273,6 +273,30 @@ export function catalogPromotionCandidate(
   return candidate;
 }
 
+/**
+ * The release contract: the promotion candidate, refused when any trigger moved since the staged commit.
+ * A recorded preparationSha256 that differs from the current one is re-measured at the staged commit in
+ * `source`, so a staging record made under the legacy rule compares under the current rule.
+ */
+export async function releaseCandidate(
+  evidenceValues: unknown[],
+  recorded: RequalificationTriggers,
+  current: RequalificationTriggers,
+  source?: string,
+): Promise<RuntimeCatalog> {
+  let candidate = catalogPromotionCandidate(committedCatalog, buildInputs, evidenceValues, recorded);
+  if (recorded.preparationSha256 !== current.preparationSha256) {
+    const staged = await committedPreparation(candidate.promotion!.sourceCommit, source);
+    if (recorded.preparationSha256 !== staged.current && recorded.preparationSha256 !== staged.legacy) {
+      throw new Error('REQUALIFICATION_TRIGGERS_MISMATCH: preparationSha256 was not measured at the staged commit');
+    }
+    candidate = catalogPromotionCandidate(committedCatalog, buildInputs, evidenceValues, { ...recorded, preparationSha256: staged.current });
+  }
+  const stale = staleRequalificationTriggers(candidate, current);
+  if (stale.length) throw new Error(`STALE_RUNTIME_QUALIFICATION: ${stale.join(', ')} changed since the staged commit; re-stage and requalify`);
+  return candidate;
+}
+
 /** A promotion may only replace the exact catalog revision it was generated from. */
 export function validateRuntimeCatalogTransition(currentValue: unknown, proposedValue: unknown): void {
   validateRuntimeCatalog(currentValue);
@@ -356,9 +380,7 @@ if (import.meta.main) {
       }
       const triggers = collectEvidence(args[1], 'requalification.json');
       if (triggers.length !== 1) throw new Error('MISSING_REQUALIFICATION_TRIGGERS');
-      const candidate = catalogPromotionCandidate(committedCatalog, buildInputs, collectEvidence(args[1]), triggers[0] as RequalificationTriggers);
-      const stale = staleRequalificationTriggers(candidate, await requalificationTriggers());
-      if (stale.length) throw new Error(`STALE_RUNTIME_QUALIFICATION: ${stale.join(', ')} changed since the staged commit; re-stage and requalify`);
+      const candidate = await releaseCandidate(collectEvidence(args[1]), triggers[0] as RequalificationTriggers, await requalificationTriggers());
       const output = path.resolve(args[3]);
       fs.writeFileSync(output, JSON.stringify(candidate, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
       process.stdout.write(`${output}\n`);