polydeukes 0.6.1 → 0.8.0

package/dist/covenant/mention.js

@@ -0,0 +1,209 @@
+/**
+ * `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 function pathSegments(path) {
+    return path
+        .replace(/^(\.\/)+/, '')
+        .replace(/\/+$/, '')
+        .split('/')
+        .filter((segment) => segment !== '');
+}
+/**
+ * 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 function provenChangePath(call) {
+    const evidence = call.fileChange;
+    if (typeof evidence !== 'object' || evidence === null)
+        return null;
+    const { kind, path } = evidence;
+    if (typeof path !== 'string')
+        return null;
+    // Core `parseInput` validates the collection shapes, not the element ones, so evidence
+    // is usable only when it could prove a target: a recognized discriminant and a path that
+    // carries segments to judge. A one-field stub, a bogus kind, or a degenerate path (`''`,
+    // `'.'`, `'/'` — zero segments) proves nothing and must fall through rather than be
+    // dereferenced or, worse, suppress the fallback — the evidence branch upholding on proof
+    // it never had is a fail-open, and an exported pure judge that throws is a bypass vector.
+    // `pathSegments` keeps a lone `.` as a segment, so require one that names a file.
+    if (!pathSegments(path).some((segment) => segment !== '.'))
+        return null;
+    return kind === 'create' || kind === 'modify' || kind === 'delete' ? path : null;
+}
+/** True iff `needle` occurs as a contiguous segment run inside `haystack` (any offset). */
+function containsSegmentRun(haystack, needle) {
+    if (needle.length === 0 || needle.length > haystack.length)
+        return false;
+    for (let start = 0; start + needle.length <= haystack.length; start++) {
+        if (needle.every((segment, i) => segment === haystack[start + i]))
+            return true;
+    }
+    return false;
+}
+/**
+ * One comparison, shared by both passes. The two directions are deliberately asymmetric:
+ *  - descendant / equal: the protected segments appear as a contiguous run at ANY offset in
+ *    the candidate, so an ABSOLUTE `file_path` (`/home/u/proj/core/src/x` — the real Edit
+ *    payload shape) matches the relative protected `core/src`;
+ *  - ancestor: the WHOLE candidate is a root-anchored prefix of the protected path, so the
+ *    relative parent op `rm -rf packages/core` matches but an unrelated `vendor/packages`
+ *    whose tail merely coincides with the protected head does NOT.
+ * The asymmetry is load-bearing: allowing any candidate *suffix* to head the protected path
+ * would block legitimate unrelated dirs (`x/packages/core`). The cost is that an ABSOLUTE
+ * ancestor path (`rm -rf /abs/.../packages/core`) is not caught — an accepted non-goal
+ * (complete Bash lockdown was never the goal; the relative form is still caught, and the
+ * over-block alternative is worse). The segment boundary is exact, so `core/src-generated`
+ * never matches `core/src`.
+ */
+function segmentsMatch(a, b) {
+    if (a.length === 0)
+        return false;
+    if (containsSegmentRun(a, b))
+        return true;
+    // Ancestor: the candidate is a proper root-anchored prefix of the protected path.
+    return a.length < b.length && a.every((segment, i) => segment === b[i]);
+}
+/**
+ * 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 function resolveDotSegments(segments) {
+    const resolved = [];
+    for (const segment of segments) {
+        if (segment === '.')
+            continue;
+        if (segment === '..' && resolved.length > 0 && resolved[resolved.length - 1] !== '..') {
+            resolved.pop();
+            continue;
+        }
+        resolved.push(segment);
+    }
+    return resolved;
+}
+/**
+ * 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 function pathMatchesProtected(candidate, protectedPath) {
+    const a = pathSegments(candidate);
+    const b = pathSegments(protectedPath);
+    if (b.length === 0)
+        return false;
+    if (segmentsMatch(a, b))
+        return true;
+    return segmentsMatch(resolveDotSegments(a), b);
+}
+/**
+ * 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 function pathCandidates(token) {
+    return token.split(/[\s=,()`]+/).filter((fragment) => fragment !== '');
+}
+/**
+ * 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 function untokenizableLineCandidates(line) {
+    const fragments = line.split(/[;&|<>]+/).filter((f) => f !== '' && f !== line);
+    return [line, ...fragments];
+}
+/**
+ * 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 function someStringValue(value, predicate) {
+    if (typeof value === 'string') {
+        return predicate(value);
+    }
+    if (Array.isArray(value)) {
+        return value.some((item) => someStringValue(item, predicate));
+    }
+    if (typeof value === 'object' && value !== null) {
+        return Object.values(value).some((item) => someStringValue(item, predicate));
+    }
+    return false;
+}
+/**
+ * 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 function mentionsPath(value, path) {
+    return someStringValue(value, (text) => pathCandidates(text).some((candidate) => pathMatchesProtected(candidate, path)));
+}

package/dist/covenant/module.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The judge as the composition roots see it: the seven verbs they call, gathered in one
+ * object. A test replaces one member of it; the roots default to the real seven.
+ *
+ * A leaf module on purpose — it imports the judge and nothing else, so the session subpath
+ * that loads it does not also load the change-set surface's translator and reader.
+ */
+import { compileDisciplineRegistrations } from './discipline.ts';
+import { dispatchCovenants } from './dispatch.ts';
+import { selfModRegistration } from './self-mod.ts';
+import { shellModRegistration } from './shell-mod.ts';
+import { planSources, supplySources } from './supply.ts';
+import { transcriptModRegistration } from './transcript-mod.ts';
+/** The judge verbs the composition roots call — the seam a test replaces one member of. */
+export type CovenantModule = {
+    dispatchCovenants: typeof dispatchCovenants;
+    compileDisciplineRegistrations: typeof compileDisciplineRegistrations;
+    selfModRegistration: typeof selfModRegistration;
+    shellModRegistration: typeof shellModRegistration;
+    transcriptModRegistration: typeof transcriptModRegistration;
+    planSources: typeof planSources;
+    supplySources: typeof supplySources;
+};
+/** The real seven — what judges a call unless a test injects a replacement. */
+export declare const covenantModule: CovenantModule;

