@cotal-ai/lang 0.0.0 → 0.15.0

package/dist/keys.js

@@ -0,0 +1,105 @@
+/**
+ * Step keys: `(scope path, effect kind, step name, occurrence)`, with the input hash compared
+ * after lookup rather than folded into the key.
+ *
+ * Never execution position. Positional keying is the durable-execution field's documented worst
+ * production pain, and an LLM author restructures control flow freely, so positions are the one
+ * thing that will not survive an edit.
+ *
+ * The scope path exists for one reason: inside a concurrency combinator, branches interleave, so
+ * a per-run occurrence counter would race. Two branches both calling `turn(x, { name: "review" })`
+ * would fight over occurrence 0 and the winner would depend on wall-clock timing, which is
+ * exactly the nondeterminism replay cannot tolerate. Each branch therefore gets its own counter
+ * namespace, and a combinator's own occurrence is allocated synchronously at the call, which sits
+ * in already-deterministic code.
+ */
+import { createHash } from "node:crypto";
+import { canonicalize } from "json-canonicalize";
+/** `sha256:<hex>` over the RFC 8785 canonical form, matching the digest discipline used for
+ *  contract artifacts elsewhere in the repo. */
+export const DIGEST_PREFIX = "sha256:";
+/**
+ * The identity a handler submits under, written on the pending entry BEFORE the handler runs.
+ *
+ * Four components, each load-bearing rather than defensive. `runId`, because two runs reaching the
+ * same step with the same inputs would otherwise derive the same id and collide at a caller-scoped
+ * idempotency boundary. `attempt`, because escalation mints twice under one entry, so the second
+ * mint needs a second identity that is still derivable before it happens. The step key and input
+ * hash are what make it the identity of THIS step's THIS call.
+ *
+ * base64url, not the `sha256:<hex>` form this carried first: an endpoint id token is
+ * `[A-Za-z0-9_-]{1,64}`, and that form is 71 characters with a colon in it, so it was never a
+ * legal id. This is 43 characters in exactly that alphabet, with no `.` to confuse the
+ * dot-separated subject a goal id rides.
+ */
+export function requestId(runId, key, inputHash, attempt = 0) {
+    return createHash("sha256")
+        .update(canonicalize([runId, stepKeyString(key), inputHash, attempt]), "utf8")
+        .digest("base64url");
+}
+export function digest(value) {
+    return DIGEST_PREFIX + createHash("sha256").update(canonicalize(value), "utf8").digest("hex");
+}
+function frameString(f) {
+    const named = f.name === null ? f.kind : `${f.kind}:${f.name}`;
+    return `/${named}#${f.occurrence}/b:${f.branch}`;
+}
+/** The canonical string form, used in the journal, the trace, and error messages. */
+export function scopePathString(scope) {
+    return scope.map(frameString).join("");
+}
+export function stepKeyString(key) {
+    const named = key.name === "" ? key.kind : `${key.kind}:${key.name}`;
+    return `${scopePathString(key.scope)}/${named}#${key.occurrence}`;
+}
+export function stepKeyEquals(a, b) {
+    return stepKeyString(a) === stepKeyString(b);
+}
+/**
+ * One counter namespace. A run has one at the root, and every branch of every concurrency scope
+ * gets its own child.
+ *
+ * Both counters are allocated synchronously at the call site, before the first await. That is the
+ * whole determinism argument: the allocating code is either sequential or is itself inside an
+ * already-deterministic namespace, so no two allocations can race.
+ */
+export class KeyScope {
+    path;
+    effectCounts = new Map();
+    scopeCounts = new Map();
+    constructor(path = []) {
+        this.path = path;
+    }
+    /** Allocate the next occurrence for an effect in this namespace, and build its key. */
+    nextEffect(kind, name = "") {
+        const tag = `${kind}:${name}`;
+        const occurrence = this.effectCounts.get(tag) ?? 0;
+        this.effectCounts.set(tag, occurrence + 1);
+        return { scope: this.path, kind, name, occurrence };
+    }
+    /**
+     * Allocate the next occurrence for a concurrency scope entered from this namespace. Call once
+     * per combinator call, then {@link branch} once per branch.
+     */
+    nextScope(kind, name = null) {
+        const tag = `${kind}:${name ?? ""}`;
+        const occurrence = this.scopeCounts.get(tag) ?? 0;
+        this.scopeCounts.set(tag, occurrence + 1);
+        return occurrence;
+    }
+    /** The child namespace for one branch of a scope opened from here. */
+    branch(kind, name, occurrence, branchKey) {
+        return new KeyScope([...this.path, { kind, name, occurrence, branch: branchKey }]);
+    }
+}
+/**
+ * The branch keys for a combinator's argument. The record form is the default because its keys
+ * survive both reordering and insertion; the array form is keyed by index, which shifts when a
+ * branch is inserted, and the validator lints it.
+ */
+export function branchKeys(branches) {
+    return Array.isArray(branches)
+        ? branches.map((_, i) => String(i))
+        : Object.keys(branches);
+}
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAwBjD;gDACgD;AAChD,MAAM,CAAC,MAAM,aAAa,GAAG,SAAkB,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,GAAY,EAAE,SAAiB,EAAE,OAAO,GAAG,CAAC;IACnF,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,YAAY,CAAC,CAAC,KAAK,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC;SAC7E,MAAM,CAAC,WAAW,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,KAAc;IACnC,OAAO,aAAa,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChG,CAAC;AAED,SAAS,WAAW,CAAC,CAAa;IAChC,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/D,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,UAAU,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC;AACnD,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,eAAe,CAAC,KAA4B;IAC1D,OAAO,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,GAAY;IACxC,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;IACrE,OAAO,GAAG,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,CAAU,EAAE,CAAU;IAClD,OAAO,aAAa,CAAC,CAAC,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,QAAQ;IAIE;IAHJ,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEzD,YAAqB,OAA8B,EAAE;QAAhC,SAAI,GAAJ,IAAI,CAA4B;IAAG,CAAC;IAEzD,uFAAuF;IACvF,UAAU,CAAC,IAAgB,EAAE,IAAI,GAAG,EAAE;QACpC,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;QAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,CAAC,CAAC,CAAC;QAC3C,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IACtD,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,IAAe,EAAE,OAAsB,IAAI;QACnD,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,IAAI,IAAI,EAAE,EAAE,CAAC;QACpC,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,CAAC,CAAC,CAAC;QAC1C,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,sEAAsE;IACtE,MAAM,CAAC,IAAe,EAAE,IAAmB,EAAE,UAAkB,EAAE,SAAiB;QAChF,OAAO,IAAI,QAAQ,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;IACrF,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,QAAgE;IACzF,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;QAC5B,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACnC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,QAAmC,CAAC,CAAC;AACvD,CAAC"}

