@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/_lib/projection_key_migration.ts

@@ -0,0 +1,122 @@
+/**
+ * The one-release-window read of the projection keys ADR-293 removed.
+ *
+ * WHAT A REMOVED KEY MAY STILL DO, AND WHAT IT MAY NOT. A consumer who wrote
+ * `lean_projection.mode: eager-all` or `projection.mode: legacy-all` asked for
+ * one thing — keep the full rule layer — and the package can still honour that
+ * intent without the key: it is exactly what the install receipt's `user_pin`
+ * expresses. So for one window those two values are read once and converted
+ * into the pin. Every OTHER prior value is dropped, because every other value
+ * asked for a form the package now decides for itself from machine evidence,
+ * and applying it would reinstate the key under another name.
+ *
+ * BOTH DISPOSITIONS ARE PRINTED. A value silently honoured and a value silently
+ * dropped are indistinguishable to the consumer who wrote it, and the dropped
+ * case is the one that changes what their machine does. {@link migrationLines}
+ * emits one line per leftover key whichever way it went.
+ *
+ * THE WINDOW IS NAMED IN THE OUTPUT, NOT ONLY IN A COMMENT. After it closes
+ * this module goes and `REMOVED_KEYS` is what remains: a leftover key is then
+ * named as ignored by the loader's own deprecation line, with no conversion.
+ * That is a deliberate narrowing — the conversion exists to carry an intent
+ * across one upgrade, not to become a second settings reader with a longer
+ * life than the key it replaced.
+ *
+ * Pure: it takes a merged settings tree and returns a verdict. It reads no
+ * file, writes none, and never throws on a malformed branch — a settings layer
+ * nothing can parse must not fail an install.
+ */
+
+type SettingsDict = Record<string, unknown>;
+
+/**
+ * The release window this conversion is open for, as it appears in every line
+ * the module prints. Delete this module when the window closes; the tombstones
+ * in `REMOVED_KEYS` carry the keys from then on.
+ */
+export const MIGRATION_WINDOW = 'one release window after the 2026-10 key removal';
+
+/**
+ * Per removed key, the ONE prior value that meant "keep the full layer". Both
+ * are the value an absent key already resolved to, which is why they are the
+ * only two that survive: honouring them changes nothing about the machine, and
+ * dropping them would silently thin a consumer who had asked not to be.
+ */
+export const LEGACY_FULL_VALUE: Readonly<Record<string, string>> = Object.freeze({
+    'lean_projection.mode': 'eager-all',
+    'projection.mode': 'legacy-all',
+});
+
+export type Disposition = 'pin' | 'dropped';
+
+export interface LegacyRow {
+    readonly key: string;
+    /** The value as written, trimmed; never normalised onto a known enum. */
+    readonly value: string;
+    readonly disposition: Disposition;
+}
+
+export interface LegacyProjectionIntent {
+    /** The receipt pin this upgrade should write, if any leftover asked for the full form. */
+    readonly pin: boolean;
+    /** One row per leftover key found, in the order of {@link LEGACY_FULL_VALUE}. */
+    readonly rows: readonly LegacyRow[];
+}
+
+/** One dotted path out of a merged settings tree; `undefined` when absent or unreachable. */
+function readDotted(root: SettingsDict, dotted: string): unknown {
+    let node: unknown = root;
+    for (const part of dotted.split('.')) {
+        if (typeof node !== 'object' || node === null || Array.isArray(node)) return undefined;
+        node = (node as SettingsDict)[part];
+    }
+    return node;
+}
+
+/**
+ * What the leftover projection keys in `merged` ask for, and what is done about
+ * it. A key whose value is not a string is not a value this package ever wrote,
+ * so it yields no row rather than a guess.
+ */
+export function readLegacyProjectionIntent(merged: SettingsDict): LegacyProjectionIntent {
+    const rows: LegacyRow[] = [];
+    let pin = false;
+    for (const [key, full] of Object.entries(LEGACY_FULL_VALUE)) {
+        const raw = readDotted(merged, key);
+        if (typeof raw !== 'string') continue;
+        const value = raw.trim();
+        if (value === '') continue;
+        const disposition: Disposition = value.toLowerCase() === full ? 'pin' : 'dropped';
+        if (disposition === 'pin') pin = true;
+        rows.push({ key, value, disposition });
+    }
+    return { pin, rows };
+}
+
+/** One line per leftover key, naming what was done with it and for how long this happens. */
+export function migrationLines(intent: LegacyProjectionIntent): string[] {
+    return intent.rows.map((row) =>
+        row.disposition === 'pin'
+            ? `${row.key}: "${row.value}" was removed (ADR-293); read once as a request to keep the rule layer full, ` +
+              `and kept as the install receipt's pin — ${MIGRATION_WINDOW}.`
+            : `${row.key}: "${row.value}" was removed (ADR-293); ignored — the package decides the layer form from ` +
+              `machine evidence, and \`doctor --check layer-form\` says which form it chose and why — ${MIGRATION_WINDOW}.`,
+    );
+}
+
+/**
+ * The installer's whole use of this module: read the leftover keys out of the
+ * machine's own settings, print what was done with each, and say whether the
+ * receipt pin should be written. Returns `false` on any unreadable layer — a
+ * settings file nothing can parse states no preference, and the absence of a
+ * preference is the full form either way.
+ */
+export function legacyProjectionPin(
+    merged: SettingsDict | null,
+    emit: (line: string) => void,
+): boolean {
+    if (merged === null) return false;
+    const intent = readLegacyProjectionIntent(merged);
+    for (const line of migrationLines(intent)) emit(line);
+    return intent.pin;
+}

