@alisio/core 0.5.2 → 0.6.0

package/dist/forge/session-dir.js

@@ -0,0 +1,239 @@
+/**
+ * The volatile session directory (spec §9.4, D19): a private folder per root session under the
+ * system temporary directory with `scratchpad/` (scripts and intermediates the model writes) and
+ * `tasks/` (live output of Forja executions), plus the helpers that keep what goes into it
+ * confined and bounded.
+ *
+ * Creation never trusts a folder it did not make private itself: every level is created `0700`
+ * and then checked with `lstat` (a directory, not a symlink, owned by this user, no group or other
+ * bits). If the shared root fails the check it is neither used, changed (`chmod`) nor followed:
+ * the session falls back to `<stateHome>/scratch/<workspaceKey>/<rootSessionId>/` and reports a
+ * diagnostic. The POSIX checks are skipped on Windows, where `%TEMP%` is already per user. This is
+ * a mediated policy, not protection against a hostile process racing the creation.
+ */
+import { lstat, mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, sep } from "node:path";
+import { ForgeError } from "./errors.js";
+import { isSafeSegment, privateDirProblem, resolveWithin, scratchBaseName, tmpRootChoice, workspaceSlug, } from "./session-path.js";
+export const SESSION_MARKER = ".alisio-session";
+const isErrno = (error, code) => !!error && typeof error === "object" && error.code === code;
+/** Creates one level `0700` if missing and checks it is private to this user (POSIX). */
+async function privateDir(path, uid) {
+    try {
+        await mkdir(path, { mode: 0o700 });
+    }
+    catch (error) {
+        if (!isErrno(error, "EEXIST"))
+            throw error;
+    }
+    if (uid === undefined)
+        return undefined;
+    const info = await lstat(path);
+    const problem = privateDirProblem({
+        isDirectory: info.isDirectory(),
+        isSymbolicLink: info.isSymbolicLink(),
+        uid: info.uid,
+        mode: info.mode,
+    }, uid);
+    return problem ? `${path}: ${problem}` : undefined;
+}
+/** Creates `parent/…/leaf` level by level, each private. The first problem found, if any. */
+async function privateChain(parent, names, uid) {
+    let current = parent;
+    for (const name of names) {
+        current = join(current, name);
+        const problem = await privateDir(current, uid);
+        if (problem)
+            return problem;
+    }
+    return undefined;
+}
+async function writeMarker(root, marker) {
+    try {
+        await writeFile(join(root, SESSION_MARKER), `${JSON.stringify(marker)}\n`, {
+            flag: "wx",
+            mode: 0o600,
+        });
+    }
+    catch (error) {
+        if (!isErrno(error, "EEXIST"))
+            throw error;
+    }
+}
+export async function ensureSessionDir(options) {
+    if (!isSafeSegment(options.rootSessionId))
+        throw new ForgeError("INVALID_INPUT", "root session id is not a safe folder name");
+    const platform = options.platform ?? process.platform;
+    const posix = platform !== "win32";
+    const uid = posix ? (options.uid ?? process.getuid?.()) : undefined;
+    const env = options.env ?? process.env;
+    const marker = {
+        sessionId: options.rootSessionId,
+        workspaceKey: options.workspaceKey,
+        createdAt: (options.now ?? Date.now)(),
+    };
+    const finish = async (root, extra) => {
+        await writeMarker(root, marker);
+        return {
+            root,
+            scratchpad: join(root, "scratchpad"),
+            tasks: join(root, "tasks"),
+            fallback: false,
+            ...extra,
+        };
+    };
+    const build = async (parent, names) => (await privateChain(parent, [...names, "scratchpad"], uid)) ??
+        (await privateChain(join(parent, ...names), ["tasks"], uid));
+    let problem;
+    try {
+        let base = tmpRootChoice({
+            env: env.ALISIO_TMPDIR,
+            config: options.configRoot,
+            os: options.osTmpdir ?? tmpdir(),
+        });
+        await mkdir(base, { recursive: true, mode: 0o700 });
+        // macOS: /tmp and /var are symlinks into /private; compare and create on the real path.
+        if (platform === "darwin")
+            base = await realpath(base);
+        const names = [
+            scratchBaseName(platform, uid),
+            workspaceSlug(options.workspace, options.workspaceKey),
+            options.rootSessionId,
+        ];
+        problem = await build(base, names);
+        if (!problem)
+            return await finish(join(base, ...names), {});
+    }
+    catch (error) {
+        problem = `${error.message}`;
+    }
+    // Untrusted or unusable shared root: never chmod it, never follow it.
+    const fallbackNames = ["scratch", options.workspaceKey, options.rootSessionId];
+    await mkdir(options.stateHome, { recursive: true, mode: 0o700 });
+    const failure = await build(options.stateHome, fallbackNames);
+    if (failure)
+        throw new ForgeError("INVALID_INPUT", `no usable scratch directory: ${failure}`);
+    const root = join(options.stateHome, ...fallbackNames);
+    return finish(root, {
+        fallback: true,
+        diagnostic: `Shared scratch root not used (${problem}); using ${root}`,
+    });
+}
+/**
+ * The scratchpad folder of a session if it already exists and is a private directory, else
+ * undefined. Unlike `ensureSessionDir` it never creates anything, so a read-only look (the HTTP
+ * listing) leaves no trace. Tries the shared temporary root first, then the state fallback.
+ */
+export async function findSessionScratchpad(options) {
+    if (!isSafeSegment(options.rootSessionId))
+        return undefined;
+    const platform = options.platform ?? process.platform;
+    const uid = platform === "win32" ? undefined : (options.uid ?? process.getuid?.());
+    const env = options.env ?? process.env;
+    const usable = async (path) => {
+        const info = await lstat(path).catch(() => undefined);
+        if (!info)
+            return false;
+        if (uid === undefined)
+            return info.isDirectory() && !info.isSymbolicLink();
+        return (privateDirProblem({
+            isDirectory: info.isDirectory(),
+            isSymbolicLink: info.isSymbolicLink(),
+            uid: info.uid,
+            mode: info.mode,
+        }, uid) === undefined);
+    };
+    try {
+        let base = tmpRootChoice({
+            env: env.ALISIO_TMPDIR,
+            config: options.configRoot,
+            os: options.osTmpdir ?? tmpdir(),
+        });
+        if (platform === "darwin")
+            base = await realpath(base).catch(() => base);
+        const primary = join(base, scratchBaseName(platform, uid), workspaceSlug(options.workspace, options.workspaceKey), options.rootSessionId, "scratchpad");
+        if (await usable(primary))
+            return primary;
+    }
+    catch {
+        // fall through to the state folder
+    }
+    const fallback = join(options.stateHome, "scratch", options.workspaceKey, options.rootSessionId, "scratchpad");
+    return (await usable(fallback)) ? fallback : undefined;
+}
+/** The marker of a session folder, or undefined when it is missing or not valid. */
+export async function readSessionMarker(root) {
+    try {
+        const info = await lstat(join(root, SESSION_MARKER));
+        if (!info.isFile())
+            return undefined;
+        const value = JSON.parse(await readFile(join(root, SESSION_MARKER), "utf8"));
+        if (typeof value.sessionId !== "string" || typeof value.workspaceKey !== "string")
+            return undefined;
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}
+const inside = (root, path) => path === root || path.startsWith(root + sep);
+/**
+ * A scratchpad path the model gave (relative, or absolute inside), checked lexically and then
+ * against the real file system: the deepest existing ancestor must resolve inside the real
+ * scratchpad, so a symlink that points out is refused. Throws `INVALID_INPUT`.
+ */
+export async function resolveScratchPath(scratchpad, input) {
+    const target = resolveWithin(scratchpad, input);
+    const realBase = await realpath(scratchpad);
+    let probe = target;
+    for (;;) {
+        try {
+            const real = await realpath(probe);
+            if (!inside(realBase, real))
+                throw new ForgeError("INVALID_INPUT", `path escapes the scratchpad: ${input}`);
+            return target;
+        }
+        catch (error) {
+            if (error instanceof ForgeError)
+                throw error;
+            // A dangling symlink is not "missing": it could point out and be created through.
+            if (!isErrno(error, "ENOENT"))
+                throw error;
+            const link = await lstat(probe).catch(() => undefined);
+            if (link?.isSymbolicLink())
+                throw new ForgeError("INVALID_INPUT", `path is a dangling symlink: ${input}`);
+            const parent = dirname(probe);
+            if (parent === probe)
+                throw error;
+            probe = parent;
+        }
+    }
+}
+/** Bytes held by the files of a folder (symlinks are counted as links, never followed). */
+export async function scratchUsage(dir) {
+    let total = 0;
+    for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            total += await scratchUsage(path);
+        else
+            total += (await lstat(path).catch(() => undefined))?.size ?? 0;
+    }
+    return total;
+}
+/**
+ * Writes a file into the scratchpad with mode `0600`, refusing paths that escape it and writes
+ * that would take the scratchpad past `maxBytes`. Nothing is ever deleted to make room.
+ */
+export async function writeScratchFile(scratchpad, path, data, options) {
+    const target = await resolveScratchPath(scratchpad, path);
+    const incoming = typeof data === "string" ? Buffer.byteLength(data) : data.byteLength;
+    const replaced = (await lstat(target).catch(() => undefined))?.size ?? 0;
+    const used = await scratchUsage(scratchpad);
+    if (used - replaced + incoming > options.maxBytes)
+        throw new ForgeError("BUDGET_EXCEEDED", `scratchpad is full: ${used} of ${options.maxBytes} bytes used; this write needs ${incoming}. Nothing was deleted.`);
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    await writeFile(target, data, { mode: 0o600 });
+    return target;
+}

