@cotal-ai/runtime 0.0.1 → 0.24.0

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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"}

package/dist/fork.js

@@ -0,0 +1,310 @@
+import { createRunSpec, readRunRecord } from "@cotal-ai/core";
+import { Journal, JournalReadOnlyError, journalEntryKeyString, run as runProgram, RunDivergence, UnwalkableScope, ScopeBranchMissing, stepKeyString, } from "@cotal-ai/lang";
+/** The journal kinds that open a scope, i.e. whose entry can ENCLOSE a cut point. */
+const SCOPE_KINDS = new Set(["parallel", "race", "fanOut", "conclave"]);
+/** The walk reached the step the caller wants to cut at. Not an error: it is where the cut ENDS. */
+export class CutReached extends Error {
+    step;
+    constructor(step) {
+        super(`the dry walk reached the cut at ${step}`);
+        this.step = step;
+        this.name = "CutReached";
+    }
+}
+/**
+ * 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 class CutJournal extends Journal {
+    cutAt;
+    constructor(init, cutAt) {
+        super(init);
+        this.cutAt = cutAt;
+    }
+    lookup(key, inputHash) {
+        if (stepKeyString(key) === this.cutAt)
+            throw new CutReached(this.cutAt);
+        return super.lookup(key, inputHash);
+    }
+}
+/** A handler that performs nothing: the cut is computed from records, never by doing anything. */
+function dryHandler(now) {
+    const stop = (_req, ctx) => {
+        throw new ForkFrontier(stepKeyString(ctx.key));
+    };
+    return {
+        now,
+        spawn: stop, turn: stop, ask: stop, checkpoint: stop, sleep: stop,
+        wait: stop, notify: stop, monitor: stop, openConclave: stop, closeConclave: stop,
+    };
+}
+/** The walk ran out of records before it reached the cut. The caller named a step this run never got
+ *  to, which is a different failure from naming one it never recorded. */
+class ForkFrontier extends Error {
+    step;
+    constructor(step) {
+        super(`the dry walk reached the frontier at ${step}`);
+        this.step = step;
+        this.name = "ForkFrontier";
+    }
+}
+/**
+ * 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 async function planFork(req) {
+    const refusals = [];
+    if (req.newProgramHash !== undefined) {
+        refusals.push({
+            code: "L5002",
+            why: "a fork onto a new program would have to pin its hash on the child's run record, and a run's spec carries no program hash — that pin is declared and unbuilt. Refused rather than accepted and dropped.",
+        });
+    }
+    if (req.worktreeBranches === true) {
+        refusals.push({
+            code: "L5019",
+            why: "a fork is specified to get its own worktree branches cut from the parent's branch head, and there is no worktree plane in this tree to cut one from",
+        });
+    }
+    const journal = new CutJournal({ run: req.parent, entries: req.entries, readOnly: true }, req.fromStepKey);
+    // THE CALLER'S LIST IS AN APPEND LOG, and every step in it appears at least twice.
+    //
+    // The stream is append-only: settling appends a second record rather than editing the first, so a
+    // completed step is a pending record AND a settled one. `RunJournalAppender.steps()` replays every
+    // step record in order and the driver seeds a journal straight from it, which is the only shape a
+    // real caller holds — this file's own suite was building a KEYED view with `Journal.entries()` and
+    // was therefore blind to it. Filtering `req.entries` put both rows of every copied step into the
+    // prefix, and `commitFork` COPIES the prefix, so the doubling was written to the child's durable
+    // stream as real records. Silent, with every key correct and simply two of each.
+    //
+    // The fold is the journal's, not a second copy of the rule: the entries below are its keyed view,
+    // last write per step in the order the run performed them.
+    const entries = journal.entries();
+    const recorded = entries.some((e) => journalEntryKeyString(e) === req.fromStepKey);
+    if (!recorded) {
+        refusals.push({
+            code: "L5017",
+            step: req.fromStepKey,
+            why: "the journal has no entry under this key; a fork cuts at a step the parent actually recorded, and a key that names nothing would silently cut at the end of history",
+        });
+    }
+    let reached = false;
+    try {
+        await runProgram(req.source, {
+            runId: req.parent,
+            handler: dryHandler(req.now),
+            journal,
+            // MIGRATION MODE. See the header: a resume's short-circuit would carry a settled scope's whole
+            // subtree into the prefix, and the entries it swept in are precisely the ones after the cut.
+            migration: true,
+            pins: req.pins,
+            ...(req.file !== undefined ? { file: req.file } : {}),
+        });
+    }
+    catch (e) {
+        const err = unwrapCut(e);
+        if (err instanceof CutReached) {
+            reached = true;
+        }
+        else if (err instanceof RunDivergence) {
+            refusals.push({
+                code: "L5001",
+                step: err.stepKey,
+                why: "the source diverged from the recorded journal before the cut was reached, so what the prefix contains is not decided; migrate the run or fork on the source it recorded",
+            });
+        }
+        else if (err instanceof UnwalkableScope) {
+            refusals.push({
+                code: "L5014",
+                step: err.scopeKey,
+                why: `the walk could not enter a scope on the way to the cut: ${err.message}`,
+            });
+        }
+        else if (err instanceof ScopeBranchMissing) {
+            // Its OWN code and not L5014's. Both stop the walk at a scope, but a conclave stops it because
+            // the handle was never journalled, and this one because the arm is gone from the source — and
+            // a refusal that named the wrong reason would send the author to fix the wrong thing.
+            refusals.push({
+                code: "L5022",
+                step: err.scopeKey,
+                why: `the walk reached ${err.scopeKey} on the way to the cut and the source no longer declares `
+                    + `${err.missing.map((k) => `\`${k}\``).join(", ")}, the branch${err.missing.length === 1 ? "" : "es"} the run settled on; `
+                    + `fork on the source it recorded, or restore the arm name`,
+            });
+        }
+        else if (!(err instanceof ForkFrontier) && !(err instanceof JournalReadOnlyError)) {
+            throw e;
+        }
+    }
+    const orphaned = new Set(journal.orphans().map((e) => journalEntryKeyString(e)));
+    // THE FRONTIER PROJECTION. A scope that ENCLOSES the cut point must not be copied as settled.
+    //
+    // The dry walk runs in migration mode, which descends into a recorded scope rather than
+    // short-circuiting it, so the cut point inside a branch is reached and everything before it is
+    // consumed — including the scope's own entry. The CHILD, though, replays in RESUME mode, where a
+    // settled scope entry is taken wholesale: it reads the recorded result, never re-enters, and its
+    // first live step lands after the whole combinator. The child then never re-runs the step it was
+    // forked for, and the recorded result it inherits already contains the answer for the branch the
+    // caller wanted re-decided. Admissible, no refusal, wrong child — the worst shape available.
+    //
+    // Dropping the enclosing entry makes the child re-enter the combinator: sibling branches replay
+    // from their own entries, which are still in the cut, and the branch holding the cut point runs
+    // live from it. That is what a fork means here.
+    const enclosing = entries.filter((e) => {
+        const k = journalEntryKeyString(e);
+        return SCOPE_KINDS.has(e.kind) && req.fromStepKey.startsWith(`${k}/b:`);
+    });
+    // Re-entering is only sound for a scope whose branches all RUN. A `race` decided a winner, and a
+    // child that re-enters would race again — re-deciding, on a fresh handler, something the parent
+    // recorded. That is not a fork of the run, it is a different run. Refused rather than re-raced,
+    // and refused rather than copied-as-settled, because both of those are silent.
+    for (const e of enclosing) {
+        if (e.kind === "parallel" || e.kind === "fanOut")
+            continue;
+        refusals.push({
+            code: "L5020",
+            step: journalEntryKeyString(e),
+            why: `the cut is inside a \`${e.kind}\`, whose outcome this run already decided. Re-entering it would decide it again on a fresh handler, and copying it settled would make the child skip the step it was forked to re-run. Fork at a step outside the ${e.kind}, or at the ${e.kind} itself.`,
+        });
+    }
+    // L5018 says one specific thing: the program's own path does not arrive at this step. When the
+    // walk stopped for a reason of its OWN — it diverged (L5001), it could not enter a scope (L5014),
+    // or the step sits inside a scope whose losing arms the walk does not enter at all (L5020) — the
+    // path may well arrive there and that sentence is FALSE. Emitting it beside the true refusal is
+    // worse than emitting nothing: both codes are actionable and they prescribe opposite repairs, so
+    // the caller re-keys a step that was correct all along instead of forking before the conclave. A
+    // refusal set is only a repair instruction if every code in it is true.
+    //
+    // L5020 is in that set for a reason worth stating: a `race` LOSER's step is recorded, settled, and
+    // genuinely performed by the parent — every arm of a race runs — yet the migration walk enters
+    // only the recorded winner, so `reached` is false for a key the program does reach. L5018 there
+    // told the caller their program does not go somewhere it does go.
+    //
+    // This runs after the projection because the gate has to be able to SEE L5020; a `some()` over a
+    // refusal set that has not been filled yet is a check that cannot fail.
+    const stoppedForAnotherReason = refusals.some((r) => r.code === "L5001" || r.code === "L5014" || r.code === "L5020");
+    if (!reached && recorded && !stoppedForAnotherReason) {
+        refusals.push({
+            code: "L5018",
+            step: req.fromStepKey,
+            why: "the step is recorded, but this replay never reached it — the program's own path does not arrive there. A cut that was never reached is the whole journal, and copying the whole journal is not a fork.",
+        });
+    }
+    const projected = new Set(enclosing.map((e) => journalEntryKeyString(e)));
+    // A REFUSED PLAN CARRIES NO CUT. An unreached walk already returned nothing, on the ground that a
+    // plausible-looking prefix is worse than an empty one; a plan that was reached and then refused
+    // has exactly the same hazard and had exactly the opposite behaviour. A caller reading `cut`
+    // without reading `admissible` got something usable-shaped out of a fork that will not happen.
+    const cut = reached && refusals.length === 0
+        ? entries.filter((e) => {
+            const k = journalEntryKeyString(e);
+            return !orphaned.has(k) && !projected.has(k);
+        })
+        : [];
+    // The respawn decision, at plan time rather than at commit time. `onFork: "respawn"` mints a
+    // fresh agent at the frontier and `"adopt"` shares the parent's; both name a durable agent
+    // handle, and `spawn` rides the durable-action machinery this host does not have. Copying the
+    // prefix anyway would produce a child that owns turns taken by an agent it can neither address
+    // nor replace.
+    for (const e of cut) {
+        if (e.kind !== "spawn")
+            continue;
+        refusals.push({
+            code: "L5019",
+            step: journalEntryKeyString(e),
+            why: "the cut contains a spawn, and a fork must respawn or adopt that agent at the frontier; both ride the durable-action machinery an agent handle comes from, which has not landed on this host. Fork at a step before the spawn, or wait for it.",
+        });
+    }
+    return {
+        parent: req.parent,
+        child: req.child,
+        at: req.now(),
+        actor: req.actor,
+        fromStep: req.fromStepKey,
+        pins: req.pins,
+        cut,
+        admissible: refusals.length === 0,
+        refusals,
+    };
+}
+/**
+ * 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 async function commitFork(kv, endpoint, plan, store) {
+    if (!plan.admissible)
+        throw new ForkNotAdmissible(plan);
+    // THIS GUARD DOES NOT COVER A CRASHED FORK, and saying so is the point of the comment. The record
+    // is written LAST precisely so a partial fork is un-drivable, which means that after a crash there
+    // is no record here to find and this check passes. What refuses the retry is one layer out: a
+    // caller gets a durable store by activating the child's journal, and an activation expecting a NEW
+    // run refuses one whose journal already has records. Both halves have cells — including one that
+    // shows a HAND-BUILT store letting the prefix land twice, because a fence in another component is
+    // a claim this file cannot make on its own.
+    const existing = await readRunRecord(kv, endpoint, plan.child);
+    if (existing !== undefined) {
+        throw new ForkNotAdmissible({
+            ...plan,
+            admissible: false,
+            refusals: [
+                {
+                    code: "L5017",
+                    why: `run ${plan.child} already has a record; a fork mints a new run, and copying a prefix into one that already exists would rewrite somebody's history`,
+                },
+            ],
+        });
+    }
+    for (const entry of plan.cut) {
+        await store.append({ ...entry, run: plan.child });
+    }
+    await createRunSpec(kv, endpoint, plan.child, { pins: plan.pins, createdAt: plan.at });
+    return { child: plan.child, copied: plan.cut.length, lineageRecorded: false };
+}
+/** A fork the plan refused, offered for commit anyway. The plan carries the per-step reason. */
+export class ForkNotAdmissible extends Error {
+    plan;
+    constructor(plan) {
+        super(`run ${plan.parent} cannot fork at ${plan.fromStep}: ` +
+            plan.refusals.map((r) => `${r.code}${r.step !== undefined ? ` at ${r.step}` : ""}`).join(", ") +
+            `. The plan carries the per-step reason; nothing was written.`);
+        this.plan = plan;
+        this.name = "ForkNotAdmissible";
+    }
+}
+/**
+ * A scope wraps what its body threw, so the cut's stop can arrive inside a wrapper.
+ *
+ * Structural rather than by class: the interpreter's scope errors carry the original on `reason`,
+ * and a fork that only recognised the bare form would report "never reached" for every cut inside a
+ * `parallel` — a refusal that reads exactly like the caller naming an unreachable step.
+ */
+function unwrapCut(e) {
+    let cur = e;
+    for (let i = 0; i < 8; i += 1) {
+        const inner = cur?.reason;
+        if (inner === undefined || inner === cur)
+            return cur;
+        cur = inner;
+    }
+    return cur;
+}
+//# sourceMappingURL=fork.js.map