package/src/scripts/_lib/prompt_shape.ts

@@ -79,7 +79,8 @@
  * slot (the git-authorization ledger, the suggestion latch) while this one
  * guards the language pin. As of this change both know `<task-notification>`,
  * `<system-reminder>` and `<agent-message`; only this one knows
- * `[SYSTEM NOTIFICATION` and `<local-command-caveat>`. That asymmetry is NOT
+ * `[SYSTEM NOTIFICATION`, `<local-command-caveat>` and the host's framed
+ * agent-message delivery (`AGENT_MESSAGE_FRAME`). That asymmetry is NOT
  * obviously a defect and was deliberately left: mistaking a real turn for a
  * machine one costs a mis-pinned reply here and a RETAINED AUTHORIZATION
  * there, so the two sides do not want the same error budget — and
@@ -95,10 +96,20 @@ export function isSyntheticPrompt(prompt: string): boolean {
     head.startsWith("<local-command-caveat>") ||
     head.startsWith("<agent-message") ||
     head.startsWith("Your claude.ai usage limit has reset") ||
-    /^\[SYSTEM NOTIFICATION\b/.test(head)
+    /^\[SYSTEM NOTIFICATION\b/.test(head) ||
+    AGENT_MESSAGE_FRAME.test(head)
   );
 }
 
+/**
+ * How Claude Code actually delivers a subagent hand-back or a cross-session
+ * message to `user_prompt_submit`: one fixed host sentence, then the wrapper
+ * tag, which the bare `<agent-message` case above never matched. Both halves
+ * are required so a human quoting the sentence keeps their turn.
+ */
+const AGENT_MESSAGE_FRAME =
+  /^Another Claude session sent a message:\s*\n\s*<(?:agent-message|cross-session-message)\b/;
+
 /**
  * A line that starts pasted DOCUMENT content rather than typed instruction.
  *

package/src/scripts/_lib/provenance_verify.ts

@@ -0,0 +1,272 @@
+/**
+ * Tie a published version's provenance attestation to THIS package's OIDC
+ * publish workflow.
+ *
+ * The gate this replaces read `dist.attestations.provenance.predicateType` out
+ * of the packument and accepted anything starting with the SLSA provenance
+ * URL. That is a presence check wearing a verification's clothes: any workflow
+ * in any repository with `id-token: write` produces a document that passes it,
+ * so an attacker who can publish from their own CI already satisfies it. The
+ * step that opened this file (`road-to-an-update-that-installs-itself-only-when-it-is-safe`
+ * 2.1) named exactly that gap — *"does not verify the attestation's signature
+ * or tie it to `publish-npm.yml`"* — and this module closes the second half.
+ *
+ * **The first half is only partly closed here, and the distinction is
+ * load-bearing.** `provenance_matches_publish` parses an UNSIGNED reading of
+ * the DSSE payload. `verify_attestation_signature` below checks the envelope's
+ * signature against the certificate the bundle carries, and requires the
+ * payload it verified to name the same workflow — but checks no trust root
+ * (see its own note). The registry-key half is `npm audit signatures`, which
+ * verifies against npm's own trusted keys and is run by the caller as a
+ * separate step; these functions are only meaningful WITH it, and the caller
+ * says so where it composes them.
+ *
+ * Why not verify the signature in-process: it needs a sigstore/cosign
+ * verification path, which is a dependency this package does not carry and
+ * which the hook and pack byte budgets would both have to absorb. Shelling out
+ * to the npm client — already a hard dependency of an upgrade — buys the same
+ * property for nothing.
+ */
+
+/**
+ * The workflow path every legitimate release of this package is built by.
+ *
+ * A literal rather than a read of `.github/workflows/`: the question is which
+ * workflow the REGISTRY says produced the tarball, and answering it from the
+ * local tree would let a checkout vouch for itself.
+ */
+export const EXPECTED_WORKFLOW_REF = '.github/workflows/publish-npm.yml';
+
+/** The repository every legitimate release of this package is built from. */
+export const EXPECTED_REPOSITORY = 'https://github.com/event4u-app/agent-config';
+
+function asRecord(v: unknown): Record<string, unknown> | null {
+    return v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
+}
+
+/** Decode the DSSE payload of the first attestation; `null` when unreadable. */
+function decode_payload(doc: unknown): Record<string, unknown> | null {
+    const list = asRecord(doc)?.['attestations'];
+    if (!Array.isArray(list) || list.length === 0) return null;
+    for (const entry of list) {
+        const payload = asRecord(asRecord(asRecord(entry)?.['bundle'])?.['dsseEnvelope'])?.['payload'];
+        if (typeof payload !== 'string' || payload === '') continue;
+        try {
+            const parsed: unknown = JSON.parse(Buffer.from(payload, 'base64').toString('utf8'));
+            const rec = asRecord(parsed);
+            if (rec !== null) return rec;
+        } catch {
+            // A payload that is not base64 JSON is not evidence of anything.
+            // Keep looking: npm may serve several attestations and only one of
+            // them has to be the provenance statement.
+        }
+    }
+    return null;
+}
+
+function external_workflow(doc: unknown): Record<string, unknown> | null {
+    const payload = decode_payload(doc);
+    if (payload === null) return null;
+    const predicate = asRecord(payload['predicate']);
+    const external = asRecord(asRecord(predicate?.['buildDefinition'])?.['externalParameters']);
+    return asRecord(external?.['workflow']);
+}
+
+/**
+ * The workflow path named by the attestation, or `null` when the document
+ * carries none that can be read.
+ */
+export function attestation_workflow_ref(doc: unknown): string | null {
+    const path_value = external_workflow(doc)?.['path'];
+    return typeof path_value === 'string' && path_value !== '' ? path_value : null;
+}
+
+/** The repository named by the attestation, or `null`. */
+export function attestation_repository(doc: unknown): string | null {
+    const repo = external_workflow(doc)?.['repository'];
+    return typeof repo === 'string' && repo !== '' ? repo : null;
+}
+
+/**
+ * Does this attestation say the tarball was built by this package's publish
+ * workflow, in this package's repository?
+ *
+ * Both halves are required and both reject on absence: a document that names
+ * no workflow is not a document that names the right one. Repository is
+ * compared with the trailing `.git` and any trailing slash removed, because
+ * the same remote is written both ways and neither spelling is an attacker
+ * signal.
+ */
+export function provenance_matches_publish(doc: unknown): boolean {
+    return payload_names_publish(decode_payload(doc));
+}
+
+/** The workflow and repository check, over one already-decoded payload. */
+function payload_names_publish(payload: Record<string, unknown> | null): boolean {
+    const predicate = asRecord(payload?.['predicate']);
+    const workflow = asRecord(asRecord(asRecord(predicate?.['buildDefinition'])?.['externalParameters'])?.['workflow']);
+    if (workflow?.['path'] !== EXPECTED_WORKFLOW_REF) return false;
+    const repo = workflow['repository'];
+    if (typeof repo !== 'string' || repo === '') return false;
+    return repo.replace(/\.git$/, '').replace(/\/$/, '') === EXPECTED_REPOSITORY;
+}
+
+/**
+ * Does the certificate's SAN carry the workflow identity as a whole URI entry?
+ * Anchored: the entry is the expected workflow followed by `@<ref>`, never a
+ * SAN that merely contains the string.
+ */
+function san_names_workflow(san: string): boolean {
+    return san.split(/,\s*/).some((e) => e.startsWith(`URI:${SAN_WORKFLOW_MARKER}@`));
+}
+
+// --- the signature half -------------------------------------------------------
+
+/**
+ * What the clauses below do and do not establish.
+ *
+ * The header above says the signature half is not closed here. It is now
+ * HALF-closed, and the half that is missing is stated first so nothing below
+ * reads as more than it is.
+ *
+ * **Closed:** the DSSE envelope's signature is verified against the public key
+ * of the certificate the bundle itself carries, over the DSSE
+ * pre-authentication encoding — so a payload edited after signing is caught,
+ * and a bundle whose signature does not belong to its own certificate is
+ * caught. And the certificate's own SAN is required to name the expected
+ * workflow, so a bundle whose PAYLOAD claims `publish-npm.yml` while its
+ * certificate was issued to some other identity is caught. Before this, both
+ * were a base64 decode and a string compare.
+ *
+ * **Not closed, and this is the residue:** there is no trust root. Nothing
+ * here checks that the certificate was issued by Fulcio, and nothing checks a
+ * Rekor inclusion proof. An attacker who can serve a registry response can mint
+ * a self-signed certificate carrying the expected SAN, sign their own payload
+ * with it, and pass every check in this file. Closing that needs a sigstore
+ * verification path with pinned roots — a dependency decision, not a line in
+ * this function, and it is registered as the `dsse-trust-root` blocker on
+ * `road-to-an-update-that-installs-itself-only-when-it-is-safe`.
+ *
+ * So the honest statement of what the provenance gate is worth today: it
+ * defeats a partial compromise — a mis-scoped workflow, an edited payload, a
+ * bundle reused from another build — and it does not defeat a forged bundle
+ * from someone who already controls what the install reads.
+ */
+
+/** Why the signature does not verify, or `null` when it does. */
+export type SignatureVerdict = string | null;
+
+/** The SAN extension OID the Fulcio leaf carries the workflow identity in. */
+const SAN_WORKFLOW_MARKER = `${EXPECTED_REPOSITORY}/${EXPECTED_WORKFLOW_REF}`;
+
+/**
+ * The DSSE pre-authentication encoding — the exact bytes a DSSE signature is
+ * taken over.
+ *
+ * `DSSEv1 SP len(payloadType) SP payloadType SP len(payload) SP payload`, with
+ * both lengths in BYTES rather than characters. Built as a Buffer throughout
+ * because the payload is arbitrary bytes and a string round-trip would mangle
+ * any that are not valid UTF-8.
+ */
+export function dssePae(payloadType: string, payload: Buffer): Buffer {
+    const type = Buffer.from(payloadType, 'utf8');
+    return Buffer.concat([
+        Buffer.from(`DSSEv1 ${String(type.length)} `, 'utf8'),
+        type,
+        Buffer.from(` ${String(payload.length)} `, 'utf8'),
+        payload,
+    ]);
+}
+
+interface Envelope {
+    readonly payloadType: string;
+    readonly payload: Buffer;
+    readonly sig: Buffer;
+    readonly certDer: Buffer;
+}
+
+function readEnvelope(entry: unknown): Envelope | null {
+    const bundle = asRecord(asRecord(entry)?.['bundle']);
+    const dsse = asRecord(bundle?.['dsseEnvelope']);
+    if (dsse === null) return null;
+    const payloadB64 = dsse['payload'];
+    const payloadType = dsse['payloadType'];
+    const sigs = dsse['signatures'];
+    if (typeof payloadB64 !== 'string' || typeof payloadType !== 'string' || !Array.isArray(sigs) || sigs.length === 0) return null;
+    const sigB64 = asRecord(sigs[0])?.['sig'];
+    if (typeof sigB64 !== 'string' || sigB64 === '') return null;
+
+    const material = asRecord(bundle?.['verificationMaterial']);
+    // Both shapes sigstore has used: a single certificate, and a chain.
+    const single = asRecord(material?.['certificate'])?.['rawBytes'];
+    const chain = asRecord(material?.['x509CertificateChain'])?.['certificates'];
+    const first = Array.isArray(chain) ? asRecord(chain[0])?.['rawBytes'] : undefined;
+    const certB64 = typeof single === 'string' ? single : typeof first === 'string' ? first : null;
+    if (certB64 === null || certB64 === '') return null;
+
+    return {
+        payloadType,
+        payload: Buffer.from(payloadB64, 'base64'),
+        sig: Buffer.from(sigB64, 'base64'),
+        certDer: Buffer.from(certB64, 'base64'),
+    };
+}
+
+/**
+ * Verify the first readable attestation's DSSE signature against its own
+ * certificate, and require that certificate to name this package's workflow.
+ *
+ * Returns a reason on every failure rather than a boolean, because the caller
+ * prints it: a refusal a user cannot act on is a refusal they route around.
+ * `crypto` is imported lazily so a caller that never verifies a signature does
+ * not pay for the module — this runs on an install path, never in a hook.
+ */
+export async function verify_attestation_signature(doc: unknown): Promise<SignatureVerdict> {
+    const list = asRecord(doc)?.['attestations'];
+    if (!Array.isArray(list) || list.length === 0) return 'the attestation bundle carries no attestations';
+    const crypto = await import('node:crypto');
+
+    let lastReason = 'no attestation carried a readable DSSE envelope';
+    for (const entry of list) {
+        const env = readEnvelope(entry);
+        if (env === null) continue;
+        let cert: InstanceType<typeof crypto.X509Certificate>;
+        try {
+            cert = new crypto.X509Certificate(env.certDer);
+        } catch {
+            lastReason = 'the signing certificate could not be parsed';
+            continue;
+        }
+        // The certificate's own identity, not the payload's claim about it.
+        const san = cert.subjectAltName ?? '';
+        if (!san_names_workflow(san)) {
+            lastReason = `the signing certificate names ${san === '' ? 'no identity' : san}, not ${SAN_WORKFLOW_MARKER}`;
+            continue;
+        }
+        let ok = false;
+        try {
+            ok = crypto.verify(null, dssePae(env.payloadType, env.payload), cert.publicKey, env.sig);
+        } catch {
+            ok = false;
+        }
+        if (!ok) {
+            lastReason = 'the DSSE signature does not verify against the certificate in the bundle';
+            continue;
+        }
+        // The payload this signature covers must itself name the workflow:
+        // otherwise a valid signature on one entry vouches for a claim made in
+        // another, which is all the unsigned check reads.
+        let verified: Record<string, unknown> | null = null;
+        try {
+            verified = asRecord(JSON.parse(env.payload.toString('utf8')));
+        } catch {
+            verified = null;
+        }
+        if (!payload_names_publish(verified)) {
+            lastReason = 'the signed payload does not name this package\'s publish workflow';
+            continue;
+        }
+        return null;
+    }
+    return lastReason;
+}

package/src/scripts/_lib/quota_parked.ts

@@ -42,6 +42,8 @@ export interface QuotaParkedMarker {
     /** Providers whose plan quota was exhausted, sorted and deduplicated. */
     readonly providers: string[];
     readonly parked_at: string;
+    /** Who established the exhaustion: the council's own seat gate, or the host's `StopFailure`. */
+    readonly source: 'council' | 'host';
 }
 
 /** Filesystem-safe path for a run's marker. Mirrors `billing_grant.grantFile`. */
@@ -65,6 +67,7 @@ export function writeQuotaParked(
     runId: string,
     providers: readonly string[],
     now: () => Date = () => new Date(),
+    source: 'council' | 'host' = 'council',
 ): QuotaParkedMarker {
     const file = markerFile(repoRoot, runId);
     const existing = readMarker(file);
@@ -73,6 +76,7 @@ export function writeQuotaParked(
         run_id: runId,
         providers: merged,
         parked_at: existing?.parked_at ?? now().toISOString(),
+        source: existing?.source ?? source,
     };
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, `${JSON.stringify(marker, null, 2)}\n`, 'utf8');
@@ -118,6 +122,27 @@ export function findQuotaParked(repoRoot: string, sessionId: string): QuotaParke
     return null;
 }
 