package/dist/forge/session-path.d.ts

@@ -0,0 +1,31 @@
+export declare const MAX_SLUG_CHARS = 80;
+/** `ALISIO_TMPDIR`, else `forge.scratch.root`, else the system temporary directory. */
+export declare function tmpRootChoice(input: {
+    env: string | undefined;
+    config: string | null | undefined;
+    os: string;
+}): string;
+/** The per-user folder under the temporary root; Windows `%TEMP%` is already per user. */
+export declare function scratchBaseName(platform: NodeJS.Platform, uid: number | undefined): string;
+/**
+ * The workspace path with every non `[A-Za-z0-9]` character as `-`. Past 80 characters it is cut
+ * and followed by `-` and the first 8 hex characters of the workspace key, so long paths neither
+ * collide nor hit path-length limits.
+ */
+export declare function workspaceSlug(workspace: string, workspaceKey: string): string;
+/** Whether `id` can be one folder name without escaping its parent. */
+export declare function isSafeSegment(id: string): boolean;
+export interface DirFacts {
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+    uid: number;
+    mode: number;
+}
+/** Why an existing folder is not private to this user, or undefined when it is. */
+export declare function privateDirProblem(facts: DirFacts, uid: number): string | undefined;
+/**
+ * Resolves `input` (relative to `base`, or absolute) and refuses anything that is not strictly
+ * inside `base`: `..`, absolute escapes, `base` itself and null bytes. Lexical only; the caller
+ * adds the symlink check on the real file system.
+ */
+export declare function resolveWithin(base: string, input: string): string;

