@cotal-ai/lang 0.0.0 → 0.15.0

package/dist/interpret.js

@@ -0,0 +1,1117 @@
+/**
+ * The interpreter: an AST walk over a validated program.
+ *
+ * Two properties make this worth reading closely, because everything else in the durability story
+ * rests on them:
+ *
+ * 1. **The interpreter owns the journal; the handler never touches it.** Every effect goes through
+ *    {@link Interpreter.performEffect}, which allocates the key, consults the journal, and either
+ *    replays a recorded result or performs the effect live and records it. That is why simulation
+ *    and production cannot drift apart on durability: neither handler is in a position to.
+ * 2. **Resume is re-running from the top.** There is no cursor and no fast-forward. Journalled
+ *    effects return their recorded results, so the deterministic prefix reproduces itself and
+ *    out-of-order concurrency replays correctly. This is the same thing as an effect handler's
+ *    resume(), implemented by re-running the pure prefix, which is why no continuation is ever
+ *    serialized.
+ */
+import { validate } from "./grammar.js";
+import { LangError, LangErrors } from "./errors.js";
+import { KeyScope, digest, requestId, scopePathString, stepKeyString } from "./keys.js";
+import { Journal, RunClock } from "./journal.js";
+import { Prng, assertCrossable, deepFreeze } from "./values.js";
+import { parseDuration } from "./duration.js";
+import { PRIMITIVES } from "./primitives.js";
+import { Cancelled, EffectError, applyCheckpointPolicy, } from "./effects.js";
+// ---- environments ------------------------------------------------------------------------------
+class Binding {
+    value;
+    mutable;
+    constructor(value, mutable) {
+        this.value = value;
+        this.mutable = mutable;
+    }
+}
+class Env {
+    parent;
+    names = new Map();
+    constructor(parent) {
+        this.parent = parent;
+    }
+    declare(name, value, mutable) {
+        this.names.set(name, new Binding(value, mutable));
+    }
+    find(name) {
+        for (let e = this; e !== null; e = e.parent) {
+            const b = e.names.get(name);
+            if (b !== undefined)
+                return b;
+        }
+        return undefined;
+    }
+    get(name) {
+        const b = this.find(name);
+        if (b === undefined)
+            throw new RuntimeFault("L2001", `${name} is not defined`);
+        return b.value;
+    }
+    has(name) {
+        return this.find(name) !== undefined;
+    }
+    set(name, value) {
+        const b = this.find(name);
+        if (b === undefined)
+            throw new RuntimeFault("L2001", `${name} is not defined`);
+        if (!b.mutable)
+            throw new RuntimeFault("L2003", `${name} is declared const`);
+        b.value = value;
+    }
+}
+/** A fault the interpreter itself raises, as opposed to one an effect handler reported. */
+export class RuntimeFault extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code} ${message}`);
+        this.code = code;
+        this.name = "RuntimeFault";
+    }
+}
+const NORMAL = { type: "normal" };
+// ---- per-branch execution state ---------------------------------------------------------------------
+class Signal {
+    cancelled = false;
+    reason;
+    listeners = [];
+    onCancel(fn) {
+        this.listeners.push(fn);
+    }
+    cancel(reason) {
+        if (this.cancelled)
+            return;
+        this.cancelled = true;
+        this.reason = reason;
+        for (const l of this.listeners)
+            l(reason);
+    }
+    child() {
+        const s = new Signal();
+        if (this.cancelled)
+            s.cancel(this.reason ?? "parent cancelled");
+        else
+            this.onCancel((r) => s.cancel(r));
+        return s;
+    }
+}
+/**
+ * One branch of execution: its own key namespace, its own clock, its own cancellation signal.
+ *
+ * The key namespace is the reason concurrency is safe here. Two branches calling the same named
+ * effect cannot race for an occurrence counter, because they do not share one.
+ */
+class Frame {
+    keys;
+    clock;
+    signal;
+    constructor(keys, clock, signal) {
+        this.keys = keys;
+        this.clock = clock;
+        this.signal = signal;
+    }
+    branch(kind, name, occurrence, branchKey) {
+        return new Frame(this.keys.branch(kind, name, occurrence, branchKey), this.clock.fork(), this.signal.child());
+    }
+}
+/** A recorded step's inputs changed, so its recorded result may no longer be the truth. */
+export class RunDivergence extends Error {
+    stepKey;
+    recordedHash;
+    programHash;
+    constructor(stepKey, recordedHash, programHash) {
+        super(`L5001 Run divergence\n\n  step  ${stepKey}   INPUT CHANGED\n        recorded  ${recordedHash}\n        program   ${programHash}\n\nThe recorded result was produced from different inputs, so replaying it would hand the program an answer to a question it is no longer asking.\n\nOptions\n  fork(run, "${stepKey}")   re-run from this step, keeping everything before it\n  revert the inputs         keep the recorded result`);
+        this.stepKey = stepKey;
+        this.recordedHash = recordedHash;
+        this.programHash = programHash;
+        this.name = "RunDivergence";
+    }
+}
+class Interpreter {
+    ast;
+    options;
+    programHash;
+    journal;
+    prng;
+    effectCount = 0;
+    ceiling;
+    steps = 0;
+    nextYield;
+    stepBudget;
+    yieldEvery;
+    constructor(ast, options, programHash) {
+        this.ast = ast;
+        this.options = options;
+        this.programHash = programHash;
+        this.journal = options.journal ?? new Journal({ run: options.runId });
+        this.prng = new Prng(options.seed ?? options.runId);
+        this.ceiling = options.effectCeiling ?? 10_000;
+        this.stepBudget = options.stepBudget ?? 1_000_000;
+        this.yieldEvery = options.yieldEvery ?? 1_024;
+        this.nextYield = this.yieldEvery;
+    }
+    // ---- the fuel ceiling -----------------------------------------------------------------------
+    /**
+     * Charge one walker dispatch.
+     *
+     * Returns null on the common path and a promise only when it is time to breathe, so a dispatch
+     * normally costs an increment and a compare rather than an allocated promise. Callers await the
+     * result only when it is non-null, which is why this is not simply an async method.
+     */
+    tick(frame) {
+        this.steps += 1;
+        if (this.steps > this.stepBudget) {
+            throw new RuntimeFault("L4013", `this run has taken more than ${this.stepBudget} interpreter steps without finishing, which means a loop that performs no effect is not terminating. The effect ceiling cannot see such a loop, because it performs nothing to count. Add an exit condition, or raise stepBudget if the program legitimately does this much work.`);
+        }
+        if (this.steps < this.nextYield)
+            return null;
+        this.nextYield = this.steps + this.yieldEvery;
+        return this.breathe(frame);
+    }
+    /**
+     * Hand the macrotask queue back, then notice if this branch was cancelled while we were away.
+     *
+     * The cancellation check is deliberately HERE and not on every dispatch. Cancellation is
+     * otherwise observed only at effect boundaries (see {@link Interpreter.performEffect}), so a race
+     * loser that spins without performing an effect never learns it lost and spins forever. Checking
+     * at the yield boundary reaches exactly that case and no other: a branch that runs fewer than
+     * `yieldEvery` dispatches between two effects never crosses this line, so the cancellation law
+     * for ordinary programs is unchanged.
+     */
+    get stepCount() {
+        return this.steps;
+    }
+    async breathe(frame) {
+        await new Promise((resolve) => {
+            setTimeout(resolve, 0);
+        });
+        if (frame.signal.cancelled)
+            throw new Cancelled(frame.signal.reason ?? "cancelled");
+    }
+    // ---- the effect seam ------------------------------------------------------------------------
+    /**
+     * Perform one effect, or replay it.
+     *
+     * Everything durable happens here. A handler is called only in the `miss` and `pending` cases,
+     * and in `pending` it is told to re-bind rather than re-issue.
+     */
+    async performEffect(kind, name, hashedInput, perform, frame) {
+        const key = frame.keys.nextEffect(kind, name);
+        const inputHash = digest(hashedInput ?? null);
+        const verdict = this.journal.lookup(key, inputHash);
+        switch (verdict.verdict) {
+            case "replay":
+                if (verdict.entry.endedAt !== undefined)
+                    frame.clock.advance(verdict.entry.endedAt);
+                return verdict.entry.result;
+            case "replay-failed": {
+                if (verdict.entry.endedAt !== undefined)
+                    frame.clock.advance(verdict.entry.endedAt);
+                const e = verdict.entry.error;
+                throw new EffectError(e.code, e.kind, e.message, e.detail);
+            }
+            case "replay-cancelled":
+                throw new Cancelled("this branch was cancelled on the recorded run");
+            case "diverged":
+                throw new RunDivergence(stepKeyString(key), verdict.recordedHash, verdict.programHash);
+            case "pending":
+            case "miss":
+                break;
+        }
+        // A cancelled branch performs no NEW effects. That is the whole of the cancellation law on
+        // this side: work already in flight is another matter, and the handler owns it.
+        if (frame.signal.cancelled) {
+            throw new Cancelled(frame.signal.reason ?? "cancelled");
+        }
+        this.effectCount += 1;
+        if (this.effectCount > this.ceiling) {
+            throw new RuntimeFault("L4009", `this run has performed more than ${this.ceiling} effects, which means a loop is not terminating. Add an exit condition or a permit.`);
+        }
+        const resume = verdict.verdict === "pending" ? verdict.entry.external : undefined;
+        // RECOVERY SUBMITS UNDER THE RECORDED IDENTITY. Re-deriving happens to agree whenever nothing
+        // moved, which is exactly why it read as correct: the whole point of writing the id down is
+        // the case where it does NOT agree, and a resumed run that re-derives is reissuing under an
+        // identity the far side may never have seen. An entry with no recorded id predates this rule.
+        const recorded = verdict.verdict === "pending" && verdict.entry.requestId !== undefined ? verdict.entry : undefined;
+        const reqId = recorded?.requestId ?? requestId(this.options.runId, key, inputHash);
+        // WHICH attempt is open, not merely which id. An id alone cannot say how much of an escalation
+        // chain is already spent, and a recovery that cannot tell replays the hop: it mints again under
+        // the id the far side already holds and reads that mint's cached expiry back as a fresh
+        // observation. An entry written before the index existed reads as attempt 0, which is what it
+        // is for every effect that never hops.
+        const attempt = recorded?.attempt ?? 0;
+        if (verdict.verdict === "miss") {
+            this.journal.begin(key, inputHash, this.options.handler.now(), reqId);
+        }
+        const ctx = {
+            key,
+            signal: frame.signal,
+            // Derived from the run, the step, the inputs and the attempt, and written on the pending
+            // entry by `begin` above BEFORE the handler runs. A handler submits under it idempotently,
+            // so a resumed run reissues the same id rather than creating a second goal.
+            requestId: reqId,
+            attempt,
+            ...(resume !== undefined ? { resume } : {}),
+            bind: async (external) => {
+                this.journal.bind(key, external);
+            },
+        };
+        try {
+            const result = await perform(ctx, inputHash);
+            assertCrossable(result, `the result of ${stepKeyString(key)}`);
+            const endedAt = this.options.handler.now();
+            this.journal.settle(key, { status: "ok", result: deepFreeze(result) }, endedAt);
+            frame.clock.advance(endedAt);
+            return result;
+        }
+        catch (e) {
+            const endedAt = this.options.handler.now();
+            if (e instanceof Cancelled) {
+                this.journal.settle(key, { status: "cancelled" }, endedAt);
+                throw e;
+            }
+            // A handler may raise a language code directly, and it survives. The simulator's "unscripted
+            // effect" is L6001, and flattening that to a generic handler fault would tell a caller acting
+            // on `code` that the handler broke, when what actually happened is that their script is
+            // incomplete. Only the L-code shape is honoured: anything else a thrown object happens to
+            // call `code` (an errno, an HTTP status) is a handler fault and is recorded as one.
+            const raised = e.code;
+            const carried = typeof raised === "string" && /^L\d{4}$/.test(raised) ? raised : null;
+            const error = e instanceof EffectError
+                ? { code: e.code, kind: e.kind, message: e.message, ...(e.detail !== undefined ? { detail: e.detail } : {}) }
+                : carried !== null
+                    ? { code: carried, kind: "handler-fault", message: e.message }
+                    : { code: "L4000", kind: "handler-fault", message: e.message };
+            this.journal.settle(key, { status: "failed", error }, endedAt);
+            frame.clock.advance(endedAt);
+            throw e instanceof EffectError ? e : new EffectError(error.code, error.kind, error.message);
+        }
+    }
+    // ---- expressions ------------------------------------------------------------------------------
+    async evaluate(node, env, frame) {
+        const pause = this.tick(frame);
+        if (pause !== null)
+            await pause;
+        switch (node.type) {
+            case "Literal":
+                return node.value;
+            case "Identifier":
+                return env.get(node.name);
+            case "TemplateLiteral": {
+                const quasis = node.quasis;
+                const exprs = node.expressions;
+                let out = "";
+                for (let i = 0; i < quasis.length; i += 1) {
+                    out += quasis[i].value.cooked;
+                    if (i < exprs.length)
+                        out += String(await this.evaluate(exprs[i], env, frame));
+                }
+                return out;
+            }
+            case "ArrayExpression": {
+                const out = [];
+                for (const el of node.elements ?? []) {
+                    if (el.type === "SpreadElement") {
+                        const spread = await this.evaluate(el.argument, env, frame);
+                        out.push(...spread);
+                    }
+                    else {
+                        out.push(await this.evaluate(el, env, frame));
+                    }
+                }
+                return out;
+            }
+            case "ObjectExpression": {
+                const out = {};
+                for (const p of node.properties ?? []) {
+                    if (p.type === "SpreadElement") {
+                        Object.assign(out, await this.evaluate(p.argument, env, frame));
+                        continue;
+                    }
+                    const key = p.key;
+                    const name = key.type === "Identifier" ? key.name : String(key.value);
+                    out[name] = await this.evaluate(p.value, env, frame);
+                }
+                return out;
+            }
+            case "MemberExpression": {
+                const obj = await this.evaluate(node.object, env, frame);
+                if (obj === null || obj === undefined) {
+                    if (node.optional === true)
+                        return undefined;
+                    throw new RuntimeFault("L4010", `cannot read a field of ${String(obj)}`);
+                }
+                const prop = node.computed === true
+                    ? String(await this.evaluate(node.property, env, frame))
+                    : node.property.name;
+                return obj[prop];
+            }
+            case "UnaryExpression": {
+                const v = await this.evaluate(node.argument, env, frame);
+                switch (node.operator) {
+                    case "!":
+                        return !v;
+                    case "-":
+                        return -v;
+                    case "+":
+                        return +v;
+                    case "typeof":
+                        return typeof v;
+                    default:
+                        throw new RuntimeFault("L1000", `unsupported unary operator ${String(node.operator)}`);
+                }
+            }
+            case "BinaryExpression": {
+                const l = await this.evaluate(node.left, env, frame);
+                const r = await this.evaluate(node.right, env, frame);
+                return applyBinary(node.operator, l, r);
+            }
+            case "LogicalExpression": {
+                const l = await this.evaluate(node.left, env, frame);
+                switch (node.operator) {
+                    case "&&":
+                        return l ? await this.evaluate(node.right, env, frame) : l;
+                    case "||":
+                        return l ? l : await this.evaluate(node.right, env, frame);
+                    case "??":
+                        // Orc's `otherwise`, spelled the way JavaScript already spells it: an event that
+                        // halted without a result resolves null, and this is the recovery path.
+                        return l === null || l === undefined
+                            ? await this.evaluate(node.right, env, frame)
+                            : l;
+                    default:
+                        throw new RuntimeFault("L1000", `unsupported logical operator ${String(node.operator)}`);
+                }
+            }
+            case "ConditionalExpression":
+                return (await this.evaluate(node.test, env, frame))
+                    ? await this.evaluate(node.consequent, env, frame)
+                    : await this.evaluate(node.alternate, env, frame);
+            case "AssignmentExpression": {
+                const value = await this.evaluate(node.right, env, frame);
+                const left = node.left;
+                if (left.type !== "Identifier") {
+                    throw new RuntimeFault("L2031", "only a plain binding can be assigned to");
+                }
+                env.set(left.name, value);
+                return value;
+            }
+            case "AwaitExpression":
+                return await this.evaluate(node.argument, env, frame);
+            case "ArrowFunctionExpression":
+            case "FunctionExpression":
+                return this.makeFunction(node, env);
+            case "CallExpression":
+                return await this.call(node, env, frame);
+            default:
+                throw new RuntimeFault("L1000", `unsupported expression ${node.type}`);
+        }
+    }
+    makeFunction(node, closure) {
+        const params = node.params ?? [];
+        const body = node.body;
+        const isExpressionBody = body.type !== "BlockStatement";
+        return async (frame, args) => {
+            const env = new Env(closure);
+            for (let i = 0; i < params.length; i += 1) {
+                await this.bindPattern(params[i], args[i], env, frame, true);
+            }
+            if (isExpressionBody)
+                return await this.evaluate(body, env, frame);
+            const c = await this.executeBlock(body, env, frame);
+            return c.type === "return" ? c.value : undefined;
+        };
+    }
+    async bindPattern(pattern, value, env, frame, mutable) {
+        switch (pattern.type) {
+            case "Identifier":
+                env.declare(pattern.name, value, mutable);
+                return;
+            case "AssignmentPattern":
+                await this.bindPattern(pattern.left, value === undefined ? await this.evaluate(pattern.right, env, frame) : value, env, frame, mutable);
+                return;
+            case "ObjectPattern": {
+                const src = (value ?? {});
+                const taken = [];
+                for (const p of pattern.properties) {
+                    if (p.type === "RestElement") {
+                        const rest = {};
+                        for (const [k, v] of Object.entries(src))
+                            if (!taken.includes(k))
+                                rest[k] = v;
+                        await this.bindPattern(p.argument, rest, env, frame, mutable);
+                        continue;
+                    }
+                    const key = p.key;
+                    const name = key.type === "Identifier" ? key.name : String(key.value);
+                    taken.push(name);
+                    await this.bindPattern(p.value, src[name], env, frame, mutable);
+                }
+                return;
+            }
+            case "ArrayPattern": {
+                const src = (value ?? []);
+                const els = pattern.elements;
+                for (let i = 0; i < els.length; i += 1) {
+                    const el = els[i];
+                    if (el === null || el === undefined)
+                        continue;
+                    if (el.type === "RestElement") {
+                        await this.bindPattern(el.argument, src.slice(i), env, frame, mutable);
+                        break;
+                    }
+                    await this.bindPattern(el, src[i], env, frame, mutable);
+                }
+                return;
+            }
+            default:
+                throw new RuntimeFault("L1000", `unsupported binding pattern ${pattern.type}`);
+        }
+    }
+    // ---- calls ----------------------------------------------------------------------------------
+    async call(node, env, frame) {
+        const callee = node.callee;
+        const argNodes = node.arguments ?? [];
+        // A primitive is dispatched by NAME, not by value. The validator forbids shadowing one, so a
+        // call spelled `turn` is always the effect, which is what keeps the flowchart projection and
+        // the linter sound.
+        if (callee.type === "Identifier" && PRIMITIVES[callee.name] !== undefined && !env.has(callee.name)) {
+            return await this.callPrimitive(callee.name, argNodes, env, frame);
+        }
+        const fn = await this.evaluate(callee, env, frame);
+        const args = [];
+        for (const a of argNodes) {
+            if (a.type === "SpreadElement")
+                args.push(...(await this.evaluate(a.argument, env, frame)));
+            else
+                args.push(await this.evaluate(a, env, frame));
+        }
+        if (typeof fn !== "function") {
+            throw new RuntimeFault("L4011", `this value is not a function, so it cannot be called`);
+        }
+        return await fn(frame, args);
+    }
+    option(bag, key) {
+        return bag === null || typeof bag !== "object" ? undefined : bag[key];
+    }
+    async callPrimitive(name, argNodes, env, frame) {
+        const spec = PRIMITIVES[name];
+        if (spec === undefined)
+            throw new RuntimeFault("L2001", `${name} is not a primitive`);
+        // Concurrency combinators take their branches unevaluated: the thunks must run inside their
+        // own frames, so evaluating them here would defeat the whole point.
+        if (spec.opensScope)
+            return await this.callScope(name, argNodes, env, frame);
+        const args = [];
+        for (const a of argNodes)
+            args.push(await this.evaluate(a, env, frame));
+        const bag = args[spec.optionsAt];
+        const stepName = (name === "checkpoint" ? args[0] : this.option(bag, "name"));
+        const handler = this.options.handler;
+        switch (name) {
+            case "spawn": {
+                // The first argument is a persona name, or a record carrying the persona WITH its model
+                // and variant. Only the persona was ever read, so the object form silently dropped model
+                // and variant from both the request and the hash: editing a model did not diverge, and the
+                // handler was never told which model to run. This was missed by an audit that exercised
+                // only the string form, which is the same defect one level up.
+                const spawnSubject = args[0];
+                const persona = typeof spawnSubject === "string" ? spawnSubject : String(this.option(spawnSubject, "persona"));
+                const model = typeof spawnSubject === "string" ? undefined : this.option(spawnSubject, "model");
+                const variant = typeof spawnSubject === "string" ? undefined : this.option(spawnSubject, "variant");
+                // Every accepted option is forwarded, including the three that are policy rather than
+                // identity. Dropping them here would be silent: the validator accepts `permits`, so an
+                // author who writes a budget gets no error and no budget. They are deliberately absent
+                // from `hashedOptions` (§5.12) because they decide the INTERPRETATION of a result, not the
+                // recorded fact, so they are reapplied from current source on resume rather than hashed.
+                const req = {
+                    persona,
+                    ...(model !== undefined ? { model } : {}),
+                    ...(variant !== undefined ? { variant } : {}),
+                    ...(this.option(bag, "worktree") !== undefined ? { worktree: this.option(bag, "worktree") } : {}),
+                    ...(this.option(bag, "role") !== undefined ? { role: this.option(bag, "role") } : {}),
+                    ...(this.option(bag, "join") !== undefined ? { join: this.option(bag, "join") } : {}),
+                    ...(this.option(bag, "permits") !== undefined
+                        ? { permits: this.option(bag, "permits") }
+                        : {}),
+                    ...(this.option(bag, "supervise") !== undefined
+                        ? { supervise: this.option(bag, "supervise") }
+                        : {}),
+                    ...(this.option(bag, "onFork") !== undefined ? { onFork: this.option(bag, "onFork") } : {}),
+                };
+                return await this.performEffect("spawn", stepName ?? persona, 
+                // Model and variant are part of the IDENTITY being spawned, so they are hashed with the
+                // persona (design 5.12). A run that swapped the model under a recorded agent would be
+                // replaying a fact about a different agent.
+                {
+                    persona,
+                    model: model ?? null,
+                    variant: variant ?? null,
+                    worktree: req.worktree ?? null,
+                    role: req.role ?? null,
+                    join: (req.join ?? []).map((c) => c.channel),
+                }, (ctx) => handler.spawn(req, ctx), frame);
+            }
+            case "turn": {
+                const agent = deepFreeze(args[0]);
+                // The deadline STOPS OBSERVATION (design 5.12), so it belongs in the projection: a turn
+                // recorded under a 1m deadline cannot answer what a 10m turn would have produced, and a
+                // resumed run under the edited deadline replaying the old result is the silent-wrong-path
+                // class. Closing that for `checkpoint` and leaving it open on the siblings closed nothing.
+                const deadline = this.option(bag, "deadline");
+                return await this.performEffect("turn", stepName, { agent: agent.agent, deadline: deadline ?? null }, (ctx) => handler.turn({ agent, ...(deadline !== undefined ? { deadline } : {}) }, ctx), frame);
+            }
+            case "ask": {
+                const agent = deepFreeze(args[0]);
+                const schema = this.option(bag, "schema");
+                // Both of these END THE ASKING: `deadline` is the cutoff and `attempts` is how many
+                // schema-failed replies are tolerated before it gives up. A record made under one attempt
+                // is not an answer to what five attempts would have produced.
+                const deadline = this.option(bag, "deadline");
+                const attempts = this.option(bag, "attempts");
+                return await this.performEffect("ask", stepName, { agent: agent.agent, schema: schema ?? null, deadline: deadline ?? null, attempts: attempts ?? null }, (ctx) => handler.ask({
+                    agent,
+                    schema,
+                    ...(deadline !== undefined ? { deadline } : {}),
+                    ...(attempts !== undefined ? { attempts } : {}),
+                }, ctx), frame);
+            }
+            case "checkpoint": {
+                const prompt = args[1];
+                // The disposition is computed from TODAY's source, after the journal is consulted, on the
+                // live path and the replay path alike. performEffect returns the RAW outcome, which is
+                // what the journal holds; the policy sandwich closes here so a resumed run under an edited
+                // onExpiry throws even though nothing about the recorded expiry changed.
+                const onExpiry = this.option(bag, "onExpiry");
+                const schema = this.option(bag, "schema");
+                // The SAME projection the entry is keyed by, so an attempt's identity is a function of the
+                // step it belongs to rather than of anything the escalation invents.
+                // Design 5.12, and every field here earns its place. `timeout` STOPS OBSERVATION, so a
+                // record made under 1m cannot answer what a 3m wait would have seen. `escalate` and its
+                // `to` CREATE AN EFFECT rather than choosing a disposition, so editing them must diverge
+                // rather than be reapplied. `fail` versus `proceed` is the one genuine reapply and stays
+                // out. Hashing only prompt and schema left a timeout edit replaying clean, which is the
+                // silent-wrong-path class this projection exists to close.
+                const cpTimeout = this.option(bag, "timeout");
+                const cpTo = this.option(bag, "to");
+                const cpInput = {
+                    prompt,
+                    schema: schema ?? null,
+                    timeout: cpTimeout ?? null,
+                    ...(onExpiry === "escalate" ? { onExpiry, to: cpTo ?? null } : {}),
+                };
+                return applyCheckpointPolicy((await this.performEffect("checkpoint", stepName, cpInput, async (ctx, inputHash) => {
+                    // ONE hash value, threaded from what the entry is actually keyed by rather than
+                    // re-digested from the projection here. The two agreed, which is exactly the problem:
+                    // a second derivation that happens to match is a coincidence maintained by hand, and
+                    // the first edit to the projection would desync attempt 1's identity from its own
+                    // step with no type error and no failing test.
+                    const attemptId = (n) => requestId(this.options.runId, ctx.key, inputHash, n);
+                    const req = {
+                        prompt,
+                        ...(schema !== undefined ? { schema } : {}),
+                        ...(cpTimeout !== undefined ? { timeout: cpTimeout } : {}),
+                        ...(onExpiry !== undefined ? { onExpiry } : {}),
+                        ...(cpTo !== undefined ? { to: cpTo } : {}),
+                    };
+                    // THE FINAL MINT DOES NOT ASK FOR AN ESCALATION. The interpreter owns the one-hop stop
+                    // rule, and it can only own it if the far side is not simultaneously told to hop: a
+                    // handler that honours `onExpiry` on the wire would mint a third attempt under an
+                    // identity this journal never allocated, and nothing here would ever learn of it.
+                    const finalReq = onExpiry === "escalate" ? { ...req, onExpiry: "proceed" } : req;
+                    // RECOVERY COMPLETES THE OPEN ATTEMPT. IT DOES NOT REPLAY THE CHAIN.
+                    //
+                    // Arriving here with a non-zero attempt means the hop was issued before the crash, so
+                    // the far side is already holding work under this very id. Re-running the live body
+                    // from the top would call the handler again under it and take that call's cached
+                    // expiry for a second observation: the stop rule would be satisfied on paper while the
+                    // run had in fact observed one attempt twice. The chain's shape is recoverable without
+                    // re-running it, because attempt 0's identity is derivable and its outcome is implied:
+                    // the only path that opens attempt 1 is attempt 0 expiring.
+                    if (ctx.attempt > 0) {
+                        const raw = await handler.checkpoint(finalReq, ctx);
+                        return {
+                            ...raw,
+                            attempts: [
+                                { attempt: 0, requestId: attemptId(0), settled: "expired" },
+                                { attempt: ctx.attempt, requestId: ctx.requestId, to: cpTo ?? null, settled: raw.outcome },
+                            ],
+                        };
+                    }
+                    const first = await handler.checkpoint(req, ctx);
+                    if (first.outcome !== "expired" || onExpiry !== "escalate") {
+                        // `ctx.attempt`, not a literal 0. Writing the literal made every recovery relabel the
+                        // open attempt as the first one, which erased the hop from the journal and left the
+                        // record claiming the escalated mint was the original.
+                        return { ...first, attempts: [{ attempt: ctx.attempt, requestId: ctx.requestId, settled: first.outcome }] };
+                    }
+                    // ESCALATION STAYS INSIDE THIS ENTRY. The program made one call, and the interpreter
+                    // owns key allocation, so a second mint must not become a second occurrence. What it
+                    // does need is a second IDENTITY, derived from attempt 1 before the mint happens, or a
+                    // crash between minting and recording leaves live work nothing in the journal names.
+                    //
+                    // Name the open attempt on the pending row BEFORE issuing it, index and all.
+                    const nextId = attemptId(1);
+                    this.journal.reissueAs(ctx.key, nextId, 1);
+                    const second = await handler.checkpoint(finalReq, { ...ctx, requestId: nextId, attempt: 1 });
+                    // ONE HOP. An escalation that can escalate again never terminates, so a second expiry
+                    // settles as expired and the program decides, exactly as `proceed` would.
+                    return {
+                        ...second,
+                        attempts: [
+                            { attempt: 0, requestId: ctx.requestId, settled: "expired" },
+                            { attempt: 1, requestId: nextId, to: cpTo ?? null, settled: second.outcome },
+                        ],
+                    };
+                }, frame)), onExpiry);
+            }
+            case "sleep": {
+                const duration = args[0];
+                parseDuration(duration); // fail at the call, not inside the handler
+                // The duration IS hashed (design 5.12). It determines the recorded fact: a resumed run
+                // reads the elapsed time back through the run clock, so editing 1h to 1m must diverge
+                // rather than silently keep the path the old duration chose. This hashed `null` until
+                // critic2 executed it, and the rule it violates is one this lane wrote and then only
+                // ever applied to the document.
+                return await this.performEffect("sleep", stepName ?? "", { duration }, (ctx) => handler.sleep({ duration }, ctx), frame);
+            }
+            case "wait": {
+                const event = deepFreeze(args[0]);
+                const timeout = this.option(bag, "timeout");
+                // A `wait` that resolved null did not observe "the event never happens": it observed "the
+                // event did not happen WITHIN THIS TIMEOUT". Editing the timeout therefore asks a different
+                // question, and replaying the recorded null answers the old one. This is the same hole the
+                // checkpoint projection closed, and leaving it open here left `?? recovery` steering off a
+                // stale cutoff.
+                return await this.performEffect("wait", stepName ?? "", { event, timeout: timeout ?? null }, (ctx) => handler.wait({ event, ...(timeout !== undefined ? { timeout } : {}) }, ctx), frame);
+            }
+            case "notify": {
+                const agents = deepFreeze(args[0]);
+                const fact = deepFreeze(args[1]);
+                return await this.performEffect("notify", stepName ?? "", { agents: agents.map((a) => a.agent), fact }, (ctx) => handler.notify({ agents, fact }, ctx), frame);
+            }
+            case "monitor": {
+                const agent = deepFreeze(args[0]);
+                return await this.performEffect("monitor", stepName ?? "", { agent: agent.agent }, (ctx) => handler.monitor({ agent }, ctx), frame);
+            }
+            default:
+                throw new RuntimeFault("L1000", `${name} is not implemented in this interpreter`);
+        }
+    }
+    /**
+     * The concurrency combinators.
+     *
+     * Each pushes a scope frame whose occurrence is allocated HERE, synchronously, in code that is
+     * already deterministic. Each branch then gets its own key namespace, so two branches running
+     * the same named effect cannot race for a counter, and replay reproduces both regardless of
+     * which one finished first.
+     */
+    async callScope(name, argNodes, env, frame) {
+        const spec = PRIMITIVES[name];
+        if (spec === undefined)
+            throw new RuntimeFault("L2001", `${name} is not a primitive`);
+        const scopeKind = name;
+        const first = await this.evaluate(argNodes[0], env, frame);
+        const bagNode = argNodes[spec.optionsAt];
+        const bag = bagNode === undefined ? undefined : await this.evaluate(bagNode, env, frame);
+        const scopeName = this.option(bag, "name") ?? null;
+        const occurrence = frame.keys.nextScope(scopeKind, scopeName);
+        if (name === "parallel" || name === "race") {
+            const entries = Array.isArray(first)
+                ? first.map((fn, i) => [String(i), fn])
+                : Object.entries(first);
+            const frames = entries.map(([k]) => frame.branch(scopeKind, scopeName, occurrence, k));
+            const running = entries.map(([, fn], i) => fn(frames[i], []));
+            if (name === "parallel") {
+                try {
+                    const results = await Promise.all(running);
+                    frame.clock.join(frames.map((f) => f.clock));
+                    return Array.isArray(first)
+                        ? results
+                        : Object.fromEntries(entries.map(([k], i) => [k, results[i]]));
+                }
+                catch (e) {
+                    // The first rejection cancels the rest, then rethrows.
+                    for (const f of frames)
+                        f.signal.cancel("a sibling branch failed");
+                    await Promise.allSettled(running);
+                    frame.clock.join(frames.map((f) => f.clock));
+                    throw e;
+                }
+            }
+            // race: first to settle wins, and the losers are cancelled BY SEMANTICS, not by an API the
+            // program calls. A cancelled branch performs no new effects; an agent reply already in
+            // flight completes and is ignored, which is the documented answer rather than an accident.
+            const winner = await Promise.race(running.map((p, i) => p.then((value) => ({ index: entries[i]?.[0], value }))));
+            for (const f of frames)
+                f.signal.cancel("a sibling branch won the race");
+            await Promise.allSettled(running);
+            frame.clock.join(frames.map((f) => f.clock));
+            return winner;
+        }
+        if (name === "fanOut") {
+            const items = first;
+            const fn = (await this.evaluate(argNodes[1], env, frame));
+            const keyFn = this.option(bag, "key");
+            const branchKeys = [];
+            for (let i = 0; i < items.length; i += 1) {
+                const item = items[i];
+                let k;
+                if (keyFn !== undefined)
+                    k = await keyFn(frame, [item]);
+                else if (item !== null && typeof item === "object" && typeof item.id === "string") {
+                    k = item.id;
+                }
+                else {
+                    throw new RuntimeFault("L3021", `fanOut needs a stable key: without one, a reordered or filtered list silently reshuffles every journal key underneath it. Pass { key: (item) => ... }, or give items a string id.`);
+                }
+                branchKeys.push(String(k));
+            }
+            if (new Set(branchKeys).size !== branchKeys.length) {
+                throw new RuntimeFault("L3024", `fanOut produced duplicate branch keys (${branchKeys.join(", ")}), so two branches would share one journal namespace and allocate the same step key with different inputs. Nothing has run yet: the keys are all evaluated before any branch launches, because rejecting after launch would be too late by exactly the side effects the check exists to prevent.`);
+            }
+            const frames = branchKeys.map((k) => frame.branch(scopeKind, scopeName, occurrence, k));
+            const results = await Promise.all(items.map((item, i) => fn(frames[i], [item, i])));
+            frame.clock.join(frames.map((f) => f.clock));
+            return results;
+        }
+        throw new RuntimeFault("L1000", `${name} is not implemented in this interpreter`);
+    }
+    // ---- statements --------------------------------------------------------------------------------
+    async executeBlock(block, env, frame) {
+        const inner = new Env(env);
+        const body = block.body ?? [];
+        for (const s of body) {
+            if (s.type === "FunctionDeclaration") {
+                inner.declare(s.id.name, this.makeFunction(s, inner), false);
+            }
+        }
+        for (const s of body) {
+            const c = await this.execute(s, inner, frame);
+            if (c.type !== "normal")
+                return c;
+        }
+        return NORMAL;
+    }
+    async execute(node, env, frame) {
+        const pause = this.tick(frame);
+        if (pause !== null)
+            await pause;
+        switch (node.type) {
+            case "ExpressionStatement":
+                await this.evaluate(node.expression, env, frame);
+                return NORMAL;
+            case "VariableDeclaration": {
+                const mutable = node.kind === "let";
+                for (const d of node.declarations) {
+                    const init = d.init === null || d.init === undefined ? undefined : await this.evaluate(d.init, env, frame);
+                    await this.bindPattern(d.id, init, env, frame, mutable);
+                }
+                return NORMAL;
+            }
+            case "FunctionDeclaration":
+                return NORMAL; // hoisted by executeBlock
+            case "BlockStatement":
+                return await this.executeBlock(node, env, frame);
+            case "IfStatement":
+                if (await this.evaluate(node.test, env, frame)) {
+                    return await this.execute(node.consequent, env, frame);
+                }
+                return node.alternate === null || node.alternate === undefined
+                    ? NORMAL
+                    : await this.execute(node.alternate, env, frame);
+            case "WhileStatement":
+                for (;;) {
+                    if (!(await this.evaluate(node.test, env, frame)))
+                        return NORMAL;
+                    const c = await this.execute(node.body, env, frame);
+                    if (c.type === "break")
+                        return NORMAL;
+                    if (c.type === "return")
+                        return c;
+                }
+            case "ForStatement": {
+                const loopEnv = new Env(env);
+                if (node.init !== null && node.init !== undefined)
+                    await this.execute(node.init, loopEnv, frame);
+                for (;;) {
+                    if (node.test !== null && node.test !== undefined && !(await this.evaluate(node.test, loopEnv, frame))) {
+                        return NORMAL;
+                    }
+                    const c = await this.execute(node.body, loopEnv, frame);
+                    if (c.type === "break")
+                        return NORMAL;
+                    if (c.type === "return")
+                        return c;
+                    if (node.update !== null && node.update !== undefined)
+                        await this.evaluate(node.update, loopEnv, frame);
+                }
+            }
+            case "ForOfStatement": {
+                const iterable = (await this.evaluate(node.right, env, frame));
+                for (const item of iterable) {
+                    const loopEnv = new Env(env);
+                    const decl = node.left;
+                    const target = decl.type === "VariableDeclaration" ? decl.declarations[0].id : decl;
+                    await this.bindPattern(target, item, loopEnv, frame, decl.kind === "let");
+                    const c = await this.execute(node.body, loopEnv, frame);
+                    if (c.type === "break")
+                        return NORMAL;
+                    if (c.type === "return")
+                        return c;
+                }
+                return NORMAL;
+            }
+            case "ReturnStatement":
+                return {
+                    type: "return",
+                    value: node.argument === null || node.argument === undefined ? undefined : await this.evaluate(node.argument, env, frame),
+                };
+            case "BreakStatement":
+                return { type: "break" };
+            case "ContinueStatement":
+                return { type: "continue" };
+            case "ThrowStatement":
+                throw await this.evaluate(node.argument, env, frame);
+            case "TryStatement": {
+                try {
+                    const c = await this.execute(node.block, env, frame);
+                    if (c.type !== "normal")
+                        return c;
+                }
+                catch (e) {
+                    // A cancellation is not a program error: it is the scope being unwound, and a catch
+                    // block must not be able to swallow it and keep working in a branch that lost a race.
+                    if (e instanceof Cancelled)
+                        throw e;
+                    const handlerNode = node.handler;
+                    if (handlerNode === null || handlerNode === undefined)
+                        throw e;
+                    const catchEnv = new Env(env);
+                    if (handlerNode.param !== null && handlerNode.param !== undefined) {
+                        await this.bindPattern(handlerNode.param, toProgramError(e), catchEnv, frame, false);
+                    }
+                    const c = await this.executeBlock(handlerNode.body, catchEnv, frame);
+                    if (c.type !== "normal")
+                        return c;
+                }
+                finally {
+                    if (node.finalizer !== null && node.finalizer !== undefined) {
+                        await this.execute(node.finalizer, env, frame);
+                    }
+                }
+                return NORMAL;
+            }
+            case "SwitchStatement": {
+                const disc = await this.evaluate(node.discriminant, env, frame);
+                const cases = node.cases;
+                const switchEnv = new Env(env);
+                let matched = false;
+                for (const c of cases) {
+                    if (!matched) {
+                        if (c.test === null || c.test === undefined)
+                            matched = true;
+                        else if (Object.is(await this.evaluate(c.test, switchEnv, frame), disc))
+                            matched = true;
+                    }
+                    if (!matched)
+                        continue;
+                    for (const s of c.consequent ?? []) {
+                        const comp = await this.execute(s, switchEnv, frame);
+                        if (comp.type === "break")
+                            return NORMAL;
+                        if (comp.type !== "normal")
+                            return comp;
+                    }
+                }
+                return NORMAL;
+            }
+            case "EmptyStatement":
+                return NORMAL;
+            default:
+                throw new RuntimeFault("L1000", `unsupported statement ${node.type}`);
+        }
+    }
+}
+// ---- helpers -------------------------------------------------------------------------------------
+function applyBinary(op, l, r) {
+    switch (op) {
+        case "===":
+            return Object.is(l, r) || l === r;
+        case "!==":
+            return !(l === r);
+        case "<":
+            return l < r;
+        case "<=":
+            return l <= r;
+        case ">":
+            return l > r;
+        case ">=":
+            return l >= r;
+        case "+":
+            return typeof l === "string" || typeof r === "string"
+                ? String(l) + String(r)
+                : l + r;
+        case "-":
+            return l - r;
+        case "*":
+            return l * r;
+        case "/":
+            return l / r;
+        case "%":
+            return l % r;
+        default:
+            throw new RuntimeFault("L1000", `unsupported operator ${op}`);
+    }
+}
+/** What a `catch` block sees: a plain record, because programs branch on data, not on classes. */
+function toProgramError(e) {
+    if (e instanceof EffectError) {
+        return deepFreeze({ code: e.code, kind: e.kind, message: e.message, ...(e.detail !== undefined ? { detail: e.detail } : {}) });
+    }
+    if (e instanceof RuntimeFault)
+        return deepFreeze({ code: e.code, kind: "runtime", message: e.message });
+    if (e !== null && typeof e === "object")
+        return e;
+    return deepFreeze({ code: "L4000", kind: "thrown", message: String(e) });
+}
+// ---- the public entry point -------------------------------------------------------------------------
+/**
+ * Run a program.
+ *
+ * A run pins to the content hash of its SOURCE, which is why prompts, schemas, and model config
+ * are covered: they are in the source. Passing an existing journal resumes rather than starts.
+ */
+export async function run(source, options) {
+    const { ast } = validate(source, options.file);
+    const programHash = digest({ source });
+    const interp = new Interpreter(ast, options, programHash);
+    const frame = new Frame(new KeyScope(), new RunClock(options.handler.now()), new Signal());
+    const env = new Env(null);
+    installGlobals(env, interp, frame);
+    const completion = await interp.executeBlock(ast, env, frame);
+    return {
+        value: completion.type === "return" ? completion.value : undefined,
+        journal: interp.journal,
+        programHash,
+        steps: interp.stepCount,
+    };
+}
+/** Re-run a program against an existing journal. Journalled effects return recorded results. */
+export async function resume(source, journal, options) {
+    journal.resetConsumed();
+    return await run(source, { ...options, journal });
+}
+function installGlobals(env, interp, rootFrame) {
+    const fn = (impl) => async (frame, args) => impl(frame, args);
+    // Pure primitives: a channel name is a name, so naming one costs nothing and journals nothing.
+    env.declare("channel", fn((_f, a) => ({ channel: a[0] })), false);
+    env.declare("run", fn(() => ({ id: interp.options.runId, programHash: interp.programHash })), false);
+    // Event constructors are pure descriptors; awaiting them is `wait`.
+    env.declare("replied", fn((_f, a) => ({ event: "replied", agent: a[0].agent })), false);
+    env.declare("message", fn((_f, a) => {
+        const ch = a[0].channel;
+        const opts = (a[1] ?? {});
+        return {
+            event: "message",
+            channel: ch,
+            ...(opts.from !== undefined ? { from: opts.from.agent } : {}),
+            ...(opts.matches !== undefined ? { matches: opts.matches } : {}),
+        };
+    }), false);
+    env.declare("idle", fn((_f, a) => ({ event: "idle", channel: a[0].channel, duration: a[1] })), false);
+    env.declare("down", fn((_f, a) => ({ event: "down", agent: a[0].agent })), false);
+    // Time and randomness, tamed. `now()` reads the branch's own run clock, which is the maximum
+    // endedAt over the effects this point actually awaited: time advances at effect boundaries as a
+    // property of the design rather than a rule anyone has to follow.
+    env.declare("now", fn((frame) => frame.clock.now()), false);
+    env.declare("random", fn((frame) => interp.prng.next(frame.keys.path)), false);
+    env.declare("randomInt", fn((frame, a) => Math.floor(interp.prng.next(frame.keys.path) * a[0])), false);
+    env.declare("pick", fn((frame, a) => {
+        const list = a[0];
+        return list[Math.floor(interp.prng.next(frame.keys.path) * list.length)];
+    }), false);
+    env.declare("duration", fn((_f, a) => parseDuration(a[0])), false);
+    // Records and arrays. Iteration order is insertion order, which is deterministic; sorting for
+    // a hash is a separate concern and happens in canonicalization, not here.
+    env.declare("keys", fn((_f, a) => Object.keys(a[0])), false);
+    env.declare("values", fn((_f, a) => Object.values(a[0])), false);
+    env.declare("entries", fn((_f, a) => Object.entries(a[0])), false);
+    env.declare("has", fn((_f, a) => Object.prototype.hasOwnProperty.call(a[0], a[1])), false);
+    env.declare("merge", fn((_f, a) => ({ ...a[0], ...a[1] })), false);
+    env.declare("len", fn((_f, a) => a[0].length), false);
+    env.declare("range", fn((_f, a) => Array.from({ length: a[0] }, (_, i) => i)), false);
+    env.declare("sum", fn((_f, a) => a[0].reduce((x, y) => x + y, 0)), false);
+    env.declare("concat", fn((_f, a) => a[0].concat(a[1])), false);
+    env.declare("slice", fn((_f, a) => a[0].slice(a[1], a[2])), false);
+    env.declare("reverse", fn((_f, a) => [...a[0]].reverse()), false);
+    env.declare("unique", fn((_f, a) => [...new Set(a[0])]), false);
+    env.declare("join", fn((_f, a) => a[0].join(a[1])), false);
+    // Higher-order builtins take an interpreter function, so they have to await it.
+    const higher = (impl) => async (frame, args) => await impl(frame, args[0], args[1]);
+    env.declare("map", higher(async (frame, list, f) => {
+        const out = [];
+        for (let i = 0; i < list.length; i += 1)
+            out.push(await f(frame, [list[i], i]));
+        return out;
+    }), false);
+    env.declare("filter", higher(async (frame, list, f) => {
+        const out = [];
+        for (let i = 0; i < list.length; i += 1)
+            if (await f(frame, [list[i], i]))
+                out.push(list[i]);
+        return out;
+    }), false);
+    env.declare("find", higher(async (frame, list, f) => {
+        for (let i = 0; i < list.length; i += 1)
+            if (await f(frame, [list[i], i]))
+                return list[i];
+        return null;
+    }), false);
+    env.declare("some", higher(async (frame, list, f) => {
+        for (let i = 0; i < list.length; i += 1)
+            if (await f(frame, [list[i], i]))
+                return true;
+        return false;
+    }), false);
+    env.declare("every", higher(async (frame, list, f) => {
+        for (let i = 0; i < list.length; i += 1)
+            if (!(await f(frame, [list[i], i])))
+                return false;
+        return true;
+    }), false);
+    // Strings and numbers.
+    env.declare("split", fn((_f, a) => a[0].split(a[1])), false);
+    env.declare("trim", fn((_f, a) => a[0].trim()), false);
+    env.declare("lower", fn((_f, a) => a[0].toLowerCase()), false);
+    env.declare("upper", fn((_f, a) => a[0].toUpperCase()), false);
+    env.declare("startsWith", fn((_f, a) => a[0].startsWith(a[1])), false);
+    env.declare("endsWith", fn((_f, a) => a[0].endsWith(a[1])), false);
+    env.declare("contains", fn((_f, a) => a[0].includes(a[1])), false);
+    env.declare("replace", fn((_f, a) => a[0].split(a[1]).join(a[2])), false);
+    env.declare("min", fn((_f, a) => Math.min(...a)), false);
+    env.declare("max", fn((_f, a) => Math.max(...a)), false);
+    env.declare("abs", fn((_f, a) => Math.abs(a[0])), false);
+    env.declare("floor", fn((_f, a) => Math.floor(a[0])), false);
+    env.declare("ceil", fn((_f, a) => Math.ceil(a[0])), false);
+    env.declare("round", fn((_f, a) => Math.round(a[0])), false);
+    env.declare("parseNumber", fn((_f, a) => Number(a[0])), false);
+    env.declare("assert", fn((_f, a) => {
+        if (!a[0])
+            throw new RuntimeFault("L4012", String(a[1] ?? "assertion failed"));
+        return null;
+    }), false);
+    env.declare("log", fn((frame, a) => {
+        interp.options.onLog?.({ scope: scopePathString(frame.keys.path), values: a });
+        return null;
+    }), false);
+    void rootFrame;
+}
+export { LangError, LangErrors };
+//# sourceMappingURL=interpret.js.map