Pin conformance authority to merge commits on main

.github/workflows/ci.yml

@@ -103,6 +103,33 @@ jobs:
       - run: pnpm lint
       - run: pnpm typecheck
       - run: pnpm test:unit
+      # The lock test verifies digests against a detached checkout of the
+      # authority, which is self-consistent however far main moves on, so it
+      # cannot see a content merge whose repin was never made. That is how
+      # three governed files drifted for four merges without a red build.
+      #
+      # A pull request is allowed to drift: the repin follows the merge, and
+      # cannot name a merge commit that does not exist yet. Main is not.
+      - name: Phase 1 authority is current
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        shell: bash
+        run: |
+          set -euo pipefail
+          # Execute the authority's guard and imports, never the unpinned copy.
+          # Clear inherited Git settings before reading the lock or archive.
+          authority_git() {
+            env -i PATH="$PATH" HOME="$RUNNER_TEMP" \
+              GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_NOSYSTEM=1 \
+              GIT_NO_REPLACE_OBJECTS=1 GIT_NO_LAZY_FETCH=1 \
+              GIT_TERMINAL_PROMPT=0 GIT_ALLOW_PROTOCOL= \
+              git "$@"
+          }
+          authority=$(authority_git show HEAD:phase1-conformance.lock.json | jq -er '.harnessAuthority.revision')
+          [[ "$authority" =~ ^[0-9a-f]{40}$ ]]
+          pinned=$(mktemp -d)
+          trap 'rm -rf "$pinned"' EXIT
+          authority_git archive "$authority" scripts/ | tar -x -C "$pinned"
+          node "$pinned/scripts/phase1-authority-freshness.mjs" HEAD "$GITHUB_WORKSPACE"
 
   e2e:
     name: E2E

docs/phase1-conformance.md

@@ -2068,24 +2068,60 @@ not appear here. Editing ordinary CI config still dirties that entry and
 requires the same file-hash repin as touching the harness itself — this is
 not discoverable until a test fails on it.
 
-A PR that repins `harnessAuthority.revision`/`.tree` to a commit within its
-own branch (rather than to something already merged) must be merged with an
-actual merge commit, never squash or rebase. Squashing silently breaks the
-invariant: the pinned revision stops being an ancestor of `main`, and the
-authority checkout keeps resolving only for as long as the now-orphaned
-source branch survives. A follow-up repin to the real merge commit is the
-only fix once that happens.
-
-The two-step converges in exactly two commits only when every digest update —
-the harness digest, both workflow pin tables, every affected row in the table
-above, and every affected `harnessAuthority.files` entry (the workflow's own
-self-referential one included) — lands in the code commit itself. The repin
-commit that follows must touch nothing but `harness.revision`,
-`harnessAuthority.revision`/`.tree`, and the test's literal copy of them. Move
-any digest into the repin commit instead and it invalidates the digests
-recorded against the commit `harness.revision` still names, forcing a third
-commit to advance the pin again — the exact shape of #102's first attempt and
-#110's first attempt.
+### Authority is pinned to merge commits on `main`
+
+`harnessAuthority.revision` names a merge commit that is already part of
+`main`. It is never a commit on the branch that introduces the change, and a
+content pull request never advances it.
+
+That ordering is forced rather than chosen. A merge commit's SHA does not
+exist until the merge happens, so the lock inside the merged tree cannot name
+it. Pinning a branch commit instead is what made every pair of conformance
+branches collide: each wrote a different `harnessAuthority.revision` into the
+same file, so whichever merged second had to be rebuilt, and whichever merged
+last left a pin describing a tree that no longer matched what shipped.
+
+Landing a change to a governed file therefore takes two pull requests:
+
+1. **The content PR** changes governed files and leaves
+   `phase1-conformance.lock.json` alone. It lands as a merge commit so the
+   follow-up can name that commit.
+   The lock test stays green: it verifies digests against the previous
+   immutable authority. The main-only freshness guard fails until the repin
+   lands.
+2. **The repin PR** follows, and is the only PR that touches the lock. It
+   points `harness.revision` and `harnessAuthority.revision`/`.tree` at the
+   content PR's merge commit on `main`, refreshes every digest to that
+   commit's tree in `harnessAuthority.files` and
+   `harnessAuthority.productionDeltas`, including the workflow entries,
+   and updates the test's literal copy and the prose records. Workflow source
+   pin tables belong in the content PR; editing a governed workflow during
+   the repin would create fresh drift. Digests and the revision move together,
+   against a commit that already exists, so there is no ordering to get wrong.
+
+Because only the repin PR writes the lock, and it runs serially on `main`,
+two content branches can no longer conflict over it.
+
+### The repin is not optional
+
+Between the two merges the authority legitimately lags, and nothing in the
+lock notices. The lock test compares digests against the authority's own
+checkout, which stays self-consistent no matter how far `main` moves on.
+#322 changed `src-tauri/Cargo.toml`, `Cargo.lock` and `keyring.rs` without a
+repin and stayed green through three further merges; the drift only surfaced
+when a later change advanced the authority and had to reconcile all three at
+once.
+
+`scripts/phase1-authority-freshness.mjs` closes that gap. It asserts the pin
+is on the first-parent history of the ref under test, that it is a merge
+commit rather than a branch tip, and that no governed file or production
+delta has moved since it was pinned. CI extracts and executes the guard and its imports from the
+pinned authority, so changing the working-tree guard cannot bypass the check. The guard also
+compares its own blob, even though it is outside the frozen harness file list.
+The first content merge has no pinned guard yet and fails closed until its
+repin lands. CI runs it on `main` pushes only, since a pull request is allowed
+to lag by construction. A forgotten repin now turns `main` red instead of
+staying silent.
 
 Before parsing or executing SDK authority, the harness queries the verified
 checkout with `git rev-parse --show-object-format`, accepts only `sha1` or