package/dist/forge/session-path.js

@@ -0,0 +1,61 @@
+/**
+ * The pure rules of the session directory (spec §9.4, D19). No I/O: `session-dir.ts` applies them
+ * to the file system.
+ */
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { ForgeError } from "./errors.js";
+export const MAX_SLUG_CHARS = 80;
+const HASH_CHARS = 8;
+/** `ALISIO_TMPDIR`, else `forge.scratch.root`, else the system temporary directory. */
+export function tmpRootChoice(input) {
+    if (input.env)
+        return input.env;
+    if (input.config)
+        return input.config;
+    return input.os;
+}
+/** The per-user folder under the temporary root; Windows `%TEMP%` is already per user. */
+export function scratchBaseName(platform, uid) {
+    return platform === "win32" ? "alisio" : `alisio-${uid}`;
+}
+/**
+ * The workspace path with every non `[A-Za-z0-9]` character as `-`. Past 80 characters it is cut
+ * and followed by `-` and the first 8 hex characters of the workspace key, so long paths neither
+ * collide nor hit path-length limits.
+ */
+export function workspaceSlug(workspace, workspaceKey) {
+    const slug = workspace.replace(/[^A-Za-z0-9]/g, "-");
+    if (slug.length <= MAX_SLUG_CHARS)
+        return slug;
+    return `${slug.slice(0, MAX_SLUG_CHARS)}-${workspaceKey.slice(0, HASH_CHARS)}`;
+}
+/** Whether `id` can be one folder name without escaping its parent. */
+export function isSafeSegment(id) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id);
+}
+/** Why an existing folder is not private to this user, or undefined when it is. */
+export function privateDirProblem(facts, uid) {
+    if (facts.isSymbolicLink)
+        return "it is a symlink";
+    if (!facts.isDirectory)
+        return "it is not a directory";
+    if (facts.uid !== uid)
+        return "it belongs to another owner";
+    if ((facts.mode & 0o077) !== 0)
+        return "it grants permissions to group or other";
+    return undefined;
+}
+/**
+ * Resolves `input` (relative to `base`, or absolute) and refuses anything that is not strictly
+ * inside `base`: `..`, absolute escapes, `base` itself and null bytes. Lexical only; the caller
+ * adds the symlink check on the real file system.
+ */
+export function resolveWithin(base, input) {
+    if (input.length === 0 || input.includes("\0"))
+        throw new ForgeError("INVALID_INPUT", "path must be a non-empty string without null bytes");
+    const target = resolve(base, input);
+    const rel = relative(base, target);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        throw new ForgeError("INVALID_INPUT", `path is outside the scratchpad: ${input}`);
+    return target;
+}

