polydeukes 0.6.1 → 0.8.0

package/dist/covenant/dispatch.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Path-routing dispatcher — routes an input to the covenant bodies whose protected paths
+ * it mentions.
+ *
+ * Matching is a pure path-mention core (zero I/O); execution reuses {@link runCovenant}
+ * (the sole judgment wrapper) and {@link appendRecordFailOpen} (the sole log seam). The
+ * dispatcher parses the payload once, to decide routing and to hand the judge thunks the
+ * one parsed call set they judge.
+ */
+import { type CanonicalTranscript, type CovenantInput, type DispatchOutcome, type EnforceLevel, type SkipReason } from '@polydeukes/core';
+import { type JudgeOutcome } from './run-covenant.ts';
+/**
+ * `WitnessPredicate` — the valve a registration offers, asked after a blocking judgment:
+ * the observation, the transcript, and the registration's own label with the matched subject.
+ */
+export type WitnessPredicate = (input: CovenantInput, transcript: CanonicalTranscript, context: {
+    label: string;
+    subject: string;
+}) => boolean;
+/**
+ * `CovenantRegistration` — one registered covenant.
+ *
+ * `protectedPaths` are literal path strings (the output shape of normalization, not
+ * globs); an empty array never matches, and empty-string entries are ignored (an empty
+ * `''` would match every input). `body` is the in-process judge: assembly binds its
+ * options into it, and the dispatcher supplies the parsed call set as its argument when a
+ * protected path is mentioned. Assembly therefore never needs the payload, so one compiled
+ * registration set judges every call.
+ *
+ * `witness`, when present, is consulted only after a *matched* registration's body has run
+ * and broken, receiving the injected transcript seam as its second argument and a
+ * `{ label, subject }` context naming what broke as its third: a `true` return relaxes
+ * that block (measured as `witnessed`).
+ *
+ * `matches`, when present, replaces path-mention routing with a content predicate: a
+ * non-null return routes (the string becomes the telemetry subject), null does not, and a
+ * throw is a fail-closed match with subject `'-'`.
+ *
+ * A registration carries EITHER a `body` or a `skip`. `skip` means assembly could not
+ * produce a judgeable body — the evidence channel is absent, or the declared evidence
+ * vocabulary could not be resolved — so a match records one `skipped` and upholds instead
+ * of judging. Judging it anyway would block every matched input with no legitimate pass
+ * path; throwing at assembly would take down every sibling registration and the witness
+ * valve with it. `reason` is the sentence the author reads; `kind` is the token the row
+ * carries, so the measurement separates an environment fact from a config fault.
+ *
+ * `enforce` is the AUTHOR's level for this one registration, distinct from the observer's
+ * dispatch-wide level; absence means the registration inherits whatever the dispatch
+ * carries.
+ *
+ * `sources` are what outside the target this registration's declaration names, each element
+ * carrying its own kind — a repo-relative file, a channel the surface supplies, or the
+ * session's conversation history. They are the supply layer's only input; a family that
+ * names nothing carries no key.
+ */
+export type CovenantRegistration = {
+    label: string;
+    protectedPaths: string[];
+    enforce?: EnforceLevel;
+    sources?: readonly ({
+        name: string;
+        file: string;
+    } | {
+        name: string;
+        sidecar: true;
+    } | {
+        name: string;
+        transcript: true;
+    })[];
+    witness?: WitnessPredicate;
+    matches?: (input: CovenantInput) => string | null;
+} & ({
+    body: (input: CovenantInput) => Promise<JudgeOutcome>;
+    skip?: never;
+} | {
+    body?: never;
+    skip: {
+        reason: string;
+        kind: SkipReason;
+    };
+});
+/**
+ * Match registrations against a {@link CovenantInput} by path mention (pure).
+ *
+ * A registration matches when any of its `protectedPaths` is an ancestor/descendant/equal of
+ * a path candidate. Candidates come from two places: every string value reachable at any
+ * depth inside `input.toolCalls[].args`, read as quote-aware tokenizer words so a
+ * quote-split write still routes, and each call's proven `fileChange` path, taken whole
+ * because an adapter already resolved it. A call carrying only the latter is the ordinary
+ * shape where a host names its target in a form the adapter must parse — the patch text of
+ * one edit rather than a path argument. An unread span with a non-empty `protectedPaths`
+ * routes fail-closed (the registration matches on its first protected path) rather than
+ * silently miss. `subagentSpawns` and `userMessages` never participate. `mentionedPath` is
+ * the first protected path (in array order) that mentions. Result preserves registration
+ * order, at most one entry per registration.
+ *
+ * A registration carrying a `matches` predicate routes on it exclusively, path mention
+ * skipped for it: non-null return → included with that string as `mentionedPath`; null →
+ * skipped; a throw → fail-closed inclusion with `'-'` (caught per registration, never
+ * bubbling to the dispatcher-level catch).
+ */
+export declare function matchRegistrations(input: CovenantInput, registrations: CovenantRegistration[]): {
+    registration: CovenantRegistration;
+    mentionedPath: string;
+    routingFailed?: boolean;
+}[];
+/** A registration assembled by a meta-covenant: one that always carries a judgeable body. */
+export type MetaCovenantRegistration = CovenantRegistration & {
+    body: NonNullable<CovenantRegistration['body']>;
+};
+/** `dispatchCovenants` input — the payload, the registration table, and the dispatch posture. */
+export type DispatchCovenantsSpec = {
+    stdinPayload: string;
+    registrations: CovenantRegistration[];
+    telemetryPath: string;
+    dispatcherLabel?: string;
+    transcript?: CanonicalTranscript;
+    enforce?: EnforceLevel;
+    world?: CovenantInput['world'];
+};
+/**
+ * Dispatch covenants for a stdin payload.
+ *
+ * Fail-closed: an unjudgeable payload — unparseable JSON, or a parseable one whose
+ * structure defeats the matching traversal (a null toolCalls element, adversarially deep
+ * nesting) — yields exitCode 2, judges nothing, and appends exactly one `blocked` record
+ * for the dispatcher itself. "Cannot judge" means block; it never means throw, because an
+ * uncaught rejection exits the hook with a non-blocking code and becomes a bypass vector.
+ * On matches, every matched registration runs sequentially via {@link runCovenant}
+ * (run-all, no short-circuit); the verdict is `2` if any body blocks, else `0`. No matches
+ * passes vacuously with zero judgments and zero telemetry.
+ *
+ * World: `spec.world` is the supply layer's result, attached to the parsed input before
+ * routing so the body, the routing predicate, and the valve all judge one world. A world
+ * the payload itself carries stands only when the spec names none.
+ *
+ * Witness: the dispatcher only BINDS the witness's arguments — the parsed input, the
+ * injected `spec.transcript` (`noopTranscript` when omitted), and a `{ label, subject }`
+ * context naming the registration and its matched path — and hands the thunk to
+ * {@link runCovenant}, which consults it after the judgment and only when the body's
+ * outcome translated to `blocked`. So the body always runs: a matched registration that
+ * upholds is never witnessed, and a `true` return relaxes a real break into
+ * `0` / `witnessed`. A predicate that throws opens nothing: an uncertain witness never
+ * leaks toward fail-open.
+ *
+ * Enforce: the level has two owners — `spec.enforce` is the observer's posture for the
+ * whole dispatch, `registration.enforce` the author's for one entry — and the dispatcher
+ * composes them per registration with the lenient side winning, then threads the effective
+ * level into {@link runCovenant}, where the translation table lives. Lenient-wins keeps an
+ * explicit `block` entry from raising a surface the observer lowered, and lets one entry
+ * lower itself under a block surface. The dispatcher's own fail-closed is outside that axis
+ * and outside the valve too (nothing judged, so no verdict to relax). Each results entry
+ * surfaces the telemetry `event` the wrapper recorded, never a recomputed one — the valve
+ * is impure, and a recompute would consult it twice for one verdict.
+ */
+export declare function dispatchCovenants(spec: DispatchCovenantsSpec): Promise<DispatchOutcome>;

