@cotal-ai/runtime 0.0.1 → 0.25.0

package/dist/engine-host.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The version-2 entry for the driver's engine table: a run on the compiled engine, hosted.
+ *
+ * What this file owns is exactly the three decisions the engine leaves to its host, and nothing
+ * the engine already decided:
+ *
+ *   - THE TRANSFORM STEP. The driver holds the author's source (a run record names the program an
+ *     author wrote), so the module the engine executes is produced here, per attempt, by the pure
+ *     `transform`. Nothing is cached: the transform re-validates, and a cached module would be a
+ *     second answer to "what does this source compile to" with no way to notice the disagreement.
+ *
+ *   - THE EVALUATOR CHOICE, made by naming the worker entry and refusing every alternative. The
+ *     entry is the compiled `worker-entry.js` of the installed `@cotal-ai/lang` — the file whose
+ *     `lockdown()` and zero-endowment Compartment the engine suite grades — resolved through the
+ *     package's own exports map. There is no in-process route here on purpose: evaluating the
+ *     module in this process would either lock down the daemon's own realm or skip confinement,
+ *     and both are decisions nobody made. A missing artifact is a loud refusal naming the build
+ *     step, never a quiet fall back to the walker.
+ *
+ *   - WHERE THE EFFECTS LIVE. The driver's handler is a live object (sockets, a mesh client, a
+ *     lease-bound appender), so the run uses the BRIDGED route: handler and durable store stay in
+ *     this process, the thread forwards the seam over a MessagePort, and no credential enters the
+ *     isolate that holds the program. The pending-entry-durable-before-the-effect ordering is the
+ *     store's own await, unchanged, because the bridge preserves the async append contract.
+ *
+ * The driver's outcome contract is the walker's, so a failure that crosses the thread boundary is
+ * rehydrated into the class `drive()` grades: L5010 back into `JournalAppendRejected` (from the
+ * store failure this process itself just witnessed — the thread only reflected it), L5012 back
+ * into `RunReleased`, and everything else into an error carrying the same name, code and message
+ * it failed with inside the thread.
+ */
+import { type EffectHandler, type JournalEntry, type JournalStore, type RunPins, type RunResult } from "@cotal-ai/lang";
+export interface EngineHostRequest {
+    readonly source: string;
+    readonly runId: string;
+    readonly pins: RunPins;
+    readonly handler: EffectHandler;
+    readonly store: JournalStore;
+    /** The activated prefix: recorded entries for a resume, empty for a fresh run. */
+    readonly entries: readonly JournalEntry[];
+    readonly shouldStop: () => string | undefined;
+    readonly file?: string;
+    readonly seed?: string;
+    readonly effectCeiling?: number;
+    readonly stepBudget?: number;
+}
+/**
+ * The compiled worker entry of the installed `@cotal-ai/lang`, and the refusal when it is absent.
+ *
+ * `import.meta.resolve` answers from the exports map without touching the disk, so existence is
+ * checked here: in this repo the artifact exists only after `pnpm --filter @cotal-ai/lang
+ * build:emit`, and a driver that cannot name a confined evaluator does not get to invent one.
+ */
+export declare function resolveWorkerEntry(): URL;
+/** Run or resume a program on the compiled engine, with the walker's `RunResult`. */
+export declare function runOnHostedEngine(req: EngineHostRequest): Promise<RunResult>;
+//# sourceMappingURL=engine-host.d.ts.map

package/dist/engine-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-host.d.ts","sourceRoot":"","sources":["../src/engine-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,OAAO,EASL,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,OAAO,EACZ,KAAK,SAAS,EAEf,MAAM,gBAAgB,CAAC;AAoBxB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,GAAG,CAUxC;AAqDD,qFAAqF;AACrF,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CAsElF"}

package/dist/engine-host.js