package/dist/covenant/module.js

@@ -0,0 +1,23 @@
+/**
+ * The judge as the composition roots see it: the seven verbs they call, gathered in one
+ * object. A test replaces one member of it; the roots default to the real seven.
+ *
+ * A leaf module on purpose — it imports the judge and nothing else, so the session subpath
+ * that loads it does not also load the change-set surface's translator and reader.
+ */
+import { compileDisciplineRegistrations } from './discipline.js';
+import { dispatchCovenants } from './dispatch.js';
+import { selfModRegistration } from './self-mod.js';
+import { shellModRegistration } from './shell-mod.js';
+import { planSources, supplySources } from './supply.js';
+import { transcriptModRegistration } from './transcript-mod.js';
+/** The real seven — what judges a call unless a test injects a replacement. */
+export const covenantModule = {
+    dispatchCovenants,
+    compileDisciplineRegistrations,
+    selfModRegistration,
+    shellModRegistration,
+    transcriptModRegistration,
+    planSources,
+    supplySources,
+};

package/dist/covenant/mutation-rules.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Detection rules for the mutation-rule seam.
+ *
+ * Pure functions only — each rule is `SimpleCommand → MutationTarget[]`, nothing more.
+ * Every rule stays silent on opaque tokens: an unknowable value is never reported as a
+ * confident path. The tokenizer already marks such commands indeterminate, so the
+ * fail-closed signal survives the silence. Protected-path matching, blocking, allowlists,
+ * and telemetry belong to the judges that consume these rules.
+ */
+import type { MutationRule, WordToken } from './bash-line.ts';
+/** The final path segment of a command word (`/usr/bin/tee` → `tee`). */
+export declare function commandBasename(word: WordToken): string;
+/**
+ * True when a `>&`-family target is an fd reference: all digits, `-` (close), or the
+ * digits+`-` move-fd form (`2>&1-` moves fd 1, touching no file). Exported as the SSOT
+ * of that boundary — the shell-evidence derivation consults the same judgment.
+ */
+export declare function isFdReference(text: string): boolean;
+/**
+ * Reports the target path of every write-direction redirect (any operator containing `>`).
+ * Read redirects (`<`) and fd duplication (`2>&1`, `>&-`) are excluded; a csh-style
+ * `>& file` whose target is not an fd reference is still a write.
+ */
+export declare const redirectWriteRule: MutationRule;
+/**
+ * Reports every non-flag argument of a `tee` command (first-word basename match, so
+ * `/usr/bin/tee` fires too). Flags are skipped until the `--` end-of-options marker;
+ * after it, `-`-prefixed words are paths. Wrapper commands (`sudo tee`) never fire —
+ * the judges' path-mention backstop covers them.
+ */
+export declare const teeRule: MutationRule;
+/**
+ * Reports the file operands of an in-place `sed` (first-word basename match, so
+ * `/usr/bin/sed` fires too). Without an in-place flag sed writes to stdout — silence.
+ * The `-e`/`-f` family is skipped with its value (the `-f` script file is read, not
+ * written); when no such flag is present the first positional operand is the sed script
+ * — skipped even after `--`. Wrapper commands (`sudo sed`) never fire — the judges'
+ * path-mention backstop covers them.
+ */
+export declare const sedInPlaceRule: MutationRule;