package/dist/covenant/dispatch.js

@@ -0,0 +1,250 @@
+/**
+ * Path-routing dispatcher — routes an input to the covenant bodies whose protected paths
+ * it mentions.
+ *
+ * Matching is a pure path-mention core (zero I/O); execution reuses {@link runCovenant}
+ * (the sole judgment wrapper) and {@link appendRecordFailOpen} (the sole log seam). The
+ * dispatcher parses the payload once, to decide routing and to hand the judge thunks the
+ * one parsed call set they judge.
+ */
+import { appendRecordFailOpen, EXIT_BREAK_BLOCKING, EXIT_UPHOLD, noopTranscript, parseInput, } from '@polydeukes/core';
+import { tokenizeCommandLine } from './bash-line.js';
+import { pathCandidates, pathMatchesProtected, provenChangePath } from './mention.js';
+import { runCovenant } from './run-covenant.js';
+/**
+ * Collect path candidates from every string value inside `value`. Each string is tokenized
+ * quote-aware (via the shared tokenizer) so quote/escape splits collapse to the word the
+ * shell would see; each resulting word text is a candidate. An unread span surfaces as
+ * `failed = true` so the caller can route fail-closed rather than fall back to a
+ * raw-substring scan — the candidates the same line's read commands contribute add routing
+ * precision, they never withdraw that flag.
+ */
+function collectPathCandidates(value) {
+    const candidates = [];
+    let failed = false;
+    const walk = (node) => {
+        if (typeof node === 'string') {
+            const result = tokenizeCommandLine(node);
+            if (result.unread.length > 0)
+                failed = true;
+            for (const command of result.commands) {
+                // Split each tokenized word the same way mentionsPath does, so a path fused to
+                // another lexeme (`--dest=path`) still surfaces as its own candidate.
+                for (const word of command.words)
+                    candidates.push(...pathCandidates(word.text));
+                for (const redirect of command.redirects) {
+                    candidates.push(...pathCandidates(redirect.target.text));
+                }
+            }
+            return;
+        }
+        if (Array.isArray(node)) {
+            for (const item of node)
+                walk(item);
+            return;
+        }
+        if (typeof node === 'object' && node !== null) {
+            for (const item of Object.values(node))
+                walk(item);
+        }
+    };
+    walk(value);
+    return { candidates, failed };
+}
+/**
+ * Match registrations against a {@link CovenantInput} by path mention (pure).
+ *
+ * A registration matches when any of its `protectedPaths` is an ancestor/descendant/equal of
+ * a path candidate. Candidates come from two places: every string value reachable at any
+ * depth inside `input.toolCalls[].args`, read as quote-aware tokenizer words so a
+ * quote-split write still routes, and each call's proven `fileChange` path, taken whole
+ * because an adapter already resolved it. A call carrying only the latter is the ordinary
+ * shape where a host names its target in a form the adapter must parse — the patch text of
+ * one edit rather than a path argument. An unread span with a non-empty `protectedPaths`
+ * routes fail-closed (the registration matches on its first protected path) rather than
+ * silently miss. `subagentSpawns` and `userMessages` never participate. `mentionedPath` is
+ * the first protected path (in array order) that mentions. Result preserves registration
+ * order, at most one entry per registration.
+ *
+ * A registration carrying a `matches` predicate routes on it exclusively, path mention
+ * skipped for it: non-null return → included with that string as `mentionedPath`; null →
+ * skipped; a throw → fail-closed inclusion with `'-'` (caught per registration, never
+ * bubbling to the dispatcher-level catch).
+ */
+export function matchRegistrations(input, registrations) {
+    const { candidates, failed } = collectPathCandidates(input.toolCalls.map((call) => call.args));
+    // A proven change path joins the candidates directly, untokenized: it is a path the
+    // adapter already resolved, not a line to be read for one, and tokenizing it would split
+    // a path containing a space into words that name nothing. Without this a call whose only
+    // evidence is its `fileChange` routes nowhere — the judge bodies read that evidence, so
+    // the input would be refused before the layer that can settle it.
+    for (const call of input.toolCalls) {
+        const proven = provenChangePath(call);
+        if (proven !== null)
+            candidates.push(proven);
+    }
+    const matches = [];
+    for (const registration of registrations) {
+        if (registration.matches !== undefined) {
+            let subject;
+            let routingFailed = false;
+            try {
+                subject = registration.matches(input);
+            }
+            catch {
+                // An uncertain predicate must not leak fail-open — route with subject '-'. The
+                // flag travels with the match because a skip registration has no body to carry
+                // that verdict out, and answering `skipped` there would turn the fail-closed
+                // routing into a pass.
+                subject = '-';
+                routingFailed = true;
+            }
+            if (subject !== null) {
+                matches.push({ registration, mentionedPath: subject, routingFailed });
+            }
+            continue;
+        }
+        const paths = registration.protectedPaths.filter((path) => path !== '');
+        const mentionedPath = paths.find((path) => candidates.some((candidate) => pathMatchesProtected(candidate, path))) ??
+            (failed ? paths[0] : undefined);
+        if (mentionedPath !== undefined) {
+            matches.push({ registration, mentionedPath });
+        }
+    }
+    return matches;
+}
+/**
+ * Dispatch covenants for a stdin payload.
+ *
+ * Fail-closed: an unjudgeable payload — unparseable JSON, or a parseable one whose
+ * structure defeats the matching traversal (a null toolCalls element, adversarially deep
+ * nesting) — yields exitCode 2, judges nothing, and appends exactly one `blocked` record
+ * for the dispatcher itself. "Cannot judge" means block; it never means throw, because an
+ * uncaught rejection exits the hook with a non-blocking code and becomes a bypass vector.
+ * On matches, every matched registration runs sequentially via {@link runCovenant}
+ * (run-all, no short-circuit); the verdict is `2` if any body blocks, else `0`. No matches
+ * passes vacuously with zero judgments and zero telemetry.
+ *
+ * World: `spec.world` is the supply layer's result, attached to the parsed input before
+ * routing so the body, the routing predicate, and the valve all judge one world. A world
+ * the payload itself carries stands only when the spec names none.
+ *
+ * Witness: the dispatcher only BINDS the witness's arguments — the parsed input, the
+ * injected `spec.transcript` (`noopTranscript` when omitted), and a `{ label, subject }`
+ * context naming the registration and its matched path — and hands the thunk to
+ * {@link runCovenant}, which consults it after the judgment and only when the body's
+ * outcome translated to `blocked`. So the body always runs: a matched registration that
+ * upholds is never witnessed, and a `true` return relaxes a real break into
+ * `0` / `witnessed`. A predicate that throws opens nothing: an uncertain witness never
+ * leaks toward fail-open.
+ *
+ * Enforce: the level has two owners — `spec.enforce` is the observer's posture for the
+ * whole dispatch, `registration.enforce` the author's for one entry — and the dispatcher
+ * composes them per registration with the lenient side winning, then threads the effective
+ * level into {@link runCovenant}, where the translation table lives. Lenient-wins keeps an
+ * explicit `block` entry from raising a surface the observer lowered, and lets one entry
+ * lower itself under a block surface. The dispatcher's own fail-closed is outside that axis
+ * and outside the valve too (nothing judged, so no verdict to relax). Each results entry
+ * surfaces the telemetry `event` the wrapper recorded, never a recomputed one — the valve
+ * is impure, and a recompute would consult it twice for one verdict.
+ */
+export async function dispatchCovenants(spec) {
+    const blockedByDispatcher = () => {
+        appendRecordFailOpen(spec.telemetryPath, {
+            event: 'blocked',
+            label: spec.dispatcherLabel ?? 'dispatcher',
+            subject: '-',
+        });
+        return { exitCode: EXIT_BREAK_BLOCKING, results: [] };
+    };
+    const parsed = parseInput(spec.stdinPayload);
+    if (!parsed.ok) {
+        return blockedByDispatcher();
+    }
+    // The world the supply layer built, spliced onto the parsed input here so a composition
+    // root never reopens the payload string its adapter path produced. Without one the key
+    // stays absent rather than holding `undefined`: the judge derives the change set from
+    // the field's absence, and an empty object would read as "supplied nothing".
+    const input = spec.world === undefined ? parsed.value : { ...parsed.value, world: spec.world };
+    let matches;
+    try {
+        matches = matchRegistrations(input, spec.registrations);
+    }
+    catch {
+        // Structurally unjudgeable input (parseInput validates the collection shapes, not the
+        // element ones) — fail-closed, same as an unparseable payload.
+        return blockedByDispatcher();
+    }
+    const transcript = spec.transcript ?? noopTranscript;
+    const results = [];
+    for (const { registration, mentionedPath, routingFailed } of matches) {
+        if (registration.skip !== undefined) {
+            if (routingFailed === true) {
+                // The routing predicate could not answer, which matchRegistrations already
+                // resolved fail-closed. A body-bearing registration would carry that verdict out
+                // by judging and blocking; a skip has no body, so the block is recorded here
+                // rather than softened into a pass. Outside the enforce axis, like every
+                // unjudgeable outcome.
+                appendRecordFailOpen(spec.telemetryPath, {
+                    event: 'blocked',
+                    label: registration.label,
+                    subject: mentionedPath,
+                });
+                results.push({
+                    label: registration.label,
+                    exitCode: EXIT_BREAK_BLOCKING,
+                    event: 'blocked',
+                });
+                continue;
+            }
+            // Nothing to judge and nothing to witness — the valve exists for a verdict, and a
+            // skip has none. Recording it keeps the no-op visible in `gain`.
+            appendRecordFailOpen(spec.telemetryPath, {
+                event: 'skipped',
+                label: registration.label,
+                subject: mentionedPath,
+                reason: registration.skip.kind,
+            });
+            results.push({ label: registration.label, exitCode: EXIT_UPHOLD, event: 'skipped' });
+            continue;
+        }
+        // Bound here, consulted in the wrapper: the context is what the umbrella prompt
+        // needs to name what broke. The local alias exists for TypeScript narrowing — a
+        // property access cannot stay narrowed inside the closure below.
+        const witness = registration.witness;
+        // Absence stays absent: the block default lives in the wrapper, not restated here.
+        // A routing that could not answer is outside the level axis on this arm too (the skip
+        // arm above already is): the body judges against subject '-' and its break must land
+        // blocked whatever level the entry or the surface declared. Every compiled entry
+        // carries a level, so without this the unjudgeable call would advise.
+        const effectiveEnforce = routingFailed === true
+            ? undefined
+            : registration.enforce === 'advise'
+                ? 'advise'
+                : spec.enforce;
+        // The parsed call set is handed to the judge HERE rather than baked in at assembly:
+        // the dispatcher is the one place that has it, so assembly stays payload-free and one
+        // compiled registration set serves every payload.
+        const body = registration.body;
+        const { exitCode, event } = await runCovenant({
+            body: () => body(input),
+            label: registration.label,
+            subject: mentionedPath,
+            telemetryPath: spec.telemetryPath,
+            enforce: effectiveEnforce,
+            ...(witness !== undefined
+                ? {
+                    witness: () => witness(input, transcript, {
+                        label: registration.label,
+                        subject: mentionedPath,
+                    }),
+                }
+                : {}),
+        });
+        results.push({ label: registration.label, exitCode, event });
+    }
+    const exitCode = results.some((result) => result.exitCode === EXIT_BREAK_BLOCKING)
+        ? EXIT_BREAK_BLOCKING
+        : EXIT_UPHOLD;
+    return { exitCode, results };
+}

