@pareto4/pp-core 1.13.0 → 1.18.0

package/pp-core/bin/lib/vault-seal.cjs

@@ -0,0 +1,1851 @@
+"use strict";
+/**
+ * src/vault-seal.cts — the seal leaf (Vault Assurance v1.2, Phase 16-03).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the git-ignored `pp-core/bin/lib/vault-seal.cjs`; do NOT
+ * hand-edit the compiled output. Behaviour is locked by
+ * `tests/vault-seal.test.cjs`.
+ *
+ * Every defect this workstream shipped was one contract restated on N
+ * surfaces with one surface left behind. Phase 16 adds four contracts that
+ * several later plans need, so each gets ONE owner here, built and pinned
+ * before any consumer exists:
+ *
+ *   - artifact presence (D-20): does a directory, or a project, hold
+ *     engine-written vault records? `collectRecordedArtifacts` /
+ *     `hasRecordedVaultArtifacts`;
+ *   - the non-source path class (D-15, D-39): which repo paths are not
+ *     governed source? `isNonSourcePath`, with `isPlanningPath` as its
+ *     `.planning/` half;
+ *   - the anchor grammar (D-14, D-35): the one shape a recorded commit may
+ *     have before it can reach a git argv. `ANCHOR_SHA_RE`;
+ *   - the door-record grammar (D-12): `formatDoorRecord` / `parseDoorRecord`.
+ *
+ * It also reads and writes the per-directory anchors file
+ * (`.vault-anchors.json`) the start anchor lives in (D-31).
+ *
+ * LAYERING (D-41). The TOP LEVEL of this file imports only Node built-ins
+ * (`fs`, `path`). That is load-bearing: `vault-trace.cts` and
+ * `vault-standards.cts` are expected to import `ANCHOR_SHA_RE` from here in
+ * 16-06, and a top-level import back into either would close a load-time
+ * require cycle. The modules this leaf needs (`vault-standards`,
+ * `project-root`, `vault`) are therefore required LAZILY, inside the
+ * functions that use them, which is the `readVaultGateActive` precedent in
+ * `src/vault.cts`. By the time any of those
+ * functions runs, every module has finished loading, so the lazy edge cannot
+ * observe a half-initialised export object.
+ *
+ * Message discipline: nothing here echoes a value it refused. A refused door
+ * record field, or a dropped anchor, is reported by naming the FIELD, never by
+ * reproducing what was found, so planning-tree text cannot inject terminal
+ * escapes or agent-directed prose through a refusal.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEAL_GIT_TIMEOUT_MS = exports.SEAL_SUBJECT_CAP = exports.SEAL_EXAMINE_CAP = exports.SEAL_CANDIDATE_CAP = exports.UNCOVERED_PATHS_PER_COMMIT_CAP = exports.COVERING_RECORD_CAP = exports.UNCOVERED_COMMIT_CAP = exports.DISABLED_WITH_ARTIFACTS_REPAIR = exports.DISABLED_WITH_ARTIFACTS_LIST_CAP = exports.VAULT_SWITCH_KEY = exports.DISABLED_WITH_ARTIFACTS_STATUS = exports.DOOR_ARTIFACT_FILENAME_RE = exports.RECORDED_ARTIFACT_KIND = exports.RECORDED_ARTIFACT_DIR_CAP = exports.TRACE_ARTIFACT_COUNT_CAP = exports.TRACE_ARTIFACT_BYTE_CAP = exports.DOOR_RECORD_PROBLEM_KIND = exports.DOOR_NAMES = exports.DOOR_RECORD_HEADING = exports.VAULT_DOOR_STARTS_FILE = exports.CERTIFICATE_CAP = exports.VAULT_CERTIFICATES_FILE = exports.ATTESTATION_PATHS_CAP = exports.ATTESTATION_CAP = exports.VAULT_ATTESTATIONS_FILE = exports.DIR_START_HISTORY_CAP = exports.VAULT_ANCHORS_FILE = exports.NON_SOURCE_PATH_CLASSES = exports.ANCHOR_BACKFILL_WHO_MAX = exports.ANCHOR_SHA_RE = void 0;
+exports.isAnchorSha = isAnchorSha;
+exports.isIsoInstant = isIsoInstant;
+exports.isAnchorBackfill = isAnchorBackfill;
+exports.normaliseAnchorBackfillWho = normaliseAnchorBackfillWho;
+exports.isPlanningPath = isPlanningPath;
+exports.nonSourceClassOf = nonSourceClassOf;
+exports.isNonSourcePath = isNonSourcePath;
+exports.readDirAnchors = readDirAnchors;
+exports.writeDirStartAnchor = writeDirStartAnchor;
+exports.readDirAttestations = readDirAttestations;
+exports.appendDirAttestations = appendDirAttestations;
+exports.readDirCertificates = readDirCertificates;
+exports.appendDirCertificates = appendDirCertificates;
+exports.readDoorStart = readDoorStart;
+exports.writeDoorStart = writeDoorStart;
+exports.consumeDoorStart = consumeDoorStart;
+exports.formatDoorRecord = formatDoorRecord;
+exports.parseDoorRecord = parseDoorRecord;
+exports.collectRecordedArtifacts = collectRecordedArtifacts;
+exports.formatDisabledWithArtifacts = formatDisabledWithArtifacts;
+exports.disabledWithArtifactsRepair = disabledWithArtifactsRepair;
+exports.disabledWithArtifactsVerdict = disabledWithArtifactsVerdict;
+exports.hasRecordedVaultArtifacts = hasRecordedVaultArtifacts;
+exports.extractRecordAnchors = extractRecordAnchors;
+exports.resolveRecordAnchors = resolveRecordAnchors;
+exports.sealIsAncestorVia = sealIsAncestorVia;
+exports.attestedFor = attestedFor;
+exports.collectCoveringRecords = collectCoveringRecords;
+exports.isPhaseRecordRel = isPhaseRecordRel;
+exports.isSummaryRecordRel = isSummaryRecordRel;
+exports.computeUncoveredSourceCommits = computeUncoveredSourceCommits;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// ─── Anchor grammar (D-14, D-35) ─────────────────────────────────────────────
+/**
+ * A recorded anchor: a full commit id, lowercase hex, at sha1 (40) or sha256
+ * (64) length. Abbreviated ids, uppercase, and anything that could be read as
+ * an option (`--output=x`) are refused, so a value that passes can be placed
+ * in a git argv as a revision. The shape of `GIT_COMMIT_DIGEST_RE` in
+ * `src/vault-command-router.cts`, which 16-06 re-binds to this constant.
+ */
+exports.ANCHOR_SHA_RE = /^[0-9a-f]{40}$|^[0-9a-f]{64}$/;
+/** True only for a string that matches `ANCHOR_SHA_RE`. Never throws. */
+function isAnchorSha(value) {
+    return typeof value === 'string' && exports.ANCHOR_SHA_RE.test(value);
+}
+/** The bound on `by`, in code points (the trace's `boundedToken` width). */
+exports.ANCHOR_BACKFILL_WHO_MAX = 80;
+/**
+ * Characters a `by` value may not carry: C0/C1 controls, a backtick (it would
+ * open inline code on a markdown line), bidi controls, zero-width characters,
+ * line/paragraph separators and the BOM.
+ */
+const BACKFILL_WHO_UNSAFE_RE = /[\u0000-\u001F\u007F-\u009F`\u200B-\u200F\u2028-\u202E\u2066-\u2069\uFEFF]/;
+/** Is `s` exactly a timestamp `toISOString` would write (form, then a round trip)? */
+function isIsoInstant(s) {
+    if (typeof s !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(s))
+        return false;
+    const d = new Date(s);
+    return !Number.isNaN(d.getTime()) && d.toISOString() === s;
+}
+/**
+ * Is this a well-formed back-fill attribution? `by` is a non-empty string of at
+ * most `ANCHOR_BACKFILL_WHO_MAX` code points, already trimmed, with none of the
+ * unsafe characters above; `at` round-trips through `toISOString` (a rolled-over
+ * date such as `2026-02-31` does not). Never throws.
+ */
+function isAnchorBackfill(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const v = value;
+    const by = v.by;
+    if (typeof by !== 'string' || by === '' || by.trim() !== by)
+        return false;
+    if (Array.from(by).length > exports.ANCHOR_BACKFILL_WHO_MAX || BACKFILL_WHO_UNSAFE_RE.test(by))
+        return false;
+    return isIsoInstant(v.at);
+}
+/**
+ * Turn a raw identity (a git `user.name`, an environment value) into a `by`
+ * value `isAnchorBackfill` accepts: unsafe characters become spaces, runs of
+ * whitespace collapse, the ends are trimmed, the length is capped. An identity
+ * with nothing left is the literal `unknown`, never an empty string, so "we
+ * did not record who" stays readable as a fact.
+ */
+function normaliseAnchorBackfillWho(raw) {
+    const flat = String(typeof raw === 'string' ? raw : '')
+        .replace(new RegExp(BACKFILL_WHO_UNSAFE_RE.source, 'g'), ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    const capped = Array.from(flat).slice(0, exports.ANCHOR_BACKFILL_WHO_MAX).join('').trim();
+    return capped === '' ? 'unknown' : capped;
+}
+// ─── Non-source path class (D-15, D-39) ──────────────────────────────────────
+/**
+ * The seven classes of path that are NOT governed source. A commit that
+ * touches only these never needs a record (SEAL-01). D-39 adds the last three
+ * (agent instructions, not client code); that is the less restrictive reading,
+ * taken on the operator's behalf and open to reversal.
+ *
+ * `claude-md` and `agents-md` are top-level files and so already inside
+ * `top-level-markdown`; they are listed on their own so the D-39 rows stay
+ * visible and a reversal removes one row, not a rule.
+ */
+exports.NON_SOURCE_PATH_CLASSES = Object.freeze([
+    Object.freeze({ id: 'planning', description: 'anything under .planning/ (either separator)' }),
+    Object.freeze({ id: 'docs', description: 'anything under the top-level docs/ directory' }),
+    Object.freeze({ id: 'changeset', description: 'anything under the top-level .changeset/ directory' }),
+    Object.freeze({ id: 'claude-dir', description: 'anything under the top-level .claude/ directory (D-39)' }),
+    Object.freeze({ id: 'claude-md', description: 'the top-level CLAUDE.md (D-39)' }),
+    Object.freeze({ id: 'agents-md', description: 'the top-level AGENTS.md (D-39)' }),
+    Object.freeze({ id: 'top-level-markdown', description: 'a .md file at the repository root (no directory part)' }),
+]);
+/**
+ * The `.planning/` prefixes, both separators. Held as data so this file, like
+ * every other file under `src/`, carries no `.planning` prefix literal in a
+ * prefix test of its own: the one-owner pin counts those.
+ */
+const PLANNING_PREFIXES = Object.freeze(['.planning/', '.planning\\']);
+/** The directory classes: prefix (always with the trailing slash) to class id. */
+const DIRECTORY_CLASSES = Object.freeze([
+    Object.freeze(['docs/', 'docs']),
+    Object.freeze(['.changeset/', 'changeset']),
+    Object.freeze(['.claude/', 'claude-dir']),
+]);
+/**
+ * True for a `.planning/`-prefixed path, with either separator. The one
+ * owner of this test: the classifier below and the commit_docs guard in
+ * `src/commands.cts` call it. Case-sensitive; `..planning/x` and
+ * `.planningx/y` are not planning paths. Never throws.
+ */
+function isPlanningPath(p) {
+    if (typeof p !== 'string')
+        return false;
+    return PLANNING_PREFIXES.some((prefix) => p.startsWith(prefix));
+}
+/**
+ * The class a path belongs to, or `null` when it is governed source.
+ *
+ * Backslashes are normalised to `/` first. Directory classes are prefix
+ * matches WITH the trailing slash, so a file literally named `docs` and a
+ * directory `docsx/` are source. Top-level markdown means no `/` at all and a
+ * `.md` suffix, so a nested `packages/x/README.md` is source. Case-sensitive:
+ * `Docs/x.md` is source. Never throws.
+ */
+function nonSourceClassOf(p) {
+    if (typeof p !== 'string' || p === '')
+        return null;
+    const n = p.replace(/\\/g, '/');
+    if (isPlanningPath(n))
+        return 'planning';
+    for (const [prefix, id] of DIRECTORY_CLASSES) {
+        if (n.startsWith(prefix))
+            return id;
+    }
+    if (n === 'CLAUDE.md')
+        return 'claude-md';
+    if (n === 'AGENTS.md')
+        return 'agents-md';
+    if (!n.includes('/') && n.endsWith('.md'))
+        return 'top-level-markdown';
+    return null;
+}
+/** True when the path is in one of the seven non-source classes. Never throws. */
+function isNonSourcePath(p) {
+    return nonSourceClassOf(p) !== null;
+}
+// ─── Anchors file (D-31) ─────────────────────────────────────────────────────
+/** The per-directory file holding a phase or quick directory's start anchor. */
+exports.VAULT_ANCHORS_FILE = '.vault-anchors.json';
+/** The anchors file is a few dozen bytes; anything past this is not one. */
+const ANCHORS_FILE_BYTE_CAP = 64 * 1024;
+/** An ISO-8601 UTC instant as `Date.prototype.toISOString` writes it. */
+const ISO_UTC_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+/** How many superseded starts a directory keeps (oldest dropped first; dropping only narrows coverage). */
+exports.DIR_START_HISTORY_CAP = 32;
+function isDirStartEntry(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return false;
+    const o = v;
+    return isAnchorSha(o.start) && typeof o.recordedAt === 'string' && ISO_UTC_RE.test(o.recordedAt);
+}
+/**
+ * Read a directory's anchors file. `null` when the file is missing, larger
+ * than a few kilobytes, not JSON, or does not carry a valid `start` anchor and
+ * an ISO `recordedAt`. Never throws: a missing anchor is a state the strict
+ * readers type, not an exception.
+ */
+function readDirAnchors(dirAbs) {
+    try {
+        const abs = node_path_1.default.join(dirAbs, exports.VAULT_ANCHORS_FILE);
+        const st = node_fs_1.default.statSync(abs);
+        if (!st.isFile() || st.size > ANCHORS_FILE_BYTE_CAP)
+            return null;
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(abs, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        const o = parsed;
+        if (!isAnchorSha(o.start))
+            return null;
+        if (typeof o.recordedAt !== 'string' || !ISO_UTC_RE.test(o.recordedAt))
+            return null;
+        // A malformed history entry is dropped, never repaired: a missing earlier
+        // start can only make a record cover LESS (D-98, rule 3).
+        const earlier = Array.isArray(o.earlier)
+            ? o.earlier.filter(isDirStartEntry).slice(0, exports.DIR_START_HISTORY_CAP).map((e) => ({ start: e.start, recordedAt: e.recordedAt }))
+            : [];
+        return { start: o.start, recordedAt: o.recordedAt, ...(earlier.length > 0 ? { earlier } : {}) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Record a directory's start anchor. The start it supersedes is not lost: it
+ * moves to the front of `earlier` (newest first, `DIR_START_HISTORY_CAP`
+ * kept), where an END-only record written before the new start still finds
+ * the start that preceded its own end (16 review iteration 2 CR-02, D-98).
+ * Every record written from now on takes the new start, so nothing committed
+ * before it is claimed by them. Refuses a value that is not an anchor BEFORE
+ * anything is written (throws), because the caller is the engine and an
+ * invalid sha there is a bug, not input. The clock is injected (`now`), per
+ * the project's pure-function convention. Writes to a temporary sibling and
+ * renames, so a reader never sees half a file.
+ */
+function writeDirStartAnchor(dirAbs, sha, opts = {}) {
+    if (!isAnchorSha(sha)) {
+        throw new Error('writeDirStartAnchor: the start anchor is not a full lowercase commit id (40 or 64 hex)');
+    }
+    const now = typeof opts.now === 'function' ? opts.now : () => new Date();
+    const previous = readDirAnchors(dirAbs);
+    const earlier = previous === null
+        ? []
+        : [{ start: previous.start, recordedAt: previous.recordedAt }, ...(previous.earlier ?? [])]
+            .filter((e) => e.start !== sha)
+            .slice(0, exports.DIR_START_HISTORY_CAP);
+    const record = { start: sha, recordedAt: now().toISOString(), ...(earlier.length > 0 ? { earlier } : {}) };
+    const abs = node_path_1.default.join(dirAbs, exports.VAULT_ANCHORS_FILE);
+    const tmp = `${abs}.${process.pid}.tmp`;
+    node_fs_1.default.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+    node_fs_1.default.renameSync(tmp, abs);
+    return record;
+}
+// ─── Attestations file (16 review iteration 3 CR-01, D-102) ──────────────────
+//
+// A resume records a new start (D-98), so the phase's own commits made between
+// its last record and the resume are covered by nothing, and the engine cannot
+// tell them from an ungoverned commit. The operator's repair is to ATTEST each
+// such commit, one by one, on the record that holds that work: never to widen
+// the record's range (iteration 3 CR-01: a widened start covered every commit
+// in between, an ungoverned one included, and the note that remained named
+// none of them). An attestation covers exactly the commit it names, only when
+// that commit lies on the record's own line between a start this directory
+// recorded and the record's end, and every later strict check lists it with
+// its subject, its paths and who attested it — a git `user.name`, recorded as
+// given and never verified. `vault anchor backfill --from --attest` is the one
+// writer.
+/** The per-directory file holding the attestations made on that directory's SUMMARY records. */
+exports.VAULT_ATTESTATIONS_FILE = '.vault-attestations.json';
+/** At most this many attestations are kept per directory; the writer refuses more. */
+exports.ATTESTATION_CAP = 200;
+/** At most this many source paths are kept per attested commit. */
+exports.ATTESTATION_PATHS_CAP = 20;
+/** The attestations file's read cap. */
+const ATTESTATIONS_FILE_BYTE_CAP = 256 * 1024;
+const ATTEST_TEXT_UNSAFE_RE = /[\u0000-\u001F\u007F-\u009F]/;
+/** `SEAL_SUBJECT_CAP` plus its ellipsis, restated because that constant is declared further down this file. */
+const ATTEST_SUBJECT_MAX = 121;
+function isAttestation(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return false;
+    const o = v;
+    if (typeof o.record !== 'string' || o.record.includes('/') || o.record.includes('\\') || !/(^|-)SUMMARY\.md$/.test(o.record))
+        return false;
+    if (!isAnchorSha(o.from) || !isAnchorSha(o.sha))
+        return false;
+    if (typeof o.subject !== 'string' || o.subject.length > ATTEST_SUBJECT_MAX || ATTEST_TEXT_UNSAFE_RE.test(o.subject))
+        return false;
+    if (!Array.isArray(o.paths) || o.paths.length > exports.ATTESTATION_PATHS_CAP)
+        return false;
+    if (!o.paths.every((p) => typeof p === 'string' && p !== '' && p.length <= 1024 && !ATTEST_TEXT_UNSAFE_RE.test(p)))
+        return false;
+    return isAnchorBackfill({ by: o.by, at: o.at });
+}
+/**
+ * A directory's attestations, in the order they were made. A missing,
+ * oversized or unparsable file, or a malformed entry, reads as none: a lost
+ * attestation can only make a record cover LESS. Never throws.
+ */
+function readDirAttestations(dirAbs) {
+    try {
+        const abs = node_path_1.default.join(dirAbs, exports.VAULT_ATTESTATIONS_FILE);
+        const st = node_fs_1.default.lstatSync(abs);
+        if (!st.isFile() || st.size > ATTESTATIONS_FILE_BYTE_CAP)
+            return [];
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(abs, 'utf8'));
+        const list = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed.attestations : null;
+        if (!Array.isArray(list))
+            return [];
+        return list.filter(isAttestation).slice(0, exports.ATTESTATION_CAP)
+            .map((a) => ({ record: a.record, from: a.from, sha: a.sha, subject: a.subject, paths: [...a.paths], by: a.by, at: a.at }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Append attestations to a directory's file. Throws, writing nothing, on an
+ * entry that is not well formed, a commit already attested for the same
+ * record, more than `ATTESTATION_CAP` in all, or a symlinked file: the caller
+ * is the engine, and each of those is a bug or a refusal it states first.
+ * Writes a temporary sibling and renames it.
+ */
+function appendDirAttestations(dirAbs, entries) {
+    if (!Array.isArray(entries) || entries.length === 0 || !entries.every(isAttestation)) {
+        throw new Error('appendDirAttestations: an attestation is not well formed');
+    }
+    const abs = node_path_1.default.join(dirAbs, exports.VAULT_ATTESTATIONS_FILE);
+    try {
+        if (node_fs_1.default.lstatSync(abs).isSymbolicLink())
+            throw new Error('appendDirAttestations: the attestations file is a symlink');
+    }
+    catch (e) {
+        if (e?.code !== 'ENOENT')
+            throw e;
+    }
+    const existing = readDirAttestations(dirAbs);
+    const seen = new Set(existing.map((a) => `${a.record}\u0000${a.sha}`));
+    for (const a of entries) {
+        const key = `${a.record}\u0000${a.sha}`;
+        if (seen.has(key))
+            throw new Error('appendDirAttestations: that commit is already attested for this record');
+        seen.add(key);
+    }
+    const next = [...existing, ...entries];
+    if (next.length > exports.ATTESTATION_CAP)
+        throw new Error(`appendDirAttestations: more than ${exports.ATTESTATION_CAP} attestations in one directory`);
+    const tmp = `${abs}.${process.pid}.tmp`;
+    node_fs_1.default.writeFileSync(tmp, `${JSON.stringify({ attestations: next }, null, 2)}\n`, 'utf8');
+    node_fs_1.default.renameSync(tmp, abs);
+    return next;
+}
+// ─── Certificates file (16 gap closure 16-18, D-107) ─────────────────────────
+//
+// SEAL-01's lower bound (computeUncoveredSourceCommits (c2)) let any earlier
+// PHASE record's end bound a later phase's reach, whether or not that phase's
+// own strict check had passed: nothing recorded said so (D-101's reason for
+// filing, D-106's ruling to fix it). A phase whose strict check named an
+// ungoverned commit and was then abandoned kept its SUMMARY, and that SUMMARY's
+// end hid the commit from every later phase. A certificate is that missing
+// fact: an engine-written entry saying "this record's END was judged by a clean
+// strict check of its phase". Its one writer is `vault anchor certify
+// <phase-dir>` (plan 16-19), which runs `check vault.trace --unpaired strict`
+// itself and certifies only on `status: checked`, `block: false` and no
+// override (D-108), so the check stays read-only (TRACE-04). It is keyed by
+// the record's END sha, so a SUMMARY written or re-anchored later is
+// uncertified until the next clean strict check. A malformed entry is dropped
+// on read and the record reads as UNCERTIFIED: the direction that bounds less.
+/** The per-directory file holding the certificates for that directory's SUMMARY records' ends. */
+exports.VAULT_CERTIFICATES_FILE = '.vault-certificates.json';
+/** At most this many certificates are kept per directory; the writer refuses more. */
+exports.CERTIFICATE_CAP = 200;
+/** The certificates file's read cap. */
+const CERTIFICATES_FILE_BYTE_CAP = 64 * 1024;
+function isSealCertificate(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return false;
+    const o = v;
+    return isAnchorSha(o.end) && isAnchorSha(o.head) && typeof o.at === 'string' && ISO_UTC_RE.test(o.at);
+}
+/**
+ * A directory's certificates, in the order they were written. A missing file,
+ * a file that is not a regular file (a symlink included), one over the byte
+ * cap, not JSON, not an object or without a `certified` array reads as none;
+ * a malformed entry is dropped and the rest kept, never repaired. Never
+ * throws: a lost certificate can only make a record bound LESS.
+ */
+function readDirCertificates(dirAbs) {
+    try {
+        const abs = node_path_1.default.join(dirAbs, exports.VAULT_CERTIFICATES_FILE);
+        const st = node_fs_1.default.lstatSync(abs);
+        if (!st.isFile() || st.size > CERTIFICATES_FILE_BYTE_CAP)
+            return [];
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(abs, 'utf8'));
+        const list = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed.certified : null;
+        if (!Array.isArray(list))
+            return [];
+        return list.filter(isSealCertificate).slice(0, exports.CERTIFICATE_CAP).map((c) => ({ end: c.end, head: c.head, at: c.at }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Append certificates to a directory's file and return the full list. Throws,
+ * writing nothing, on an empty list, an entry that is not well formed, a
+ * symlinked file, or more than `CERTIFICATE_CAP` in all: the caller is the
+ * engine, and each of those is a bug or a refusal it states first. A repeated
+ * `end` (already certified, or twice in `entries`) keeps the FIRST entry, so
+ * certifying the same end again changes nothing. Writes a temporary sibling
+ * and renames it.
+ */
+function appendDirCertificates(dirAbs, entries) {
+    if (!Array.isArray(entries) || entries.length === 0 || !entries.every(isSealCertificate)) {
+        throw new Error('appendDirCertificates: a certificate is not well formed');
+    }
+    const abs = node_path_1.default.join(dirAbs, exports.VAULT_CERTIFICATES_FILE);
+    try {
+        if (node_fs_1.default.lstatSync(abs).isSymbolicLink())
+            throw new Error('appendDirCertificates: the certificates file is a symlink');
+    }
+    catch (e) {
+        if (e?.code !== 'ENOENT')
+            throw e;
+    }
+    const next = readDirCertificates(dirAbs);
+    const seen = new Set(next.map((c) => c.end));
+    for (const c of entries) {
+        if (seen.has(c.end))
+            continue;
+        seen.add(c.end);
+        next.push({ end: c.end, head: c.head, at: c.at });
+    }
+    if (next.length > exports.CERTIFICATE_CAP)
+        throw new Error(`appendDirCertificates: more than ${exports.CERTIFICATE_CAP} certificates in one directory`);
+    const tmp = `${abs}.${process.pid}.tmp`;
+    node_fs_1.default.writeFileSync(tmp, `${JSON.stringify({ certified: next }, null, 2)}\n`, 'utf8');
+    node_fs_1.default.renameSync(tmp, abs);
+    return next;
+}
+// ─── Door starts file (16 review CR-01) ──────────────────────────────────────
+//
+// A door captures its START before its agent runs and writes its record after
+// the door's last source commit, many steps later. A shell variable cannot
+// carry the start between the two (each agent step runs a fresh shell), and the
+// agent never types a sha (D-12). So `vault door-record --begin` records the
+// start HERE, in the project's `.planning/` (never a phase directory: that
+// directory's `.vault-anchors.json` is the phase's own start, D-59), keyed by
+// door name, and the record step reads it back. A later `--begin` of the same
+// door replaces its entry: every door run begins afresh, so an interrupted
+// run's commits stay uncovered (and SEAL-01 names them) rather than a stale
+// start widening a later run's range. A successful record CONSUMES the entry
+// (16 review iteration 2 WR-01, D-100), so that "afresh" no longer rests on the
+// prose step running: a record with no fresh `--begin` halts.
+/** The project-level file holding each door's most recent start (`.planning/` root). */
+exports.VAULT_DOOR_STARTS_FILE = '.vault-door-starts.json';
+/** The whole file, or `{}` when it is missing, oversized, not JSON or not an object. Never throws. */
+function readDoorStarts(planningAbs) {
+    try {
+        const abs = node_path_1.default.join(planningAbs, exports.VAULT_DOOR_STARTS_FILE);
+        const st = node_fs_1.default.lstatSync(abs);
+        if (!st.isFile() || st.size > ANCHORS_FILE_BYTE_CAP)
+            return {};
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(abs, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * The start the named door's last `--begin` recorded, or `null` when there is
+ * none or it is malformed (not an anchor, no ISO `recordedAt`). Never throws.
+ */
+function readDoorStart(planningAbs, door) {
+    if (!exports.DOOR_NAMES.includes(door))
+        return null;
+    const all = readDoorStarts(planningAbs);
+    const entry = Object.prototype.hasOwnProperty.call(all, door) ? all[door] : undefined;
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+        return null;
+    const o = entry;
+    if (!isAnchorSha(o.start))
+        return null;
+    if (typeof o.recordedAt !== 'string' || !ISO_UTC_RE.test(o.recordedAt))
+        return null;
+    return { start: o.start, recordedAt: o.recordedAt };
+}
+/**
+ * Record `door`'s start, replacing its earlier entry and keeping the other
+ * doors' valid entries. Throws on a door name or sha the engine should never
+ * pass (a bug, not input), before anything is written; writes a temporary
+ * sibling and renames it, so a reader never sees half a file. The file must
+ * not be a symlink (a write is never redirected out of the tree).
+ */
+function writeDoorStart(planningAbs, door, sha, opts = {}) {
+    if (!exports.DOOR_NAMES.includes(door))
+        throw new Error('writeDoorStart: not a door that writes a record');
+    if (!isAnchorSha(sha))
+        throw new Error('writeDoorStart: the start is not a full lowercase commit id (40 or 64 hex)');
+    const abs = node_path_1.default.join(planningAbs, exports.VAULT_DOOR_STARTS_FILE);
+    try {
+        if (node_fs_1.default.lstatSync(abs).isSymbolicLink())
+            throw new Error('writeDoorStart: the door starts file is a symlink');
+    }
+    catch (e) {
+        if (e?.code !== 'ENOENT')
+            throw e;
+    }
+    const now = typeof opts.now === 'function' ? opts.now : () => new Date();
+    const record = { start: sha, recordedAt: now().toISOString() };
+    const next = {};
+    for (const name of exports.DOOR_NAMES) {
+        if (name === door)
+            next[name] = record;
+        else {
+            const kept = readDoorStart(planningAbs, name);
+            if (kept)
+                next[name] = kept;
+        }
+    }
+    const tmp = `${abs}.${process.pid}.tmp`;
+    node_fs_1.default.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    node_fs_1.default.renameSync(tmp, abs);
+    return record;
+}
+/**
+ * Consume `door`'s start (16 review iteration 2 WR-01, D-100): remove its entry
+ * when, and only when, it still holds `start` — the value the record about to
+ * be written read — keeping every other door's valid entry. A record therefore
+ * uses a `--begin` once: a second record without a fresh `--begin` finds no
+ * start and halts naming `--begin`, instead of reusing run 1's start and
+ * covering everything committed since. An entry that changed in between (a
+ * newer `--begin`) is left alone and `false` is returned. Throws on a door name
+ * the engine should never pass, or when the file is a symlink; writes a
+ * temporary sibling and renames it.
+ */
+function consumeDoorStart(planningAbs, door, start) {
+    if (!exports.DOOR_NAMES.includes(door))
+        throw new Error('consumeDoorStart: not a door that writes a record');
+    const abs = node_path_1.default.join(planningAbs, exports.VAULT_DOOR_STARTS_FILE);
+    if (node_fs_1.default.lstatSync(abs).isSymbolicLink())
+        throw new Error('consumeDoorStart: the door starts file is a symlink');
+    const current = readDoorStart(planningAbs, door);
+    if (current === null || current.start !== start)
+        return false;
+    const next = {};
+    for (const name of exports.DOOR_NAMES) {
+        if (name === door)
+            continue;
+        const kept = readDoorStart(planningAbs, name);
+        if (kept)
+            next[name] = kept;
+    }
+    const tmp = `${abs}.${process.pid}.tmp`;
+    node_fs_1.default.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    node_fs_1.default.renameSync(tmp, abs);
+    return true;
+}
+// ─── Door-record grammar (D-12) ──────────────────────────────────────────────
+/** The heading a door record opens with, at column 0. */
+exports.DOOR_RECORD_HEADING = '## Vault Door Record';
+/** The doors that write a door record (D-11). */
+exports.DOOR_NAMES = Object.freeze(['code-review-fix', 'validate-phase', 'add-tests', 'audit-fix']);
+/**
+ * The modes a door record may name; `null` is written as `none`. `practices`
+ * is still accepted so a door record written by an older engine (which had a
+ * practices mode) parses; this engine writes only `standards`.
+ */
+const DOOR_MODES = Object.freeze(['practices', 'standards']);
+/** How an absent value is spelled on its line. */
+const DOOR_NONE = 'none';
+/** Why a door record did not parse. Frozen, so a typo is a build error. */
+exports.DOOR_RECORD_PROBLEM_KIND = Object.freeze({
+    DUPLICATE: 'door_record_duplicate',
+    MALFORMED: 'door_record_malformed',
+    FIELD_INVALID: 'door_record_field_invalid',
+});
+/** The line keys, in the one order a record is written and read. */
+const DOOR_RECORD_KEYS = Object.freeze([
+    'door',
+    'mode',
+    'vault-repo',
+    'vault-ref',
+    'vault-sha',
+    'degraded',
+    'phase',
+    'start-commit',
+    'end-commit',
+    'recorded-at',
+]);
+/** `- key: value`, the one line shape inside the section. */
+const DOOR_LINE_RE = /^- ([a-z-]+): (.*)$/;
+/**
+ * Is this free-text value safe to place on a record line an agent reads?
+ * Asks the standards leaf's reason-clause judge, which owns the refused set
+ * (newline, backtick, control, bidi, separator and zero-width characters, a
+ * fence marker, a block tag, empty, over 200 code points). Required lazily;
+ * see the layering note in the header.
+ */
+function isDisplaySafeValue(value) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const standards = require('./vault-standards.cjs');
+    return standards.validateReasonClause(value).ok && value !== DOOR_NONE && value.trim() === value;
+}
+/** The record's ten line values, in key order; throws naming the field on a refused value. */
+function doorRecordValues(rec) {
+    const refuse = (field) => {
+        throw new Error(`formatDoorRecord: the ${field} field is not valid for a door record`);
+    };
+    const r = (rec && typeof rec === 'object' ? rec : {});
+    if (!exports.DOOR_NAMES.includes(r.door))
+        refuse('door');
+    if (r.mode !== null && !DOOR_MODES.includes(r.mode))
+        refuse('mode');
+    const text = (field, v) => {
+        if (v === null)
+            return DOOR_NONE;
+        if (typeof v !== 'string' || !isDisplaySafeValue(v))
+            return refuse(field);
+        return v;
+    };
+    const vault = r.vault === undefined ? refuse('vault') : r.vault;
+    if (vault !== null && (typeof vault !== 'object' || Array.isArray(vault)))
+        refuse('vault');
+    const degraded = r.degraded === undefined ? refuse('degraded') : r.degraded;
+    // Exactly one of the two: the coordinates of a loaded vault, or the
+    // degraded one-liner saying why there were none (D-12 "or").
+    if ((vault === null) === (degraded === null))
+        refuse('vault');
+    if (vault !== null && !isAnchorSha(vault.sha))
+        refuse('vault-sha');
+    if (!isAnchorSha(r.startCommit))
+        refuse('start-commit');
+    if (!isAnchorSha(r.endCommit))
+        refuse('end-commit');
+    if (typeof r.recordedAt !== 'string' || !ISO_UTC_RE.test(r.recordedAt))
+        refuse('recorded-at');
+    return {
+        door: r.door,
+        mode: r.mode === null ? DOOR_NONE : r.mode,
+        'vault-repo': vault === null ? DOOR_NONE : text('vault-repo', vault.repo),
+        'vault-ref': vault === null ? DOOR_NONE : text('vault-ref', vault.ref),
+        'vault-sha': vault === null ? DOOR_NONE : vault.sha,
+        degraded: text('degraded', degraded),
+        phase: r.phase === undefined ? refuse('phase') : text('phase', r.phase),
+        'start-commit': r.startCommit,
+        'end-commit': r.endCommit,
+        'recorded-at': r.recordedAt,
+    };
+}
+/**
+ * Serialise a door record: the heading line, then one `- key: value` line per
+ * field in the fixed key order, then a newline. An absent value is written
+ * `none`. Throws, naming the field, on any value the parser would refuse, so
+ * the writer can never emit a record its own reader rejects.
+ */
+function formatDoorRecord(rec) {
+    const values = doorRecordValues(rec);
+    const lines = [exports.DOOR_RECORD_HEADING, ...DOOR_RECORD_KEYS.map((k) => `- ${k}: ${values[k]}`)];
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Read a door record back out of a text (an artifact a door wrote into).
+ *
+ * The heading counts only as a whole column-0 line outside the frontmatter,
+ * fenced code and HTML comments; the section ends at the next ATX heading,
+ * thematic break or the end of the text — the `parseConsultedSection` rule,
+ * asked of the standards leaf's own scanner (`findLiveSection`). No heading →
+ * `{ ok: true, record: null }`. Two headings → a duplicate problem. Inside the
+ * section only the ten key lines, in order, each once, are legal; blank lines
+ * aside, anything else is malformed. Never throws.
+ */
+function parseDoorRecord(text) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const standards = require('./vault-standards.cjs');
+        const { lines, headings, body } = standards.findLiveSection(text, exports.DOOR_RECORD_HEADING);
+        if (headings.length === 0)
+            return { ok: true, record: null };
+        const fail = (kind, field, idx) => ({
+            ok: false,
+            record: null,
+            problems: [{ kind, field, line: idx === null ? null : idx + 1 }],
+        });
+        if (headings.length > 1)
+            return fail(exports.DOOR_RECORD_PROBLEM_KIND.DUPLICATE, null, headings[1]);
+        if (body.length !== DOOR_RECORD_KEYS.length) {
+            return fail(exports.DOOR_RECORD_PROBLEM_KIND.MALFORMED, null, body.length > DOOR_RECORD_KEYS.length ? body[DOOR_RECORD_KEYS.length] : headings[0]);
+        }
+        const raw = {};
+        for (let k = 0; k < DOOR_RECORD_KEYS.length; k += 1) {
+            const m = DOOR_LINE_RE.exec(lines[body[k]]);
+            if (!m || m[1] !== DOOR_RECORD_KEYS[k])
+                return fail(exports.DOOR_RECORD_PROBLEM_KIND.MALFORMED, DOOR_RECORD_KEYS[k], body[k]);
+            raw[DOOR_RECORD_KEYS[k]] = m[2];
+        }
+        const at = (key) => body[DOOR_RECORD_KEYS.indexOf(key)];
+        const invalid = (key) => fail(exports.DOOR_RECORD_PROBLEM_KIND.FIELD_INVALID, key, at(key));
+        const textOrNull = (key) => {
+            const v = raw[key];
+            if (v === DOOR_NONE)
+                return null;
+            return isDisplaySafeValue(v) ? v : undefined;
+        };
+        if (!exports.DOOR_NAMES.includes(raw.door))
+            return invalid('door');
+        if (raw.mode !== DOOR_NONE && !DOOR_MODES.includes(raw.mode))
+            return invalid('mode');
+        const repo = textOrNull('vault-repo');
+        if (repo === undefined)
+            return invalid('vault-repo');
+        const ref = textOrNull('vault-ref');
+        if (ref === undefined)
+            return invalid('vault-ref');
+        const sha = raw['vault-sha'] === DOOR_NONE ? null : raw['vault-sha'];
+        if (sha !== null && !isAnchorSha(sha))
+            return invalid('vault-sha');
+        const coords = [repo, ref, sha];
+        if (coords.some((c) => c === null) && coords.some((c) => c !== null))
+            return invalid('vault-repo');
+        const degraded = textOrNull('degraded');
+        if (degraded === undefined)
+            return invalid('degraded');
+        if ((sha === null) === (degraded === null))
+            return invalid('degraded');
+        const phase = textOrNull('phase');
+        if (phase === undefined)
+            return invalid('phase');
+        if (!isAnchorSha(raw['start-commit']))
+            return invalid('start-commit');
+        if (!isAnchorSha(raw['end-commit']))
+            return invalid('end-commit');
+        if (!ISO_UTC_RE.test(raw['recorded-at']))
+            return invalid('recorded-at');
+        return {
+            ok: true,
+            record: {
+                door: raw.door,
+                mode: raw.mode === DOOR_NONE ? null : raw.mode,
+                vault: sha === null ? null : { repo: repo, ref: ref, sha },
+                degraded,
+                phase,
+                startCommit: raw['start-commit'],
+                endCommit: raw['end-commit'],
+                recordedAt: raw['recorded-at'],
+            },
+        };
+    }
+    catch {
+        return { ok: false, record: null, problems: [{ kind: exports.DOOR_RECORD_PROBLEM_KIND.MALFORMED, field: null, line: null }] };
+    }
+}
+// ─── Recorded-artifact presence (D-20) ───────────────────────────────────────
+/**
+ * A single artifact is read whole; anything larger is skipped, not streamed.
+ * MOVED here from `src/check-command-router.cts` by 16-03 and read back from
+ * there (the `TRACE_REGENERATE_COMMAND` precedent), so the trace gate's scan
+ * and this predicate's scan cannot be capped differently.
+ */
+exports.TRACE_ARTIFACT_BYTE_CAP = 1024 * 1024;
+/** A directory with more candidate artifacts than this is not a phase directory. */
+exports.TRACE_ARTIFACT_COUNT_CAP = 200;
+/** How many planning directories the project-level predicate visits at most. */
+exports.RECORDED_ARTIFACT_DIR_CAP = 2000;
+/** What an engine-written record found in a directory is. Frozen; one id per D-20 record type. */
+exports.RECORDED_ARTIFACT_KIND = Object.freeze({
+    STANDARDS_BLOCK: 'standards_block',
+    STANDARDS_CONSULTED: 'standards_consulted',
+    DOOR_RECORD: 'door_record',
+});
+/**
+ * The artifacts a door writes its record into (16-15): `-REVIEW-FIX.md`,
+ * `-VALIDATION.md`, `-ADD-TESTS.md`, `-AUDIT-FIX.md`, alone or after a prefix.
+ */
+exports.DOOR_ARTIFACT_FILENAME_RE = Object.freeze(/(^|-)(REVIEW-FIX|VALIDATION|ADD-TESTS|AUDIT-FIX)\.md$/);
+/** The router's own filename rules for the two record-bearing artifacts. */
+const PLAN_FILENAME_RE = /(^|-)PLAN\.md$/;
+const SUMMARY_FILENAME_RE = /(^|-)SUMMARY\.md$/;
+function readers() {
+    /* eslint-disable @typescript-eslint/no-require-imports */
+    return {
+        standards: require('./vault-standards.cjs'),
+    };
+    /* eslint-enable @typescript-eslint/no-require-imports */
+}
+/** The project root a directory belongs to (the router's rule: `findProjectRoot(x) || x`). */
+function resolveRoot(root, from) {
+    if (typeof root === 'string' && root !== '')
+        return root;
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const projectRoot = require('./project-root.cjs');
+    return projectRoot.findProjectRoot(from) || from;
+}
+/** Every record kind one candidate's text holds, each once. */
+function classifyCandidate(r, text, role) {
+    const kinds = [];
+    // A parse FAILURE is not presence: a malformed record is the trace gate's
+    // business, and this predicate only answers whether the engine wrote one.
+    if (!role.doorOnly && role.plan) {
+        const block = r.standards.parseStandardsBlock(text);
+        if (block.present && block.record !== null)
+            kinds.push(exports.RECORDED_ARTIFACT_KIND.STANDARDS_BLOCK);
+    }
+    if (!role.doorOnly && role.summary) {
+        const section = r.standards.parseConsultedSection(text);
+        if (section.present && section.planId !== null)
+            kinds.push(exports.RECORDED_ARTIFACT_KIND.STANDARDS_CONSULTED);
+    }
+    const door = parseDoorRecord(text);
+    if (door.ok && door.record !== null)
+        kinds.push(exports.RECORDED_ARTIFACT_KIND.DOOR_RECORD);
+    return kinds;
+}
+/**
+ * The engine-written vault records one directory holds (phase-level, D-20).
+ *
+ * The scan shape of the router's `collectTraceArtifacts`: `readdir`, sort,
+ * filename rules, a `seen` counter, a cap without `break`. Candidates are
+ * `*PLAN.md`, `*SUMMARY.md` and the door artifacts. Each candidate under the
+ * byte cap is read ONCE and classified by the real parsers, never a regex:
+ *   - `standards_block`: a parsed `<vault_standards>` record (PLAN);
+ *   - `standards_consulted`: a parsed `## Standards Consulted` section (SUMMARY);
+ *   - `door_record`: a parsed door record (any candidate).
+ * A missing directory reads as empty.
+ *
+ * This reader does NOT check `.platform-bindings.json`. Its callers are the
+ * handlers, which are bindings-inert before they get here (D-37), and the
+ * project-level predicate below, which checks bindings first (D-42).
+ */
+function collectRecordedArtifacts(dirAbs, opts = {}) {
+    const fsx = opts.fs ?? node_fs_1.default;
+    const byteCap = typeof opts.byteCap === 'number' ? opts.byteCap : exports.TRACE_ARTIFACT_BYTE_CAP;
+    const countCap = typeof opts.countCap === 'number' ? opts.countCap : exports.TRACE_ARTIFACT_COUNT_CAP;
+    const doorOnly = opts.doorOnly === true;
+    let entries;
+    try {
+        entries = fsx.readdirSync(dirAbs).map(String);
+    }
+    catch {
+        return { artifacts: [], truncated: false, seen: 0, skipped: 0 };
+    }
+    const root = resolveRoot(opts.root, dirAbs);
+    const relOf = (abs) => node_path_1.default.relative(root, abs).split(node_path_1.default.sep).join('/') || '.';
+    const r = readers();
+    const artifacts = [];
+    let seen = 0;
+    let admitted = 0;
+    let skipped = 0;
+    for (const name of entries.sort()) {
+        if (opts.onlyFile !== undefined && name !== opts.onlyFile)
+            continue;
+        const plan = PLAN_FILENAME_RE.test(name);
+        const summary = SUMMARY_FILENAME_RE.test(name);
+        const door = exports.DOOR_ARTIFACT_FILENAME_RE.test(name);
+        if (doorOnly ? !door : !(plan || summary || door))
+            continue;
+        // The router's 04-07 rule: count every candidate, admit no more than the cap.
+        seen += 1;
+        if (admitted >= countCap)
+            continue;
+        admitted += 1;
+        const abs = node_path_1.default.join(dirAbs, name);
+        let text;
+        try {
+            const st = fsx.statSync(abs);
+            if (!st.isFile() || st.size > byteCap) {
+                skipped += 1;
+                continue;
+            }
+            text = String(fsx.readFileSync(abs, 'utf8'));
+        }
+        catch {
+            skipped += 1;
+            continue;
+        }
+        for (const kind of classifyCandidate(r, text, { plan, summary, doorOnly })) {
+            artifacts.push({ rel: relOf(abs), abs, kind });
+            if (opts.stopAtFirst === true)
+                return { artifacts, truncated: false, seen, skipped };
+        }
+    }
+    return { artifacts, truncated: seen > countCap, seen, skipped };
+}
+// ─── disabled_with_artifacts (SEAL-02 handlers, 16-09; D-21, D-22, D-39) ─────
+/**
+ * The status the trace gate answers when `vault.enabled` is off over a phase
+ * that holds engine-written records. The literal is restated at the emitting
+ * line (the producer-audit and FENCE 2 probes read emission sites); this
+ * constant is what tests compare against.
+ */
+exports.DISABLED_WITH_ARTIFACTS_STATUS = 'disabled_with_artifacts';
+/** The one switch that can silence the vault gates. */
+exports.VAULT_SWITCH_KEY = 'vault.enabled';
+/** How many artifact paths a verdict lists before it only counts. */
+exports.DISABLED_WITH_ARTIFACTS_LIST_CAP = 20;
+/**
+ * The repair, and only the repair (D-39, INVARIANT 4): turn the switch back on
+ * so the records can be checked. There is no override for this verdict, and
+ * the records are never named as something to get rid of.
+ */
+exports.DISABLED_WITH_ARTIFACTS_REPAIR = 'so the gate can check them. This verdict has no override; the records stay as they are.';
+/**
+ * The one-line message (D-39). Every value it interpolates is engine-derived
+ * (a count, the resolver's repo-relative directory), never artifact text.
+ */
+function formatDisabledWithArtifacts(facts) {
+    const n = facts.artifactCount;
+    const unread = typeof facts.unreadCount === 'number' && facts.unreadCount > 0 ? facts.unreadCount : 0;
+    const where = facts.phaseRel === '' ? 'this phase' : facts.phaseRel;
+    const found = `${n} recorded vault artifact${n === 1 ? '' : 's'} in ${where}`;
+    const what = unread === 0
+        ? `${found} cannot be checked`
+        : `${found}, and ${unread} candidate file${unread === 1 ? '' : 's'} there not read (over the size or count `
+            + 'cap, or unreadable), so a record cannot be ruled out; none of it can be checked';
+    return `Vault records ${n > 0 ? 'present' : 'not ruled out'} while \`${exports.VAULT_SWITCH_KEY}\` is off `
+        + `(${exports.DISABLED_WITH_ARTIFACTS_STATUS}): ${what}, so this phase cannot be recorded as governed (SEAL-02). `
+        + disabledWithArtifactsRepair();
+}
+/**
+ * The repair sentence alone: the message's tail, and the trusted tail of the
+ * gate's problem detail, so the two can never name different repairs.
+ */
+function disabledWithArtifactsRepair() {
+    return `Repair: set \`${exports.VAULT_SWITCH_KEY}\` to true ${exports.DISABLED_WITH_ARTIFACTS_REPAIR}`;
+}
+/**
+ * The `disabled_with_artifacts` verdict body over one phase's scan, or `null`
+ * when the scan found no record (the caller then answers exactly as before).
+ *
+ * Paths are de-duplicated (one file can hold two records) and listed in scan
+ * order up to `DISABLED_WITH_ARTIFACTS_LIST_CAP`; `artifactCount` counts them
+ * all.
+ *
+ * ABSENCE MUST BE PROVEN (16-09, D-69, amending D-44's handler sentence). A
+ * scan that found no record but did not read every candidate (a file over the
+ * byte cap, an unreadable one, or more candidates than the count cap) cannot
+ * say "never recorded", so it answers this verdict with `artifactCount: 0` and
+ * `unreadCount`, never `null`. A `null` here makes the handler answer
+ * `inactive` / `inert`, `block: false`: a dispatched seal gate passing where it
+ * proved nothing. Turning the switch back on lets the trace gate name the
+ * unread file itself (`artifact_too_large`, `artifact_unreadable`,
+ * `artifacts_truncated`).
+ */
+function disabledWithArtifactsVerdict(scan, opts) {
+    const admitted = Math.min(scan.seen, exports.TRACE_ARTIFACT_COUNT_CAP);
+    const unread = scan.skipped + (scan.truncated ? scan.seen - admitted : 0);
+    if (scan.artifacts.length === 0 && unread === 0)
+        return null;
+    const rels = [];
+    const kinds = [];
+    for (const a of scan.artifacts) {
+        if (!rels.includes(a.rel))
+            rels.push(a.rel);
+        if (!kinds.includes(a.kind))
+            kinds.push(a.kind);
+    }
+    return {
+        artifacts: rels.slice(0, exports.DISABLED_WITH_ARTIFACTS_LIST_CAP),
+        artifactCount: rels.length,
+        ...(unread > 0 ? { unreadCount: unread } : {}),
+        kinds,
+        message: formatDisabledWithArtifacts({
+            artifactCount: rels.length,
+            phaseRel: opts.phaseRel,
+            ...(unread > 0 ? { unreadCount: unread } : {}),
+        }),
+    };
+}
+/** The sub-directories of a planning root, sorted; `null` when absence cannot be proven. */
+function childDirs(fsx, dirAbs) {
+    try {
+        return fsx.readdirSync(dirAbs, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => node_path_1.default.join(dirAbs, d.name))
+            .sort();
+    }
+    catch (e) {
+        const code = e?.code;
+        return code === 'ENOENT' || code === 'ENOTDIR' ? [] : null;
+    }
+}
+/** Raised inside the enumeration when absence can no longer be proven (D-44). */
+class CannotProveAbsence extends Error {
+}
+/** Every directory the project-level predicate reads, in order, lazily. */
+function* planningDirs(fsx, planning) {
+    const listed = (dir) => {
+        const out = childDirs(fsx, dir);
+        if (out === null)
+            throw new CannotProveAbsence();
+        return out;
+    };
+    for (const dir of listed(node_path_1.default.join(planning, 'phases')))
+        yield { dir, doorOnly: false };
+    for (const ws of listed(node_path_1.default.join(planning, 'workstreams'))) {
+        for (const dir of listed(node_path_1.default.join(ws, 'phases')))
+            yield { dir, doorOnly: false };
+    }
+    // Quick task directories are always under the ROOT planning tree, never a
+    // workstream's (src/init.cts quick-dir resolution).
+    for (const dir of listed(node_path_1.default.join(planning, 'quick')))
+        yield { dir, doorOnly: false };
+    yield { dir: node_path_1.default.join(planning, 'audits'), doorOnly: true };
+}
+/**
+ * Does this project hold ANY engine-written vault record? (project-level, D-20)
+ *
+ * The question the resolver's injected seal predicate asks (16-08): a seal
+ * gate renders for a config-inactive capability only when this is true.
+ *
+ *   - No `.platform-bindings.json` at the project root → false, first, before
+ *     any planning file is read (D-42): a non-Pareto project never holds
+ *     recorded artifacts, even if it ran a vault verb that wrote one, because
+ *     every vault handler answers it inert first (D-37), and a seal that
+ *     rendered there would dispatch a gate whose handler cannot block.
+ *   - Otherwise every phase directory (root and workstream), every quick
+ *     directory and the door artifacts in `.planning/audits` are scanned with
+ *     `collectRecordedArtifacts`; the first record found answers true and
+ *     nothing more is read.
+ *   - When absence cannot be PROVEN — the directory cap is passed, a
+ *     directory's candidates were truncated or skipped, or a planning root
+ *     could not be listed for a reason other than not existing — the answer is
+ *     true (D-44). A false here silences the seal, so it must mean "looked
+ *     everywhere and found nothing". A true only lets the seal gate render; its
+ *     handler then reads the phase it is asked about and blocks only on the
+ *     records actually there.
+ */
+function hasRecordedVaultArtifacts(cwd, opts = {}) {
+    const fsx = opts.fs ?? node_fs_1.default;
+    let root;
+    try {
+        root = resolveRoot(undefined, cwd);
+        // 16-05 (D-37): the one bindings predicate the five vault handlers ask
+        // first, required lazily (D-41: this leaf imports only fs and path at load
+        // time) and handed this function's file system, so the seam still holds.
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const vaultMod = require('./vault.cjs');
+        if (!vaultMod.hasPlatformBindings(root, fsx))
+            return false;
+    }
+    catch {
+        return false;
+    }
+    try {
+        let visited = 0;
+        for (const { dir, doorOnly } of planningDirs(fsx, node_path_1.default.join(root, '.planning'))) {
+            visited += 1;
+            if (visited > exports.RECORDED_ARTIFACT_DIR_CAP)
+                return true;
+            const scan = collectRecordedArtifacts(dir, { root, fs: fsx, doorOnly, stopAtFirst: true });
+            if (scan.artifacts.length > 0)
+                return true;
+            if (scan.truncated || scan.skipped > 0)
+                return true;
+        }
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Read a record's start, end and back-fill anchors, by record kind.
+ *
+ *   - `standards_consulted`: the parsed section's optional anchor line
+ *     (`anchors: { start?, end, backfill? }`, 16-06);
+ *   - `door_record`: the record's `startCommit` / `endCommit` (a door record is
+ *     written by its door, so it is never back-filled).
+ * Every other kind, and every record written before Phase 16, has none: all
+ * three are `undefined`. A value that is present but fails its grammar is
+ * DROPPED and reported in `problems` by field, so 16-07 can type it; it never
+ * reaches a caller that might place it in a git argv (T-16-07). Never throws.
+ *
+ * 16-06 re-premised `backfill` (D-55): 16-03 read it as a sha taken from the
+ * back-fill object's `at`. D-32 makes the back-fill an attribution — who and
+ * when — while the sha the operator supplied with `--at` becomes the record's
+ * END anchor, so `backfill` is now that `{ by, at }` pair.
+ */
+function extractRecordAnchors(text, kind) {
+    const out = { start: undefined, end: undefined, backfill: undefined, problems: [] };
+    const take = (field, value) => {
+        if (value === undefined || value === null)
+            return;
+        if (isAnchorSha(value))
+            out[field] = value;
+        else
+            out.problems.push({ kind: 'anchor_invalid', field });
+    };
+    const takeBackfill = (value) => {
+        if (value === undefined || value === null)
+            return;
+        if (isAnchorBackfill(value))
+            out.backfill = { by: value.by, at: value.at };
+        else
+            out.problems.push({ kind: 'anchor_invalid', field: 'backfill' });
+    };
+    try {
+        const body = typeof text === 'string' ? text : '';
+        if (kind === exports.RECORDED_ARTIFACT_KIND.STANDARDS_CONSULTED) {
+            const standards = readers().standards;
+            const section = standards.parseConsultedSection(body);
+            if (section.present !== true || section.planId === null) {
+                out.problems.push({ kind: 'record_unparsable', field: 'record' });
+                return out;
+            }
+            const anchors = (section.anchors && typeof section.anchors === 'object' ? section.anchors : {});
+            take('start', anchors.start);
+            take('end', anchors.end);
+            takeBackfill(anchors.backfill);
+            // A prefixed anchor line that did not parse is dropped by the parser and
+            // reported as `standards_anchor_malformed`; it is an invalid anchor here.
+            const problems = Array.isArray(section.problems) ? section.problems : [];
+            if (problems.some((p) => p && p.kind === standards.STANDARDS_PROBLEM_KIND.ANCHOR_MALFORMED)) {
+                out.problems.push({ kind: 'anchor_invalid', field: 'end' });
+            }
+        }
+        else if (kind === exports.RECORDED_ARTIFACT_KIND.DOOR_RECORD) {
+            const parsed = parseDoorRecord(body);
+            if (!parsed.ok || parsed.record === null) {
+                out.problems.push({ kind: 'record_unparsable', field: 'record' });
+                return out;
+            }
+            take('start', parsed.record.startCommit);
+            take('end', parsed.record.endCommit);
+        }
+    }
+    catch {
+        out.problems.push({ kind: 'record_unparsable', field: 'record' });
+    }
+    return out;
+}
+// ─── SEAL-01: commits no record covers (16-07; D-15, D-16, D-31) ─────────────
+//
+// THE QUESTION. A phase's records end at their END anchors. A commit made after
+// them is invisible to every reader that judges records, so an unrecorded
+// change could ship under a phase whose records all say "governed". The strict
+// trace points (ship:pre, verify:post on a full-phase run, quick's
+// execute:post) ask instead: which commits reachable from HEAD are reachable
+// from none of this phase's ends, and are covered by no other record's range?
+//
+// THE RANGE RULE (D-31, research C-7). A commit c is covered iff some record r
+// has start_r < c <= end_r in ancestry: `rev-list start_r..end_r`, start
+// exclusive, end inclusive. The simpler ancestor rule ("c is an ancestor of
+// some recorded end") was measured to hide an ungoverned commit followed by ANY
+// later record (E1 -> X -> Q: X is an ancestor of Q's end), which is a record
+// claiming governance it never had. Per-record calls are required: the union of
+// ranges is not `ends --not starts`.
+//
+// ASSUMPTIONS (16-RESEARCH A1, A3), stated where they bind:
+//   - A1: merge commits are excluded (`--no-merges`); the commits a merge brings
+//     in are examined themselves. An "evil merge" carrying its own source edit
+//     is not seen.
+//   - A3: a shallow clone may not hold an old anchor; that reads as an unknown
+//     anchor, and the router's remedy names `git fetch --unshallow`.
+//
+// SAFETY OF THE ARGV (T-16-25). Every recorded sha is checked against
+// `ANCHOR_SHA_RE` before any git call. Revisions for `rev-list` go on STDIN,
+// never in argv (research Pitfall 6); a sha placed in argv (`merge-base`,
+// `diff-tree`, `log`) comes after the subcommand and is hex by construction,
+// so it can never be read as an option.
+//
+// BOUNDS (T-16-28). Every call is the injected bounded `execGit` (timeout, no
+// throw; ENOBUFS and a timeout come back as a failed exit). Each count has a
+// cap, and passing one is a typed failure, never a silent partial answer.
+/** At most this many uncovered source commits are listed; the rest are counted. */
+exports.UNCOVERED_COMMIT_CAP = 50;
+/**
+ * At most this many covering records may need their range computed. Only a
+ * record whose END is itself one of the candidates can cover a candidate (see
+ * `computeUncoveredSourceCommits`), so this counts the records written after
+ * the phase being judged, not every record the project holds.
+ */
+exports.COVERING_RECORD_CAP = 200;
+/** At most this many source paths are named per uncovered commit. */
+exports.UNCOVERED_PATHS_PER_COMMIT_CAP = 20;
+/**
+ * At most this many commits after the phase's ends are examined at all, and at
+ * most this many commits a single record's range may hold. 5000 full ids are
+ * ~205 KB of `rev-list` output (sha-1) or ~325 KB (sha-256), well inside
+ * the 1 MiB child-process output buffer `execGit` runs with.
+ */
+exports.SEAL_CANDIDATE_CAP = 5000;
+/** At most this many uncovered commits have their paths read (one `diff-tree` each). */
+exports.SEAL_EXAMINE_CAP = 500;
+/** A commit subject is bounded to this many characters before it leaves the leaf. */
+exports.SEAL_SUBJECT_CAP = 120;
+/** Each git call's timeout. */
+exports.SEAL_GIT_TIMEOUT_MS = 10_000;
+/**
+ * A record's anchors as the seal judges them: `extractRecordAnchors`, plus ONE
+ * fallback for the start.
+ *
+ * A SUMMARY record (the standards section) that carries an END but no START
+ * takes the start its own directory's `.vault-anchors.json` records. That file
+ * is the one `vault standards consulted` reads the start from when it writes
+ * the record, so the fallback reads the same CLI-recorded value from the same
+ * place, at a later moment (D-59). It exists for the worktree executor (deferred-items item 12): the
+ * anchors file is untracked, a linked worktree does not have it, so a record
+ * written there carries the end only; the strict points run in the checkout
+ * that wrote the file, where the start is readable.
+ *
+ * Not applied when the record's own anchor was present and malformed (a
+ * `problems` entry): a hand-edited start is reported as `anchor_invalid` at
+ * every point (D-58), and must not be quietly replaced by another value. Not
+ * applied to a door record, whose start is its own `--begin` start and whose
+ * directory's anchors file is the phase's, not the door's. Never throws.
+ */
+function resolveRecordAnchors(text, kind, dirAbs, opts = {}) {
+    const anchors = extractRecordAnchors(text, kind);
+    const out = { ...anchors, startFrom: anchors.start !== undefined ? 'record' : undefined };
+    const summaryKind = kind === exports.RECORDED_ARTIFACT_KIND.STANDARDS_CONSULTED;
+    if (!summaryKind || anchors.end === undefined || anchors.start !== undefined)
+        return out;
+    if (anchors.problems.some((p) => p.kind === 'anchor_invalid'))
+        return out;
+    const dir = opts.dirAnchors !== undefined ? opts.dirAnchors : readDirAnchors(dirAbs);
+    if (!dir || !isAnchorSha(dir.start))
+        return out;
+    // D-98: the LATEST recorded start that precedes this record's own end. A
+    // start recorded after the record's work (a resume) is not its start, so a
+    // run-1 worktree record keeps run 1's start and a later one takes the later
+    // start. Without an ancestry check (no git), the current start alone — the
+    // reading that covers least.
+    const candidates = [dir.start, ...(dir.earlier ?? []).map((e) => e.start)];
+    const end = anchors.end;
+    const chosen = typeof opts.isAncestor === 'function'
+        ? candidates.find((c) => {
+            try {
+                return opts.isAncestor(c, end);
+            }
+            catch {
+                return false;
+            }
+        })
+        : candidates[0];
+    if (chosen !== undefined) {
+        out.start = chosen;
+        out.startFrom = 'directory';
+    }
+    return out;
+}
+/**
+ * The ancestry predicate the strict gate injects: one bounded `merge-base
+ * --is-ancestor` per question, shapes checked before git is reached, any
+ * failure read as "not an ancestor" (the reading that covers less).
+ */
+function sealIsAncestorVia(execGit, root, timeoutMs = exports.SEAL_GIT_TIMEOUT_MS) {
+    return (ancestor, descendant) => {
+        if (!isAnchorSha(ancestor) || !isAnchorSha(descendant))
+            return false;
+        try {
+            const r = execGit(['merge-base', '--is-ancestor', ancestor, descendant], { cwd: root, timeout: timeoutMs });
+            return r.exitCode === 0 && (r.error === undefined || r.error === null) && (r.signal === undefined || r.signal === null);
+        }
+        catch {
+            return false;
+        }
+    };
+}
+/** The attestations a directory holds for one record file, as the seal reads them. */
+function attestedFor(attestations, recordName) {
+    return attestations.filter((a) => a.record === recordName).map((a) => ({ sha: a.sha, from: a.from }));
+}
+/** A cheap pre-filter: a record written before 16-06 carries neither marker and is not parsed. */
+const CONSULTED_ANCHOR_MARKER = '- anchors: ';
+/**
+ * Every record in the project's planning tree that carries an END anchor.
+ *
+ * Walks the roots `hasRecordedVaultArtifacts` walks, in its order: phase
+ * directories (root and every workstream), quick-task directories, and the
+ * door artifacts in `.planning/audits`. In each directory the candidates are
+ * `*SUMMARY.md` (a standards section) and the door
+ * artifacts (a door record), each read once under `TRACE_ARTIFACT_BYTE_CAP`.
+ * A record carrying an end but no start is returned with `start` undefined
+ * (it covers nothing, D-31) unless its directory's anchors file supplies one
+ * (`resolveRecordAnchors`, D-59).
+ *
+ * `exclude` names records (repo-relative) the caller judges itself: the trace
+ * gate passes the phase's own SUMMARYs, which are its END anchors, not its
+ * coverage. The caller is bindings-inert before it gets here (D-37). Never
+ * throws.
+ */
+function collectCoveringRecords(root, opts = {}) {
+    const fsx = opts.fs ?? node_fs_1.default;
+    const exclude = new Set(opts.exclude ?? []);
+    const records = [];
+    let incomplete = false;
+    let unread = 0;
+    const relOf = (abs) => node_path_1.default.relative(root, abs).split(node_path_1.default.sep).join('/');
+    try {
+        let visited = 0;
+        for (const { dir, doorOnly } of planningDirs(fsx, node_path_1.default.join(root, '.planning'))) {
+            visited += 1;
+            if (visited > exports.RECORDED_ARTIFACT_DIR_CAP) {
+                incomplete = true;
+                break;
+            }
+            let entries;
+            try {
+                entries = fsx.readdirSync(dir).map(String).sort();
+            }
+            catch (e) {
+                const code = e?.code;
+                if (code !== 'ENOENT' && code !== 'ENOTDIR')
+                    incomplete = true;
+                continue;
+            }
+            let dirAnchors;
+            let dirAttestations;
+            let dirCertifiedEnds;
+            let admitted = 0;
+            for (const name of entries) {
+                const summary = !doorOnly && SUMMARY_FILENAME_RE.test(name);
+                const door = exports.DOOR_ARTIFACT_FILENAME_RE.test(name);
+                if (!summary && !door)
+                    continue;
+                const abs = node_path_1.default.join(dir, name);
+                const rel = relOf(abs);
+                if (exclude.has(rel))
+                    continue;
+                if (admitted >= exports.TRACE_ARTIFACT_COUNT_CAP) {
+                    incomplete = true;
+                    break;
+                }
+                admitted += 1;
+                let text;
+                try {
+                    const st = fsx.statSync(abs);
+                    if (!st.isFile() || st.size > exports.TRACE_ARTIFACT_BYTE_CAP) {
+                        unread += 1;
+                        incomplete = true;
+                        continue;
+                    }
+                    text = String(fsx.readFileSync(abs, 'utf8'));
+                }
+                catch {
+                    unread += 1;
+                    incomplete = true;
+                    continue;
+                }
+                const tries = [];
+                if (summary && text.includes(CONSULTED_ANCHOR_MARKER))
+                    tries.push(exports.RECORDED_ARTIFACT_KIND.STANDARDS_CONSULTED);
+                if (door && text.includes(exports.DOOR_RECORD_HEADING))
+                    tries.push(exports.RECORDED_ARTIFACT_KIND.DOOR_RECORD);
+                for (const kind of tries) {
+                    if (dirAnchors === undefined && kind !== exports.RECORDED_ARTIFACT_KIND.DOOR_RECORD)
+                        dirAnchors = readDirAnchors(dir);
+                    const a = resolveRecordAnchors(text, kind, dir, { dirAnchors: dirAnchors ?? null, isAncestor: opts.isAncestor });
+                    if (a.end === undefined)
+                        continue;
+                    const rec = { rel, start: a.start, end: a.end, backfill: a.backfill, startFrom: a.startFrom };
+                    if (kind !== exports.RECORDED_ARTIFACT_KIND.DOOR_RECORD) {
+                        if (dirAttestations === undefined)
+                            dirAttestations = readDirAttestations(dir);
+                        const att = attestedFor(dirAttestations, name);
+                        if (att.length > 0)
+                            rec.attested = att;
+                        // 16-18 D-107: read once per directory, for a PHASE record only (a
+                        // quick task's record is never certified: it never bounds, D-104);
+                        // set only, never `false`, so an uncertified record reads as before.
+                        if (isPhaseRecordRel(rel)) {
+                            if (dirCertifiedEnds === undefined)
+                                dirCertifiedEnds = new Set(readDirCertificates(dir).map((c) => c.end));
+                            if (dirCertifiedEnds.has(a.end))
+                                rec.certified = true;
+                        }
+                    }
+                    records.push(rec);
+                    break;
+                }
+            }
+        }
+    }
+    catch {
+        incomplete = true;
+    }
+    return { records, incomplete, unread };
+}
+/**
+ * Is this record a PHASE plan's (a file directly inside a `phases/<dir>/`
+ * directory, at the root or in a workstream)? A quick task's lives in
+ * `quick/<dir>/` and a door artifact may sit in `audits/`. Read off the
+ * repo-relative path the walk produced (16 review iteration 3 WR-02, D-104).
+ */
+function isPhaseRecordRel(rel) {
+    const parts = String(rel).split('/');
+    return parts.length >= 3 && parts[parts.length - 3] === 'phases';
+}
+/**
+ * Is this record a SUMMARY (a phase plan's or a quick task's), as opposed to
+ * a door artifact? Read off the file name alone; whether it is a PHASE record
+ * is `isPhaseRecordRel`'s question. The one owner of summary-ness for SEAL-01's
+ * lower bound (c2) and for `vault anchor certify` (16 gap closure 16-18, D-107).
+ */
+function isSummaryRecordRel(rel) {
+    return SUMMARY_FILENAME_RE.test(String(rel).split('/').pop() ?? '');
+}
+const DEFAULT_SEAL_CAPS = Object.freeze({
+    uncovered: exports.UNCOVERED_COMMIT_CAP,
+    coveringRecords: exports.COVERING_RECORD_CAP,
+    pathsPerCommit: exports.UNCOVERED_PATHS_PER_COMMIT_CAP,
+    candidates: exports.SEAL_CANDIDATE_CAP,
+    examine: exports.SEAL_EXAMINE_CAP,
+});
+/** One line of untrusted text, controls collapsed and bounded; the router's sanitiser still runs on it. */
+function boundedLine(value, cap) {
+    const flat = value.replace(/[\u0000-\u001F\u007F-\u009F]+/g, ' ').replace(/\s+/g, ' ').trim();
+    return flat.length > cap ? `${flat.slice(0, cap)}…` : flat;
+}
+/**
+ * Which commits after this phase's END anchors touch governed source and are
+ * covered by no other record's range? (SEAL-01, D-15, D-16, D-31)
+ *
+ * In order, every step through the injected bounded `execGit` with `cwd: root`:
+ *   (a) every sha in `phaseEnds` and in `coveringRecords` must pass
+ *       `ANCHOR_SHA_RE`, or `anchor_invalid`, before any git call;
+ *   (b) every phase end must exist: `rev-list --no-walk --ignore-missing
+ *       --stdin`, the printed set compared with the input set, else
+ *       `anchor_unknown` naming the missing ones;
+ *   (c) every phase end must be an ancestor of HEAD: `merge-base --is-ancestor
+ *       <end> HEAD`, else `anchor_not_ancestor` naming them;
+ *   (c2) the lower bound (16 review CR-04): without `phaseRecords`, the
+ *       phase's ends. With them, each own record whose start is an ancestor of
+ *       its end (`merge-base --is-ancestor`) contributes its start..end range;
+ *       their common base (`merge-base --octopus` when they differ) is walked
+ *       back (`rev-list --max-count=<cap+1>`), and the ends of OTHER phase
+ *       plans' SUMMARY records found there that are CERTIFIED (`certified ===
+ *       true`: their directory's certificates file holds the end, written only
+ *       by `vault anchor certify` after a clean strict check of that phase —
+ *       16 gap closure 16-18, D-107, closing D-106) are the lower bound, so the
+ *       commits between the latest certified phase record and this phase's
+ *       start are candidates too. An UNCERTIFIED phase record (its own strict
+ *       check blocked, never ran, was overridden, or ran before this engine)
+ *       covers its own range but never bounds, so the commit its gate named is
+ *       named again here; a quick task's record (its one strict gate records
+ *       nothing, D-104) and a door record (no gate, D-90) never bound. No
+ *       certified phase record in the window (D-109): the oldest point where a
+ *       windowed quick or uncertified phase SUMMARY record started (its end
+ *       without a usable start), via `merge-base --octopus` with the base;
+ *       with none, the base itself (nothing before it was governed). A full
+ *       window with an earlier SUMMARY record beyond it is `cap_exceeded`,
+ *       naming `vault anchor certify` as the repair. An own record with no
+ *       usable start keeps its end as a bound, as before;
+ *   (d) the candidates: `rev-list --parents --max-count=<cap+1> HEAD --stdin`
+ *       with one `^<bound>` line per bound on stdin; merge commits (two or more
+ *       parents) are reachable but never candidates (research A1). MEASURED
+ *       FORM (git 2.55.0): a `^<sha>` line is the revision syntax `rev-list
+ *       --stdin` has always read; a `--not` line on stdin also works on 2.55.0,
+ *       but pseudo-options on stdin are newer than `--stdin` itself, so the
+ *       portable spelling is used. More than the cap is `cap_exceeded`;
+ *   (e) coverage: only a record whose END is itself reachable here can cover a
+ *       candidate (an end reachable from a bound puts its whole range there
+ *       too, and an end that is not an ancestor of HEAD, or unknown, covers
+ *       nothing on this branch, so neither needs a git call); a merge commit
+ *       counts as reachable here (16 review WR-05). This phase's own ranges
+ *       cover too, and are not counted against the record cap. For each
+ *       such record: no start → skipped (`no_start`); `merge-base
+ *       --is-ancestor <start> <end>` exit 1 → skipped (`start_not_ancestor`),
+ *       128 → skipped (`start_unknown`); otherwise `rev-list --first-parent
+ *       --max-count=<cap+1> --stdin` with `^<start>` and `<end>` on stdin, and
+ *       its commits are covered: the record's own line only, never what a merge
+ *       brought in from another branch (16 review WR-02). A skipped record covers nothing; it is never a failure. More
+ *       than `coveringRecords` such records is `cap_exceeded`;
+ *   (f) the uncovered candidates, in `rev-list` order, up to `examine`: the
+ *       paths from `diff-tree -r -z --root --no-commit-id --name-only
+ *       --no-renames <sha>` (`--no-renames`, so moving source into `docs/` still
+ *       lists the source path; `-z`, so a non-ASCII path is not C-quoted), the
+ *       commit kept when at least one path is not `isNonSourcePath`, its
+ *       subject from `log -1 --format=%s <sha>`. The scan stops after
+ *       `uncovered` source commits (`truncated`). A scan stopped by `examine`
+ *       with none found is `cap_exceeded`: the rest could not be checked.
+ * Any non-zero exit, a timeout or ENOBUFS (`execGit` reports both as a failed
+ * exit) is `git_failed`. Never throws.
+ */
+function computeUncoveredSourceCommits(opts) {
+    const caps = { ...DEFAULT_SEAL_CAPS, ...(opts.caps ?? {}) };
+    const timeout = typeof opts.timeoutMs === 'number' ? opts.timeoutMs : exports.SEAL_GIT_TIMEOUT_MS;
+    const git = (args, input) => {
+        try {
+            return opts.execGit(args, { cwd: opts.root, timeout, ...(input !== undefined ? { input } : {}) });
+        }
+        catch (e) {
+            // The real execGit never throws; an injected one might, and a throw here
+            // must still become a typed failure rather than escape the gate.
+            return { exitCode: 1, stdout: '', stderr: String(e?.message ?? e), error: e };
+        }
+    };
+    const hard = (r) => (r.error !== undefined && r.error !== null)
+        || (r.signal !== undefined && r.signal !== null);
+    const failed = (args, r) => ({
+        ok: false,
+        reason: 'git_failed',
+        detail: `git ${args[0]} failed (exit ${r.exitCode})${r.stderr ? `: ${boundedLine(r.stderr, exports.SEAL_SUBJECT_CAP)}` : ''}`,
+    });
+    const lines = (out) => out.split(/\r?\n/).map((l) => l.trim()).filter((l) => l !== '');
+    // (a) the grammar, before any git call.
+    const ends = [...new Set(Array.isArray(opts.phaseEnds) ? opts.phaseEnds : [])];
+    if (ends.length === 0)
+        return { ok: false, reason: 'anchor_invalid', detail: 'no phase end anchor was given' };
+    if (!ends.every(isAnchorSha)) {
+        return { ok: false, reason: 'anchor_invalid', detail: 'a phase end anchor is not a full lowercase commit id' };
+    }
+    const covering = Array.isArray(opts.coveringRecords) ? opts.coveringRecords : [];
+    for (const r of covering) {
+        if (!isAnchorSha(r.end) || (r.start !== undefined && !isAnchorSha(r.start))) {
+            return { ok: false, reason: 'anchor_invalid', detail: 'a covering record anchor is not a full lowercase commit id' };
+        }
+    }
+    const own = Array.isArray(opts.phaseRecords) ? opts.phaseRecords : null;
+    for (const r of own ?? []) {
+        if (!isAnchorSha(r.end) || (r.start !== undefined && !isAnchorSha(r.start))) {
+            return { ok: false, reason: 'anchor_invalid', detail: 'a phase record anchor is not a full lowercase commit id' };
+        }
+    }
+    // (b) every phase end exists.
+    const existArgs = ['rev-list', '--no-walk', '--ignore-missing', '--stdin'];
+    const exist = git(existArgs, `${ends.join('\n')}\n`);
+    if (exist.exitCode !== 0 || hard(exist))
+        return failed(existArgs, exist);
+    const present = new Set(lines(exist.stdout));
+    const unknown = ends.filter((e) => !present.has(e));
+    if (unknown.length > 0) {
+        return { ok: false, reason: 'anchor_unknown', anchors: unknown, detail: `${unknown.length} end anchor(s) are not in this repository` };
+    }
+    // (c) every phase end is an ancestor of HEAD.
+    const notAncestor = [];
+    for (const end of ends) {
+        const args = ['merge-base', '--is-ancestor', end, 'HEAD'];
+        const r = git(args);
+        if (r.exitCode === 0 && !hard(r))
+            continue;
+        if (r.exitCode === 1 && !hard(r)) {
+            notAncestor.push(end);
+            continue;
+        }
+        return failed(args, r);
+    }
+    if (notAncestor.length > 0) {
+        return { ok: false, reason: 'anchor_not_ancestor', anchors: notAncestor, detail: `${notAncestor.length} end anchor(s) are not ancestors of HEAD` };
+    }
+    // (c2) the lower bound (16 review CR-04). Without the phase's own records
+    // its ends bound the candidates, as D-15 first wrote it. With them, the
+    // phase claims only its own start..end ranges: the candidates reach back to
+    // the latest earlier record's end, so an ungoverned commit made after that
+    // end and before this phase's start (E1 -> X -> P, start = X) is named here,
+    // at this phase's strict point, not only by an earlier phase whose gate may
+    // have run before X existed.
+    const lower = own === null ? ends : [];
+    const ownRanges = [];
+    if (own !== null) {
+        const tops = [];
+        const bounds = new Set();
+        for (const r of own) {
+            let valid = false;
+            if (r.start !== undefined) {
+                const args = ['merge-base', '--is-ancestor', r.start, r.end];
+                const res = git(args);
+                if (hard(res))
+                    return failed(args, res);
+                valid = res.exitCode === 0;
+            }
+            if (valid) {
+                ownRanges.push(r);
+                if (!tops.includes(r.start))
+                    tops.push(r.start);
+            }
+            else {
+                // No usable start (D-59 already reports a missing one): its end keeps
+                // bounding the candidates, exactly as before this rule.
+                bounds.add(r.end);
+            }
+        }
+        for (const e of ends)
+            if (!own.some((r) => r.end === e))
+                bounds.add(e);
+        if (tops.length === 0) {
+            for (const e of ends)
+                bounds.add(e);
+        }
+        else {
+            let base = tops[0];
+            if (tops.length > 1) {
+                const mbArgs = ['merge-base', '--octopus', ...tops];
+                const mb = git(mbArgs);
+                if (mb.exitCode !== 0 || hard(mb))
+                    return failed(mbArgs, mb);
+                base = lines(mb.stdout)[0] ?? '';
+                if (!isAnchorSha(base))
+                    return { ok: false, reason: 'git_failed', detail: 'git merge-base printed a line that is not a commit id' };
+            }
+            const winArgs = ['rev-list', `--max-count=${caps.candidates + 1}`, '--stdin'];
+            const win = git(winArgs, `${base}\n`);
+            if (win.exitCode !== 0 || hard(win))
+                return failed(winArgs, win);
+            const window = new Set(lines(win.stdout));
+            // Only a CERTIFIED phase plan's SUMMARY bounds (16 gap closure 16-18,
+            // D-107, closing the residual D-104 stated and D-106 ruled must be
+            // fixed). A bound says "every commit up to here was judged by a strict
+            // check that passed", and only a certificate records that: it is written
+            // by `vault anchor certify` alone, after that verb has itself run the
+            // phase's strict check and read `status: checked`, `block: false` and no
+            // override (D-108), and it is keyed by the record's END, so a SUMMARY
+            // written later is uncertified until the next clean check. An
+            // uncertified phase record — its own strict check blocked (an abandoned
+            // phase keeps its SUMMARY), never ran, was overridden, or ran before this
+            // engine — covers its own range but never bounds, so the commit its gate
+            // named is named again at this phase. A quick task's record never bounds
+            // (its one strict gate writes no record of passing, D-104), nor does a
+            // door record (it has no gate of its own, D-90); both still COVER. No
+            // fixpoint is needed: a certificate is only ever written after a clean
+            // strict check whose own bound was itself a certified end or the point
+            // where governance began, so trusting it never trusts an unjudged range.
+            const bounding = covering.filter((r) => isSummaryRecordRel(r.rel) && isPhaseRecordRel(r.rel) && r.certified === true);
+            const earlier = [...new Set(bounding.map((r) => r.end).filter((e) => window.has(e)))];
+            if (earlier.length > 0) {
+                for (const e of earlier)
+                    bounds.add(e);
+            }
+            else {
+                if (window.size > caps.candidates) {
+                    // The window did not reach the first commit: an earlier record may
+                    // end further back than the cap, in which case the commits between
+                    // it and this start cannot all be examined. Any SUMMARY counts here
+                    // (a quick or an uncertified one too): it says governance had begun
+                    // further back. Both details name the repair (D-109): certifying the
+                    // earlier phases, oldest first, gives this check a trusted bound,
+                    // and each certification is bounded by its own window.
+                    const repair = "; repair: certify the earlier phases oldest first (`pp-tools vault anchor certify <phase-dir>` once its strict check passes)";
+                    const beyond = covering.filter((r) => isSummaryRecordRel(r.rel) && !window.has(r.end));
+                    if (beyond.length > caps.coveringRecords) {
+                        return { ok: false, reason: 'cap_exceeded', detail: `${beyond.length} records would need an ancestry check against this phase's start, above the ${caps.coveringRecords}-record cap${repair}` };
+                    }
+                    for (const r of beyond) {
+                        const args = ['merge-base', '--is-ancestor', r.end, base];
+                        const res = git(args);
+                        if (hard(res))
+                            return failed(args, res);
+                        if (res.exitCode === 0) {
+                            return { ok: false, reason: 'cap_exceeded', detail: `more than ${caps.candidates} commits lie between this phase's start and the latest earlier record's end${repair}` };
+                        }
+                    }
+                }
+                // No certified phase record ends before this phase's start (D-109).
+                // A quick record or an uncertified phase record that does no longer
+                // bounds by its end, but it says governance had begun: the bound
+                // reaches back to where the oldest such record started (its end, when
+                // it has no usable start), so the commits between it and this start
+                // are candidates, and each record's own commits are covered by its
+                // range. With none, the start itself is where governance begins:
+                // nothing before it was governed. Only a bounding record (a certified
+                // phase SUMMARY) is skipped here, and none is in the window.
+                const reach = [];
+                for (const r of covering) {
+                    if (!isSummaryRecordRel(r.rel) || (isPhaseRecordRel(r.rel) && r.certified === true) || !window.has(r.end))
+                        continue;
+                    let point = r.end;
+                    if (r.start !== undefined) {
+                        const args = ['merge-base', '--is-ancestor', r.start, r.end];
+                        const res = git(args);
+                        if (hard(res))
+                            return failed(args, res);
+                        if (res.exitCode === 0)
+                            point = r.start;
+                    }
+                    if (!reach.includes(point))
+                        reach.push(point);
+                }
+                if (reach.length === 0) {
+                    bounds.add(base);
+                }
+                else {
+                    const mbArgs = ['merge-base', '--octopus', base, ...reach];
+                    const mb = git(mbArgs);
+                    if (mb.exitCode !== 0 || hard(mb))
+                        return failed(mbArgs, mb);
+                    const oldest = lines(mb.stdout)[0] ?? '';
+                    if (!isAnchorSha(oldest))
+                        return { ok: false, reason: 'git_failed', detail: 'git merge-base printed a line that is not a commit id' };
+                    bounds.add(oldest);
+                }
+            }
+        }
+        lower.push(...bounds);
+    }
+    // (d) the candidates: every commit reachable from HEAD and from none of the
+    // lower bounds, read with its parents so the merge commits stay in the set
+    // that decides which covering records are relevant (16 review WR-05) and
+    // out of the set that is classified (research A1).
+    const candArgs = ['rev-list', '--parents', `--max-count=${caps.candidates + 1}`, 'HEAD', '--stdin'];
+    const cand = git(candArgs, `${lower.map((e) => `^${e}`).join('\n')}\n`);
+    if (cand.exitCode !== 0 || hard(cand))
+        return failed(candArgs, cand);
+    const reachable = lines(cand.stdout).map((l) => l.split(/\s+/));
+    if (!reachable.every((row) => row.every(isAnchorSha)))
+        return { ok: false, reason: 'git_failed', detail: 'git rev-list printed a line that is not a commit id' };
+    if (reachable.length > caps.candidates) {
+        return { ok: false, reason: 'cap_exceeded', detail: `more than ${caps.candidates} commits are reachable from HEAD and from none of this phase's bounds` };
+    }
+    const reachableSet = new Set(reachable.map((row) => row[0]));
+    const candidates = reachable.filter((row) => row.length <= 2).map((row) => row[0]);
+    // (e) coverage, from the records whose end is itself reachable here: the
+    // other records (counted against the cap, D-62) and this phase's own ranges.
+    const relevantOthers = covering.filter((r) => reachableSet.has(r.end));
+    if (relevantOthers.length > caps.coveringRecords) {
+        return { ok: false, reason: 'cap_exceeded', detail: `${relevantOthers.length} records end after this phase, above the ${caps.coveringRecords}-record cap` };
+    }
+    const relevant = [...relevantOthers, ...ownRanges.filter((r) => reachableSet.has(r.end))];
+    const covered = new Set();
+    const skippedRecords = [];
+    for (const r of relevant) {
+        // 16 review iteration 3 CR-01 (D-102): an attested commit covers ITSELF
+        // only, and only when it is on the record's own line between the start it
+        // names and the record's end. Nothing between is covered by it, so an
+        // ungoverned commit beside an attested one stays a candidate.
+        const byFrom = new Map();
+        for (const a of Array.isArray(r.attested) ? r.attested : []) {
+            if (!isAnchorSha(a.sha) || !isAnchorSha(a.from))
+                continue;
+            if (!byFrom.has(a.from))
+                byFrom.set(a.from, new Set());
+            byFrom.get(a.from).add(a.sha);
+        }
+        for (const [from, shas] of byFrom) {
+            const attArgs = ['rev-list', '--first-parent', `--max-count=${caps.candidates + 1}`, '--stdin'];
+            const att = git(attArgs, `^${from}\n${r.end}\n`);
+            if (att.exitCode !== 0 || hard(att))
+                return failed(attArgs, att);
+            const line = lines(att.stdout);
+            if (line.length > caps.candidates) {
+                return { ok: false, reason: 'cap_exceeded', detail: `an attested record's line holds more than ${caps.candidates} commits` };
+            }
+            for (const c of line)
+                if (shas.has(c))
+                    covered.add(c);
+        }
+        if (r.start === undefined) {
+            skippedRecords.push({ rel: r.rel, reason: 'no_start' });
+            continue;
+        }
+        const ancArgs = ['merge-base', '--is-ancestor', r.start, r.end];
+        const anc = git(ancArgs);
+        if (hard(anc))
+            return failed(ancArgs, anc);
+        if (anc.exitCode === 1) {
+            skippedRecords.push({ rel: r.rel, reason: 'start_not_ancestor' });
+            continue;
+        }
+        if (anc.exitCode !== 0) {
+            skippedRecords.push({ rel: r.rel, reason: 'start_unknown' });
+            continue;
+        }
+        // 16 review WR-02: a record covers its OWN line only. `--first-parent`
+        // walks from its end back to its start along the line the work was done
+        // on, so commits a merge brought into the range from another branch (a
+        // teammate's ungoverned source on `main`, merged mid-task) stay candidates
+        // instead of being counted as governed by a record that never saw them.
+        const rangeArgs = ['rev-list', '--first-parent', `--max-count=${caps.candidates + 1}`, '--stdin'];
+        const range = git(rangeArgs, `^${r.start}\n${r.end}\n`);
+        if (range.exitCode !== 0 || hard(range))
+            return failed(rangeArgs, range);
+        const inRange = lines(range.stdout);
+        if (inRange.length > caps.candidates) {
+            return { ok: false, reason: 'cap_exceeded', detail: `a covering record's range holds more than ${caps.candidates} commits` };
+        }
+        for (const c of inRange)
+            covered.add(c);
+    }
+    // (f) classify the uncovered candidates.
+    const uncoveredAll = candidates.filter((c) => !covered.has(c));
+    const uncovered = [];
+    let examined = 0;
+    for (const sha of uncoveredAll) {
+        if (uncovered.length >= caps.uncovered || examined >= caps.examine)
+            break;
+        examined += 1;
+        const treeArgs = ['diff-tree', '-r', '-z', '--root', '--no-commit-id', '--name-only', '--no-renames', sha];
+        const tree = git(treeArgs);
+        if (tree.exitCode !== 0 || hard(tree))
+            return failed(treeArgs, tree);
+        const sourcePaths = tree.stdout.split('\0').filter((p) => p !== '' && !isNonSourcePath(p));
+        if (sourcePaths.length === 0)
+            continue;
+        const subjArgs = ['log', '-1', '--format=%s', sha];
+        const subj = git(subjArgs);
+        if (subj.exitCode !== 0 || hard(subj))
+            return failed(subjArgs, subj);
+        uncovered.push({
+            sha,
+            shortSha: sha.slice(0, 12),
+            subject: boundedLine(subj.stdout, exports.SEAL_SUBJECT_CAP),
+            sourcePaths: sourcePaths.slice(0, caps.pathsPerCommit),
+            pathsTruncated: sourcePaths.length > caps.pathsPerCommit,
+            sourcePathCount: sourcePaths.length,
+        });
+    }
+    const truncated = examined < uncoveredAll.length;
+    if (truncated && uncovered.length === 0) {
+        return { ok: false, reason: 'cap_exceeded', detail: `${uncoveredAll.length} commits are covered by no record and only ${examined} could be examined` };
+    }
+    return {
+        ok: true,
+        uncovered,
+        truncated,
+        candidateCount: candidates.length,
+        uncoveredCount: uncoveredAll.length,
+        examined,
+        skippedRecords,
+    };
+}