package/dist/primitives.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The effect primitives and the builtins, as data.
+ *
+ * One table drives four things that must never disagree: the validator's call-shape checks, the
+ * error catalog's callee documentation, the interpreter's dispatch, and the derived flowchart's
+ * node kinds. Keeping them in one place is why an unknown option key can answer with a full
+ * signature instead of a shrug.
+ */
+import type { CalleeDoc } from "./errors.js";
+/** The journalled effect kinds. `channel` is pure and deliberately absent. */
+export declare const EFFECT_KINDS: readonly ["spawn", "turn", "ask", "checkpoint", "sleep", "wait", "notify", "monitor", "conclave"];
+export type EffectKind = (typeof EFFECT_KINDS)[number];
+/** Which of a call's inputs decide whether a recorded result is still valid (design doc 5.12). */
+export interface PrimitiveSpec extends CalleeDoc {
+    /** The effect kind journalled, or null for a pure primitive that writes no entry. */
+    readonly kind: EffectKind | null;
+    /** A step name is required, not merely allowed. */
+    readonly nameRequired: boolean;
+    /** Every accepted option key. Bags are closed: anything else is L3011. */
+    readonly options: readonly string[];
+    /** The argument index the option bag occupies. Fixed per primitive, never "the last record":
+     *  `notify(agents, fact, opts)` and `checkpoint(name, prompt, opts)` both take a record in an
+     *  earlier position, and treating that as options would reject perfectly good data. */
+    readonly optionsAt: number;
+    /**
+     * Option keys folded into the input hash. Everything else only steered live execution.
+     *
+     * NORMATIVE AND EXECUTED. This was documentation for a while, and drifted: the interpreter grew
+     * a projection per primitive and this table stayed at whatever it said on the day it was written,
+     * so "align interpret to the table" was a change that would have reintroduced the very holes the
+     * projections closed. `options.smoke` now edits each key on a resumed run and requires exactly
+     * the keys listed here to raise L5001, which is what makes the table a claim rather than a note.
+     */
+    readonly hashedOptions: readonly string[];
+    /**
+     * Keys whose VALUE decides whether they are hashed: listed here with the values that put them
+     * into the projection, absent from `hashedOptions` because they are not always in it.
+     *
+     * There is exactly one of these and it is the subtlest rule in the table. `onExpiry` chooses how
+     * to READ a recorded expiry at `fail` and `proceed`, which is a reapply and must replay clean;
+     * at `escalate` it MINTS A SECOND EFFECT, which is a different question being asked and must
+     * diverge. Flattening that either way breaks something real: hash it always and editing `fail`
+     * to `proceed` stops working, hash it never and switching an answered checkpoint to `escalate`
+     * silently keeps the old answer.
+     */
+    readonly hashedValues?: Readonly<Record<string, readonly unknown[]>>;
+    /** True when the positional subject is part of the input hash. */
+    readonly hashesSubject: boolean;
+    /** This primitive opens a concurrency scope, so it pushes a scope frame. */
+    readonly opensScope: boolean;
+}
+export declare const PRIMITIVES: Readonly<Record<string, PrimitiveSpec>>;
+/** Event constructors. Pure: they build a descriptor and perform no effect. */
+export declare const EVENT_CONSTRUCTORS: Readonly<Record<string, CalleeDoc>>;
+/** Pure primitives that write no journal entry. */
+export declare const PURE_PRIMITIVES: Readonly<Record<string, CalleeDoc>>;
+/** The builtin library. Small on purpose (design doc 4). */
+export declare const BUILTINS: readonly string[];
+/** Every name the program may reference without defining it, and may never shadow. */
+export declare const RESERVED_NAMES: ReadonlySet<string>;
+/** Host globals a program might reach for out of habit, each rejected by name (L2012). */
+export declare const FORBIDDEN_GLOBALS: ReadonlySet<string>;
+/** The Promise API, rejected separately so its error can point at the right replacement (L2011). */
+export declare const PROMISE_NAMES: ReadonlySet<string>;
+/** Step names: kebab-case, 1 to 64 characters. */
+export declare const STEP_NAME_RE: RegExp;
+/**
+ * The bound on a `notify` fact.
+ *
+ * `notify` is the only primitive that moves program-authored bytes toward an agent's context, so
+ * an unconstrained field here would be scripted payloads through the side door and the first
+ * non-negotiable would hold everywhere except the one place it is easiest to break. Eight short
+ * scalars rendered as a labelled table is not enough room to write an instruction, which is the
+ * property we want.
+ */
+export declare const NOTIFY_BOUND: Readonly<{
+    /** `decision` and `outcome` are tokens, not prose. */
+    tokenRe: RegExp;
+    detailKeyRe: RegExp;
+    maxDetailKeys: 8;
+    maxDetailStringLength: 128;
+}>;
+export declare function primitiveDoc(name: string): CalleeDoc | undefined;
+//# sourceMappingURL=primitives.d.ts.map

