@pareto4/pp-core 1.13.0 → 1.17.1

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

@@ -0,0 +1,699 @@
+"use strict";
+/**
+ * src/vault-index.cts — the vault INDEX.md machine layer (Vault Assurance v1.2,
+ * Phase 14-02, D-06).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the git-ignored `pp-core/bin/lib/vault-index.cjs`; do NOT
+ * hand-edit the compiled output. Behaviour is locked by
+ * `tests/vault-index.test.cjs`.
+ *
+ * In standards mode (`vault.mode: standards`) the client vault's own INDEX.md
+ * is the machine layer: one `- \`path\` — what it is; used when …` line per
+ * document, grouped by `##` section. This module is the ONE owner of:
+ *   - the grammar constants (the single text the REL-02 one-pager quotes),
+ *   - the entry head split shared with `discovery-vault-check`,
+ *   - the vault-path classifier and its typed reasons,
+ *   - the tolerant INDEX parser,
+ *   - the membership resolver,
+ *   - the frozen index reason codes and every index sentence,
+ *   - the display sanitiser for vault-derived text,
+ *   - the external-content fence-marker constants and `defangFenceMarkers`,
+ *   - the standards card-line text.
+ * A surface that needs any of these quotes it from here rather than spelling
+ * its own copy, so the grammar the engine parses, the path rule discovery
+ * applies and the sentence an operator reads cannot drift apart.
+ *
+ * It imports NOTHING project-internal (no node builtins either). This is
+ * load-bearing: `src/vault.cts`, `src/discovery-vault-check.cts`,
+ * `src/check-command-router.cts`, `src/vault-command-router.cts`,
+ * `src/vault-practices.cts` and `src/practices-review-check.cts` all require
+ * it, and a leaf with no dependencies cannot close a require cycle among them
+ * (the `src/vault-mode.cts` precedent). The leaf therefore never touches the
+ * filesystem: resolution is pure string membership in a set the caller built
+ * from the manifest, and the bounded read of INDEX.md lives in `vault.cts`.
+ *
+ * Message discipline (T-13-03, T-14-04): no text here takes or echoes a
+ * configured value. Vault-derived text (a path, a section title, a case
+ * variant of the index filename) is quoted only after `sanitiseVaultText`,
+ * which strips terminal control and bidi characters, bounds the length and
+ * defangs the fence markers. The card line is built from fields its caller
+ * has already sanitised.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VAULT_INDEX_WITHHELD_KINDS = exports.VAULT_INDEX_UNCHECKED_CAUSES = exports.VAULT_INDEX_UNPARSEABLE_CAUSES = exports.VAULT_INDEX_REASON = exports.DISPLAY_UNSAFE_TEXT_CHAR_RE = exports.ZERO_WIDTH_SPACE = exports.EXTERNAL_CONTENT_FENCE_END = exports.EXTERNAL_CONTENT_FENCE_START = exports.VAULT_PATH_REASONS = exports.VAULT_INDEX_LIST_BOUND = exports.VAULT_TEXT_MAX = exports.VAULT_INDEX_GRAMMAR = exports.VAULT_SECTION_HEADING_PREFIX = exports.VAULT_USED_WHEN_RE = exports.VAULT_USED_WHEN_MARKER = exports.VAULT_ENTRY_SEPARATOR = exports.VAULT_ENTRY_PREFIX = exports.VAULT_INDEX_BYTE_CAP = exports.VAULT_INDEX_FILENAME = void 0;
+exports.classifyVaultPath = classifyVaultPath;
+exports.isSafeVaultPath = isSafeVaultPath;
+exports.splitVaultEntryLine = splitVaultEntryLine;
+exports.parseVaultIndex = parseVaultIndex;
+exports.defangFenceMarkers = defangFenceMarkers;
+exports.sanitiseVaultText = sanitiseVaultText;
+exports.isDisplaySafeVaultPath = isDisplaySafeVaultPath;
+exports.displayVaultPath = displayVaultPath;
+exports.resolveVaultIndexEntries = resolveVaultIndexEntries;
+exports.vaultIndexReasonShort = vaultIndexReasonShort;
+exports.vaultIndexReasonText = vaultIndexReasonText;
+exports.vaultIndexWarningMessage = vaultIndexWarningMessage;
+exports.vaultIndexBlockMessage = vaultIndexBlockMessage;
+exports.vaultIndexResolutionText = vaultIndexResolutionText;
+exports.vaultStandardsCardLine = vaultStandardsCardLine;
+// ─── Grammar (D-01, D-02, D-05) ──────────────────────────────────────────────
+/** The index file, named exactly (case-sensitive) at the vault root. */
+exports.VAULT_INDEX_FILENAME = 'INDEX.md';
+/** The bounded read cap for INDEX.md: 256 KiB. The reader reads cap+1 bytes to detect oversize. */
+exports.VAULT_INDEX_BYTE_CAP = 262144;
+/** An entry line starts at column 0 with a hyphen, a space and a backtick. */
+exports.VAULT_ENTRY_PREFIX = '- `';
+/** Between the closing backtick and the remainder: space, em dash (U+2014), space. */
+exports.VAULT_ENTRY_SEPARATOR = ' \u2014 ';
+/** The canonical spelling of the used-when clause marker. */
+exports.VAULT_USED_WHEN_MARKER = '; used when ';
+/**
+ * The matcher for the used-when clause: `;`, whitespace, `used when`,
+ * whitespace, case-insensitive. The FIRST match splits (D-02). The split is
+ * never at a bare `;`: the real `practices/` entry carries `; used
+ * automatically …`, and splitting there would invent a clause (D-22).
+ */
+exports.VAULT_USED_WHEN_RE = /;\s+used when\s+/i;
+/** A section is opened by a level-2 ATX heading at column 0. */
+exports.VAULT_SECTION_HEADING_PREFIX = '## ';
+/** The six grammar values bundled, frozen, for a consumer that quotes the grammar whole. */
+exports.VAULT_INDEX_GRAMMAR = Object.freeze({
+    filename: exports.VAULT_INDEX_FILENAME,
+    byteCap: exports.VAULT_INDEX_BYTE_CAP,
+    entryPrefix: exports.VAULT_ENTRY_PREFIX,
+    separator: exports.VAULT_ENTRY_SEPARATOR,
+    usedWhenMarker: exports.VAULT_USED_WHEN_MARKER,
+    sectionHeadingPrefix: exports.VAULT_SECTION_HEADING_PREFIX,
+});
+/** The bound on a sanitised vault-derived string (equal to vault.cts SUMMARY_HEADING_MAX). */
+exports.VAULT_TEXT_MAX = 500;
+/** The bound on an envelope list of index paths; the counts beside it stay exact (D-14). */
+exports.VAULT_INDEX_LIST_BOUND = 20;
+// ─── Path safety (D-08) ──────────────────────────────────────────────────────
+/**
+ * Why a vault path is unsafe, in classification order. Every reason maps to
+ * discovery's single `path_unsafe`; INDEX keeps the typed reason.
+ */
+exports.VAULT_PATH_REASONS = Object.freeze([
+    'empty',
+    'nul',
+    'control_char',
+    'backslash',
+    'absolute',
+    'traversal',
+    'leading_dot',
+    'dot_segment',
+    'empty_segment',
+    // 14-REVIEW WR-02: a path that cannot be displayed as written (a bidi,
+    // line-separator, format or zero-width character, any whitespace other than
+    // a single interior U+0020, a `"`, a fence marker, or over VAULT_TEXT_MAX
+    // code points — `isDisplaySafeVaultPath`).
+    // Refusing it is what makes `resolved ⇒ the displayed path is the checked
+    // path` hold: nothing selectable can render under a name that is not the file.
+    'display_unsafe',
+]);
+// C0 controls other than NUL (NUL has its own reason), DEL, and the C1 block.
+const CONTROL_CHAR_RE = /[\u0001-\u001F\u007F-\u009F]/;
+// A Windows drive prefix (`C:/x`, `c:x`) is absolute (D-08 tightening 1).
+const DRIVE_PREFIX_RE = /^[A-Za-z]:/;
+/**
+ * Classify a vault-relative path. The base is discovery's rule moved verbatim
+ * (non-empty; no backslash, no NUL; not starting with `/` or `.`; no empty,
+ * `.` or `..` segment), plus D-08's two tightenings: a Windows drive prefix is
+ * absolute, and any C0 or C1 control character is unsafe — a path the engine
+ * echoes must not carry terminal control bytes.
+ *
+ * Percent-encoding and unicode (look-alike dots included) are LITERAL: never
+ * decoded, never normalised. Resolution is exact membership, so they cannot
+ * traverse. A trailing slash yields an empty last segment: `empty_segment`.
+ *
+ * Order is pinned by the leaf test: traversal is checked before leading_dot so
+ * `../x` reports `traversal`. `display_unsafe` is checked last (14-REVIEW
+ * WR-02): a path that passes every structural rule but cannot be displayed
+ * exactly as written (`isDisplaySafeVaultPath`) is refused, so a path that
+ * resolves is always echoed byte-for-byte.
+ */
+function classifyVaultPath(p) {
+    if (typeof p !== 'string' || p === '')
+        return { ok: false, reason: 'empty' };
+    if (p.includes('\0'))
+        return { ok: false, reason: 'nul' };
+    if (CONTROL_CHAR_RE.test(p))
+        return { ok: false, reason: 'control_char' };
+    if (p.includes('\\'))
+        return { ok: false, reason: 'backslash' };
+    if (p.startsWith('/') || DRIVE_PREFIX_RE.test(p))
+        return { ok: false, reason: 'absolute' };
+    const segs = p.split('/');
+    if (segs.includes('..'))
+        return { ok: false, reason: 'traversal' };
+    if (p.startsWith('.'))
+        return { ok: false, reason: 'leading_dot' };
+    if (segs.includes('.'))
+        return { ok: false, reason: 'dot_segment' };
+    if (segs.includes(''))
+        return { ok: false, reason: 'empty_segment' };
+    // Last, so every structural reason keeps its precedence (14-REVIEW WR-02).
+    // The same predicate decides displayVaultPath's quoting (iteration 2 WR-01).
+    if (!isDisplaySafeVaultPath(p, exports.VAULT_TEXT_MAX))
+        return { ok: false, reason: 'display_unsafe' };
+    return { ok: true };
+}
+/** The boolean form of `classifyVaultPath`. */
+function isSafeVaultPath(p) {
+    return classifyVaultPath(p).ok;
+}
+/**
+ * Split one already-`trimEnd()`-ed line into its entry head. The order is
+ * discovery's (`discovery-vault-check.cts` parseEntry): prefix → closing
+ * backtick → separator. Path safety is NOT judged here; each consumer applies
+ * `classifyVaultPath` after the split, so an unsafe path with a bad separator
+ * stays malformed rather than unsafe.
+ *
+ * The path is LITERAL: no trim inside the backticks (discovery extracts
+ * `" a.md "` as written), and empty backticks yield path `''`, which the
+ * classifier reports `empty`.
+ */
+function splitVaultEntryLine(line) {
+    if (typeof line !== 'string' || !line.startsWith(exports.VAULT_ENTRY_PREFIX))
+        return null;
+    const close = line.indexOf('`', exports.VAULT_ENTRY_PREFIX.length);
+    if (close === -1)
+        return { malformed: true };
+    const after = line.slice(close + 1);
+    if (!after.startsWith(exports.VAULT_ENTRY_SEPARATOR))
+        return { malformed: true };
+    const rest = after.slice(exports.VAULT_ENTRY_SEPARATOR.length);
+    if (rest.trim() === '')
+        return { malformed: true };
+    return { path: line.slice(exports.VAULT_ENTRY_PREFIX.length, close), rest };
+}
+// CommonMark 0.31.2 fenced code blocks: ≤3 spaces of indent, then ≥3 backticks
+// or ≥3 tildes (never mixed). A backtick fence's info string may not contain a
+// backtick, or the line is not a fence opener.
+const FENCE_OPEN_RE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+// A level-2 heading at column 0; `##` alone is an empty heading. `###` never
+// matches because its third character is neither whitespace nor end of line.
+const SECTION_HEADING_RE = /^##(?:[ \t]+(.*))?$/;
+/**
+ * Strip an optional ATX closing sequence (`## Title ##`): a trailing run of
+ * `#` that is the whole title or follows a space/tab, together with that
+ * space/tab run. Same result as `title.replace(/(?:^|[ \t]+)#+$/, '')`, but a
+ * backwards scan rather than a regex: the regex retried `[ \t]+` from every
+ * position of a whitespace run, so one heading padded to the 256 KiB cap
+ * parsed in ~26 s (14-SECURITY T-14-05).
+ */
+function stripAtxClosing(title) {
+    let hashes = title.length;
+    while (hashes > 0 && title[hashes - 1] === '#')
+        hashes -= 1;
+    if (hashes === title.length)
+        return title;
+    if (hashes === 0)
+        return '';
+    let ws = hashes;
+    while (ws > 0 && (title[ws - 1] === ' ' || title[ws - 1] === '\t'))
+        ws -= 1;
+    return ws === hashes ? title : title.slice(0, ws);
+}
+// A level-1 heading at column 0 resets the section.
+const LEVEL1_HEADING_RE = /^#(?:[ \t].*)?$/;
+// D-28: an entry prefix indented 1-3 spaces is a near-miss, not a nested list.
+const INDENTED_ENTRY_RE = /^ {1,3}- `/;
+function buildEntry(section, path, rest, line) {
+    const m = exports.VAULT_USED_WHEN_RE.exec(rest);
+    if (m) {
+        const usedWhen = rest.slice(m.index + m[0].length).trim();
+        if (usedWhen !== '') {
+            return { section, path, description: rest.slice(0, m.index).trim(), usedWhen, line };
+        }
+    }
+    // No clause, or an empty one: the whole remainder is the description and the
+    // key is omitted — a clause is never invented and text is never dropped.
+    return { section, path, description: rest.trim(), line };
+}
+/**
+ * Parse an INDEX.md text tolerantly. Never throws; a non-string is read as
+ * `''`. One leading BOM is stripped and CRLF is tolerated; each line is
+ * `trimEnd()`-ed before matching.
+ *
+ * Entries are column-0 `- \`path\` — remainder` lines outside fenced code
+ * blocks and HTML comments. Blank lines, paragraphs, headings other than level
+ * 2, other bullets and deeper-indented items are prose and ignored silently. A
+ * column-0 line that starts like an entry but fails the head split, or an entry
+ * prefix indented 1-3 spaces, is a `malformed_entry` diagnostic — never an
+ * error. A fence or comment still open at end of text is an `unclosed_block`
+ * diagnostic naming its opening line, so the entries it swallowed cannot
+ * vanish silently.
+ */
+function parseVaultIndex(text) {
+    let src = typeof text === 'string' ? text : '';
+    if (src.charCodeAt(0) === 0xfeff)
+        src = src.slice(1);
+    const lines = src.split(/\r?\n/);
+    const sections = [];
+    // A Set beside the ordered list: `sections.includes` was O(S²) over a
+    // cap-sized index of distinct headings (14-SECURITY T-14-05).
+    const seenSections = new Set();
+    const entries = [];
+    const diagnostics = [];
+    let section = null;
+    let inFence = null;
+    let inComment = null;
+    for (let i = 0; i < lines.length; i += 1) {
+        const lineNo = i + 1;
+        const line = lines[i].trimEnd();
+        if (inFence) {
+            const close = FENCE_OPEN_RE.exec(line);
+            if (close && close[1][0] === inFence.char && close[1].length >= inFence.len && close[2].trim() === '') {
+                inFence = null;
+            }
+            continue;
+        }
+        if (inComment) {
+            if (line.includes('-->'))
+                inComment = null;
+            continue;
+        }
+        const fence = FENCE_OPEN_RE.exec(line);
+        if (fence && !(fence[1][0] === '`' && fence[2].includes('`'))) {
+            inFence = { char: fence[1][0], len: fence[1].length, openLine: lineNo };
+            continue;
+        }
+        const lead = line.trimStart();
+        if (lead.startsWith('<!--')) {
+            if (!lead.slice(4).includes('-->'))
+                inComment = { openLine: lineNo };
+            continue;
+        }
+        const h2 = SECTION_HEADING_RE.exec(line);
+        if (h2) {
+            const title = stripAtxClosing(h2[1] ?? '').trim();
+            section = title === '' ? null : title;
+            if (section !== null && !seenSections.has(section)) {
+                seenSections.add(section);
+                sections.push(section);
+            }
+            continue;
+        }
+        if (LEVEL1_HEADING_RE.test(line)) {
+            section = null;
+            continue;
+        }
+        if (line.startsWith(exports.VAULT_ENTRY_PREFIX)) {
+            const head = splitVaultEntryLine(line);
+            if (head === null || 'malformed' in head) {
+                diagnostics.push({ kind: 'malformed_entry', line: lineNo });
+            }
+            else {
+                entries.push(buildEntry(section, head.path, head.rest, lineNo));
+            }
+            continue;
+        }
+        if (INDENTED_ENTRY_RE.test(line)) {
+            diagnostics.push({ kind: 'malformed_entry', line: lineNo });
+        }
+    }
+    if (inFence)
+        diagnostics.push({ kind: 'unclosed_block', line: inFence.openLine });
+    if (inComment)
+        diagnostics.push({ kind: 'unclosed_block', line: inComment.openLine });
+    return { sections, entries, diagnostics };
+}
+// ─── Fence-marker owner (D-17, D-26) ─────────────────────────────────────────
+// External-content fence markers (D-15 / T-24-05). The SUMMARY writer, the
+// practice excerpt and the review check all fence untrusted vault text between
+// these two literals; this leaf is their one cycle-free owner (14-04 re-points
+// the three source copies here).
+exports.EXTERNAL_CONTENT_FENCE_START = '<!-- vault:external-content-start -->';
+exports.EXTERNAL_CONTENT_FENCE_END = '<!-- vault:external-content-end -->';
+// Zero-width space (U+200B) — invisible when rendered, but breaks an exact
+// string match against the literal fence marker (CR-01 / T-24-05). Used by
+// `defangFenceMarkers` to neutralize a spoofed marker planted inside untrusted
+// body text without visibly mangling the text for a human/agent reader.
+exports.ZERO_WIDTH_SPACE = '\u200B';
+/**
+ * Neutralize any occurrence of the external-content fence marker strings
+ * inside untrusted body text BEFORE it is wrapped between the real markers
+ * (CR-01 / T-24-05 fence-spoof escape). Without this, a practice body
+ * containing the literal end-fence marker (`<!-- vault:external-content-end
+ * -->`) could make a downstream consumer that naively splits on the exact
+ * marker treat the injected text as being OUTSIDE the untrusted-content
+ * fence — the classic "premature fence close" prompt-injection escape.
+ *
+ * Replaces each literal marker occurrence with a defanged variant (a
+ * zero-width space inserted immediately after the opening `<!--`) that is
+ * visually indistinguishable but no longer matches the real marker string —
+ * so only the two GENUINE markers `boundedFencedExcerpt` appends afterward
+ * remain real fence boundaries.
+ */
+function defangFenceMarkers(body) {
+    let result = body;
+    for (const marker of [exports.EXTERNAL_CONTENT_FENCE_START, exports.EXTERNAL_CONTENT_FENCE_END]) {
+        if (result.includes(marker)) {
+            const defanged = `${marker.slice(0, 4)}${exports.ZERO_WIDTH_SPACE}${marker.slice(4)}`;
+            result = result.split(marker).join(defanged);
+        }
+    }
+    return result;
+}
+// ─── Display sanitiser (D-15, D-27) ──────────────────────────────────────────
+// C0, DEL, C1, the line/paragraph separators, and the bidi formatting controls
+// (embeddings/overrides U+202A-202E, isolates U+2066-2069, plus the marks
+// U+200E/200F and U+061C — the Trojan Source set). JSON.stringify passes all
+// of these through unescaped except C0, so --raw would carry them too.
+const UNSAFE_DISPLAY_RE = /[\u0000-\u001F\u007F-\u009F\u2028\u2029\u202A-\u202E\u2066-\u2069\u200E\u200F\u061C]/g;
+/**
+ * Make one vault-derived string safe to echo: every control, line-separator
+ * and bidi character becomes a space, whitespace runs collapse to one space,
+ * the ends are trimmed, the fence markers are defanged, and the result is cut
+ * to `max` code points with a trailing `…` when longer. Pure; never throws; a
+ * non-string becomes `''`.
+ *
+ * Defang runs AFTER the collapse, because a control byte inside a marker
+ * would otherwise become a space and reassemble a live marker.
+ */
+function sanitiseVaultText(s, max = exports.VAULT_TEXT_MAX) {
+    if (typeof s !== 'string')
+        return '';
+    const flat = s.replace(UNSAFE_DISPLAY_RE, ' ').replace(/\s+/g, ' ').trim();
+    const defanged = defangFenceMarkers(flat);
+    const points = Array.from(defanged);
+    const bound = Number.isFinite(max) && max >= 0 ? Math.floor(max) : exports.VAULT_TEXT_MAX;
+    if (points.length <= bound)
+        return defanged;
+    return `${points.slice(0, bound).join('')}\u2026`;
+}
+// The ONE character predicate for path display (14-REVIEW iteration 2, WR-01).
+// A path carrying any of these is display-unsafe, and `displayVaultPath`
+// escapes exactly these — so the set that decides "needs quoting" and the set
+// that gets escaped cannot drift apart again. Members: everything
+// UNSAFE_DISPLAY_RE strips; every whitespace character other than U+0020
+// (no-break space, U+2000-200A, ideographic space, U+FEFF …), which the
+// sanitiser would collapse; every format or default-ignorable code point
+// (zero-width space and joiners, soft hyphen, word joiner, variation
+// selectors, tag characters), which renders as nothing; and `"` and `\`, so a
+// display that starts with `"` is always the quoted form and every `\` inside
+// it starts an escape.
+//
+// The set is held in two parts so prose has one owner too (15-REVIEW iter-3
+// IN-01): `DISPLAY_UNSAFE_TEXT_CHAR_RE` is every member except `"` and `\`,
+// which are legal in prose and unsafe only in a path display, and a reason
+// clause (`validateReasonClause` in vault-standards) refuses exactly it. The
+// path predicate below is that set plus the two escape characters, never a
+// second copy of it.
+exports.DISPLAY_UNSAFE_TEXT_CHAR_RE = /[\u0000-\u001F\u007F-\u009F\u2028\u2029\u202A-\u202E\u2066-\u2069\u200E\u200F\u061C]|[^\S ]|\p{Cf}|\p{Default_Ignorable_Code_Point}/u;
+const DISPLAY_UNSAFE_CHAR_RE = new RegExp(`${exports.DISPLAY_UNSAFE_TEXT_CHAR_RE.source}|["\\\\]`, 'u');
+const DISPLAY_UNSAFE_CHAR_RE_G = new RegExp(DISPLAY_UNSAFE_CHAR_RE.source, 'gu');
+/**
+ * Whether a vault path can be echoed exactly as written. False for a path
+ * that carries a `DISPLAY_UNSAFE_CHAR_RE` character, a run of two spaces,
+ * leading or trailing space, a fence marker, or more than `max` code points.
+ * Everything `sanitiseVaultText` would rewrite is covered, so this is never
+ * looser than the sanitiser. The classifier's `display_unsafe` reason and
+ * `displayVaultPath`'s quoting both ask this one question.
+ */
+function isDisplaySafeVaultPath(p, max = exports.VAULT_TEXT_MAX) {
+    if (typeof p !== 'string')
+        return false;
+    if (DISPLAY_UNSAFE_CHAR_RE.test(p))
+        return false;
+    if (p.startsWith(' ') || p.endsWith(' ') || p.includes('  '))
+        return false;
+    if (defangFenceMarkers(p) !== p)
+        return false;
+    const bound = Number.isFinite(max) && max >= 0 ? Math.floor(max) : exports.VAULT_TEXT_MAX;
+    return Array.from(p).length <= bound;
+}
+/**
+ * Echo a vault path WITHOUT rewriting it into a plausible different name
+ * (14-REVIEW WR-02, and iteration 2 WR-01). A display-safe path is returned
+ * as written. Any other path is returned double-quoted, with every
+ * `DISPLAY_UNSAFE_CHAR_RE` character escaped — `"` and `\` as `\"` and `\\`,
+ * the rest as `\uXXXX` per UTF-16 unit — and U+0020 kept as written, so
+ * padding and runs stay visible. A fence marker is broken by spelling its
+ * first space `\u0020`. So the quoted body holds no character that renders as
+ * nothing or as a different character, and removing the quotes never yields a
+ * display-safe path. Bounded at `max` code points inside the quotes, plus
+ * at most the rest of one escape and the `…`.
+ */
+function displayVaultPath(p, max = exports.VAULT_TEXT_MAX) {
+    if (typeof p !== 'string')
+        return '';
+    if (isDisplaySafeVaultPath(p, max))
+        return p;
+    let escaped = p.replace(DISPLAY_UNSAFE_CHAR_RE_G, (c) => (c === '"' || c === '\\'
+        ? `\\${c}`
+        : Array.from({ length: c.length }, (_, i) => `\\u${c.charCodeAt(i).toString(16).toUpperCase().padStart(4, '0')}`).join('')));
+    for (const marker of [exports.EXTERNAL_CONTENT_FENCE_START, exports.EXTERNAL_CONTENT_FENCE_END]) {
+        escaped = escaped.split(marker).join(`${marker.slice(0, 4)}\\u0020${marker.slice(5)}`);
+    }
+    const bound = Number.isFinite(max) && max >= 0 ? Math.floor(max) : exports.VAULT_TEXT_MAX;
+    if (Array.from(escaped).length <= bound)
+        return `"${escaped}"`;
+    // Truncate on token boundaries, so the cut never leaves half an escape (a
+    // dangling `\` or `\u00`); every `\` in `escaped` starts an escape, because
+    // a raw `\` was escaped above. The token that crosses the bound is kept, so
+    // the body before the `…` is at least `bound` code points: with the `…` it is
+    // over-length, and removing the quotes can never yield a display-safe name.
+    let body = '';
+    let used = 0;
+    for (const token of escaped.match(/\\(?:["\\]|u[0-9A-F]{4})|[\s\S]/gu) ?? []) {
+        if (used >= bound)
+            break;
+        body += token;
+        used += Array.from(token).length;
+    }
+    return `"${body}\u2026"`;
+}
+/**
+ * Resolve parsed entries by exact string membership. The caller builds both
+ * sets from the manifest's recorded `files[]` (`resolvable` = what the SUMMARY
+ * tree may list; `withheld` = the credential-pattern files it omits). No path
+ * is ever joined, stat'ed or opened — the leaf has no filesystem — and an
+ * unsafe path is classified before the resolvable set is consulted, so it can
+ * never resolve.
+ *
+ * Order per entry: withheld → withheld · classify → unsafe · resolvable →
+ * resolved · else unresolved. Withheld comes FIRST (D-35, 14-SECURITY
+ * T-14-02): a credential file whose name is display-unsafe (`keys/a  b.pem`,
+ * `keys/"prod".pem`) is in `files[]`, and classifying it first named it on
+ * the unsafe list. Withheld membership is an exact string compare that can
+ * only withhold more, never make an entry usable.
+ */
+function resolveVaultIndexEntries(entries, resolvable, withheld) {
+    const out = [];
+    const counts = { entries: entries.length, resolved: 0, unresolved: 0, unsafe: 0, withheld: 0 };
+    for (const entry of entries) {
+        if (withheld.has(entry.path)) {
+            out.push({ ...entry, resolution: 'withheld' });
+            counts.withheld += 1;
+            continue;
+        }
+        const verdict = classifyVaultPath(entry.path);
+        if (!verdict.ok) {
+            out.push({ ...entry, resolution: 'unsafe', unsafeReason: verdict.reason });
+            counts.unsafe += 1;
+        }
+        else if (resolvable.has(entry.path)) {
+            out.push({ ...entry, resolution: 'resolved' });
+            counts.resolved += 1;
+        }
+        else {
+            out.push({ ...entry, resolution: 'unresolved' });
+            counts.unresolved += 1;
+        }
+    }
+    return { entries: out, counts };
+}
+// ─── Reasons (D-12) ──────────────────────────────────────────────────────────
+/**
+ * The five degraded-index reasons. Frozen so a typo is a build error rather
+ * than a verdict that silently reports a different code. `UNRESOLVABLE` exists
+ * so a record cannot claim N governing entries when none of them names a file
+ * in the fetched tree (T-14-12). `UNCHECKED` (14-REVIEW iteration 2, WR-02) is
+ * the fail-closed arm: the engine could not run the check at all, so the record
+ * states that and claims nothing about INDEX.md itself — reusing
+ * `vault_index_unparseable` would record a fault in a file that was never read.
+ */
+exports.VAULT_INDEX_REASON = Object.freeze({
+    MISSING: 'vault_index_missing',
+    UNPARSEABLE: 'vault_index_unparseable',
+    EMPTY: 'vault_index_empty',
+    UNRESOLVABLE: 'vault_index_unresolvable',
+    UNCHECKED: 'vault_index_unchecked',
+});
+/** The measured causes behind `vault_index_unparseable`: each one is a fact about the bytes read. */
+exports.VAULT_INDEX_UNPARSEABLE_CAUSES = Object.freeze(['oversize', 'nul', 'invalid_utf8', 'unreadable']);
+/**
+ * The measured causes behind `vault_index_unchecked` (14-REVIEW WR-01, and
+ * iteration 2 WR-02): the cached manifest records no file list to check
+ * against, or the check faulted after the manifest was read. Neither says
+ * anything about INDEX.md, so neither sentence does.
+ */
+exports.VAULT_INDEX_UNCHECKED_CAUSES = Object.freeze(['no_file_list', 'check_faulted']);
+const REASON_SHORT = Object.freeze({
+    [exports.VAULT_INDEX_REASON.MISSING]: 'missing',
+    [exports.VAULT_INDEX_REASON.UNPARSEABLE]: 'unparseable',
+    [exports.VAULT_INDEX_REASON.EMPTY]: 'empty',
+    [exports.VAULT_INDEX_REASON.UNRESOLVABLE]: 'unresolvable',
+    [exports.VAULT_INDEX_REASON.UNCHECKED]: 'unchecked',
+});
+const CAUSE_PHRASE = Object.freeze({
+    oversize: 'it is larger than the 256 KiB cap',
+    nul: 'it contains a NUL byte',
+    invalid_utf8: 'it is not valid UTF-8',
+    unreadable: 'it could not be opened as a regular file',
+});
+const UNCHECKED_CAUSE_PHRASE = Object.freeze({
+    no_file_list: 'the cached manifest records no file list to check it against',
+    check_faulted: 'the check faulted after the cached manifest was read',
+});
+// A case variant is a vault filename: bounded hard, it only needs to be recognisable.
+const CASE_VARIANT_MAX = 80;
+/** The short form of a reason (the envelope's `indexStatus` value). */
+function vaultIndexReasonShort(reason) {
+    return REASON_SHORT[reason];
+}
+/**
+ * One sentence per reason, each naming INDEX.md, with no trailing period (the
+ * messages that embed it add their own). Only the measured cause is stated.
+ * An unknown code yields a generic sentence; the code itself is never echoed.
+ */
+function vaultIndexReasonText(reason, detail = {}) {
+    const d = detail && typeof detail === 'object' ? detail : {};
+    switch (reason) {
+        case exports.VAULT_INDEX_REASON.MISSING: {
+            const base = 'no file named exactly INDEX.md at the vault root is listed in the fetched tree';
+            const variant = typeof d.caseVariant === 'string' ? sanitiseVaultText(d.caseVariant, CASE_VARIANT_MAX) : '';
+            return variant === '' ? base : `${base} (found \`${variant}\`; the engine reads INDEX.md exactly)`;
+        }
+        case exports.VAULT_INDEX_REASON.UNPARSEABLE: {
+            const base = 'INDEX.md could not be read as text';
+            const cause = typeof d.cause === 'string' && Object.prototype.hasOwnProperty.call(CAUSE_PHRASE, d.cause)
+                ? CAUSE_PHRASE[d.cause]
+                : '';
+            return cause === '' ? base : `${base}: ${cause}`;
+        }
+        case exports.VAULT_INDEX_REASON.EMPTY:
+            return 'INDEX.md parsed with zero entries — no line of the form - `path` — description';
+        case exports.VAULT_INDEX_REASON.UNRESOLVABLE:
+            return 'INDEX.md lists entries but none of them names a file in the fetched tree';
+        case exports.VAULT_INDEX_REASON.UNCHECKED: {
+            // States only what was measured: the check did not run. INDEX.md may be
+            // perfectly valid, so no sentence here says it was read or is at fault.
+            const base = 'the engine could not check INDEX.md against the cached file list';
+            const cause = typeof d.cause === 'string' && Object.prototype.hasOwnProperty.call(UNCHECKED_CAUSE_PHRASE, d.cause)
+                ? UNCHECKED_CAUSE_PHRASE[d.cause]
+                : '';
+            return cause === '' ? base : `${base}: ${cause}`;
+        }
+        default:
+            return 'INDEX.md is degraded';
+    }
+}
+/**
+ * The degraded-index WARNING (policy off, D-13): two lines, the second naming
+ * the repair. Planning continues; nothing here is a block. The unchecked arm
+ * (14-REVIEW iteration 2, WR-02) names the local repair — re-fetch, then
+ * report a persisting fault — and never sends the vault owner to edit a file
+ * the check did not read.
+ */
+function vaultIndexWarningMessage(reason, detail) {
+    if (reason === exports.VAULT_INDEX_REASON.UNCHECKED) {
+        return [
+            `⚠ Vault (standards mode): the index check did not run — ${vaultIndexReasonText(reason, detail)}.`,
+            'Planning continues without a checked index; with vault.required off this is a warning. '
+                + 'Remedy: re-run pp-tools vault fetch, then pp-tools check vault.status; if it persists, report it as an engine fault.',
+        ].join('\n');
+    }
+    return [
+        `⚠ Vault (standards mode): the index is degraded — ${vaultIndexReasonText(reason, detail)}.`,
+        'Planning continues without a usable INDEX.md; with vault.required off this is a warning. '
+            + "Remedy: fix INDEX.md in the vault repo (the vault owner's), then pp-tools vault fetch "
+            + 'and re-run pp-tools check vault.status.',
+    ].join('\n');
+}
+/**
+ * The degraded-index BLOCK message (policy on, D-13), in the register of
+ * `buildVaultBlockMessage`: pure-read diagnosis first, then repair-only
+ * remedies. No remedy names deleting a file or a cache — a deletion remedy
+ * would let an operator clear the evidence instead of fixing the index
+ * (memory: gate-message-remedy-hazard).
+ */
+function vaultIndexBlockMessage(reason, detail) {
+    if (reason === exports.VAULT_INDEX_REASON.UNCHECKED) {
+        return [
+            `vault.required is on and the client vault is loaded but the engine could not check its index: ${vaultIndexReasonText(reason, detail)}.`,
+            'Diagnose (pure reads — none of these can change this verdict):',
+            '  pp-tools check vault.status --raw   # this verdict, with the index fields',
+            "Remedy (repair only — re-fetching rewrites the cached manifest the check reads):",
+            '  pp-tools vault fetch, then re-run the gate; if it persists, report it as an engine fault',
+            '  or pp-tools config set vault.mode practices  # if this project is not on standards mode yet',
+            '  or set PP_VAULT_OVERRIDE_REASON to a substantive explanation for an attributed, recorded override',
+        ].join('\n');
+    }
+    return [
+        `vault.required is on and the client vault is loaded but its INDEX.md is degraded: ${vaultIndexReasonText(reason, detail)}.`,
+        'Diagnose (pure reads — none of these can change this verdict):',
+        '  pp-tools check vault.status --raw   # this verdict, with the index fields',
+        '  pp-tools vault summary              # the INDEX section names what did and did not resolve',
+        "Remedy (repair only — the index is the vault owner's):",
+        '  fix INDEX.md in the vault repo, then pp-tools vault fetch and re-run the gate',
+        '  or pp-tools config set vault.mode practices  # if this project is not on standards mode yet',
+        '  or set PP_VAULT_OVERRIDE_REASON to a substantive explanation for an attributed, recorded override',
+    ].join('\n');
+}
+/**
+ * What a withheld entry names, ONE text for the per-entry sentence and the
+ * SUMMARY aggregate line (14-REVIEW IN-01). The withheld set is not only
+ * credential-pattern files: the engine-written `SUMMARY.md` and `INDEX.md`
+ * itself (14-REVIEW WR-03) are withheld too, and the old "(credential
+ * pattern)" label was untrue for them.
+ */
+exports.VAULT_INDEX_WITHHELD_KINDS = '(INDEX.md itself, SUMMARY.md or a credential-pattern file)';
+/**
+ * Why an entry did or did not resolve — the "why" SUMMARY's Not resolvable
+ * list prints. A withheld entry's sentence names no path (VSEC-03 count-only
+ * discipline). A trailing-slash path is a directory, not a document (D-08).
+ */
+function vaultIndexResolutionText(entry) {
+    const e = entry && typeof entry === 'object' ? entry : {};
+    switch (e.resolution) {
+        case 'resolved':
+            return 'resolved';
+        case 'unresolved':
+            return 'not in the fetched tree';
+        case 'withheld':
+            return `names a file withheld from this listing ${exports.VAULT_INDEX_WITHHELD_KINDS}`;
+        case 'unsafe': {
+            const reason = exports.VAULT_PATH_REASONS.includes(String(e.unsafeReason))
+                ? String(e.unsafeReason)
+                : 'unclassified';
+            if (reason === 'empty_segment' && typeof e.path === 'string' && e.path.endsWith('/')) {
+                return 'names a directory, not a file — not readable as a document';
+            }
+            if (reason === 'display_unsafe') {
+                return 'cannot be displayed as written (a format, zero-width or non-space whitespace character, a double quote, a space run or padding, or over-length) — shown quoted and escaped, not readable as a document';
+            }
+            return `unsafe path (${reason})`;
+        }
+        default:
+            return 'not resolved';
+    }
+}
+// ─── Card line (D-15, D-28) ──────────────────────────────────────────────────
+/**
+ * The one-line standards card shown on a healthy standards verdict. Every
+ * field arrives already sanitised (repo and ref through the router's manifest
+ * sanitiser); this function neither sanitises nor reads config. The suffix
+ * appears only when at least one entry is not usable. It says "not usable",
+ * not "unresolved" (14-REVIEW iteration 2, IN-01): the count is every entry
+ * that did not resolve — absent, unsafe or withheld — while the envelope's
+ * `indexUnresolved` lists the absent ones only, so one word must not mean both.
+ */
+function vaultStandardsCardLine(f) {
+    const line = `Vault (standards mode): ${f.repo}@${f.ref} sha ${f.sha8} — ${f.fileCount} files; INDEX.md: ${f.indexEntries} entries`;
+    return f.unusable > 0 ? `${line} (${f.unusable} not usable — see .planning/vault/SUMMARY.md)` : line;
+}