package/dist/forge/slots.d.ts

@@ -0,0 +1,16 @@
+export interface SlotLimits {
+    perSession: number;
+    perProcess: number;
+}
+export declare const DEFAULT_SLOT_LIMITS: Readonly<SlotLimits>;
+export declare class SlotTable {
+    #private;
+    constructor(limits?: SlotLimits);
+    get active(): number;
+    activeIn(session: string): number;
+    /**
+     * Takes a slot or throws `BUDGET_EXCEEDED` with the reason. The returned release is idempotent,
+     * so a cleanup path can call it more than once without freeing a slot twice.
+     */
+    acquire(session: string): () => void;
+}

package/dist/forge/slots.js

@@ -0,0 +1,47 @@
+/**
+ * Concurrency slots of the JavaScript engine (spec D-29, §6.5): one active execution per SESSION
+ * and a few per process. The session (not the root session) is the unit because a subagent's
+ * `js_run` must not wait on its parent's. Pure bookkeeping: no I/O, no timers.
+ */
+import { ForgeError } from "./errors.js";
+export const DEFAULT_SLOT_LIMITS = { perSession: 1, perProcess: 4 };
+export class SlotTable {
+    #limits;
+    #perSession = new Map();
+    #total = 0;
+    constructor(limits = DEFAULT_SLOT_LIMITS) {
+        this.#limits = limits;
+    }
+    get active() {
+        return this.#total;
+    }
+    activeIn(session) {
+        return this.#perSession.get(session) ?? 0;
+    }
+    /**
+     * Takes a slot or throws `BUDGET_EXCEEDED` with the reason. The returned release is idempotent,
+     * so a cleanup path can call it more than once without freeing a slot twice.
+     */
+    acquire(session) {
+        if (this.activeIn(session) >= this.#limits.perSession) {
+            throw new ForgeError("BUDGET_EXCEEDED", "Another js_run is still running in this session; wait for it to finish.");
+        }
+        if (this.#total >= this.#limits.perProcess) {
+            throw new ForgeError("BUDGET_EXCEEDED", `Too many js_run executions are active in this process (${this.#limits.perProcess}); try again shortly.`);
+        }
+        this.#perSession.set(session, this.activeIn(session) + 1);
+        this.#total++;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const next = this.activeIn(session) - 1;
+            if (next <= 0)
+                this.#perSession.delete(session);
+            else
+                this.#perSession.set(session, next);
+            this.#total--;
+        };
+    }
+}

package/dist/forge/state-delta.d.ts

@@ -0,0 +1,54 @@
+export declare const MAX_STATE_KEY_CHARS = 128;
+export declare const MAX_STATE_VALUE_BYTES: number;
+export declare const DEFAULT_STATE_TOTAL_BYTES: number;
+/** What `start.state` carries (values) plus the revisions the host keeps to compare later. */
+export interface StateSnapshot {
+    values: Record<string, unknown>;
+    /** Includes tombstoned keys; a key absent here was never written (revision 0). */
+    revisions: Record<string, number>;
+}
+/** A stored row. An empty `valueJson` is a tombstone. */
+export interface StateEntry {
+    valueJson: string;
+    revision: number;
+}
+export type StateOp = {
+    op: "set";
+    key: string;
+    value: unknown;
+} | {
+    op: "delete";
+    key: string;
+};
+export interface StateWrite {
+    key: string;
+    /** Empty for a tombstone. */
+    valueJson: string;
+    revision: number;
+}
+/** The local copy a running script reads and writes. Writes accumulate; nothing is persisted. */
+export declare class StateDelta {
+    #private;
+    constructor(snapshot: StateSnapshot);
+    get(key: string): unknown;
+    set(key: string, value: unknown): void;
+    delete(key: string): void;
+    /** The last operation per key, in the order each key was first touched. */
+    ops(): StateOp[];
+}
+export interface CommitPlan {
+    writes: StateWrite[];
+    /** Live bytes (keys plus values) of the root session after the writes. */
+    totalBytes: number;
+}
+/**
+ * Decides what a delta writes. Throws `STATE_CONFLICT` when a touched key changed since the
+ * snapshot (nothing is applied, nothing retried) and `BUDGET_EXCEEDED` when the live total would
+ * pass `maxTotalBytes`.
+ */
+export declare function planCommit(input: {
+    current: ReadonlyMap<string, StateEntry>;
+    snapshot: StateSnapshot;
+    ops: readonly StateOp[];
+    maxTotalBytes: number;
+}): CommitPlan;