package/dist/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../src/primitives.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,8EAA8E;AAC9E,eAAO,MAAM,YAAY,mGAUf,CAAC;AACX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,kGAAkG;AAClG,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACjC,mDAAmD;IACnD,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;2FAEuF;IACvF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC,CAAC,CAAC;IACrE,kEAAkE;IAClE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAmK7D,CAAC;AAEH,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAqBjE,CAAC;AAEH,mDAAmD;AACnD,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAW9D,CAAC;AAEH,4DAA4D;AAC5D,eAAO,MAAM,QAAQ,EAAE,SAAS,MAAM,EAcpC,CAAC;AAEH,sFAAsF;AACtF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAO7C,CAAC;AAEH,0FAA0F;AAC1F,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAKhD,CAAC;AAEH,oGAAoG;AACpG,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,CAAwB,CAAC;AAEvE,kDAAkD;AAClD,eAAO,MAAM,YAAY,QAAyC,CAAC;AAEnE;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY;IACvB,sDAAsD;;;;;EAKtD,CAAC;AAEH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAEhE"}

package/dist/primitives.js

@@ -0,0 +1,265 @@
+/**
+ * The effect primitives and the builtins, as data.
+ *
+ * One table drives four things that must never disagree: the validator's call-shape checks, the
+ * error catalog's callee documentation, the interpreter's dispatch, and the derived flowchart's
+ * node kinds. Keeping them in one place is why an unknown option key can answer with a full
+ * signature instead of a shrug.
+ */
+/** The journalled effect kinds. `channel` is pure and deliberately absent. */
+export const EFFECT_KINDS = [
+    "spawn",
+    "turn",
+    "ask",
+    "checkpoint",
+    "sleep",
+    "wait",
+    "notify",
+    "monitor",
+    "conclave",
+];
+export const PRIMITIVES = Object.freeze({
+    spawn: {
+        kind: "spawn",
+        nameRequired: false,
+        options: ["name", "worktree", "join", "role", "permits", "supervise", "onFork"],
+        optionsAt: 1,
+        hashedOptions: ["worktree", "join", "role"],
+        hashesSubject: true,
+        opensScope: false,
+        signature: "spawn(persona, { name?, worktree?, join?, role?, permits?, supervise?, onFork? }) -> AgentHandle",
+        doc: "Bring an agent into the run. Permits are budgets whose violation is catchable; supervise is a declarative restart policy.",
+        example: 'const builder = await spawn("builder", { worktree: "wt-1", join: [team] })',
+    },
+    turn: {
+        kind: "turn",
+        nameRequired: true,
+        options: ["name", "deadline"],
+        optionsAt: 1,
+        hashedOptions: ["deadline"],
+        hashesSubject: true,
+        opensScope: false,
+        signature: "turn(agent, { name, deadline? }) -> { status, to?, note?, at }",
+        doc: "Wake an agent for one turn. It reads its own channels and speaks for itself; the result is its yield status, one of done, blocked, or handoff.",
+        example: 'const r = await turn(builder, { name: "build" })\nif (r.status === "blocked") { await turn(planner, { name: "unblock" }) }',
+    },
+    ask: {
+        kind: "ask",
+        nameRequired: true,
+        options: ["name", "schema", "deadline", "attempts"],
+        optionsAt: 1,
+        hashedOptions: ["schema", "deadline", "attempts"],
+        hashesSubject: true,
+        opensScope: false,
+        signature: "ask(agent, { name, schema, deadline?, attempts? }) -> record",
+        doc: "The narrow case where the program itself needs a value. The agent publishes a record, the program awaits it, and the record is schema-checked.",
+        example: 'const est = await ask(planner, { name: "estimate", schema: { days: "number" } })',
+    },
+    checkpoint: {
+        kind: "checkpoint",
+        nameRequired: true,
+        options: ["schema", "timeout", "onExpiry", "to"],
+        optionsAt: 2,
+        // `to` is unconditionally hashed because it cannot legally appear without `escalate` (L3044),
+        // so wherever it exists it is addressing a mint. `onExpiry` is the conditional one.
+        hashedOptions: ["schema", "timeout", "to"],
+        hashedValues: { onExpiry: ["escalate"] },
+        hashesSubject: true,
+        opensScope: false,
+        signature: 'checkpoint(name, prompt, { schema?, timeout?, onExpiry?, to? }) -> { status, value?, by?, at, artifact? }',
+        doc: "A durable pause a human or another agent resolves from anywhere, raced against a durable timer. onExpiry is fail, proceed, or escalate.",
+        example: 'const ok = await checkpoint("approve-plan", "Approve the plan?", { timeout: "10m", onExpiry: "proceed" })',
+    },
+    sleep: {
+        kind: "sleep",
+        nameRequired: false,
+        options: ["name"],
+        optionsAt: 1,
+        hashedOptions: [],
+        // The duration is the subject and it IS hashed: a resumed run reads 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 said `false` while the interpreter hashed it.
+        hashesSubject: true,
+        opensScope: false,
+        signature: "sleep(duration, { name? }) -> null",
+        doc: "A durable timer. A resumed run does not re-sleep an elapsed sleep; use fork to re-run from this step.",
+        example: 'await sleep("30m")',
+    },
+    wait: {
+        kind: "wait",
+        nameRequired: false,
+        options: ["name", "timeout"],
+        optionsAt: 1,
+        // A recorded null means "not within THIS timeout", never "never".
+        hashedOptions: ["timeout"],
+        hashesSubject: true,
+        opensScope: false,
+        signature: "wait(event, { name?, timeout? }) -> value | null",
+        doc: "Await one event. Resolves null on timeout rather than throwing, which is what makes ?? the recovery operator.",
+        example: 'const m = await wait(message(team, { from: builder }), { name: "await-build", timeout: "20m" })\n           ?? await turn(planner, { name: "chase" })',
+    },
+    notify: {
+        kind: "notify",
+        nameRequired: false,
+        options: ["name"],
+        optionsAt: 2,
+        hashedOptions: [],
+        hashesSubject: true,
+        opensScope: false,
+        signature: "notify(agents, fact, { name? }) -> null",
+        doc: "Tell agents about a branch decision. It writes a notice onto the run, rendered ahead of each agent's next turn; it is never a channel message.",
+        example: 'await notify([planner], { decision: "build", outcome: "blocked" })',
+    },
+    monitor: {
+        kind: "monitor",
+        nameRequired: false,
+        options: ["name"],
+        optionsAt: 1,
+        hashedOptions: [],
+        hashesSubject: true,
+        opensScope: false,
+        signature: "monitor(agent, { name? }) -> null",
+        doc: "Register interest in an agent's health, after which down(agent) is an ordinary awaitable event a concurrent branch can watch.",
+        example: 'await monitor(builder)\nconst d = await wait(down(builder), { name: "gone", timeout: "1h" })',
+    },
+    parallel: {
+        kind: null,
+        nameRequired: false,
+        options: ["name"],
+        optionsAt: 1,
+        hashedOptions: [],
+        hashesSubject: false,
+        opensScope: true,
+        signature: "parallel(branches, { name? }) -> results",
+        doc: "Run branches concurrently and settle all of them. The record form is the default; array branches are keyed by index and are linted. The first rejection cancels the rest.",
+        example: 'await parallel({ lint: () => turn(linter, { name: "lint" }),\n                 tests: () => turn(tester, { name: "tests" }) }, { name: "checks" })',
+    },
+    race: {
+        kind: null,
+        nameRequired: false,
+        options: ["name"],
+        optionsAt: 1,
+        hashedOptions: [],
+        hashesSubject: false,
+        opensScope: true,
+        signature: "race(branches, { name? }) -> { index, value }",
+        doc: "Run branches concurrently and take the first to settle. Losers are cancelled by semantics: they perform no new effects, and an in-flight agent reply completes and is ignored.",
+        example: 'await race({ reply: () => wait(replied(builder), { timeout: "20m" }),\n             giveUp: () => sleep("1h") }, { name: "await-or-move-on" })',
+    },
+    fanOut: {
+        kind: null,
+        nameRequired: true,
+        options: ["name", "key"],
+        optionsAt: 2,
+        hashedOptions: [],
+        hashesSubject: false,
+        opensScope: true,
+        signature: "fanOut(items, fn, { name, key? }) -> results",
+        doc: "Run fn(item, index) per item concurrently. key maps an item to the stable string that names its journal namespace, and defaults to a record item's string id.",
+        example: 'await fanOut(["security", "perf"], (lens) => turn(reviewers[lens], { name: "review" }),\n             { name: "reviews", key: (lens) => lens })',
+    },
+    conclave: {
+        kind: "conclave",
+        nameRequired: true,
+        options: ["name", "channel"],
+        optionsAt: 2,
+        hashedOptions: [],
+        hashesSubject: true,
+        opensScope: true,
+        signature: "conclave(members, fn, { name, channel? }) -> result",
+        doc: "Open a scoped sub-team: create a conclave channel, join the members, run fn with that channel, then have them leave. It scopes the derived flowchart the same way it scopes the journal.",
+        example: 'await conclave([a, b], (ch) => turn(a, { name: "huddle" }), { name: "triage" })',
+    },
+});
+/** Event constructors. Pure: they build a descriptor and perform no effect. */
+export const EVENT_CONSTRUCTORS = Object.freeze({
+    replied: {
+        signature: "replied(agent) -> Event",
+        doc: "The agent finished a reply.",
+        example: 'await wait(replied(builder), { timeout: "20m" })',
+    },
+    message: {
+        signature: "message(channel, { from?, matches? }) -> Event",
+        doc: "A message landed on the channel, optionally filtered by sender or content match.",
+        example: 'await wait(message(team, { from: builder }), { timeout: "20m" })',
+    },
+    idle: {
+        signature: "idle(channel, duration) -> Event",
+        doc: "The channel went quiet for the duration.",
+        example: 'await wait(idle(team, "10m"), { timeout: "1h" })',
+    },
+    down: {
+        signature: "down(agent) -> Event",
+        doc: "A monitored agent died. Carries the reason.",
+        example: 'const d = await wait(down(builder), { timeout: "1h" })',
+    },
+});
+/** Pure primitives that write no journal entry. */
+export const PURE_PRIMITIVES = Object.freeze({
+    channel: {
+        signature: "channel(name) -> ChannelHandle",
+        doc: "Name a channel. Pure: a name is a name, and membership is what costs something.",
+        example: 'const team = channel("feat-auth")',
+    },
+    run: {
+        signature: "run() -> { id, programHash, startedAt }",
+        doc: "This run's own metadata.",
+        example: "const id = run().id",
+    },
+});
+/** The builtin library. Small on purpose (design doc 4). */
+export const BUILTINS = Object.freeze([
+    // records
+    "keys", "values", "entries", "has", "merge",
+    // arrays
+    "len", "map", "filter", "find", "some", "every", "sort", "slice", "concat", "join",
+    "reverse", "unique", "range", "sum",
+    // strings
+    "split", "trim", "lower", "upper", "startsWith", "endsWith", "contains", "replace",
+    // numbers
+    "min", "max", "abs", "floor", "ceil", "round", "parseNumber",
+    // data and control
+    "json", "assert", "log",
+    // tamed nondeterminism
+    "random", "randomInt", "pick", "now", "duration",
+]);
+/** Every name the program may reference without defining it, and may never shadow. */
+export const RESERVED_NAMES = new Set([
+    ...Object.keys(PRIMITIVES),
+    ...Object.keys(EVENT_CONSTRUCTORS),
+    ...Object.keys(PURE_PRIMITIVES),
+    ...BUILTINS,
+    "any",
+    "all",
+]);
+/** Host globals a program might reach for out of habit, each rejected by name (L2012). */
+export const FORBIDDEN_GLOBALS = new Set([
+    "globalThis", "global", "window", "self", "process", "console", "fetch", "Date", "Math",
+    "RegExp", "Object", "Reflect", "Proxy", "Symbol", "WeakMap", "WeakSet", "Function",
+    "setTimeout", "setInterval", "setImmediate", "queueMicrotask", "require", "module",
+    "exports", "__dirname", "__filename", "Buffer", "crypto", "performance", "structuredClone",
+]);
+/** The Promise API, rejected separately so its error can point at the right replacement (L2011). */
+export const PROMISE_NAMES = new Set(["Promise"]);
+/** Step names: kebab-case, 1 to 64 characters. */
+export const STEP_NAME_RE = /^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$/;
+/**
+ * The bound on a `notify` fact.
+ *
+ * `notify` is the only primitive that moves program-authored bytes toward an agent's context, so
+ * an unconstrained field here would be scripted payloads through the side door and the first
+ * non-negotiable would hold everywhere except the one place it is easiest to break. Eight short
+ * scalars rendered as a labelled table is not enough room to write an instruction, which is the
+ * property we want.
+ */
+export const NOTIFY_BOUND = Object.freeze({
+    /** `decision` and `outcome` are tokens, not prose. */
+    tokenRe: STEP_NAME_RE,
+    detailKeyRe: /^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$/,
+    maxDetailKeys: 8,
+    maxDetailStringLength: 128,
+});
+export function primitiveDoc(name) {
+    return PRIMITIVES[name] ?? EVENT_CONSTRUCTORS[name] ?? PURE_PRIMITIVES[name];
+}
+//# sourceMappingURL=primitives.js.map