package/dist/fork.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@cotal-ai/runtime` — where a cotal-lang run is HOSTED.
+ *
+ * `packages/lang` is the language: the parser and validator, the effect interface, the step journal,
+ * the interpreter, the simulator, the dry run. It depends on nothing in this repo, and that
+ * independence is what lets a program be tested without a broker. This package is the other half:
+ * the mesh bindings that make a run durable and drivable — the journal's storage over the
+ * activation barrier, the effect handler over the real planes, and the run driver hosted on the
+ * manager daemon.
+ */
+export { RunJournalStore, RunJournalUnavailable } from "./journal-store.js";
+export { startRun, driveRun, PauseToken, type RunLease, type DriveRequest, type DriveOutcome, type AdoptingHandler } from "./run-driver.js";
+export { MeshHandler, EpfSettleWatcher, CheckpointAnswerMissing, NotYetDurable, waitConsumerName, waitConsumerConfig, rearmOutstandingPauses, outstandingPauseTokens, type MeshHandlerBinding, type SettleWatcher, } from "./mesh-handler.js";
+export { resolveCheckpoint, openCheckpointToken, CheckpointNotOpen, type ResolveCheckpointDeps, type ResolveCheckpointRequest, type ResolveCheckpointResult, } from "./resolve-checkpoint.js";
+export { renderRunContext, UnrenderableNotice, type RunContextRender } from "./run-context.js";
+export { migrateRun, commitMigration, MigrationNotAdmissible, type MigrateRequest, type MigrateReport, type MigrateOrphan, type MigrateOverrides, type MigrateDivergence, type OrphanVerdict, } from "./migrate.js";
+export { planFork, commitFork, ForkNotAdmissible, CutJournal, CutReached, type ForkRequest, type ForkPlan, type ForkRefusal, type ForkCommitResult, } from "./fork.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC5I,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,uBAAuB,EACvB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,kBAAkB,EACvB,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC/F,OAAO,EACL,UAAU,EACV,eAAe,EACf,sBAAsB,EACtB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,QAAQ,EACR,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,UAAU,EACV,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,gBAAgB,GACtB,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * `@cotal-ai/runtime` — where a cotal-lang run is HOSTED.
+ *
+ * `packages/lang` is the language: the parser and validator, the effect interface, the step journal,
+ * the interpreter, the simulator, the dry run. It depends on nothing in this repo, and that
+ * independence is what lets a program be tested without a broker. This package is the other half:
+ * the mesh bindings that make a run durable and drivable — the journal's storage over the
+ * activation barrier, the effect handler over the real planes, and the run driver hosted on the
+ * manager daemon.
+ */
+export { RunJournalStore, RunJournalUnavailable } from "./journal-store.js";
+export { startRun, driveRun, PauseToken } from "./run-driver.js";
+export { MeshHandler, EpfSettleWatcher, CheckpointAnswerMissing, NotYetDurable, waitConsumerName, waitConsumerConfig, rearmOutstandingPauses, outstandingPauseTokens, } from "./mesh-handler.js";
+export { resolveCheckpoint, openCheckpointToken, CheckpointNotOpen, } from "./resolve-checkpoint.js";
+export { renderRunContext, UnrenderableNotice } from "./run-context.js";
+export { migrateRun, commitMigration, MigrationNotAdmissible, } from "./migrate.js";
+export { planFork, commitFork, ForkNotAdmissible, CutJournal, CutReached, } from "./fork.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAA6E,MAAM,iBAAiB,CAAC;AAC5I,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,uBAAuB,EACvB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,GAGvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,GAIlB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAyB,MAAM,kBAAkB,CAAC;AAC/F,OAAO,EACL,UAAU,EACV,eAAe,EACf,sBAAsB,GAOvB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,QAAQ,EACR,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,UAAU,GAKX,MAAM,WAAW,CAAC"}

package/dist/journal-store.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The step journal's durable half: a `JournalStore` over the run journal's activation barrier.
+ *
+ * `packages/lang` decides WHAT is recorded and WHEN, and hands whole entries to a store that owns
+ * only durability. This is that store for a run hosted on the mesh, and it is deliberately thin —
+ * every hard property it has (one authoritative writer, a serial pump, a head that advances only
+ * from a PubAck) belongs to `RunJournalAppender` and is not re-implemented here.
+ *
+ * What this file DOES own is the translation between two vocabularies that must not be confused:
+ *
+ *   - The language's `append` contract is "resolve only once the entry is somewhere a resume on
+ *     another host will find it". The appender's resolution is a PubAck, which is exactly that, so
+ *     the awaits line up with no buffering in between.
+ *   - The language reads a store's refusal as `L5010 JournalAppendRejected` — "the log said no",
+ *     the run losing its ability to record, never an effect result. Every terminal state of the
+ *     barrier is that: superseded, stalled, or refused. So this store throws for all of them, and
+ *     lets the journal wrap them, rather than inventing an outcome for a step whose effect already
+ *     ran.
+ *
+ * A store that could return to the interpreter after a barrier failure would be worse than one that
+ * throws: the interpreter would carry on driving a run this process no longer speaks for.
+ */
+import type { JournalEntry, JournalStore } from "@cotal-ai/lang";
+import { RunJournalAppender } from "@cotal-ai/core";
+/**
+ * A run whose journal writer is finished, offered to the interpreter as a durability failure.
+ *
+ * The distinction the barrier draws — someone else took the run, versus this appender lost its head
+ * — is preserved in `cause` for the driver, and flattened for the language, which has exactly one
+ * correct response to both: stop, and record nothing else.
+ */
+export declare class RunJournalUnavailable extends Error {
+    readonly run: string;
+    readonly cause: unknown;
+    /**
+     * True when it is NOT known whether the entry landed.
+     *
+     * A refusal is determinate: the stream said no, and nothing was written. A stalled append is not —
+     * the publish may already be on disk — and the language's L5010 text says which, because "the
+     * entry was not recorded" is a claim, and making it about an ambiguous append would be the
+     * durability layer telling the run the more comfortable of two possibilities.
+     */
+    readonly indeterminate: boolean;
+    constructor(run: string, cause: unknown);
+}
+export declare class RunJournalStore implements JournalStore {
+    private readonly appender;
+    constructor(appender: RunJournalAppender);
+    /** True once the underlying appender is finished. A driver polls this to stop early rather than
+     *  discovering it on the next entry — the interpreter has no such concept and does not need one. */
+    get isFinished(): boolean;
+    append(entry: JournalEntry): Promise<void>;
+}
+//# sourceMappingURL=journal-store.d.ts.map

package/dist/journal-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-store.d.ts","sourceRoot":"","sources":["../src/journal-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAoC,MAAM,gBAAgB,CAAC;AAEtF;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAY5C,QAAQ,CAAC,GAAG,EAAE,MAAM;aACF,KAAK,EAAE,OAAO;IAZlC;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;gBAGrB,GAAG,EAAE,MAAM,EACF,KAAK,EAAE,OAAO;CAMnC;AAED,qBAAa,eAAgB,YAAW,YAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,kBAAkB;IAEzD;wGACoG;IACpG,IAAI,UAAU,IAAI,OAAO,CAExB;IAEK,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAqBjD"}

package/dist/journal-store.js

@@ -0,0 +1,60 @@
+import { RunJournalAppender, RunSuperseded, RunJournalStalled } from "@cotal-ai/core";
+/**
+ * A run whose journal writer is finished, offered to the interpreter as a durability failure.
+ *
+ * The distinction the barrier draws — someone else took the run, versus this appender lost its head
+ * — is preserved in `cause` for the driver, and flattened for the language, which has exactly one
+ * correct response to both: stop, and record nothing else.
+ */
+export class RunJournalUnavailable extends Error {
+    run;
+    cause;
+    /**
+     * True when it is NOT known whether the entry landed.
+     *
+     * A refusal is determinate: the stream said no, and nothing was written. A stalled append is not —
+     * the publish may already be on disk — and the language's L5010 text says which, because "the
+     * entry was not recorded" is a claim, and making it about an ambiguous append would be the
+     * durability layer telling the run the more comfortable of two possibilities.
+     */
+    indeterminate;
+    constructor(run, cause) {
+        super(`run ${run} can no longer record: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.run = run;
+        this.cause = cause;
+        this.indeterminate = cause instanceof RunJournalStalled;
+        this.name = "RunJournalUnavailable";
+    }
+}
+export class RunJournalStore {
+    appender;
+    constructor(appender) {
+        this.appender = appender;
+    }
+    /** True once the underlying appender is finished. A driver polls this to stop early rather than
+     *  discovering it on the next entry — the interpreter has no such concept and does not need one. */
+    get isFinished() {
+        return this.appender.isFinished;
+    }
+    async append(entry) {
+        // A run's journal takes only that run's entries. The language checks this where a journal is
+        // SEEDED; this is the other end, where an entry is made durable — a PubAck on one run's subject
+        // must never be what makes another run's journal report an entry as recorded.
+        if (entry.run !== this.appender.run) {
+            throw new Error(`entry belongs to run ${entry.run}, but this store appends to run ${this.appender.run}; a journal entry is durable on its own run's subject or not at all`);
+        }
+        try {
+            // The stamp is the entry's own clock — its end when it has one, its start while it is pending
+            // — carried so a record is readable on its own. It is NOT the journal's ordering: the PubAck
+            // sequence is that, and nothing downstream sorts by this.
+            await this.appender.append(entry, entry.endedAt ?? entry.startedAt);
+        }
+        catch (e) {
+            if (e instanceof RunSuperseded || e instanceof RunJournalStalled) {
+                throw new RunJournalUnavailable(this.appender.run, e);
+            }
+            throw e;
+        }
+    }
+}
+//# sourceMappingURL=journal-store.js.map