@@ -0,0 +1,189 @@
+/**
+ * The version-2 entry for the driver's engine table: a run on the compiled engine, hosted.
+ *
+ * What this file owns is exactly the three decisions the engine leaves to its host, and nothing
+ * the engine already decided:
+ *
+ *   - THE TRANSFORM STEP. The driver holds the author's source (a run record names the program an
+ *     author wrote), so the module the engine executes is produced here, per attempt, by the pure
+ *     `transform`. Nothing is cached: the transform re-validates, and a cached module would be a
+ *     second answer to "what does this source compile to" with no way to notice the disagreement.
+ *
+ *   - THE EVALUATOR CHOICE, made by naming the worker entry and refusing every alternative. The
+ *     entry is the compiled `worker-entry.js` of the installed `@cotal-ai/lang` — the file whose
+ *     `lockdown()` and zero-endowment Compartment the engine suite grades — resolved through the
+ *     package's own exports map. There is no in-process route here on purpose: evaluating the
+ *     module in this process would either lock down the daemon's own realm or skip confinement,
+ *     and both are decisions nobody made. A missing artifact is a loud refusal naming the build
+ *     step, never a quiet fall back to the walker.
+ *
+ *   - WHERE THE EFFECTS LIVE. The driver's handler is a live object (sockets, a mesh client, a
+ *     lease-bound appender), so the run uses the BRIDGED route: handler and durable store stay in
+ *     this process, the thread forwards the seam over a MessagePort, and no credential enters the
+ *     isolate that holds the program. The pending-entry-durable-before-the-effect ordering is the
+ *     store's own await, unchanged, because the bridge preserves the async append contract.
+ *
+ * The driver's outcome contract is the walker's, so a failure that crosses the thread boundary is
+ * rehydrated into the class `drive()` grades: L5010 back into `JournalAppendRejected` (from the
+ * store failure this process itself just witnessed — the thread only reflected it), L5012 back
+ * into `RunReleased`, and everything else into an error carrying the same name, code and message
+ * it failed with inside the thread.
+ */
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { EffectError, Journal, JournalAppendRejected, RunReleased, assertNodeFloor, journalEntryKeyString, runInWorker, transform, } from "@cotal-ai/lang";
+/**
+ * How often the host polls its own stop conditions (work horizon, pause) with NO bridge traffic to
+ * ride on. The per-effect granularity the walker has does not come from this timer: every effect is
+ * bracketed by durable appends, and the store below asks `shouldStop` on each one, so the flag is
+ * current at every effect boundary the thread checks it at. What only the timer covers is a stop
+ * with no append coming to carry it: one arriving in the worker's boot window, after the upfront
+ * sample below but before the thread's first pre-effect check (measured: without the timer, one
+ * effect the stop should have prevented is dispatched), and one arriving while an effect is parked
+ * in this process for hours. The timer PUBLISHES; the run honours a published stop at its next
+ * pre-effect check, which is `shouldStop`'s one reader in the language, on both engines. Two
+ * consequences follow and are the language's own properties rather than this host's: a stop during
+ * a long PURE stretch waits for the next effect boundary or the fuel refusal (L4013), and a stop
+ * that lands after the run's LAST pre-effect check is published but never observed, on the walker
+ * exactly as here (measured, both engines). A stop read at the fuel yield would be a change to
+ * both engines, not to this host.
+ */
+const STOP_POLL_MS = 100;
+/**
+ * The compiled worker entry of the installed `@cotal-ai/lang`, and the refusal when it is absent.
+ *
+ * `import.meta.resolve` answers from the exports map without touching the disk, so existence is
+ * checked here: in this repo the artifact exists only after `pnpm --filter @cotal-ai/lang
+ * build:emit`, and a driver that cannot name a confined evaluator does not get to invent one.
+ */
+export function resolveWorkerEntry() {
+    const url = new URL(import.meta.resolve("@cotal-ai/lang/engine/worker-entry"));
+    if (!existsSync(fileURLToPath(url))) {
+        throw new Error(`the compiled engine's worker entry is not built: ${fileURLToPath(url)} does not exist. ` +
+            `The version-2 engine runs only the compiled artifact (its thread cannot load TypeScript sources); ` +
+            `build it with \`pnpm --filter @cotal-ai/lang build:emit\`.`);
+    }
+    return url;
+}
+/**
+ * A store wrapper that remembers the failure it threw, so the class the thread reports back as
+ * L5010 can be rebuilt from the facts THIS process witnessed rather than parsed out of a message.
+ */
+class WitnessedStore {
+    inner;
+    beforeAppend;
+    failure;
+    /** `beforeAppend` is the stop check riding the append: every effect begins with a pending append
+     *  and ends with a settled one, so asking here is the walker's own between-effects granularity. */
+    constructor(inner, beforeAppend) {
+        this.inner = inner;
+        this.beforeAppend = beforeAppend;
+    }
+    async append(entry) {
+        this.beforeAppend();
+        try {
+            await this.inner.append(entry);
+        }
+        catch (e) {
+            this.failure = { entry, reason: e };
+            throw e;
+        }
+    }
+}
+function rehydrate(failed, store) {
+    if (failed.code === "L5010") {
+        // The append that failed happened in this process; the thread's L5010 is its reflection. A
+        // reflection with no witnessed failure behind it means the two sides disagree about what
+        // happened, and that is said rather than papered over with a parsed message.
+        if (store.failure === undefined) {
+            return new Error(`the engine thread reported L5010 (journal append rejected) but this host's store recorded no failed append; the run cannot be graded: ${failed.message}`);
+        }
+        return new JournalAppendRejected(journalEntryKeyString(store.failure.entry), store.failure.entry.state, store.failure.reason);
+    }
+    if (failed.code === "L5012") {
+        return new RunReleased(failed.reason ?? failed.message);
+    }
+    // An effect failure carries its domain across whole, because callers branch on `kind` exactly as
+    // they do when the walker raises the same class in-process.
+    if (failed.code !== undefined && failed.kind !== undefined) {
+        return new EffectError(failed.code, failed.kind, failed.message, failed.detail);
+    }
+    const e = new Error(failed.message);
+    e.name = failed.name;
+    if (failed.code !== undefined)
+        e.code = failed.code;
+    return e;
+}
+/** Run or resume a program on the compiled engine, with the walker's `RunResult`. */
+export async function runOnHostedEngine(req) {
+    // The floor the engine itself enforces in the thread, asked here first: a driver below it must
+    // refuse BEFORE it stamps a fresh run with a version it cannot execute.
+    assertNodeFloor(process.versions.node);
+    const entry = resolveWorkerEntry();
+    const { module } = transform(req.source, req.file !== undefined ? { file: req.file } : {});
+    // Assigned right after the worker exists; every append comes FROM that worker, so no check can
+    // fire before the assignment. Publishing is idempotent and the reason is read where the run has
+    // always read it.
+    let publish = () => { };
+    const store = new WitnessedStore(req.store, () => {
+        const reason = req.shouldStop();
+        if (reason !== undefined)
+            publish(reason);
+    });
+    const worker = runInWorker({
+        source: req.source,
+        module,
+        runId: req.runId,
+        handler: "bridged",
+        pins: req.pins,
+        entries: req.entries,
+        ...(req.file !== undefined ? { file: req.file } : {}),
+        ...(req.seed !== undefined ? { seed: req.seed } : {}),
+        ...(req.effectCeiling !== undefined ? { effectCeiling: req.effectCeiling } : {}),
+        ...(req.stepBudget !== undefined ? { stepBudget: req.stepBudget } : {}),
+    }, { entry, bridge: { handler: req.handler, store } });
+    publish = (reason) => worker.stop(reason);
+    // A horizon that passed before the run began is published before the thread's first pre-effect
+    // check, so the run stops with ZERO effects — the same answer the walker gives.
+    const already = req.shouldStop();
+    if (already !== undefined)
+        worker.stop(already);
+    // The host's stop conditions with no bridge traffic to ride on; see STOP_POLL_MS. The callback
+    // runs on the timer's own stack, where a throwing `shouldStop` would otherwise become an
+    // UNCAUGHT exception that bypasses every catch the driver holds and leaves the worker running -
+    // the walker route surfaces the same throw inside the driver's try, so this route must answer
+    // the same way: stop the run, and re-raise the fault from the await below, on the caller's
+    // stack. (The same throw at an append boundary already answers honestly: the store's
+    // before-append check rejects that append, and the run is graded through the L5010 path.)
+    let pollFault;
+    const poll = setInterval(() => {
+        try {
+            const reason = req.shouldStop();
+            if (reason !== undefined)
+                worker.stop(reason);
+        }
+        catch (e) {
+            pollFault = e ?? new Error("the host's stop check threw a falsy value");
+            clearInterval(poll);
+            worker.stop("the host's stop check itself threw; the driver re-raises the fault");
+        }
+    }, STOP_POLL_MS);
+    try {
+        const result = await worker.done;
+        if (pollFault !== undefined)
+            throw pollFault;
+        if (!result.ok)
+            throw rehydrate(result, store);
+        return {
+            value: result.value,
+            journal: new Journal({ run: req.runId, entries: result.entries }),
+            programHash: result.programHash,
+            pins: result.pins,
+            steps: result.steps,
+        };
+    }
+    finally {
+        clearInterval(poll);
+    }
+}
+//# sourceMappingURL=engine-host.js.map

