@north-light/crouter 0.3.244 → 0.3.246

package/dist/commands/sys/context/resolve.d.ts

@@ -1,5 +1,6 @@
 import { type MemoryTarget } from '../../../core/memory-resolver.js';
 import { type DeliveryPayload, type DeliveryRecord, type GateOutcome } from '../../../core/substrate/plan.js';
+import { type GateClause } from '../../../core/substrate/gate-explain.js';
 import { type Rung, type SurfaceEntry, type SurfaceEvent } from '../../../core/substrate/schema.js';
 import { type NodeConfigSubject } from '../../../core/substrate/subject-fields.js';
 export declare const resolveLeaf: import("../../../core/command.js").LeafDef;
@@ -45,11 +46,14 @@ export interface DocRow {
  *  above the no-delivery floor — boot keeps rung-`none` winners in the plan so
  *  the catalog can still count them. */
 export declare function delivers(record: DeliveryRecord): boolean;
-export declare function docRow(record: DeliveryRecord, includeAll: boolean): DocRow;
-export declare function gateText(gate: GateOutcome): string;
+export declare function docRow(record: DeliveryRecord, includeAll: boolean, subject: NodeConfigSubject | null): DocRow;
+/** A gate verdict as one cell: `pass`, or `fail:` plus the clauses that failed
+ *  — the planner's generic sentence only when the explainer cannot decompose
+ *  the predicate. */
+export declare function gateText(gate: GateOutcome, clauses: readonly GateClause[]): string;
 export declare function entryText(entry: SurfaceEntry | null): string | null;
 /** Why a considered document delivers nothing, in the order the planner applies
  *  its checks — the first failing one is the answer an engineer acts on. */
-export declare function exclusionReason(record: DeliveryRecord): string;
+export declare function exclusionReason(record: DeliveryRecord, subject: NodeConfigSubject | null): string;
 export declare function describeSubject(subject: Record<string, unknown>): string;
 export declare function cell(v: unknown): string;

package/dist/commands/sys/context/resolve.js

@@ -16,6 +16,7 @@ import { envNodeId, envProfileId } from '../../../shared/env.js';
 import { realpathOrSelf } from '../../../core/fs-utils.js';
 import { ambientMemoryTarget, resolveMemoryDocForTarget, } from '../../../core/memory-resolver.js';
 import { planDelivery, } from '../../../core/substrate/plan.js';
+import { explainRecordGate, formatClause } from '../../../core/substrate/gate-explain.js';
 import { emptyContextExposureState, exposureTarget } from '../../../core/substrate/injected-store.js';
 import { renderPreferencesForSubject, renderKnowledgeForSubject } from '../../../core/substrate/render.js';
 import { memoryReadDocBlocks, renderOnCommandDocsForSubject, renderOnReadDocsForSubject, renderPreCommandDocsForSubject, renderWorkspaceOpenDocsForSubject, } from '../../../core/substrate/on-read.js';
@@ -193,7 +194,7 @@ function planSection(snapshot, event, payload, granularity, includeAll) {
     const plan = planDelivery(snapshot.subject, snapshot.target, event, payload);
     if (granularity === 'summary')
         return { event, counts: countsOf(plan) };
-    const docs = plan.docs.filter((r) => includeAll || delivers(r)).map((r) => docRow(r, includeAll));
+    const docs = plan.docs.filter((r) => includeAll || delivers(r)).map((r) => docRow(r, includeAll, plan.subject));
     return { event, docs };
 }
 /** A document delivers when it won its canonical name AND resolved to a rung
@@ -202,7 +203,7 @@ function planSection(snapshot, event, payload, granularity, includeAll) {
 export function delivers(record) {
     return record.winner && rungAtLeast(record.finalRung, 'name');
 }
-export function docRow(record, includeAll) {
+export function docRow(record, includeAll, subject) {
     const row = {
         name: record.name,
         kind: record.kind,
@@ -214,16 +215,22 @@ export function docRow(record, includeAll) {
         final_rung: record.finalRung,
         winner: record.winner,
         shadowed_by: record.shadowedBy === null ? null : `${record.shadowedBy.scope}:${record.shadowedBy.path}`,
-        doc_gate: gateText(record.docGate),
-        entry_gate: record.entryGate === null ? null : gateText(record.entryGate),
+        doc_gate: gateText(record.docGate, explainRecordGate(record, 'doc', subject)),
+        entry_gate: record.entryGate === null ? null : gateText(record.entryGate, explainRecordGate(record, 'entry', subject)),
         matched_entry: entryText(record.matchedEntry),
     };
     if (includeAll && !delivers(record))
-        row.excluded = exclusionReason(record);
+        row.excluded = exclusionReason(record, subject);
     return row;
 }
-export function gateText(gate) {
-    return gate.pass ? 'pass' : `fail: ${gate.reason}`;
+/** A gate verdict as one cell: `pass`, or `fail:` plus the clauses that failed
+ *  — the planner's generic sentence only when the explainer cannot decompose
+ *  the predicate. */
+export function gateText(gate, clauses) {
+    return gate.pass ? 'pass' : `fail: ${gateReason(gate.reason, clauses)}`;
+}
+function gateReason(fallback, clauses) {
+    return clauses.length === 0 ? fallback : clauses.map(formatClause).join('; ');
 }
 export function entryText(entry) {
     if (entry === null)
@@ -239,16 +246,17 @@ export function entryText(entry) {
 }
 /** Why a considered document delivers nothing, in the order the planner applies
  *  its checks — the first failing one is the answer an engineer acts on. */
-export function exclusionReason(record) {
-    if (!record.docGate.pass)
-        return `document gate: ${record.docGate.reason}`;
+export function exclusionReason(record, subject) {
+    if (!record.docGate.pass) {
+        return `document gate: ${gateReason(record.docGate.reason, explainRecordGate(record, 'doc', subject))}`;
+    }
     if (record.shadowedBy !== null)
         return `shadowed by ${record.shadowedBy.scope}:${record.shadowedBy.path}`;
     if (record.authoredEntries.length === 0)
         return 'no surface entry for this event';
     if (record.matchedEntry === null) {
         return record.entryGate !== null && !record.entryGate.pass
-            ? `entry gate: ${record.entryGate.reason}`
+            ? `entry gate: ${gateReason(record.entryGate.reason, explainRecordGate(record, 'entry', subject))}`
             : 'no authored entry matched this event\u2019s payload';
     }
     if (record.cappedRung === 'none') {

package/dist/commands/sys/panels/profiles-panel.js

@@ -18,7 +18,8 @@ import { PROFILE_PROJECT_MEMORY_VALUES } from '../../../api/dto/profiles.js';
 import { cliClient } from '../../api-client.js';
 import { clearDefaultProfile, defaultProfileDirs, getDefaultProfileId, setDefaultProfileId, } from '../../../core/profiles/default-binding.js';
 import { ROOT_PROFILE_ID, addProfileProject, createProfile, listProfiles, pauseProfile, removeProfileProject, renameProfile, resumeProfile, } from '../../../core/profiles/manifest.js';
-import { profileCoversCwd, tildify } from '../../../core/profiles/select.js';
+import { tildify } from '../../../core/fs-utils.js';
+import { profileCoversCwd } from '../../../core/profiles/select.js';
 import { padAnsi, theme, visibleRange, wrapText, } from '../../../core/tui/panel.js';
 /** Coarse "used ..." for telling otherwise-alike profiles apart. */
 function relativeUsed(iso) {

package/dist/core/fs-utils.d.ts

@@ -3,6 +3,9 @@ export declare function realpathOrSelf(p: string): string;
 /** Expand a leading `~` against `homeDir` (pi's own convention). Other forms
  *  — absolute, relative, `~user` — pass through as pi leaves them. */
 export declare function expandTilde(p: string, homeDir?: string): string;
+/** Collapse the home prefix to `~` so a path reads short. The inverse of
+ *  `expandTilde`, and the ONE collapse every surface prints paths through. */
+export declare function tildify(p: string, homeDir?: string): string;
 export declare function ensureDir(dir: string): void;
 export declare function writeJson(path: string, data: unknown): void;
 export interface AtomicWriteOptions {

package/dist/core/fs-utils.js

@@ -1,5 +1,5 @@
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync, cpSync, readlinkSync, renameSync, chmodSync, realpathSync, } from 'node:fs';
-import { dirname, join, relative } from 'node:path';
+import { dirname, join, relative, sep } from 'node:path';
 import { homedir, platform } from 'node:os';
 /** `realpathSync`, tolerant of a path that doesn't exist or can't be resolved. */
 export function realpathOrSelf(p) {
@@ -19,6 +19,15 @@ export function expandTilde(p, homeDir = homedir()) {
         return join(homeDir, p.slice(2));
     return p;
 }
+/** Collapse the home prefix to `~` so a path reads short. The inverse of
+ *  `expandTilde`, and the ONE collapse every surface prints paths through. */
+export function tildify(p, homeDir = homedir()) {
+    if (p === homeDir)
+        return '~';
+    if (p.startsWith(homeDir + sep))
+        return '~' + p.slice(homeDir.length);
+    return p;
+}
 export function ensureDir(dir) {
     mkdirSync(dir, { recursive: true });
 }

package/dist/core/profiles/select.d.ts

@@ -11,9 +11,6 @@ export declare function resolveProfileSearchAction(bindings: BindingResolution<B
 export declare function profileCoversCwd(entry: ProfileEntry, cwd: string): boolean;
 /** Resolve the headless selector against existing state without changing it. */
 export declare function selectProfileForCwdReadOnly(cwd: string): string;
-/** Collapse the home prefix to `~` so project paths read short. Exported so the
- *  Profiles settings panel prints a project dir exactly as this menu does. */
-export declare function tildify(p: string): string;
 /** Select the profile a node about to boot at `cwd` should run under.
  *
  *  1. `explicitProfile` present → resolve it as a user-typed operand (exact id,

package/dist/core/profiles/select.js

@@ -9,12 +9,12 @@
 // spawn.ts call it, never re-derive it.
 import { spawnSync } from 'node:child_process';
 import { existsSync, realpathSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { basename, resolve as resolvePath, sep } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { emitKeypressEvents } from 'node:readline';
 import { listProfiles, loadProfileManifest, resolveProfileOperand, updateProfileLastUsed, createProfile, addProfileProject, ensureRootProfile, ROOT_PROFILE_ID, } from './manifest.js';
 import { getDefaultProfileId, setDefaultProfileId, clearDefaultProfile, } from './default-binding.js';
+import { tildify } from '../fs-utils.js';
 import { stdoutColor } from '../output.js';
 import { inTmux } from '../runtime/placement-tmux.js';
 import { surfaceTmuxStyleArgs } from '../runtime/surface-bg.js';
@@ -135,16 +135,6 @@ const accent = stdoutColor.cyan;
 function key(k) {
     return accent(bold(k));
 }
-/** Collapse the home prefix to `~` so project paths read short. Exported so the
- *  Profiles settings panel prints a project dir exactly as this menu does. */
-export function tildify(p) {
-    const home = homedir();
-    if (p === home)
-        return '~';
-    if (p.startsWith(home + sep))
-        return '~' + p.slice(home.length);
-    return p;
-}
 /** Coarse "last used" for disambiguating profiles that otherwise look alike
  *  (notably several profiles claiming the SAME dir). null → never used. */
 function relativeUsed(iso) {

package/dist/core/substrate/gate-explain.d.ts

@@ -0,0 +1,48 @@
+import type { NodeConfigSubject } from './subject-fields.js';
+import type { DeliveryRecord } from './plan.js';
+/** The subject has no value at this field path — distinct from a value of
+ *  `null`, which a gate can legitimately demand. */
+export declare const ABSENT: unique symbol;
+/** One failing condition of a gate.
+ *
+ *  `mismatch` and `malformed` are two different remedies on two different
+ *  objects: dial the node's configuration, or edit the document. */
+export interface GateClause {
+    /** The gate field as authored (`kind`, `cwd`, `orchestration.depth`). Empty
+     *  for a defect of the gate as a whole, such as an empty `gate: {}`. */
+    field: string;
+    failure: 'mismatch' | 'malformed';
+    /** The subject's resolved value at `field`, or `ABSENT`. */
+    actual: unknown;
+    /** The matcher as authored, structurally — rendered by `formatClause`. */
+    demand: unknown;
+    /** What is wrong with the gate itself. Only when `failure` is `malformed`. */
+    defect?: string;
+}
+/** The failing clauses of `condition` against `subject`, or an empty list when
+ *  the failure cannot be decomposed — an `any`/`not` combinator swallowed it,
+ *  or the predicate is a shape this walk does not recognise. An empty list is
+ *  the caller's signal to print the generic reason instead. */
+export declare function explainGate(condition: unknown, subject: NodeConfigSubject): GateClause[];
+/** The grammar's own break between the reader's value and the gate's demand —
+ *  the only place a clause line may be split. */
+export declare const CLAUSE_SEPARATOR = " | gate: ";
+/** One clause as one line of plain text — the ONLY place a gate failure is put
+ *  into human words. Callers own indentation, colour, wrapping, and joining. */
+export declare function formatClause(clause: GateClause): string;
+/** The pattern as the thing it demands: an anchored literal path collapsed to
+ *  the directory it names, else the longest literal run it insists on, else an
+ *  admission that it is a pattern. The source is never printed. */
+export declare function readableRegex(source: string): string;
+/** Which of a record's two gates is being explained. */
+export type GateSide = 'doc' | 'entry';
+/** The failing clauses of one record's document or entry gate, or an empty list
+ *  when there is nothing to explain — the gate passed, there is no subject to
+ *  match against, or the predicate resists decomposition. An evaluator that
+ *  throws is the planner's own `failed to evaluate` outcome and keeps its
+ *  sentence. */
+export declare function explainRecordGate(record: DeliveryRecord, side: GateSide, subject: NodeConfigSubject | null): GateClause[];
+/** Does every failing clause name a node value the reader can change? Only then
+ *  is "dial the snapshot" a true instruction — a malformed gate is fixed in the
+ *  document. */
+export declare function allMismatches(clauses: readonly GateClause[]): boolean;

package/dist/core/substrate/gate-explain.js

@@ -0,0 +1,424 @@
+// gate-explain.ts — why a gate refused THIS node, in the words the reader can
+// act on: their own value on the left, the gate's demand on the right.
+//
+// This is a SECOND, opt-in read of the same predicate `evalCondition` already
+// judged (predicate.ts), never a replacement for it. It shares that engine's
+// leaf primitives (`matchField`, `getField`), so a leaf verdict cannot drift
+// between the verdict and its explanation; only the structural walk exists
+// twice, and the fallback covers the walk. It is never called while planning —
+// only while rendering a document a human is already looking at.
+//
+// It is advisory. When it cannot decompose a failure it returns nothing, and
+// every caller falls back to the planner's generic sentence rather than
+// inventing one.
+import { getField, matchField, evalCondition } from '../predicate.js';
+import { tildify } from '../fs-utils.js';
+/** The subject has no value at this field path — distinct from a value of
+ *  `null`, which a gate can legitimately demand. */
+export const ABSENT = Symbol('absent');
+// The structural walk.
+/** The failing clauses of `condition` against `subject`, or an empty list when
+ *  the failure cannot be decomposed — an `any`/`not` combinator swallowed it,
+ *  or the predicate is a shape this walk does not recognise. An empty list is
+ *  the caller's signal to print the generic reason instead. */
+export function explainGate(condition, subject) {
+    return walk(condition, subject) ?? [];
+}
+/** The failing clauses of one predicate, or `null` when its failure is opaque.
+ *  Opacity travels outward: a sibling's mismatch is not the remedy when an
+ *  undecomposable branch also failed, so the whole explanation is abandoned. */
+function walk(condition, subject) {
+    if (condition == null || typeof condition !== 'object')
+        return [];
+    if (Array.isArray(condition))
+        return collect(condition, subject);
+    const c = condition;
+    const clauses = [];
+    if ('any' in c || 'not' in c) {
+        // Neither is decomposed: an OR has no single failing branch to name, and a
+        // satisfied negation has no failing clause at all. When one of them is what
+        // failed, the whole explanation is abandoned — an honest generic sentence
+        // beats an invented clause. When it PASSED, the failure is elsewhere and
+        // the rest of the predicate still explains itself.
+        if ('any' in c && !evalCondition({ any: c['any'] }, subject))
+            return null;
+        if ('not' in c && !evalCondition({ not: c['not'] }, subject))
+            return null;
+    }
+    if ('all' in c) {
+        const nested = collect(Array.isArray(c['all']) ? c['all'] : [c['all']], subject);
+        if (nested === null)
+            return null;
+        clauses.push(...nested);
+    }
+    const fields = Object.keys(c).filter((key) => key !== 'all' && key !== 'any' && key !== 'not');
+    // An empty condition is inert — it matches nothing, and no field explains why.
+    if (fields.length === 0 && !('all' in c) && !('any' in c) && !('not' in c)) {
+        return [{ field: '', failure: 'malformed', actual: ABSENT, demand: c, defect: 'is empty, and an empty gate never matches' }];
+    }
+    for (const field of fields) {
+        const matcher = c[field];
+        if (matchField(getField(subject, field), matcher))
+            continue;
+        clauses.push(clauseFor(field, matcher, subject));
+    }
+    return clauses;
+}
+/** Every sub-predicate's clauses, or `null` as soon as one is opaque. */
+function collect(subs, subject) {
+    const clauses = [];
+    for (const sub of subs) {
+        const nested = walk(sub, subject);
+        if (nested === null)
+            return null;
+        clauses.push(...nested);
+    }
+    return clauses;
+}
+function clauseFor(field, matcher, subject) {
+    const raw = getField(subject, field);
+    const actual = raw === undefined ? ABSENT : raw;
+    const defect = matcherDefect(matcher);
+    return defect === null
+        ? { field, failure: 'mismatch', actual, demand: matcher }
+        : { field, failure: 'malformed', actual, demand: matcher, defect };
+}
+const KNOWN_OPS = new Set([
+    'eq', 'ne', 'in', 'nin', 'exists', 'contains', 'containsAll', 'containsAny',
+    'matches', 'imatches', 'gt', 'gte', 'lt', 'lte',
+]);
+/** What makes this matcher unsatisfiable by ANY node, or null when it is a
+ *  well-formed demand this node merely does not meet. */
+function matcherDefect(matcher) {
+    // A scalar or an array is compared directly by the engine — a demand this
+    // node fails, never a defect of the gate.
+    if (matcher === null || Array.isArray(matcher) || typeof matcher !== 'object')
+        return null;
+    for (const [op, arg] of Object.entries(matcher)) {
+        if (!KNOWN_OPS.has(op))
+            return `uses unknown operator "${op}" \u2014 unknown operators never match`;
+        if (op === 'matches' || op === 'imatches') {
+            if (typeof arg !== 'string')
+                return 'is matched against something that is not a pattern \u2014 it never matches';
+            try {
+                new RegExp(arg, op === 'imatches' ? 'i' : '');
+            }
+            catch {
+                return 'has an invalid regular expression \u2014 an invalid pattern never matches';
+            }
+        }
+        if (['gt', 'gte', 'lt', 'lte'].includes(op) && Number.isNaN(Number(arg))) {
+            return `compares ${op} against something that is not a number \u2014 it never matches`;
+        }
+    }
+    return null;
+}
+// The single phrasing site.
+/** The rail row a gate field names, because that row is the remedy. */
+function labelFor(field) {
+    if (field === 'hasManager')
+        return 'manager';
+    if (field === 'orchestration.depth')
+        return 'depth';
+    return field;
+}
+/** The grammar's own break between the reader's value and the gate's demand —
+ *  the only place a clause line may be split. */
+export const CLAUSE_SEPARATOR = ' | gate: ';
+/** One clause as one line of plain text — the ONLY place a gate failure is put
+ *  into human words. Callers own indentation, colour, wrapping, and joining. */
+export function formatClause(clause) {
+    if (clause.failure === 'malformed') {
+        const label = clause.field === '' ? 'the gate' : labelFor(clause.field);
+        return `${label} ${clause.defect ?? 'never matches'}`;
+    }
+    return `${labelFor(clause.field)}: ${renderActual(clause.actual)}${CLAUSE_SEPARATOR}${renderDemand(clause.demand)}`;
+}
+function renderActual(value) {
+    if (value === ABSENT || value === null || value === undefined)
+        return 'none';
+    if (typeof value === 'boolean')
+        return value ? 'yes' : 'no';
+    if (Array.isArray(value))
+        return value.map((v) => renderActual(v)).join(', ');
+    if (typeof value === 'string')
+        return value === '' ? 'none' : shortPath(value);
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    return String(value);
+}
+/** The gate's demand, per matcher shape. Never regex source, never a full
+ *  home-prefixed path. */
+function renderDemand(matcher) {
+    if (matcher === null || matcher === undefined)
+        return 'none';
+    if (typeof matcher === 'boolean')
+        return matcher ? 'yes' : 'no';
+    if (typeof matcher === 'string')
+        return matcher === '' ? 'none' : shortPath(matcher);
+    if (typeof matcher === 'number')
+        return String(matcher);
+    if (Array.isArray(matcher))
+        return orList(matcher);
+    const ops = Object.entries(matcher);
+    if (ops.length === 0)
+        return 'nothing';
+    return ops.map(([op, arg]) => renderOp(op, arg)).join(' and ');
+}
+function renderOp(op, arg) {
+    switch (op) {
+        case 'eq':
+            return renderDemand(arg);
+        case 'ne':
+            return `not ${renderDemand(arg)}`;
+        case 'in':
+            return orList(arg);
+        case 'nin':
+            return `not ${orList(arg)}`;
+        case 'exists':
+            return arg === false ? 'no value' : 'any value';
+        case 'contains':
+            return `includes ${renderDemand(arg)}`;
+        case 'containsAll':
+            return `includes all of ${commaList(arg)}`;
+        case 'containsAny':
+            return `includes any of ${commaList(arg)}`;
+        case 'matches':
+        case 'imatches':
+            return typeof arg === 'string' ? readableRegex(arg) : 'a pattern';
+        case 'gt':
+            return `> ${String(arg)}`;
+        case 'gte':
+            return `\u2265 ${String(arg)}`;
+        case 'lt':
+            return `< ${String(arg)}`;
+        case 'lte':
+            return `\u2264 ${String(arg)}`;
+        default:
+            return `${op} ${String(arg)}`;
+    }
+}
+function orList(arg) {
+    const items = (Array.isArray(arg) ? arg : [arg]).map((v) => renderDemand(v));
+    return items.length === 0 ? 'nothing' : items.join(' or ');
+}
+function commaList(arg) {
+    return (Array.isArray(arg) ? arg : [arg]).map((v) => renderDemand(v)).join(', ');
+}
+function shortPath(value) {
+    return value.startsWith('/') ? tildify(value) : value;
+}
+// Regex reduction — every real `cwd` gate is an anchored literal path, whole or
+// followed by one alternation of the projects it covers, and it should read as
+// the directory or directories it means.
+const META = new Set(['\\', '^', '$', '.', '|', '?', '*', '+', '(', ')', '[', ']', '{', '}']);
+/** The pattern as the thing it demands: an anchored literal path collapsed to
+ *  the directory it names, else the longest literal run it insists on, else an
+ *  admission that it is a pattern. The source is never printed. */
+export function readableRegex(source) {
+    let body = source;
+    if (body.startsWith('^'))
+        body = body.slice(1);
+    // The house `cwd` idiom: a trailing "this directory or anything under it".
+    body = body.replace(/\((?:\?:)?\\?\/\|\$\)\??$/, '');
+    if (body.endsWith('$') && !body.endsWith('\\$'))
+        body = body.slice(0, -1);
+    const literal = unescapeLiteral(body);
+    if (literal !== null && literal !== '')
+        return shortPath(literal);
+    const branches = distributeAlternation(body);
+    if (branches !== null)
+        return branches.map((branch) => shortPath(branch)).join(' or ');
+    const run = longestLiteralRun(source);
+    return run === null ? 'a pattern' : `contains "${shortPath(run)}"`;
+}
+/** The pattern's plain text when it holds no unescaped metacharacter, else
+ *  null. `\/` and `\.` are literal characters and survive; `\d` and friends are
+ *  classes and disqualify the whole pattern. */
+function unescapeLiteral(source) {
+    let out = '';
+    for (let i = 0; i < source.length; i++) {
+        const ch = source[i];
+        if (ch === '\\') {
+            const next = source[i + 1];
+            if (next === undefined || (!META.has(next) && next !== '/' && next !== '-'))
+                return null;
+            out += next;
+            i++;
+            continue;
+        }
+        if (META.has(ch))
+            return null;
+        out += ch;
+    }
+    return out;
+}
+/** The paths a literal prefix followed by ONE alternation group means: each
+ *  branch appended to the prefix, so the reader is handed directories they can
+ *  actually be in rather than the prefix they all share. Null when the body is
+ *  any other shape — a second group, text after the group, or a branch holding
+ *  a metacharacter outside the glob vocabulary. */
+function distributeAlternation(body) {
+    const open = body.indexOf('(');
+    if (open === -1 || !body.endsWith(')'))
+        return null;
+    const prefix = unescapeLiteral(body.slice(0, open));
+    if (prefix === null)
+        return null;
+    let inner = body.slice(open + 1, -1);
+    if (inner.startsWith('?:'))
+        inner = inner.slice(2);
+    // One group only: a nested group is a shape this reduction does not read.
+    if (inner.includes('(') || inner.includes(')'))
+        return null;
+    const branches = inner.split('|');
+    if (branches.length < 2)
+        return null;
+    const paths = [];
+    for (const branch of branches) {
+        const text = branchText(branch);
+        if (text === null)
+            return null;
+        paths.push(prefix + text);
+    }
+    return paths;
+}
+/** One branch as plain text, with a whole-segment wildcard rendered as the path
+ *  glob it means. The vocabulary is exactly `[^/]+` and `.*`; any other
+ *  metacharacter means the branch is not a path and the whole shape is
+ *  abandoned. */
+function branchText(branch) {
+    let out = '';
+    for (let i = 0; i < branch.length; i++) {
+        if (branch.startsWith('[^/]+', i)) {
+            out += '*';
+            i += 4;
+            continue;
+        }
+        if (branch.startsWith('[^\\/]+', i)) {
+            out += '*';
+            i += 5;
+            continue;
+        }
+        if (branch.startsWith('.*', i)) {
+            out += '*';
+            i += 1;
+            continue;
+        }
+        const ch = branch[i];
+        if (ch === '\\') {
+            const next = branch[i + 1];
+            if (next === undefined || (!META.has(next) && next !== '/' && next !== '-'))
+                return null;
+            out += next;
+            i++;
+            continue;
+        }
+        if (META.has(ch))
+            return null;
+        out += ch;
+    }
+    return out;
+}
+/** The longest stretch of characters EVERY string the pattern accepts contains,
+ *  or null when it guarantees nothing longer than a single character. Only text
+ *  outside every group and character class counts: a group may be alternated or
+ *  quantified away, so its contents are not guaranteed. A top-level alternation
+ *  guarantees nothing at all. */
+function longestLiteralRun(source) {
+    let best = '';
+    let run = '';
+    let depth = 0;
+    let inClass = false;
+    const flush = () => {
+        if (run.length > best.length)
+            best = run;
+        run = '';
+    };
+    for (let i = 0; i < source.length; i++) {
+        const ch = source[i];
+        if (ch === '\\') {
+            const next = source[i + 1];
+            i++;
+            if (depth === 0 && !inClass && next !== undefined && (META.has(next) || next === '/' || next === '-')) {
+                run += next;
+                continue;
+            }
+            flush();
+            continue;
+        }
+        if (inClass) {
+            if (ch === ']')
+                inClass = false;
+            continue;
+        }
+        if (ch === '[') {
+            flush();
+            inClass = true;
+            continue;
+        }
+        if (ch === '(') {
+            flush();
+            depth++;
+            continue;
+        }
+        if (ch === ')') {
+            flush();
+            if (depth > 0)
+                depth--;
+            continue;
+        }
+        // Branches share no text, so nothing survives a top-level alternation.
+        if (ch === '|' && depth === 0)
+            return null;
+        if (ch === '{') {
+            // A repetition count can be zero — the character it applies to goes, and
+            // the count itself is syntax, not text the pattern matches.
+            if (run.length > 0)
+                run = run.slice(0, -1);
+            flush();
+            const close = source.indexOf('}', i);
+            if (close !== -1)
+                i = close;
+            continue;
+        }
+        if (META.has(ch) || depth > 0) {
+            // A quantifier applies to the character before it, which is therefore not
+            // guaranteed — drop it from the run.
+            if ((ch === '?' || ch === '*') && run.length > 0)
+                run = run.slice(0, -1);
+            flush();
+            continue;
+        }
+        run += ch;
+    }
+    flush();
+    return best.length > 1 ? best : null;
+}
+/** The failing clauses of one record's document or entry gate, or an empty list
+ *  when there is nothing to explain — the gate passed, there is no subject to
+ *  match against, or the predicate resists decomposition. An evaluator that
+ *  throws is the planner's own `failed to evaluate` outcome and keeps its
+ *  sentence. */
+export function explainRecordGate(record, side, subject) {
+    const outcome = side === 'doc' ? record.docGate : record.entryGate;
+    if (outcome === null || outcome.pass || subject === null)
+        return [];
+    const predicate = side === 'doc'
+        ? record.doc.gate
+        : record.authoredEntries.find((decision) => !decision.gate.pass)?.entry.gate;
+    if (predicate === undefined)
+        return [];
+    try {
+        return explainGate(predicate, subject);
+    }
+    catch {
+        return [];
+    }
+}
+/** Does every failing clause name a node value the reader can change? Only then
+ *  is "dial the snapshot" a true instruction — a malformed gate is fixed in the
+ *  document. */
+export function allMismatches(clauses) {
+    return clauses.length > 0 && clauses.every((clause) => clause.failure === 'mismatch');
+}