+/** The plan's rolling rate window; a host marker older than this no longer describes it. */
+export const HOST_RATE_WINDOW_MS = 5 * 3_600_000;
+
+/** True when a host-sourced marker was parked inside the rate window ending at `nowMs`. */
+export function recentHostMarker(repoRoot: string, nowMs: number = Date.now(), windowMs: number = HOST_RATE_WINDOW_MS): boolean {
+    let names: string[];
+    try {
+        names = fs.readdirSync(path.join(repoRoot, QUOTA_PARKED_DIR_REL));
+    } catch {
+        return false;
+    }
+    for (const name of names) {
+        if (!name.endsWith('.json')) continue;
+        const m = readMarker(path.join(repoRoot, QUOTA_PARKED_DIR_REL, name));
+        if (m === null || m.source !== 'host') continue;
+        const at = Date.parse(m.parked_at);
+        if (Number.isFinite(at) && nowMs - at >= 0 && nowMs - at < windowMs) return true;
+    }
+    return false;
+}
+
 function readMarker(file: string): QuotaParkedMarker | null {
     try {
         const raw: unknown = JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -126,7 +151,8 @@ function readMarker(file: string): QuotaParkedMarker | null {
         if (typeof o['run_id'] !== 'string' || typeof o['parked_at'] !== 'string') return null;
         if (!Array.isArray(o['providers'])) return null;
         const providers = o['providers'].filter((p): p is string => typeof p === 'string');
-        return { run_id: o['run_id'], providers, parked_at: o['parked_at'] };
+        const source = o['source'] === 'host' ? 'host' : 'council';
+        return { run_id: o['run_id'], providers, parked_at: o['parked_at'], source };
     } catch {
         return null;
     }

package/src/scripts/_lib/ratification_artifact.ts

@@ -84,6 +84,18 @@ export interface RatificationArtifact {
     verdict: RatificationVerdict;
     /** `merge`, or an ISO-8601 instant. Never a bare "later". */
     effective_after: string;
+    /**
+     * The digest of the gated content this record reviewed, or `null` on a
+     * record that carries none.
+     *
+     * Not in {@link RATIFICATION_FIELDS}: those six are required of every
+     * record, and the 23 records on the trunk predate this field. What makes
+     * it required in practice is the CALLER — `check_kernel_edit_ratified`
+     * passes an expected digest on every run, and a record with no `subject`
+     * then fails `subject-absent`. A record is only ever read as part of the
+     * diff it ships in, so nothing on the trunk is re-judged.
+     */
+    subject: string | null;
 }
 
 export interface RatificationProblem {
@@ -103,7 +115,10 @@ export interface RatificationProblem {
         | 'unknown-seat-verdict'
         | 'seat-dissent'
         | 'providers-exceed-seats'
-        | 'header-not-derived';
+        | 'header-not-derived'
+        | 'subject-absent'
+        | 'subject-malformed'
+        | 'subject-mismatch';
     message: string;
 }
 
@@ -322,6 +337,16 @@ export interface RatificationReading {
     problems: RatificationProblem[];
 }
 
+/**
+ * A `subject` digest: the lower-case hex sha-256 `subjectDigest` produces.
+ *
+ * Shape is checked apart from equality on purpose. A typo'd digest and a
+ * digest that moved because a gated file was edited after the review are
+ * different failures, and a reader that reported both as "mismatch" would
+ * send an author looking for an edit that never happened.
+ */
+export const SUBJECT_RE = /^[0-9a-f]{64}$/u;
+
 /** `merge`, or an ISO-8601 instant with a timezone. */
 const EFFECTIVE_AFTER_RE =
     /^(merge|\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2}))$/;
@@ -364,10 +389,18 @@ export function readProviders(fm: AdrFrontmatter): string[] {
  * Pass `null` when it could not be established — the diversity rule then does
  * not fire, and the caller says so, because an unmeasured count is not
  * evidence that diversity was unavailable.
+ *
+ * `expectedSubject` is the digest of the gated content the record is being
+ * read against, recomputed from the tree by the caller. Pass `null` to read a
+ * record's shape without binding it to any content — which is what a reader
+ * that is not judging a diff does. Pass a digest and the record must carry
+ * `subject`, and carry that one: a record whose `subject` is absent or
+ * different did not review this content, whatever its verdict says.
  */
 export function readRatification(
     text: string,
     configuredProviders: number | null,
+    expectedSubject: string | null = null,
 ): RatificationReading {
     const problems: RatificationProblem[] = [];
     const fm = readAdrFrontmatter(text);
@@ -427,6 +460,35 @@ export function readRatification(
 
     problems.push(...seatProblems(readSeats(fm, text), providers, verdict));
 
+    // The content binding. Shape first, then equality, so a malformed digest is
+    // never reported as content that moved.
+    const subject = scalarOf(fm, 'subject');
+    if (subject !== null && !SUBJECT_RE.test(subject)) {
+        problems.push({
+            code: 'subject-malformed',
+            message:
+                `subject \`${subject}\` is not a sha-256 hex digest (${String(SUBJECT_RE)}) — ` +
+                'print it with `ratification_subject`',
+        });
+    } else if (expectedSubject !== null) {
+        if (subject === null) {
+            problems.push({
+                code: 'subject-absent',
+                message:
+                    'missing `subject:` — a record names who reviewed; without a digest it does not ' +
+                    `name WHAT, so the gated content may have changed since. Expected \`${expectedSubject}\``,
+            });
+        } else if (subject !== expectedSubject) {
+            problems.push({
+                code: 'subject-mismatch',
+                message:
+                    `subject \`${subject}\` is not the digest of this diff's gated content ` +
+                    `(\`${expectedSubject}\`) — the record reviewed different content, so it does not ` +
+                    'answer for this change',
+            });
+        }
+    }
+
     // Diversity, against the REQUIRED count.
     //
     // Round 1 refused the previous shape: the count came from the user-global
@@ -465,6 +527,7 @@ export function readRatification(
             providers,
             verdict: verdict as RatificationVerdict,
             effective_after: effective as string,
+            subject,
         },
         problems: [],
     };