package/dist/covenant/mutation-rules.js

@@ -0,0 +1,146 @@
+/**
+ * Detection rules for the mutation-rule seam.
+ *
+ * Pure functions only — each rule is `SimpleCommand → MutationTarget[]`, nothing more.
+ * Every rule stays silent on opaque tokens: an unknowable value is never reported as a
+ * confident path. The tokenizer already marks such commands indeterminate, so the
+ * fail-closed signal survives the silence. Protected-path matching, blocking, allowlists,
+ * and telemetry belong to the judges that consume these rules.
+ */
+const REDIRECT_WRITE_RULE_NAME = 'redirect-write';
+const TEE_RULE_NAME = 'tee';
+const SED_IN_PLACE_RULE_NAME = 'sed-in-place';
+/** The final path segment of a command word (`/usr/bin/tee` → `tee`). */
+export function commandBasename(word) {
+    return word.text.slice(word.text.lastIndexOf('/') + 1);
+}
+/**
+ * True when a `>&`-family target is an fd reference: all digits, `-` (close), or the
+ * digits+`-` move-fd form (`2>&1-` moves fd 1, touching no file). Exported as the SSOT
+ * of that boundary — the shell-evidence derivation consults the same judgment.
+ */
+export function isFdReference(text) {
+    return text === '-' || /^[0-9]+-?$/.test(text);
+}
+/**
+ * Reports the target path of every write-direction redirect (any operator containing `>`).
+ * Read redirects (`<`) and fd duplication (`2>&1`, `>&-`) are excluded; a csh-style
+ * `>& file` whose target is not an fd reference is still a write.
+ */
+export const redirectWriteRule = {
+    name: REDIRECT_WRITE_RULE_NAME,
+    detect(command) {
+        const targets = [];
+        for (const redirect of command.redirects) {
+            if (!redirect.operator.includes('>'))
+                continue;
+            if (redirect.operator.endsWith('>&') && isFdReference(redirect.target.text))
+                continue;
+            if (redirect.target.opaque)
+                continue;
+            targets.push({ path: redirect.target.text, rule: REDIRECT_WRITE_RULE_NAME });
+        }
+        return targets;
+    },
+};
+/**
+ * Reports every non-flag argument of a `tee` command (first-word basename match, so
+ * `/usr/bin/tee` fires too). Flags are skipped until the `--` end-of-options marker;
+ * after it, `-`-prefixed words are paths. Wrapper commands (`sudo tee`) never fire —
+ * the judges' path-mention backstop covers them.
+ */
+export const teeRule = {
+    name: TEE_RULE_NAME,
+    detect(command) {
+        const first = command.words[0];
+        if (first === undefined || first.opaque)
+            return [];
+        if (commandBasename(first) !== 'tee')
+            return [];
+        const targets = [];
+        let optionsEnded = false;
+        for (const word of command.words.slice(1)) {
+            if (!optionsEnded) {
+                if (word.text === '--') {
+                    optionsEnded = true;
+                    continue;
+                }
+                // A lone `-` is a file operand, not a flag — GNU tee writes a literal `-` file.
+                if (word.text.startsWith('-') && word.text !== '-')
+                    continue;
+            }
+            if (word.opaque)
+                continue;
+            targets.push({ path: word.text, rule: TEE_RULE_NAME });
+        }
+        return targets;
+    },
+};
+/** True for any in-place flag form: `-i`, `-i<suffix>`, `--in-place`, `--in-place=<suffix>`. */
+function isInPlaceFlag(text) {
+    return text.startsWith('-i') || text === '--in-place' || text.startsWith('--in-place=');
+}
+// The script-flag forms whose value arrives in the NEXT word. isScriptFlag must cover
+// every flag listed here, or `scriptSkipped` mis-seeds and the wrong operand is dropped.
+const SEPARATED_SCRIPT_FLAGS = ['-e', '-f', '--expression', '--file'];
+/** True for any script-supplying flag form (`-e`/`-f` family) — its value is never a file. */
+function isScriptFlag(text) {
+    return (SEPARATED_SCRIPT_FLAGS.includes(text) ||
+        text.startsWith('-e') ||
+        text.startsWith('-f') ||
+        text.startsWith('--expression=') ||
+        text.startsWith('--file='));
+}
+/**
+ * Reports the file operands of an in-place `sed` (first-word basename match, so
+ * `/usr/bin/sed` fires too). Without an in-place flag sed writes to stdout — silence.
+ * The `-e`/`-f` family is skipped with its value (the `-f` script file is read, not
+ * written); when no such flag is present the first positional operand is the sed script
+ * — skipped even after `--`. Wrapper commands (`sudo sed`) never fire — the judges'
+ * path-mention backstop covers them.
+ */
+export const sedInPlaceRule = {
+    name: SED_IN_PLACE_RULE_NAME,
+    detect(command) {
+        const first = command.words[0];
+        if (first === undefined || first.opaque)
+            return [];
+        if (commandBasename(first) !== 'sed')
+            return [];
+        const args = command.words.slice(1);
+        if (!args.some((word) => isInPlaceFlag(word.text)))
+            return [];
+        const targets = [];
+        let optionsEnded = false;
+        let skipNext = false;
+        // With no script flag anywhere, the first positional operand is the script itself.
+        let scriptSkipped = args.some((word) => isScriptFlag(word.text));
+        for (const word of args) {
+            if (skipNext) {
+                skipNext = false;
+                continue;
+            }
+            if (!optionsEnded) {
+                if (word.text === '--') {
+                    optionsEnded = true;
+                    continue;
+                }
+                // A lone `-` is an operand, not a flag — same boundary as the tee rule.
+                if (word.text.startsWith('-') && word.text !== '-') {
+                    // The separated flag forms carry their value in the NEXT word — skip it too.
+                    if (SEPARATED_SCRIPT_FLAGS.includes(word.text))
+                        skipNext = true;
+                    continue;
+                }
+            }
+            if (!scriptSkipped) {
+                scriptSkipped = true;
+                continue;
+            }
+            if (word.opaque)
+                continue;
+            targets.push({ path: word.text, rule: SED_IN_PLACE_RULE_NAME });
+        }
+        return targets;
+    },
+};

