polydeukes 0.6.0 → 0.7.1

package/dist/covenant/declaration-engine.js

@@ -0,0 +1,415 @@
+/**
+ * The declaration engine — `judge = relate ∘ extract` as a pure function of one `World`.
+ *
+ * `compileDeclaration` resolves a shape-validated declaration against the extract registry
+ * and answers either something judgeable or a config fault naming where the declaration is
+ * wrong; it never throws. `judgeDeclaration` then runs the extraction pipelines over a
+ * world value and evaluates the relations, answering a verdict. `witnessOpens` evaluates
+ * the witness block on its own, so a caller can let a satisfied condition stand after the
+ * verdict without re-reading it.
+ *
+ * The engine knows nothing but its two arguments: no files, no tools, no session. Whatever
+ * a host can express as named values in a `World` it can judge here.
+ */
+import { BINARY_COMBINATOR_NAMES } from '@polydeukes/core';
+import { EXTRACT_STEPS, fault, SupplyFailure, UNARY_STEP_NAMES, } from './extract-steps.js';
+import { relateEmpty, relateEqual, relateImplies, relateNonEmpty, relateOrdered, relateSubset, relateUnchanged, } from './relations.js';
+export { EXTRACT_STEPS, UNARY_STEP_NAMES } from './extract-steps.js';
+/** The world name a paired source reads: its value is `{ pre, post }`, one state each. */
+const PAIRED_SOURCE = 'state';
+function isFault(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.kind === 'config-fault');
+}
+function isCombinator(step) {
+    return BINARY_COMBINATOR_NAMES.includes(step.op);
+}
+function combinatorReferences(step) {
+    return step.op === 'onlyIn' ? [step.of, step.notIn] : step.of;
+}
+/** Resolve one pipeline's steps against the registry, answering the fault of the first bad one. */
+function compilePipeline(name, steps, location) {
+    const [first, ...rest] = steps;
+    if (first === undefined || (!isCombinator(first) && first.op !== 'source')) {
+        const found = first === undefined ? 'an empty pipeline' : `'${first.op}'`;
+        return fault(location, `a pipeline begins with 'source' or one of ${BINARY_COMBINATOR_NAMES.join(', ')} — found ${found}`);
+    }
+    const combinator = isCombinator(first) ? first : undefined;
+    const unarySteps = combinator === undefined ? steps : rest;
+    for (const step of unarySteps) {
+        const entry = EXTRACT_STEPS[step.op];
+        if (entry === undefined) {
+            return fault(location, `'${step.op}' is not a registered extract step — the registry carries ${UNARY_STEP_NAMES.join(', ')}`);
+        }
+        const bad = entry.validate(step, location);
+        if (bad !== undefined)
+            return bad;
+    }
+    const paired = combinator === undefined && first.op === 'source' && first.of === PAIRED_SOURCE;
+    return {
+        name,
+        paired,
+        references: combinator === undefined ? [] : combinatorReferences(combinator),
+        combinator,
+        steps: unarySteps,
+    };
+}
+function compileExtract(extract, known, location) {
+    const added = [];
+    for (const [name, steps] of Object.entries(extract)) {
+        const compiled = compilePipeline(name, steps, `${location} ${name}`);
+        if (isFault(compiled))
+            return compiled;
+        known.set(name, compiled);
+        added.push(compiled);
+    }
+    for (const pipeline of added) {
+        for (const reference of pipeline.references) {
+            if (known.get(reference)?.paired === true) {
+                return fault(`${location} ${pipeline.name}`, `'${pipeline.name}' combines '${reference}', which reads a before/after pair — a combinator takes single extractions`);
+            }
+        }
+    }
+    return undefined;
+}
+/** The extract names a relation reads, and whether it takes a paired extraction. */
+function relationReferences(relation) {
+    if (relation.op === 'equal')
+        return relation.of;
+    if (relation.op === 'subset')
+        return [relation.of, relation.in];
+    if (relation.op === 'implies')
+        return [relation.of, relation.requires];
+    return [relation.of];
+}
+function checkRelateShapes(relate, pipelines, location) {
+    for (const entry of relate) {
+        const wantsPair = entry.relation.op === 'unchanged';
+        for (const name of relationReferences(entry.relation)) {
+            const pipeline = pipelines.get(name);
+            if (pipeline === undefined) {
+                return fault(`${location} '${entry.id}'`, `'${entry.relation.op}' references '${name}', which no extract in scope defines`);
+            }
+            const paired = pipeline.paired;
+            if (paired === wantsPair)
+                continue;
+            return fault(`${location} '${entry.id}'`, wantsPair
+                ? `'unchanged' compares a before/after pair, and '${name}' reads a single state`
+                : `'${entry.relation.op}' takes a single extraction, and '${name}' reads a before/after pair`);
+        }
+    }
+    return undefined;
+}
+function compileRegexList(patterns, flags, location) {
+    const compiled = [];
+    for (const pattern of patterns ?? []) {
+        try {
+            compiled.push(new RegExp(pattern, flags));
+        }
+        catch {
+            return fault(location, `cannot compile the expression '${pattern}'`);
+        }
+    }
+    return compiled;
+}
+/**
+ * Resolve a shape-validated declaration into something judgeable, or answer the first thing
+ * wrong with it: a step outside the registry, an argument outside a step's closed keys, an
+ * uncompilable expression, or a paired extraction where a single one belongs.
+ */
+export function compileDeclaration(spec) {
+    const decl = spec.declaration;
+    const pipelines = new Map();
+    const extractFault = compileExtract(decl.extract, pipelines, `${decl.discipline} extract`);
+    if (extractFault !== undefined)
+        return extractFault;
+    const relateFault = checkRelateShapes(decl.relate, pipelines, `${decl.discipline} relate`);
+    if (relateFault !== undefined)
+        return relateFault;
+    let scope;
+    if (decl.scope !== undefined) {
+        const where = `${decl.discipline} scope`;
+        const include = compileRegexList(decl.scope.include, '', where);
+        if (isFault(include))
+            return include;
+        const exclude = compileRegexList(decl.scope.exclude, decl.scope.excludeIgnoreCase === true ? 'i' : '', where);
+        if (isFault(exclude))
+            return exclude;
+        scope = { source: decl.scope.source, include, exclude };
+    }
+    const witness = compileWitness(decl.witness, pipelines, decl.discipline);
+    if (isFault(witness))
+        return witness;
+    return { pipelines, relate: decl.relate, supply: decl.supply ?? {}, scope, witness };
+}
+function compileWitness(block, bodyPipelines, discipline) {
+    if (block === undefined)
+        return undefined;
+    const pipelines = new Map(bodyPipelines);
+    if (block.extract !== undefined) {
+        const bad = compileExtract(block.extract, pipelines, `${discipline} witness.extract`);
+        if (bad !== undefined)
+            return bad;
+    }
+    const relateFault = checkRelateShapes(block.relate, pipelines, `${discipline} witness relate`);
+    if (relateFault !== undefined)
+        return relateFault;
+    return { pipelines, relate: block.relate };
+}
+class Extractor {
+    pipelines;
+    supply;
+    world;
+    cache = new Map();
+    problem;
+    constructor(pipelines, supply, world) {
+        this.pipelines = pipelines;
+        this.supply = supply;
+        this.world = world;
+    }
+    /** The pipeline's items, or `undefined` once a supply problem has ended the judgment. */
+    resolve(name) {
+        if (this.problem !== undefined)
+            return undefined;
+        const cached = this.cache.get(name);
+        if (cached !== undefined)
+            return cached;
+        const pipeline = this.pipelines.get(name);
+        if (pipeline === undefined)
+            return undefined;
+        const result = pipeline.paired ? this.runPaired(pipeline) : this.runSingle(pipeline);
+        if (result === undefined)
+            return undefined;
+        this.cache.set(name, result);
+        return result;
+    }
+    runPaired(pipeline) {
+        if (!(PAIRED_SOURCE in this.world)) {
+            this.problem = this.absent(PAIRED_SOURCE);
+            return undefined;
+        }
+        const state = this.world[PAIRED_SOURCE];
+        if (typeof state !== 'object' ||
+            state === null ||
+            Array.isArray(state) ||
+            !('pre' in state) ||
+            !('post' in state)) {
+            this.problem = {
+                kind: 'error',
+                source: PAIRED_SOURCE,
+                reason: `'${PAIRED_SOURCE}' must be a before/after pair — an object carrying 'pre' and 'post'`,
+            };
+            return undefined;
+        }
+        const sides = state;
+        const pre = this.runSteps(pipeline, sides.pre, PAIRED_SOURCE);
+        if (pre === undefined)
+            return undefined;
+        const post = this.runSteps(pipeline, sides.post, PAIRED_SOURCE);
+        if (post === undefined)
+            return undefined;
+        return { pair: { pre, post } };
+    }
+    /**
+     * A pipeline reading one world value, or a combinator joining two other extractions —
+     * the two ways a pipeline can begin.
+     */
+    runSingle(pipeline) {
+        const combinator = pipeline.combinator;
+        if (combinator !== undefined) {
+            const [leftName, rightName] = combinatorReferences(combinator);
+            const left = this.resolve(leftName)?.single;
+            const right = this.resolve(rightName)?.single;
+            if (left === undefined || right === undefined)
+                return undefined;
+            const items = this.runStepList(pipeline.steps, combine(combinator, left, right), pipeline.name);
+            return items === undefined ? undefined : { single: items };
+        }
+        const source = sourceName(pipeline);
+        if (!(source in this.world)) {
+            // `empty` is the one policy that continues the judgment: the absence becomes an empty
+            // item list, and what that means for the verdict is the pipeline's own arithmetic.
+            if (this.supply[source] === 'empty')
+                return { single: [] };
+            this.problem = this.absent(source);
+            return undefined;
+        }
+        const items = this.runSteps(pipeline, this.world[source], source);
+        return items === undefined ? undefined : { single: items };
+    }
+    /**
+     * What an absent source means under the declaration's supply policy: skip, or fail. The
+     * paired source reaches only this, never the empty reading — config validation refuses
+     * `empty` there, and an absent pair is not a pair of empty states either way.
+     */
+    absent(source) {
+        return this.supply[source] === 'pass'
+            ? { kind: 'pass', source }
+            : { kind: 'error', source, reason: `the world carries no source named '${source}'` };
+    }
+    /** The steps after the source; the paired path re-enters here once per state. */
+    runSteps(pipeline, value, source) {
+        return this.runStepList(pipeline.steps.slice(1), [{ key: '0', value }], source);
+    }
+    runStepList(steps, items, source) {
+        let current = items;
+        for (const step of steps) {
+            try {
+                current = EXTRACT_STEPS[step.op].run(current, step);
+            }
+            catch (error) {
+                if (!(error instanceof SupplyFailure))
+                    throw error;
+                this.problem = { kind: 'error', source, reason: error.message };
+                return undefined;
+            }
+        }
+        return current;
+    }
+}
+/** The world name a source-headed pipeline reads. */
+function sourceName(pipeline) {
+    return String(pipeline.steps[0].of);
+}
+function combine(step, left, right) {
+    if (step.op === 'union')
+        return [...left, ...right];
+    const rightKeys = new Set(right.map((item) => item.key));
+    return step.op === 'onlyIn'
+        ? left.filter((item) => !rightKeys.has(item.key))
+        : left.filter((item) => rightKeys.has(item.key));
+}
+/** The paired path runs the whole pipeline over one state; the single path skips the source. */
+function evaluate(entry, extractor) {
+    const relation = entry.relation;
+    const items = (name) => extractor.resolve(name)?.single;
+    if (relation.op === 'unchanged') {
+        const pair = extractor.resolve(relation.of)?.pair;
+        return pair === undefined ? undefined : relateUnchanged(pair.pre, pair.post);
+    }
+    if (relation.op === 'equal') {
+        const left = items(relation.of[0]);
+        const right = items(relation.of[1]);
+        return left === undefined || right === undefined ? undefined : relateEqual(left, right);
+    }
+    if (relation.op === 'subset') {
+        const of = items(relation.of);
+        const inItems = items(relation.in);
+        return of === undefined || inItems === undefined ? undefined : relateSubset(of, inItems);
+    }
+    if (relation.op === 'implies') {
+        const of = items(relation.of);
+        const requires = items(relation.requires);
+        return of === undefined || requires === undefined ? undefined : relateImplies(of, requires);
+    }
+    const of = items(relation.of);
+    if (of === undefined)
+        return undefined;
+    if (relation.op === 'empty')
+        return relateEmpty(of);
+    if (relation.op === 'nonEmpty')
+        return relateNonEmpty(of, relation.of);
+    return relateOrdered(of, relation.strict === true);
+}
+/** The template of an entry, chosen by the side of the witness that will render it. */
+function templateFor(entry, witness) {
+    if ('message' in entry)
+        return entry.message;
+    return witness.side === 'right' ? entry.messageBySide.right : entry.messageBySide.left;
+}
+function renderText(value) {
+    return typeof value === 'string' ? value : String(value);
+}
+/**
+ * The break text: the first witness fills the template, and the witnesses beyond it are
+ * counted in a suffix rather than listed, so one break stays one line.
+ */
+function renderMessage(entry, witnesses) {
+    const first = witnesses[0];
+    const rendered = templateFor(entry, first)
+        .replaceAll('{key}', first.key)
+        .replaceAll('{value}', renderText(first.value))
+        .replaceAll('{before}', first.before === undefined ? '' : renderText(first.before));
+    return witnesses.length > 1 ? `${rendered} (+${witnesses.length - 1})` : rendered;
+}
+function stripBefore(witnesses) {
+    return witnesses.map(({ key, value, side }) => side === undefined ? { key, value } : { key, value, side });
+}
+/**
+ * Whether the declaration's scope admits this world. An absent scope admits every world, and
+ * an absent `include` admits every path the `exclude` list does not name.
+ */
+function inScope(scope, world) {
+    if (scope === undefined)
+        return true;
+    const target = world[scope.source];
+    if (typeof target !== 'string')
+        return false;
+    const included = scope.include.length === 0 || scope.include.some((p) => p.test(target));
+    return included && !scope.exclude.some((pattern) => pattern.test(target));
+}
+function verdictFor(problem) {
+    return problem.kind === 'pass'
+        ? { kind: 'not-applicable', reason: 'supply-pass', source: problem.source }
+        : { kind: 'supply-error', source: problem.source, reason: problem.reason };
+}
+/**
+ * Whether the declaration's scope admits this world — the routing question, asked without
+ * judging. A surface routes on the same predicate the judgment starts with, so a world it
+ * sends to the body is never one the body answers `not-applicable` for.
+ */
+export function scopeAdmits(compiled, world) {
+    return inScope(compiled.scope, world);
+}
+/**
+ * Judge one compiled declaration against one world.
+ *
+ * The scope decides first, so a declaration that does not apply never reads a source it
+ * would have failed on. Then every relate entry is evaluated in declaration order, one
+ * break per entry that does not hold. The first supply failure ends the judgment: a
+ * partially read world produces no partial verdict.
+ */
+export function judgeDeclaration(spec) {
+    const { compiled, world } = spec;
+    if (!inScope(compiled.scope, world))
+        return { kind: 'not-applicable', reason: 'scope' };
+    const extractor = new Extractor(compiled.pipelines, compiled.supply, world);
+    const breaks = [];
+    for (const entry of compiled.relate) {
+        const witnesses = evaluate(entry, extractor);
+        if (extractor.problem !== undefined)
+            return verdictFor(extractor.problem);
+        if (witnesses === undefined || witnesses.length === 0)
+            continue;
+        breaks.push({
+            id: entry.id,
+            message: renderMessage(entry, witnesses),
+            witnesses: stripBefore(witnesses),
+        });
+    }
+    return breaks.length === 0 ? { kind: 'pass' } : { kind: 'broken', breaks };
+}
+/**
+ * Whether the declaration's witness condition holds for this world — the valve that stands
+ * after the verdict. It is closed unless every witness entry holds: a declaration with no
+ * witness block, a world outside the scope, and a source the witness cannot read all leave
+ * it shut, so the valve opens only on a condition that was actually met.
+ */
+export function witnessOpens(spec) {
+    const { compiled, world } = spec;
+    const witness = compiled.witness;
+    if (witness === undefined)
+        return false;
+    if (!inScope(compiled.scope, world))
+        return false;
+    const extractor = new Extractor(witness.pipelines, compiled.supply, world);
+    for (const entry of witness.relate) {
+        const witnesses = evaluate(entry, extractor);
+        if (extractor.problem !== undefined || witnesses === undefined)
+            return false;
+        if (witnesses.length > 0)
+            return false;
+    }
+    return true;
+}