package/dist/engine-host.js.map

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

package/dist/fork.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Fork a run from a named step: the fork cut, and the two things a fork must not re-decide.
+ *
+ * `fork(runId, fromStepKey)` is the repair verb. It does not roll the parent back — the parent is
+ * untouched — it starts a NEW run that owns the parent's history up to a named step and re-runs from
+ * there. Two decisions inside that sentence carry the whole design:
+ *
+ * **The cut is computed by a DRY WALK IN MIGRATION MODE, and the mode is load-bearing rather than a
+ * default.** A resume's replay short-circuits a settled scope: it takes the scope's recorded outcome
+ * and never walks its branches, so every entry underneath it is accounted for in one step. That is
+ * exactly right for a resume, which only needs to get past it, and exactly wrong here — the step a
+ * caller wants to cut at can be INSIDE such a scope, and a walk that never entered it would either
+ * miss the cut entirely or sweep entries that come after the cut point into the prefix. A fork with a
+ * silently-too-large prefix is the worst available outcome: it looks like a fork, drives like a fork,
+ * and has already replayed the work the caller forked to avoid.
+ *
+ * **The prefix inherits the parent's pins UNCHANGED, seed included.** The child gets a new run id and
+ * `resolvePins` defaults a seed to the run id, so re-resolving pins for the child would reseed it —
+ * and a reseeded prefix redecides every pure draw inside history it was supposed to be copying. A
+ * parent that drew `left` would give a child that draws `right`, and nothing would diverge, because a
+ * `pick` is pure and no entry records it. So the parent's `RunPins` are copied verbatim; the fresh
+ * derivation begins at the frontier, which is what "fork" means.
+ *
+ * What this file does NOT do, named rather than implied:
+ *   - It does not respawn agents. `onFork` is specified to mint a fresh agent at the frontier, and
+ *     `spawn` rides the durable-action machinery this host does not have, so a cut containing a
+ *     spawn is REFUSED (L5019) rather than copied and hoped about.
+ *   - It does not cut worktree branches. There is no worktree plane in this tree; a caller that
+ *     asks for one is refused rather than told a branch exists.
+ *   - It does not record LINEAGE. The child's run record cannot say it is a fork of anything: a
+ *     run's spec has no such field, and inventing one changes the run record's shape — the kind of
+ *     change the `migration` record was raised for a decision on rather than made here.
+ *     `commitFork` reports `lineageRecorded: false` so the gap is something a caller reads rather
+ *     than something a reader has to notice.
+ */
+import type { KV } from "@nats-io/kv";
+import { Journal, type JournalEntry, type JournalInit, type JournalStore, type LookupVerdict, type RunPins, type StepKey } from "@cotal-ai/lang";
+/** One reason a fork was refused, carrying the code a reader repairs against — the `L` catalogue
+ *  in `@cotal-ai/lang`. */
+export interface ForkRefusal {
+    readonly code: string;
+    readonly step?: string;
+    readonly why: string;
+}
+export interface ForkPlan {
+    readonly parent: string;
+    readonly child: string;
+    readonly at: number;
+    readonly actor: string;
+    /** The step the child re-runs FROM. Never part of the cut: the cut is what happened before it. */
+    readonly fromStep: string;
+    /** The parent's pins, verbatim — what the child must be created under, not what it would resolve. */
+    readonly pins: RunPins;
+    /** The entries the child inherits as history, in the parent's recorded order. */
+    readonly cut: readonly JournalEntry[];
+    readonly admissible: boolean;
+    readonly refusals: readonly ForkRefusal[];
+}
+export interface ForkRequest {
+    readonly parent: string;
+    /** The child's run id. Allocated by the caller, because minting an id is not this file's decision. */
+    readonly child: string;
+    /** A journal key string, e.g. `/checkpoint:approve#0`. Not a sequence number: it survives edits. */
+    readonly fromStepKey: string;
+    /** The program the parent was running. */
+    readonly source: string;
+    readonly entries: readonly JournalEntry[];
+    /** Read back from the parent's run record. Never re-derived: see the header. */
+    readonly pins: RunPins;
+    readonly actor: string;
+    readonly now: () => number;
+    readonly file?: string;
+    /**
+     * The `newProgramHash` fork option. Accepted only to be REFUSED: the run record carries no
+     * program hash to pin — a declared but unbuilt capability this branch does not invent — so a fork
+     * "pinned to" one would record nothing at all and the caller would have been told it happened.
+     */
+    readonly newProgramHash?: string;
+    /** Worktree branches for the child. There is no worktree plane in this tree, so asking for one
+     *  is refused. */
+    readonly worktreeBranches?: boolean;
+}
+/** The walk reached the step the caller wants to cut at. Not an error: it is where the cut ENDS. */
+export declare class CutReached extends Error {
+    readonly step: string;
+    constructor(step: string);
+}
+/**
+ * A read-only journal that stops the walk when it first LOOKS UP a named step.
+ *
+ * Before delegating, never after: `Journal.lookup` marks a key consumed as its first act, so a stop
+ * placed after the delegation would put the cut step itself into the prefix — and the child would
+ * then replay the very step it was forked to re-run.
+ *
+ * Exported because the fork's correctness claim is about WHICH WALK produced the cut, and a suite
+ * that cannot run the wrong walk cannot show the right one is different from it.
+ */
+export declare class CutJournal extends Journal {
+    private readonly cutAt;
+    constructor(init: JournalInit, cutAt: string);
+    lookup(key: StepKey, inputHash: string): LookupVerdict;
+}
+/**
+ * Compute the fork cut. Reads; never writes.
+ *
+ * The plan is the product whether or not the fork is admissible — a refused fork owes the caller the
+ * code and the step, because that is what makes the next attempt a repair rather than a guess.
+ */
+export declare function planFork(req: ForkRequest): Promise<ForkPlan>;
+export interface ForkCommitResult {
+    readonly child: string;
+    readonly copied: number;
+    /**
+     * Always false, and reported rather than omitted.
+     *
+     * The child's record cannot say it is a fork of anything: `RunSpecValue` has no lineage field,
+     * and adding one — or a `fork` record kind beside `migration` — changes the run record's shape,
+     * which is a decision to raise rather than one to make in this file. A caller that needs the
+     * lineage has it in the {@link ForkPlan} it passed; nothing durable carries it yet.
+     */
+    readonly lineageRecorded: false;
+}
+/**
+ * Copy the cut into the child, and only then create the child's record.
+ *
+ * THE ORDER IS THE DURABILITY ARGUMENT. A crash between the two writes is the case this has to be
+ * right for, and writing the spec first would leave a child that has a record and half a history —
+ * which `driveRun` would happily take over, replaying a prefix that stops in the middle of the
+ * parent's past and then performing effects from there. Written last, a crash leaves journal entries
+ * under an id with no record: `driveRun` refuses a run it cannot read a record for, and `startRun`
+ * refuses a run whose journal already has records. **Neither entry point will touch it**, which is
+ * the failure a partial fork should have.
+ *
+ * The entries are rewritten onto the child's run id as they are copied. That is not bookkeeping: a
+ * journal takes only its own run's entries, and the prefix is now the CHILD's history — the parent's
+ * copy stays exactly where it was, because fork is not rollback.
+ */
+export declare function commitFork(kv: KV, endpoint: string, plan: ForkPlan, store: JournalStore): Promise<ForkCommitResult>;
+/** A fork the plan refused, offered for commit anyway. The plan carries the per-step reason. */
+export declare class ForkNotAdmissible extends Error {
+    readonly plan: ForkPlan;
+    constructor(plan: ForkPlan);
+}
+//# sourceMappingURL=fork.d.ts.map

package/dist/fork.d.ts.map

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