package/dist/covenant/relations.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The seven relations, each answering a witness list rather than a boolean: an empty list
+ * means the relation holds, and every other list names the elements that broke it, in the
+ * order the extraction supplied them. No relation sorts or deduplicates, because the two
+ * surfaces that read a judgment agree on the witness order only if it is the input's.
+ *
+ * `empty`, `subset` and `ordered` are written directly; the other four are expansions over
+ * them — `nonEmpty` is the negation of `empty`, `equal` is `subset` in both directions,
+ * `implies` is `subset` of the two key projections, and `unchanged` is `equal` over the keys
+ * the two states share.
+ */
+import { type Items } from './extract-steps.ts';
+/** One element for which a relation does not hold; `side` is `equal`'s two directions. */
+export type Witness = {
+    readonly key: string;
+    readonly value: unknown;
+    readonly side?: 'left' | 'right';
+};
+/** The pre value behind an `unchanged` witness, for the message that reports the change. */
+export type WitnessWithBefore = Witness & {
+    readonly before?: unknown;
+};
+/** Every item is a witness: the relation asked for none. */
+export declare function relateEmpty(of: Items): readonly Witness[];
+/**
+ * The negation of `empty`. Emptiness itself is the witness, so the one witness names the
+ * extraction rather than an element — there is no element to name.
+ */
+export declare function relateNonEmpty(of: Items, extractName: string): readonly Witness[];
+/** The `of` items whose value occurs nowhere in `in`, in `of` order, duplicates kept. */
+export declare function relateSubset(of: Items, inItems: Items): readonly Witness[];
+/** `subset` both ways: the left-only items first, then the right-only ones. */
+export declare function relateEqual(left: Items, right: Items): readonly Witness[];
+/** `subset` of the key projections: the `of` items whose key `requires` does not carry. */
+export declare function relateImplies(of: Items, requires: Items): readonly Witness[];
+/**
+ * Adjacent pairs rise; `strict` forbids equal neighbours. The witness is the later item of
+ * each pair that breaks it, so a caller reading the first witness sees where the sequence
+ * turned — an ordering reduced to a sort would answer only whether it held.
+ */
+export declare function relateOrdered(of: Items, strict: boolean): readonly Witness[];
+/**
+ * `equal` over the shared keys: the post item of every key both states carry whose value
+ * changed. A key only one side has is an addition or a removal, not a change.
+ */
+export declare function relateUnchanged(pre: Items, post: Items): readonly WitnessWithBefore[];