package/dist/covenant/extract-steps.d.ts

@@ -0,0 +1,122 @@
+/**
+ * `EXTRACT_STEPS` — the registry of unary extract steps, the open half of the extraction
+ * vocabulary. A declaration can name a step only if this table carries it; anything else is
+ * refused when the declaration is compiled, before any value is produced.
+ *
+ * Every entry is a triple: `args` is the closed set of argument keys it admits, `validate`
+ * turns a wrong key or a wrong type into a config fault, and `run` maps `Items` to `Items`
+ * and to nothing else — no step answers a boolean, because the last comparison of a
+ * judgment belongs to the relation position.
+ *
+ * The seventeen steps:
+ *
+ * - `source` — lift `World[of]` into a single item keyed `'0'`.
+ * - `json` — parse each item's string value; an unparseable value fails supply.
+ * - `select` — project a dot path, spreading an array result into position-keyed items; a
+ *   path the object does not carry projects to nothing.
+ * - `items` — spread each array value one level into position-keyed items; a non-array value
+ *   is dropped, and an element that is itself an array stays one item. The keys are
+ *   positions within their own array, so two items each holding one collide under `'0'`,
+ *   and a relation that compares keys reads them as positions and nothing else. Pair this
+ *   step with `keyBy` when the elements are objects carrying the key the relation needs.
+ * - `keyBy` — re-index each element by one of its fields, as a string.
+ * - `keyByPattern` — re-index each item by capture group 1 of a constant regular expression
+ *   over its stringified value, dropping what does not match or leaves the group unbound.
+ *   The pair of `keyBy`: one re-keys by an object field, the other by a pattern over the
+ *   value.
+ * - `field` — keep the key, replace the value with one property of it.
+ * - `filter` — keep the items every constant predicate admits.
+ * - `flattenKeys` — enumerate a nested object's leaves as dot paths, key and value alike.
+ * - `sort` — stable sort by value: numbers numerically, strings by code point.
+ * - `lines` — split a string into trimmed non-empty lines keyed by source line number.
+ * - `matches` — keep the items whose value matches a constant regular expression.
+ * - `toolUses` — one item per tool call of a session snapshot, keyed by the call's own
+ *   observation ordinal; `names` and `subagentType` narrow it and conjoin.
+ * - `userTexts` — one item per user turn of a session snapshot whose text matches a
+ *   constant expression, keyed by the turn's ordinal, the value carrying the snapshot clock.
+ * - `agentType` — one item per parsed sidecar record whose `agentType` equals `is`, keyed by
+ *   its position in the record list.
+ * - `first` — the first item alone, under its own key; it does not sort.
+ * - `ageMs` — add `ageMs = observedAtMs − timestampMs` to each value, dropping an item whose
+ *   timestamp is not a number or lies after the clock, because an undated or future-dated
+ *   observation is not a recent one.
+ *
+ * A step that would compare two world values against each other is not a unary step: that
+ * comparison belongs to a combinator, and the combinators are three and closed.
+ */
+/** One element of an extraction. `key` combines and compares, `value` is what a relation sees. */
+export type Item = {
+    readonly key: string;
+    readonly value: unknown;
+};
+/** The input and the output of every extract step; the order is the supply's. */
+export type Items = readonly Item[];
+/** An extraction split by a paired source into its two states. */
+export type PairedItems = {
+    readonly pre: Items;
+    readonly post: Items;
+};
+/**
+ * One session's observations as plain data — the value a host flattens its own history into
+ * once, so this module judges data rather than a query interface. `index` is an observation
+ * ordinal within its own list, and `observedAtMs` the clock the ages are measured against.
+ */
+export type SessionSnapshot = {
+    readonly observedAtMs: number;
+    readonly userMessages: readonly {
+        index: number;
+        text: string;
+        timestampMs?: number;
+    }[];
+    readonly toolCalls: readonly {
+        index: number;
+        name: string;
+        args: Record<string, unknown>;
+        succeeded?: boolean;
+    }[];
+};
+/** Source name to value. `state` carries `{ pre, post }` and is read as a pair. */
+export type World = Readonly<Record<string, unknown>>;
+/** What compilation answers with instead of a compiled declaration; never a throw. */
+export type ConfigFault = {
+    readonly kind: 'config-fault';
+    readonly location: string;
+    readonly reason: string;
+};
+/** One registry entry: the closed argument keys, their validator, and the runner. */
+export type ExtractStepEntry = {
+    readonly args: ReadonlySet<string>;
+    validate(args: Readonly<Record<string, unknown>>, location: string): ConfigFault | undefined;
+    run(items: Items, args: Readonly<Record<string, unknown>>): Items;
+};
+/**
+ * A value `json` could not parse, thrown out of `run` and caught by the engine, which
+ * names the source and answers a supply failure. It never leaves the engine.
+ */
+export declare class SupplyFailure extends Error {
+}
+/** Build the value compilation answers with when a declaration is wrong at `location`. */
+export declare function fault(location: string, reason: string): ConfigFault;
+/**
+ * The canonical form of a value for structural comparison — object keys sorted so that two
+ * objects written in different orders compare equal. `undefined` is distinct from `null`:
+ * an absent field and a field set to null are different answers, and a discipline that
+ * excludes `null` must not thereby exclude the absent one.
+ */
+export declare function canonical(value: unknown): string;
+/** Structural equality — the equality every relation and the `filter` predicates use. */
+export declare function sameValue(left: unknown, right: unknown): boolean;
+/**
+ * The order `sort` and `Ordered` share, chosen once for a whole list rather than pair by
+ * pair: all-numbers compare numerically, anything else by its stringified form. A per-pair
+ * choice would order a mixed list inconsistently — `2 < 10` numerically and `'10' < '2'` as
+ * text, so the answer would depend on which pairs the comparison happened to visit.
+ */
+export declare function comparatorFor(items: Items): (left: Item, right: Item) => number;
+/**
+ * The unary vocabulary, by step name. A declaration may name only these; the engine looks a
+ * step up here when it compiles and refuses any name the table does not carry.
+ */
+export declare const EXTRACT_STEPS: Readonly<Record<string, ExtractStepEntry>>;
+/** The names the registry carries — the whole of the unary vocabulary. */
+export declare const UNARY_STEP_NAMES: readonly string[];