package/dist/forge/state-delta.js

@@ -0,0 +1,99 @@
+/**
+ * The pure rules of the state shared across executions (spec §9.2, D11): a script gets a snapshot,
+ * its writes accumulate into a delta, and the delta is applied only if every key it touches still
+ * has the revision the script saw. No I/O: the SQLite adapter lives in `state-store.ts`.
+ *
+ * A delete leaves a tombstone (empty `valueJson`) that keeps counting revisions, so a key that is
+ * deleted and re-created by another execution never repeats a revision a stale snapshot holds.
+ */
+import { ForgeError } from "./errors.js";
+export const MAX_STATE_KEY_CHARS = 128;
+export const MAX_STATE_VALUE_BYTES = 64 * 1024;
+export const DEFAULT_STATE_TOTAL_BYTES = 512 * 1024;
+const bytes = (text) => Buffer.byteLength(text, "utf8");
+function checkKey(key) {
+    if (key.length === 0 || key.length > MAX_STATE_KEY_CHARS)
+        throw new ForgeError("INVALID_INPUT", `state key must be 1 to ${MAX_STATE_KEY_CHARS} characters`);
+}
+/** The JSON of a value, or INVALID_INPUT when it is not JSON or is over the per-value limit. */
+function encodeValue(key, value) {
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch {
+        json = undefined;
+    }
+    if (json === undefined)
+        throw new ForgeError("INVALID_INPUT", `state value for "${key}" is not JSON-serializable`);
+    if (bytes(json) > MAX_STATE_VALUE_BYTES)
+        throw new ForgeError("INVALID_INPUT", `state value for "${key}" exceeds ${MAX_STATE_VALUE_BYTES} bytes`);
+    return json;
+}
+/** The local copy a running script reads and writes. Writes accumulate; nothing is persisted. */
+export class StateDelta {
+    #values;
+    #ops = new Map();
+    constructor(snapshot) {
+        this.#values = new Map(Object.entries(snapshot.values));
+    }
+    get(key) {
+        return this.#values.get(key);
+    }
+    set(key, value) {
+        checkKey(key);
+        const json = encodeValue(key, value);
+        const stored = JSON.parse(json);
+        this.#values.set(key, stored);
+        this.#record({ op: "set", key, value: stored });
+    }
+    delete(key) {
+        checkKey(key);
+        this.#values.delete(key);
+        this.#record({ op: "delete", key });
+    }
+    /** The last operation per key, in the order each key was first touched. */
+    ops() {
+        return [...this.#ops.values()];
+    }
+    #record(op) {
+        this.#ops.set(op.key, op);
+    }
+}
+/**
+ * Decides what a delta writes. Throws `STATE_CONFLICT` when a touched key changed since the
+ * snapshot (nothing is applied, nothing retried) and `BUDGET_EXCEEDED` when the live total would
+ * pass `maxTotalBytes`.
+ */
+export function planCommit(input) {
+    const writes = [];
+    const next = new Map(input.current);
+    for (const op of input.ops) {
+        const existing = input.current.get(op.key);
+        const seen = input.snapshot.revisions[op.key] ?? 0;
+        if (seen !== (existing?.revision ?? 0))
+            throw new ForgeError("STATE_CONFLICT", `state key "${op.key}" changed since this execution started; nothing was applied`);
+        if (op.op === "delete") {
+            if (!existing || existing.valueJson === "")
+                continue;
+            const write = { key: op.key, valueJson: "", revision: existing.revision + 1 };
+            writes.push(write);
+            next.set(op.key, { valueJson: write.valueJson, revision: write.revision });
+            continue;
+        }
+        const write = {
+            key: op.key,
+            valueJson: encodeValue(op.key, op.value),
+            revision: (existing?.revision ?? 0) + 1,
+        };
+        writes.push(write);
+        next.set(op.key, { valueJson: write.valueJson, revision: write.revision });
+    }
+    let totalBytes = 0;
+    for (const [key, entry] of next)
+        if (entry.valueJson !== "")
+            totalBytes += bytes(key) + bytes(entry.valueJson);
+    if (totalBytes > input.maxTotalBytes)
+        throw new ForgeError("BUDGET_EXCEEDED", `state would use ${totalBytes} bytes; the limit per session is ${input.maxTotalBytes}`);
+    return { writes, totalBytes };
+}