package/dist/covenant/relations.js

@@ -0,0 +1,68 @@
+/**
+ * The seven relations, each answering a witness list rather than a boolean: an empty list
+ * means the relation holds, and every other list names the elements that broke it, in the
+ * order the extraction supplied them. No relation sorts or deduplicates, because the two
+ * surfaces that read a judgment agree on the witness order only if it is the input's.
+ *
+ * `empty`, `subset` and `ordered` are written directly; the other four are expansions over
+ * them — `nonEmpty` is the negation of `empty`, `equal` is `subset` in both directions,
+ * `implies` is `subset` of the two key projections, and `unchanged` is `equal` over the keys
+ * the two states share.
+ */
+import { canonical, comparatorFor, sameValue } from './extract-steps.js';
+/** Every item is a witness: the relation asked for none. */
+export function relateEmpty(of) {
+    return of.map(({ key, value }) => ({ key, value }));
+}
+/**
+ * The negation of `empty`. Emptiness itself is the witness, so the one witness names the
+ * extraction rather than an element — there is no element to name.
+ */
+export function relateNonEmpty(of, extractName) {
+    return of.length === 0 ? [{ key: extractName, value: null }] : [];
+}
+/** The `of` items whose value occurs nowhere in `in`, in `of` order, duplicates kept. */
+export function relateSubset(of, inItems) {
+    const present = new Set(inItems.map((item) => canonical(item.value)));
+    return of
+        .filter((item) => !present.has(canonical(item.value)))
+        .map(({ key, value }) => ({ key, value }));
+}
+/** `subset` both ways: the left-only items first, then the right-only ones. */
+export function relateEqual(left, right) {
+    return [
+        ...relateSubset(left, right).map((witness) => ({ ...witness, side: 'left' })),
+        ...relateSubset(right, left).map((witness) => ({ ...witness, side: 'right' })),
+    ];
+}
+/** `subset` of the key projections: the `of` items whose key `requires` does not carry. */
+export function relateImplies(of, requires) {
+    const keys = new Set(requires.map((item) => item.key));
+    return of.filter((item) => !keys.has(item.key)).map(({ key, value }) => ({ key, value }));
+}
+/**
+ * Adjacent pairs rise; `strict` forbids equal neighbours. The witness is the later item of
+ * each pair that breaks it, so a caller reading the first witness sees where the sequence
+ * turned — an ordering reduced to a sort would answer only whether it held.
+ */
+export function relateOrdered(of, strict) {
+    const witnesses = [];
+    const compare = comparatorFor(of);
+    for (let index = 1; index < of.length; index += 1) {
+        const order = compare(of[index - 1], of[index]);
+        if (order > 0 || (strict && order === 0)) {
+            witnesses.push({ key: of[index].key, value: of[index].value });
+        }
+    }
+    return witnesses;
+}
+/**
+ * `equal` over the shared keys: the post item of every key both states carry whose value
+ * changed. A key only one side has is an addition or a removal, not a change.
+ */
+export function relateUnchanged(pre, post) {
+    const before = new Map(pre.map((item) => [item.key, item.value]));
+    return post
+        .filter((item) => before.has(item.key) && !sameValue(before.get(item.key), item.value))
+        .map((item) => ({ key: item.key, value: item.value, before: before.get(item.key) }));
+}

package/dist/covenant/run-covenant.d.ts