package/dist/primitives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.js","sourceRoot":"","sources":["../src/primitives.ts"],"names":[],"mappings":"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"}

package/dist/sim.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The simulation handler: the same interpreter, a different handler.
+ *
+ * That is the whole design, and it is why simulation is v1 scope rather than a later nicety. It
+ * costs one implementation of an interface the runtime needed anyway, and it is the test harness
+ * for everything else: scripted turns, instant sleeps, injected checkpoint answers, and injected
+ * faults, with no broker, no agents, and no wall-clock waiting.
+ *
+ * The rule that makes it worth trusting: **an unscripted effect is an error, never a default**. A
+ * simulator that invents a plausible turn result is a simulator that green-lights broken programs,
+ * which is worse than having no simulator at all.
+ */
+import type { AgentHandleValue, AskRequest, ChannelHandleValue, CheckpointRequest, CheckpointRaw, CheckpointResultValue, ConclaveRequest, EffectContext, EffectHandler, MonitorRequest, NotifyRequest, SleepRequest, SpawnRequest, TurnRequest, TurnResultValue, WaitRequest } from "./effects.js";
+/** A scripted outcome: one value used for every occurrence, or one per occurrence in order. */
+export type Scripted<T> = T | readonly T[];
+export interface SimFault {
+    /** The step key, either in full (`/parallel:x#0/b:a/turn:build#1`) or short (`turn:build#1`). */
+    readonly at: string;
+    readonly kind: string;
+    readonly code?: string;
+    readonly message?: string;
+}
+export interface SimScript {
+    readonly turns?: Readonly<Record<string, Scripted<TurnResultValue>>>;
+    readonly asks?: Readonly<Record<string, Scripted<unknown>>>;
+    readonly checkpoints?: Readonly<Record<string, Scripted<CheckpointResultValue>>>;
+    /** Keyed by the `wait` step's name. A scripted `null` is a timeout, which is a choice. */
+    readonly events?: Readonly<Record<string, Scripted<unknown>>>;
+    readonly clock?: {
+        readonly start?: number;
+        /** Virtual time each turn consumes. Default "5m". */
+        readonly turn?: string;
+        readonly ask?: string;
+        readonly checkpoint?: string;
+        readonly wait?: string;
+    };
+    readonly faults?: readonly SimFault[];
+}
+export declare class SimUnscriptedError extends Error {
+    readonly code: string;
+    readonly stepKey: string;
+    constructor(code: string, stepKey: string, message: string);
+}
+interface Consumption {
+    readonly table: string;
+    readonly name: string;
+    readonly occurrence: number;
+}
+/**
+ * The simulation handler.
+ *
+ * Every effect resolves from the script or fails loudly. Sleeps are instant and advance the
+ * virtual clock by the duration the program asked for, so a program that waits four hours is
+ * tested in microseconds without pretending the wait did not happen.
+ */
+export declare class SimHandler implements EffectHandler {
+    readonly script: SimScript;
+    private virtualNow;
+    private readonly occurrences;
+    private readonly consumed;
+    private readonly agents;
+    constructor(script?: SimScript);
+    now(): number;
+    /** Advance virtual time. Sleeps do this by their full duration; turns by a scripted default. */
+    advance(ms: number): void;
+    private advanceBy;
+    /** Which occurrence of this (table, name) we are on, counted per simulated run. */
+    private nextOccurrence;
+    private checkFault;
+    /**
+     * Resolve one scripted outcome, or fail. `name` falls back to the effect kind for unnamed
+     * steps, which is the same fallback the journal key uses, so a script and a real trace read
+     * against each other without translation.
+     */
+    private resolve;
+    spawn(req: SpawnRequest, ctx: EffectContext): Promise<AgentHandleValue>;
+    turn(_req: TurnRequest, ctx: EffectContext): Promise<TurnResultValue>;
+    ask(_req: AskRequest, ctx: EffectContext): Promise<unknown>;
+    /**
+     * Reports WHAT HAPPENED and never whether it throws. A script says `resolved` or `expired`; the
+     * interpreter journals that and applies today's `onExpiry` afterwards. A simulator that decided
+     * the disposition would bake it into the record exactly as a production handler would.
+     */
+    checkpoint(_req: CheckpointRequest, ctx: EffectContext): Promise<CheckpointRaw>;
+    /** Instant, and honest: the clock moves by exactly what the program asked to wait. */
+    sleep(req: SleepRequest, ctx: EffectContext): Promise<null>;
+    wait(req: WaitRequest, ctx: EffectContext): Promise<unknown | null>;
+    notify(_req: NotifyRequest, ctx: EffectContext): Promise<null>;
+    monitor(_req: MonitorRequest, ctx: EffectContext): Promise<null>;
+    openConclave(req: ConclaveRequest, ctx: EffectContext): Promise<ChannelHandleValue>;
+    closeConclave(_req: ConclaveRequest, ctx: EffectContext): Promise<null>;
+    /**
+     * Script entries the run never reached. Usually a renamed step, which is worth saying out loud:
+     * a script that silently stops matching is a test that silently stops testing.
+     */
+    unusedScript(): readonly string[];
+    /** Every effect the run performed, in order, for the dry-run report. */
+    performed(): readonly Consumption[];
+}
+export {};
+//# sourceMappingURL=sim.d.ts.map

package/dist/sim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim.d.ts","sourceRoot":"","sources":["../src/sim.ts"],"names":[],"mappings":"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"}