scripts/phase1-authority-freshness.d.mts

@@ -0,0 +1,16 @@
+export type AuthorityDrift = {
+  group: 'files' | 'productionDeltas';
+  path: string;
+  pinned: string | null;
+  shipped: string | null;
+};
+
+export type AuthorityFreshness = {
+  revision: string;
+  ref: string;
+  reachable: boolean;
+  adrift: AuthorityDrift[];
+  failures: string[];
+};
+
+export function checkAuthorityFreshness(ref?: string, repositoryRoot?: string): AuthorityFreshness;

scripts/phase1-authority-freshness.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * Guards the three properties the conformance lock cannot check itself.
+ *
+ * `phase1-conformance.lock.json` records digests for the governed harness
+ * files and production deltas, and the lock test verifies them against a
+ * detached checkout of `harnessAuthority.revision`. That is self-consistent by
+ * construction: the authority's tree is immutable, so the digests keep
+ * matching it no matter how far the branch moves on. Nothing there notices
+ * when the code that actually ships has left the authority behind.
+ *
+ * That is how #322 changed `keyring.rs`, `Cargo.toml` and `Cargo.lock` without
+ * a repin and stayed green across three further merges.
+ *
+ * Run against a ref, default `HEAD`:
+ *   node scripts/phase1-authority-freshness.mjs [ref]
+ */
+import { execFileSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createGitEnvironment } from './phase1-conformance-lock.mjs';
+
+const projectRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+function runGit(repositoryRoot, args) {
+  return execFileSync('git', args, {
+    cwd: repositoryRoot,
+    env: createGitEnvironment(),
+    timeout: 30_000,
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+}
+
+/**
+ * One tree listing per ref, rather than a `rev-parse` per file. The lock
+ * governs 35 paths, so the naive form spawns seventy processes and takes
+ * long enough to trip a test timeout.
+ */
+function blobsAt(git, ref) {
+  const blobs = new Map();
+  let listing;
+  try {
+    listing = git(['ls-tree', '-r', '-z', ref]);
+  } catch {
+    return blobs;
+  }
+  for (const record of listing.split('\0')) {
+    if (record === '') {
+      continue;
+    }
+    const tab = record.indexOf('\t');
+    if (tab < 0) {
+      continue;
+    }
+    const [, type, oid] = record.slice(0, tab).split(/\s+/u);
+    if (type === 'blob') {
+      blobs.set(record.slice(tab + 1), oid);
+    }
+  }
+  return blobs;
+}
+
+export function checkAuthorityFreshness(ref = 'HEAD', repositoryRoot = projectRoot) {
+  const git = (args) => runGit(repositoryRoot, args);
+  ref = git(['rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`]);
+  // Read the lock as it exists at `ref`, not from the working tree. Reading
+  // from disk would compare today's pin against a historical tree, which
+  // silently answers a different question than the one being asked.
+  const lock = JSON.parse(git(['show', `${ref}:phase1-conformance.lock.json`]));
+  const authority = lock.harnessAuthority;
+  const revision = authority.revision;
+  if (!/^[0-9a-f]{40}$/u.test(revision)) {
+    throw new Error('harnessAuthority.revision must be an immutable Git ID');
+  }
+  const failures = [];
+
+  // Orphaned pin: a squash or rebase leaves the authority reachable only while
+  // the source branch survives.
+  let reachable = true;
+  try {
+    git(['merge-base', '--is-ancestor', revision, ref]);
+  } catch {
+    reachable = false;
+    failures.push(`harnessAuthority.revision ${revision} is not an ancestor of ${ref}`);
+  }
+
+  // A branch-tip pin is what makes two conformance branches collide. Authority
+  // belongs on a merge commit that is already part of the history.
+  if (reachable) {
+    if (!git(['rev-list', '--first-parent', ref]).split('\n').includes(revision)) {
+      failures.push(
+        'harnessAuthority.revision must be on the first-parent history of the checked ref',
+      );
+    }
+    const parents = git(['rev-list', '--parents', '-n', '1', revision]).split(/\s+/u).slice(1);
+    if (parents.length < 2) {
+      failures.push(
+        `harnessAuthority.revision ${revision} has ${parents.length} parent(s);` +
+          ' authority must be pinned to a merge commit',
+      );
+    }
+  }
+
+  // The pin must describe what ships, or the executed harness and the shipped
+  // tree have silently diverged.
+  const adrift = [];
+  if (reachable) {
+    const pinnedBlobs = blobsAt(git, revision);
+    const shippedBlobs = blobsAt(git, ref);
+    const guard = 'scripts/phase1-authority-freshness.mjs';
+    if (!pinnedBlobs.has(guard)) {
+      failures.push('Pinned freshness guard is missing; a repin is due');
+    }
+    const groups = {
+      files: [...authority.files, { path: guard }],
+      productionDeltas: authority.productionDeltas,
+    };
+    for (const group of ['files', 'productionDeltas']) {
+      for (const entry of groups[group] ?? []) {
+        const pinned = pinnedBlobs.get(entry.path) ?? null;
+        const shipped = shippedBlobs.get(entry.path) ?? null;
+        if (pinned !== shipped) {
+          adrift.push({ group, path: entry.path, pinned, shipped });
+        }
+      }
+    }
+  }
+  if (adrift.length > 0) {
+    failures.push(
+      `${adrift.length} governed file(s) have moved since the authority was` +
+        ' pinned; a repin is due',
+    );
+  }
+
+  return { revision, ref, reachable, adrift, failures };
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const ref = process.argv[2] ?? 'HEAD';
+  const result = checkAuthorityFreshness(ref, process.argv[3] ?? projectRoot);
+  if (result.failures.length === 0) {
+    process.stdout.write(
+      `Phase 1 authority ${result.revision.slice(0, 8)} is current for ${ref}.\n`,
+    );
+    process.exit(0);
+  }
+  for (const failure of result.failures) {
+    process.stderr.write(`${failure}\n`);
+  }
+  for (const entry of result.adrift) {
+    process.stderr.write(`  ${entry.group}: ${entry.path}\n`);
+  }
+  process.exit(1);
+}