@@ -0,0 +1,95 @@
+/**
+ * `runCovenant` — the covenant execution wrapper.
+ *
+ * Calls an in-process judge thunk the assembly has already bound its payload and options
+ * into, translates the thunk's exit-code equivalent by policy (1 → blocking 2), writes the
+ * break reason to stderr, and appends exactly one telemetry record per call via
+ * {@link appendRecordFailOpen} (the core's fail-open wrapper around its sole collector —
+ * no local logger). {@link translateExitCode} is pure.
+ */
+import { type CovenantVerdict, type EnforceLevel, EXIT_BREAK_BLOCKING, EXIT_UPHOLD, type SkipReason, type TelemetryEvent } from '@polydeukes/core';
+import type { Break } from './declaration-engine.ts';
+/** The wrapper's final verdict — `1` never escapes: a break becomes the blocking `2`. */
+type WrapperExitCode = typeof EXIT_UPHOLD | typeof EXIT_BREAK_BLOCKING;
+/**
+ * What a judge thunk answers: `0` uphold, `1` break, `2` unjudgeable, and `reason` naming
+ * the break for the agent that has to read it. `witnesses` carries the elements a
+ * declaration's break was found on; the body answers with values and the wrapper turns
+ * them into the row's fifth field.
+ *
+ * `skipped` is the body's own report that it evaluated no relation — exit 0 without a
+ * judgment. It is recorded as a `skipped` row carrying that token rather than as `passed`,
+ * which would read as a covenant upheld.
+ */
+export type JudgeOutcome = {
+    exitCode: number;
+    reason?: string;
+    witnesses?: readonly Break[];
+    skipped?: SkipReason;
+};
+/**
+ * `runCovenant` specification.
+ *
+ * `body` is an in-process judge thunk with the payload and its options already bound by
+ * the assembly; it is the only judgment this wrapper performs. `subject` defaults to the
+ * `-` sentinel in telemetry when absent. `telemetryPath` is always an explicit argument.
+ * `enforce` selects the translation column: absent defaults to `block`. `witness` is the
+ * valve axis — a zero-arg thunk whose arguments the caller has already bound, consulted
+ * only once the body has run and its outcome translated to `blocked`.
+ */
+export type RunCovenantSpec = {
+    body: () => Promise<JudgeOutcome>;
+    label: string;
+    subject?: string;
+    telemetryPath: string;
+    enforce?: EnforceLevel;
+    witness?: () => boolean;
+};
+/**
+ * Translate a body outcome into the wrapper verdict and telemetry event (pure).
+ *
+ * `bodyExitCode === 0` (uphold) passes; every other outcome — a break report (`1`), the
+ * body's own fail-closed (`2`), any uninterpretable code (`3+`), or a body that answered
+ * nothing interpretable (`null`) — is fail-closed to the blocking `2` / `blocked`. The
+ * unconditional 1→2 translation lives here, isolated, so it has one place to evolve in.
+ *
+ * `enforce` relaxes ONLY the verdict cell: under `advise` a break report (`1`) becomes
+ * `0` / `advised` — recorded, not blocking. Every unjudgeable outcome (`2`, `3+`, `null`)
+ * stays `2` / `blocked` regardless of level.
+ */
+export declare function translateExitCode(bodyExitCode: number | null, enforce?: EnforceLevel): {
+    exitCode: WrapperExitCode;
+    event: TelemetryEvent;
+};
+/** Turn a pure judge's verdict into the outcome a thunk answers. */
+export declare function outcomeFromVerdict(verdict: CovenantVerdict): JudgeOutcome;
+/** The unjudgeable outcome: a misassembly or an input no judge could read (`2`, no reason). */
+export declare const UNJUDGEABLE_OUTCOME: JudgeOutcome;
+/** What one wrapped judgment answers — the final exit code and the telemetry event recorded. */
+export type RunCovenantVerdict = {
+    exitCode: typeof EXIT_UPHOLD | typeof EXIT_BREAK_BLOCKING;
+    event: TelemetryEvent;
+};
+/**
+ * Run a covenant body through the wrapper.
+ *
+ * The order is judge → translate → valve: the body always runs, and only a `blocked`
+ * translation has anything for the valve to relax into `0` / `witnessed`. Whatever that
+ * leaves is recorded ONCE — one call, one row — so a witnessed break never leaves a
+ * `blocked` row beside its `witnessed` one.
+ *
+ * The break reason goes to stderr whenever the thunk carried one, whatever the level and
+ * whatever the final event: gating it on the verdict would leave `advised` mute and the
+ * valve silent about what it opened.
+ *
+ * A body that answers `skipped` evaluated no relation, so it never reaches the translation
+ * table or the valve: the row says so and the call upholds.
+ *
+ * Resolves with the wrapper's final `exitCode` (`0` or `2`) and the telemetry `event` that
+ * was recorded. The event is surfaced rather than left to callers: the valve is impure, so
+ * recomputing the event would consult it a second time. Logging is fail-open
+ * via {@link appendRecordFailOpen}: a telemetry failure never alters the verdict and never
+ * throws. The gate closes; the measurement stays open.
+ */
+export declare function runCovenant(spec: RunCovenantSpec): Promise<RunCovenantVerdict>;
+export {};