package/dist/covenant/mention.d.ts

@@ -0,0 +1,117 @@
+/**
+ * `mentionsPath` — the single path-mention semantic shared by the dispatcher and the
+ * pure judges.
+ *
+ * Both the path-routing dispatcher (`matchRegistrations`) and any covenant judge that keys
+ * on a protected path import this one function, so the two layers can never drift apart.
+ * Argument names are never inspected — only string *values* are scanned, at any depth,
+ * keeping the traversal agent-neutral.
+ *
+ * Interior `.`/`..` resolution is a SECOND comparison, never a replacement: raw segments
+ * match first, dot-resolved segments only if that fails. Because the result is a union, a
+ * newly closed notation can only ever add matches — a replacement pass would silently
+ * withdraw defences that the raw comparison already had.
+ *
+ * A glob, a variable expansion, and a tilde are deliberately NOT read. None can be resolved
+ * without running the shell or touching the filesystem, and a judge that guesses at them
+ * either misses the real target or blocks an innocent one. They stay undecidable here and
+ * are answered where undecidability belongs: the Bash axis's opaque-token rule and the skip
+ * registrations. A spelling some layer genuinely *can* resolve — the home directory in front
+ * of the session transcript — is closed by the layer that knows the value, via a dedicated
+ * `matches` predicate rather than a protected path, so no home spelling is inferred here.
+ */
+/**
+ * Normalize a path into segments: strip leading `./`, trailing `/`, split on `/`, drop
+ * empties. Exported so the self-mod judge can tell a judgeable evidence path from a
+ * degenerate one (`''`, `'.'`, `'/'` — zero segments) that proves nothing.
+ *
+ * A lone `.` survives as a segment, and resolving interior dots is a separate pass inside
+ * {@link pathMatchesProtected}. Folding that pass in here would change what the
+ * degenerate-evidence check built on top of this function counts as degenerate.
+ */
+export declare function pathSegments(path: string): string[];
+/**
+ * Return the mutation target proven by a call's `fileChange` evidence, or `null` when the
+ * evidence proves none.
+ *
+ * @param call - The tool call whose evidence is inspected
+ * @returns The change path when the evidence carries a recognized kind and a path with at
+ *   least one non-`.` segment; otherwise `null`
+ */
+export declare function provenChangePath(call: {
+    fileChange?: unknown;
+}): string | null;
+/**
+ * Resolve `.` and `..` against the preceding segment — pure string work, no filesystem and
+ * no working directory, so the answer is the same wherever the judge runs.
+ *
+ * A `..` with nothing left to cancel is KEPT rather than dropped. Dropping it would collapse
+ * `../packages` into `packages` and hand a sibling checkout the protection meant for this
+ * one; keeping it leaves a segment that matches nothing, which is the honest answer for a
+ * path that points outside the tree.
+ *
+ * Exported so a judge whose own equality needs the same second pass (the transcript
+ * predicate) shares this one implementation instead of forking it per site.
+ */
+export declare function resolveDotSegments(segments: string[]): string[];
+/**
+ * True iff `candidate` names the protected path, a descendant of it, or a (relative) ancestor
+ * of it — compared on path segments, not raw substrings, by {@link segmentsMatch}.
+ *
+ * Two passes, unioned. The raw pass is the shipped semantic and runs first: a command that
+ * spells the protected path out loud is caught by it no matter what the path resolves to
+ * afterwards, which is why `rm -rf .claude/hooks/../..` breaks here rather than needing a
+ * rule of its own. The dot-resolved pass runs only when the raw one finds nothing, and is
+ * what `packages/core/./dist/index.js` and `packages/core/src/../dist/index.js` need. Because
+ * it is a union it can only ever add matches, never withdraw one.
+ */
+export declare function pathMatchesProtected(candidate: string, protectedPath: string): boolean;
+/**
+ * Extract path candidates from one string token. The token is split on shell separators
+ * that join a path to other lexemes — whitespace, `=`, `,`, parentheses, backtick — so a path
+ * embedded in a compound token (a `--flag=path`, an opaque command substitution, an eval's
+ * quoted argument) surfaces as its own candidate while a standalone token stays intact (so the
+ * segment-boundary trap still rejects a sibling like `core/src-generated`). `/` is never a
+ * separator (it is the path's own segment boundary); `:` is deliberately NOT a separator
+ * either — splitting on it shatters URLs (`https://…`) into fragments that the offset-free
+ * descendant match then over-blocks, and a colon-joined path list is already reached by the
+ * contiguous-run match without the split.
+ */
+export declare function pathCandidates(token: string): string[];
+/**
+ * Extract path candidates from a whole command line the tokenizer REFUSED — the fallback-only
+ * counterpart of {@link pathCandidates}.
+ *
+ * The precondition is the opposite one. On the tokenized path an operator between two words
+ * has already become a word boundary, so `pathCandidates`' separator set never needed the
+ * operators themselves. A fallback branch has no tokenizer left and gets the raw line, where
+ * nothing consumed them and a path glued to one (`packages/core/dist;echo x`) stayed a single
+ * unmatchable segment — so the set here is wider by exactly what the tokenizer would have
+ * eaten: `;` `&` `|` `<` `>`.
+ *
+ * The line itself stays a candidate alongside the fragments, so a protected path whose own
+ * segment carries an operator (`pkg/a&b/dist`) is still matchable; an added form can only add
+ * a match, never withdraw one. `:` stays out for the reason {@link pathCandidates} records.
+ *
+ * Widening a fragment boundary widens the ancestor direction with it: `…?x=1&packages=1`
+ * splits to a bare `packages`, which `segmentsMatch` accepts as a root-anchored ancestor of a
+ * protected `packages/core/dist`. That over-block is accepted rather than narrowed — the
+ * narrowing that would spare it also drops a glued ancestor destroy
+ * (`rm -rf packages/core;echo x`), which is the defence this fallback exists to provide.
+ */
+export declare function untokenizableLineCandidates(line: string): string[];
+/**
+ * True when `predicate` holds for any string value inside `value`, at any depth.
+ *
+ * Arrays and plain objects are walked by value; keys are never scanned, and non-string
+ * primitives never match. Short-circuits on the first hit — the walk answers an existence
+ * question, so a caller that needs every match wants its own traversal.
+ */
+export declare function someStringValue(value: unknown, predicate: (text: string) => boolean): boolean;
+/**
+ * Recursively test whether any string value inside `value` matches `path` by path-segment
+ * containment (ancestor / descendant / equal). Each string is split into path candidates,
+ * each tested via {@link pathMatchesProtected}. Only string values are scanned; keys,
+ * numbers, and other primitives never match.
+ */
+export declare function mentionsPath(value: unknown, path: string): boolean;