package/dist/forge/state-machine.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The Forja execution lifecycle (spec §5.2). Pure: no I/O.
+ *
+ * `cancelling` and `timed_out_pending` exist because a terminal state is only reached once the
+ * host has confirmed the guest stopped; a terminal state is reached exactly once.
+ */
+export type ExecutionState = "validating" | "preparing" | "running" | "cancelling" | "timed_out_pending" | "collecting" | "succeeded" | "failed" | "cancelled" | "timed_out";
+export declare class InvalidTransitionError extends Error {
+    readonly from: ExecutionState;
+    readonly to: ExecutionState;
+    constructor(from: ExecutionState, to: ExecutionState);
+}
+export declare function canTransition(from: ExecutionState, to: ExecutionState): boolean;
+export declare class ExecutionStateMachine {
+    #private;
+    get state(): ExecutionState;
+    get isTerminal(): boolean;
+    /** Moves to `to`, or throws without changing state when the diagram does not allow it. */
+    transition(to: ExecutionState): void;
+}

package/dist/forge/state-machine.js

@@ -0,0 +1,40 @@
+const TRANSITIONS = {
+    validating: ["preparing", "failed"],
+    preparing: ["running", "failed", "cancelled"],
+    running: ["collecting", "failed", "cancelling", "timed_out_pending"],
+    cancelling: ["cancelled"],
+    timed_out_pending: ["timed_out"],
+    collecting: ["succeeded", "failed"],
+    succeeded: [],
+    failed: [],
+    cancelled: [],
+    timed_out: [],
+};
+export class InvalidTransitionError extends Error {
+    from;
+    to;
+    constructor(from, to) {
+        super(`Invalid execution transition: ${from} -> ${to}`);
+        this.from = from;
+        this.to = to;
+        this.name = "InvalidTransitionError";
+    }
+}
+export function canTransition(from, to) {
+    return TRANSITIONS[from].includes(to);
+}
+export class ExecutionStateMachine {
+    #state = "validating";
+    get state() {
+        return this.#state;
+    }
+    get isTerminal() {
+        return TRANSITIONS[this.#state].length === 0;
+    }
+    /** Moves to `to`, or throws without changing state when the diagram does not allow it. */
+    transition(to) {
+        if (!canTransition(this.#state, to))
+            throw new InvalidTransitionError(this.#state, to);
+        this.#state = to;
+    }
+}

package/dist/forge/state-store.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The SQLite adapter of the cross-execution state (spec §9.2). The rules (limits, revisions,
+ * conflicts) are the pure functions of `state-delta.ts`; this file only reads the rows and applies
+ * the plan in one immediate transaction, so a conflicting delta writes nothing.
+ *
+ * The host takes `snapshot()` when an execution starts, feeds the script's `state.set` and
+ * `state.delete` into a `StateDelta`, and calls `commit()` only when the execution succeeds. A
+ * failed execution simply never commits: its delta is dropped (FJ-AC-17).
+ */
+import type { SqlDatabase } from "@alisio/sdk";
+import { type StateOp, type StateSnapshot } from "./state-delta.ts";
+export declare class SqliteStateStore {
+    #private;
+    constructor(db: SqlDatabase, options?: {
+        maxTotalBytes?: number | (() => number);
+        now?: () => number;
+    });
+    /** Live values and every revision (tombstones included) of a root session. */
+    snapshot(rootSessionId: string): StateSnapshot;
+    /**
+     * Applies a delta against the snapshot it was built from. Throws `STATE_CONFLICT` or
+     * `BUDGET_EXCEEDED` without writing anything. Returns the number of rows written.
+     */
+    commit(rootSessionId: string, snapshot: StateSnapshot, ops: readonly StateOp[]): number;
+}