package/dist/covenant/discipline.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Discipline registration compiler.
+ *
+ * `compileDisciplineRegistrations` turns validated entries into dispatcher registrations —
+ * one per entry, routed by the declaration's own scope (`matches`), judged by an in-process
+ * thunk that runs the compiled declaration over each world the input yields. Absolute paths
+ * are relativized against the repo root first, so a path outside the root never routes: a
+ * declaration's scope is written repo-relative.
+ */
+import { type CanonicalTranscript, type CovenantInput, type DisciplineEntry } from '@polydeukes/core';
+import { type World } from './declaration-engine.ts';
+import type { CovenantRegistration } from './dispatch.ts';
+/**
+ * `CompileDisciplinesSpec` — validated entries plus the assembly values baked into each
+ * registration's judge thunk and matches closure.
+ *
+ * `transcript` is the session history a `transcript` binding reads. Absent means no session
+ * CHANNEL, not an empty one — the declaration's own `supply` policy disposes of it.
+ *
+ * `postIsWholeFile` says whether a change's `post` is the file the call leaves behind.
+ * Absent means true — a session call carries the whole text it is about to write, so a
+ * `file` binding naming the changed path reads that text. A diff-translated change carries
+ * only the hunk's added lines as `post`; on that surface the binding reads the tree instead,
+ * which holds the state the change set left.
+ *
+ * `observesPreState` says whether this surface has a pre-state channel at all. Absent means
+ * true — the reader answers per location, and its `undefined` is that one location failing.
+ * False is a surface that can never answer, so a shell write it derives yields no world
+ * rather than the unjudgeable exit: an absent channel is an environment fact, not a break.
+ * That write routes to the entry's skip arm, since an entry handed no world would otherwise
+ * answer pass for a file it never read.
+ */
+export type CompileDisciplinesSpec = {
+    disciplines: DisciplineEntry[];
+    rootDir: string;
+    shellTools: string[];
+    commandArgs: string[];
+    readPreState: (location: string) => string | null | undefined;
+    postIsWholeFile?: boolean;
+    observesPreState?: boolean;
+    witness?: CovenantRegistration['witness'];
+    transcript?: CanonicalTranscript;
+};
+/** One change as one world, under the repo-relative path the declaration's scope reads. */
+export type SuppliedWorld = {
+    readonly path: string;
+    readonly world: World;
+};
+/**
+ * `worldsFromInput` input — one observation, the root its paths are relativized against,
+ * and the shell surface that says which of the input's calls is a shell call.
+ */
+export type WorldsFromInputSpec = {
+    input: CovenantInput;
+    rootDir: string;
+    shellTools: string[];
+    commandArgs: string[];
+};
+/**
+ * Turn each observation of the input into one world, in input order.
+ *
+ * The seven source names are fixed: `target.path`, `pre`, `post`, the paired `state`,
+ * `changes`, `command`, and `actor`. A side the change does not carry is an ABSENT key, never a
+ * fabricated default — what a missing source means is the declaration's own `supply` policy
+ * to state. `state` exists only where both sides do, so a declaration comparing before with
+ * after refuses a change that has no before. A path outside the root is dropped, as
+ * everywhere else in this module: a declaration's scope is written repo-relative.
+ *
+ * `changes` is the observation unit's change set, the same array instance in every world so
+ * a large commit costs one list rather than one per change. It is derived from this input
+ * unless the host supplied its own — a host whose observation is wider than the changes it
+ * dispatches at once has a set no derivation here could reach.
+ *
+ * `actor` is the input's actor object, carried by every world of the input — the file
+ * worlds and the call world alike. An input without one leaves the key absent, since `{}`
+ * is the positive value saying the host observed an actor that is not a subagent.
+ *
+ * `command` is the first shell call's command line with its heredoc bodies and herestring
+ * words deleted, carried by every world of the input. bash hands those bytes to the command
+ * as stdin data instead of executing them — except a body or word bash expands first, which
+ * stays — and whether they become a file write is the shell-evidence path's judgment, which
+ * reads the command as written.
+ * A shell call changing no in-scope file is still one observation, so it yields the single
+ * CALL WORLD — subject `'-'`, no `target.path`, so a path-scoped declaration finds no string
+ * and refuses it. A surface whose shell tools are empty observes no shell call, hence no
+ * `command` and no call world.
+ */
+export declare function worldsFromInput(spec: WorldsFromInputSpec): SuppliedWorld[];
+/**
+ * Compile validated discipline entries into dispatcher registrations.
+ *
+ * One registration per entry: `label` = id (per-discipline telemetry), `protectedPaths`
+ * = [] (routing is the matches closure, not path mention), `body` = the judge thunk with
+ * the entry and the assembly values bound in. Each entry gains a second, body-less
+ * registration for its shell axis, and one common `shell-unjudgeable` registration is
+ * appended last whatever the entry count.
+ *
+ * An entry whose declaration does not compile becomes a **skip registration** that routes
+ * nothing and names its location on stderr. Assembly never throws — one bad entry taking
+ * down its siblings, the meta-covenants, and the witness valve would leave no way to fix
+ * the config that caused it.
+ */
+export declare function compileDisciplineRegistrations(spec: CompileDisciplinesSpec): CovenantRegistration[];