@karowanorg/orc-core 0.1.0

package/dist/cost.js

@@ -0,0 +1,51 @@
+/**
+ * Default list-price ESTIMATES for the gpt-5.x families, keyed by longest
+ * matching prefix. These are editable placeholders — real billing depends on
+ * your account/agreement. Override with config `costRates` or ORC_COST_RATES.
+ */
+export const DEFAULT_COST_RATES = {
+    "gpt-5.6": { inputPer1M: 1.25, outputPer1M: 10, cachedInputPer1M: 0.125 },
+    "gpt-5.5": { inputPer1M: 1.25, outputPer1M: 10, cachedInputPer1M: 0.125 },
+    "gpt-5.3": { inputPer1M: 1.25, outputPer1M: 10, cachedInputPer1M: 0.125 },
+    "gpt-5": { inputPer1M: 1.25, outputPer1M: 10, cachedInputPer1M: 0.125 },
+};
+export function loadCostRates(override) {
+    let fromEnv = {};
+    if (process.env.ORC_COST_RATES) {
+        try {
+            fromEnv = JSON.parse(process.env.ORC_COST_RATES);
+        }
+        catch {
+            /* ignore malformed env */
+        }
+    }
+    return { ...DEFAULT_COST_RATES, ...fromEnv, ...(override ?? {}) };
+}
+/** Longest-prefix match so "gpt-5.6-sol" resolves to the "gpt-5.6" rate. */
+export function rateForModel(rates, model) {
+    if (!model)
+        return undefined;
+    if (rates[model])
+        return rates[model];
+    let best;
+    let bestLen = -1;
+    for (const [key, rate] of Object.entries(rates)) {
+        if (model.startsWith(key) && key.length > bestLen) {
+            best = rate;
+            bestLen = key.length;
+        }
+    }
+    return best;
+}
+export function estimateCostUsd(rates, model, tokens) {
+    const rate = rateForModel(rates, model);
+    if (!rate)
+        return undefined;
+    const cached = tokens.cachedInputTokens ?? 0;
+    const freshInput = Math.max((tokens.inputTokens ?? 0) - cached, 0);
+    const cachedRate = rate.cachedInputPer1M ?? rate.inputPer1M;
+    const cost = (freshInput / 1_000_000) * rate.inputPer1M +
+        (cached / 1_000_000) * cachedRate +
+        ((tokens.outputTokens ?? 0) / 1_000_000) * rate.outputPer1M;
+    return cost;
+}

package/dist/engine.d.ts

@@ -0,0 +1,54 @@
+import { type Json, type Policy, type ThunkSpec } from "./contracts.js";
+export interface VmHooks {
+    /**
+     * Called synchronously when the program makes a call. MUST NOT re-enter the
+     * VM (no evalCode / executePendingJobs from inside). Record and return.
+     */
+    onCall(seq: number, spec: ThunkSpec): void;
+    onLog(message: string): void;
+    onPhase(name: string): void;
+}
+export type ProgramState = {
+    state: "pending";
+} | {
+    state: "ok";
+    result: Json;
+} | {
+    state: "error";
+    error: string;
+};
+export declare class ProgramVM {
+    private readonly policy;
+    private readonly hooks;
+    private runtime;
+    private ctx;
+    private deferreds;
+    private nextSeq;
+    private stepsRemaining;
+    private interrupted;
+    private disposed;
+    private jsonParse?;
+    private jsonSerialize?;
+    private constructor();
+    static create(bundle: string, policy: Policy, hooks: VmHooks, startSeq?: number): Promise<ProgramVM>;
+    private installHostFunctions;
+    private evalOrThrow;
+    private resetBudget;
+    /** Drain the VM job queue to quiescence. One turn = one step budget. */
+    drain(): void;
+    /**
+     * Deliver exactly one completion, then drain to quiescence.
+     * This one-per-drain policy is replay-visible and frozen (§5.3).
+     */
+    deliver(seq: number, outcome: {
+        status: "ok";
+        value: Json;
+    } | {
+        status: "error";
+        error: string;
+    }): void;
+    /** Sequence numbers of calls made but not yet delivered. */
+    pendingSeqs(): number[];
+    state(): ProgramState;
+    dispose(): void;
+}

package/dist/engine.js

@@ -0,0 +1,474 @@
+/**
+ * The deterministic program VM: quickjs-emscripten (sync build) with a
+ * host-controlled event loop.
+ *
+ * Determinism contract (design doc §5.3):
+ * - The bootstrap actively strips ambient authority (Date, Math.random,
+ *   WeakRef, FinalizationRegistry) — a fresh QuickJS context ships all of them.
+ * - orc drives the event loop itself; jobs run only inside drain().
+ * - Sequence identity: each agent()/ext.* call gets the next sequence number in
+ *   call order. Scheduling is replayed deterministically, so call order is
+ *   stable across live execution and replay.
+ * - Delivery granularity is part of the replay contract: exactly ONE completion
+ *   is resolved per quiescent drain.
+ * - The step budget is the interrupt handler's invocation count per turn —
+ *   never wall-clock (which would abort replay at a different point than live).
+ * - Values cross the boundary as VM-parsed canonical JSON literals; the journal
+ *   digest is computed host-side over the exact canonical bytes.
+ */
+import { getQuickJS, } from "quickjs-emscripten";
+import { canonicalJson } from "./canonical.js";
+import { PolicyError } from "./contracts.js";
+const BOOTSTRAP = String.raw `
+"use strict";
+(function () {
+  var deny = function (name) {
+    var f = function () { throw new Error(name + " is not available in orc programs (deterministic sandbox)"); };
+    return f;
+  };
+  var deniedDate = deny("Date");
+  deniedDate.now = deny("Date.now");
+  deniedDate.parse = deny("Date.parse");
+  deniedDate.UTC = deny("Date.UTC");
+  globalThis.Date = deniedDate;
+  Math.random = deny("Math.random");
+  globalThis.WeakRef = undefined;
+  globalThis.FinalizationRegistry = undefined;
+
+  var groupCounter = 0;
+  var currentPhase = "";
+
+  function dispatch(spec) {
+    if (spec.phase === undefined && currentPhase) spec.phase = currentPhase;
+    return __orc_dispatch(JSON.stringify(spec));
+  }
+
+  function normTimeout(v) {
+    if (v === false) return false;
+    if (typeof v === "number") return v;
+    return undefined;
+  }
+
+  // Dispatch a leaf and, when its completion resolves, restore the phase that
+  // was active at CALL time. Correct under concurrency because orc delivers
+  // exactly one completion per quiescent drain: the restore microtask runs
+  // (and any synchronous agent() calls in the await continuation capture the
+  // right phase) before the next completion is ever delivered.
+  function dispatchLeaf(spec) {
+    var capturedPhase = currentPhase;
+    return dispatch(spec).then(
+      function (v) { currentPhase = capturedPhase; return v; },
+      function (e) { currentPhase = capturedPhase; throw e; }
+    );
+  }
+
+  globalThis.agent = function (prompt, opts) {
+    var o = opts || {};
+    return dispatchLeaf({
+      kind: "agent",
+      prompt: String(prompt),
+      id: o.id,
+      harness: o.harness,
+      model: o.model,
+      reasoningEffort: o.reasoningEffort,
+      schema: o.schema,
+      readOnly: o.readOnly === false ? false : true,
+      cwd: o.cwd,
+      host: o.host,
+      phase: o.phase,
+      idleTimeoutMs: normTimeout(o.idleTimeout),
+      groupId: o.__groupId,
+    });
+  };
+
+  // Independent fan-out: every lane runs to completion and comes back as a
+  // settled outcome ({status:"ok",value}|{status:"error",error}), so one lane's
+  // failure never cancels or wastes its siblings. The caller decides how to
+  // handle partial failure. (For fail-fast, use Promise.all over agent().)
+  globalThis.parallel = function (specs) {
+    var gid = "g" + ++groupCounter;
+    return Promise.all(
+      specs.map(function (s) {
+        var o = Object.assign({}, s);
+        var prompt = o.prompt;
+        delete o.prompt;
+        o.__groupId = gid; // lane-grouping metadata for the monitor
+        return globalThis.settle(globalThis.agent(prompt, o));
+      })
+    );
+  };
+
+  globalThis.settle = function (p) {
+    return Promise.resolve(p).then(
+      function (v) { return { status: "ok", value: v === undefined ? null : v }; },
+      function (e) { return { status: "error", error: String((e && e.message) || e) }; }
+    );
+  };
+
+  // Lexically scoped ONLY (the rejected persistent-global marker is not offered):
+  // phase(name, fn) labels every call made inside fn, and — thanks to the
+  // call-time capture + one-per-drain restore above — that holds across awaits
+  // and concurrent sibling phases without mislabeling.
+  globalThis.phase = function (name, fn) {
+    var label = String(name);
+    if (typeof fn !== "function") {
+      throw new Error(
+        'phase(name, fn) requires a function, e.g. phase("' + label + '", () => {...}). ' +
+        'For a single call, use the per-call { phase: "' + label + '" } option instead.'
+      );
+    }
+    __orc_phase(label);
+    var prev = currentPhase;
+    currentPhase = label;
+    try {
+      var r = fn();
+      if (r && typeof r.then === "function") {
+        return r.then(
+          function (v) { currentPhase = prev; return v; },
+          function (e) { currentPhase = prev; throw e; }
+        );
+      }
+      currentPhase = prev;
+      return r;
+    } catch (e) {
+      currentPhase = prev;
+      throw e;
+    }
+  };
+
+  globalThis.log = function (msg) { __orc_log(String(msg)); };
+
+  globalThis.ext = new Proxy({}, {
+    get: function (_t, name) {
+      return function (payload) {
+        return dispatchLeaf({
+          kind: "ext:" + String(name),
+          payload: payload === undefined ? null : payload,
+          readOnly: true, // host overrides from the extension registration
+        });
+      };
+    },
+  });
+
+  globalThis.__orc_api = {
+    agent: globalThis.agent,
+    parallel: globalThis.parallel,
+    phase: globalThis.phase,
+    log: globalThis.log,
+    settle: globalThis.settle,
+    ext: globalThis.ext,
+  };
+})();
+`;
+const INVOKE = String.raw `
+"use strict";
+(function () {
+  var mod = typeof __orc_mod !== "undefined" ? __orc_mod : undefined;
+  var fn = mod && (typeof mod.default === "function" ? mod.default : typeof mod === "function" ? mod : null);
+  if (!fn) throw new Error("program has no default-exported function");
+  globalThis.__orc_state = "pending";
+  globalThis.__orc_result = null;
+  Promise.resolve(fn(globalThis.__orc_api)).then(
+    function (v) { globalThis.__orc_state = "ok"; globalThis.__orc_result = v === undefined ? null : v; },
+    function (e) {
+      globalThis.__orc_state = "error";
+      // QuickJS Error.stack does NOT include the message line (unlike V8).
+      var msg = e && e.message ? String(e.message) : String(e);
+      var stack = e && e.stack ? String(e.stack) : "";
+      globalThis.__orc_result = stack ? msg + "\n" + stack : msg;
+    }
+  );
+})();
+`;
+const STRICT_JSON_SERIALIZER = String.raw `
+(function () {
+  var isArray = Array.isArray;
+  var getPrototypeOf = Object.getPrototypeOf;
+  var getOwnPropertyDescriptor = Object.getOwnPropertyDescriptor;
+  var keys = Object.keys;
+  var objectPrototype = Object.prototype;
+  var stringify = JSON.stringify;
+  var isFiniteNumber = Number.isFinite;
+
+  function encode(value, depth, ancestors) {
+    if (depth > 256) throw new TypeError("JSON nesting exceeds 256");
+    if (value === null || typeof value === "boolean" || typeof value === "string") {
+      return stringify(value);
+    }
+    if (typeof value === "number") {
+      if (!isFiniteNumber(value)) throw new TypeError("JSON numbers must be finite");
+      return stringify(value);
+    }
+    if (typeof value !== "object") {
+      throw new TypeError("unsupported JSON value: " + typeof value);
+    }
+    for (var a = 0; a < ancestors.length; a++) {
+      if (ancestors[a] === value) throw new TypeError("JSON value contains a cycle");
+    }
+    ancestors[ancestors.length] = value;
+    try {
+      var out = "";
+      var i;
+      if (isArray(value)) {
+        out = "[";
+        for (i = 0; i < value.length; i++) {
+          var item = getOwnPropertyDescriptor(value, i);
+          if (!item) throw new TypeError("JSON arrays cannot be sparse");
+          if (!("value" in item)) throw new TypeError("JSON properties cannot be accessors");
+          if (i) out += ",";
+          out += encode(item.value, depth + 1, ancestors);
+        }
+        return out + "]";
+      }
+      var prototype = getPrototypeOf(value);
+      if (prototype !== objectPrototype && prototype !== null) {
+        throw new TypeError("JSON objects must be plain objects");
+      }
+      var names = keys(value);
+      out = "{";
+      for (i = 0; i < names.length; i++) {
+        var name = names[i];
+        var property = getOwnPropertyDescriptor(value, name);
+        if (!("value" in property)) throw new TypeError("JSON properties cannot be accessors");
+        if (i) out += ",";
+        out += stringify(name) + ":" + encode(property.value, depth + 1, ancestors);
+      }
+      return out + "}";
+    } finally {
+      ancestors.length -= 1;
+    }
+  }
+
+  return function (value) { return encode(value, 0, []); };
+})()
+`;
+export class ProgramVM {
+    policy;
+    hooks;
+    runtime;
+    ctx;
+    deferreds = new Map();
+    nextSeq = 0;
+    stepsRemaining = 0;
+    interrupted = false;
+    disposed = false;
+    jsonParse;
+    jsonSerialize;
+    constructor(runtime, ctx, policy, hooks) {
+        this.policy = policy;
+        this.hooks = hooks;
+        this.runtime = runtime;
+        this.ctx = ctx;
+    }
+    static async create(bundle, policy, hooks, startSeq = 0) {
+        const QuickJS = await getQuickJS();
+        const runtime = QuickJS.newRuntime();
+        let vm;
+        try {
+            runtime.setMemoryLimit(policy.memoryLimitBytes);
+            runtime.setMaxStackSize(policy.maxStackBytes);
+            const ctx = runtime.newContext();
+            vm = new ProgramVM(runtime, ctx, policy, hooks);
+            vm.nextSeq = startSeq;
+            const json = ctx.getProp(ctx.global, "JSON");
+            try {
+                // Keep the intrinsic handle outside the program's reach. Sandbox code
+                // may replace globalThis.JSON.parse, but replay materialization must
+                // still use the original parser.
+                vm.jsonParse = ctx.getProp(json, "parse");
+            }
+            finally {
+                json.dispose();
+            }
+            const serializer = ctx.evalCode(STRICT_JSON_SERIALIZER, "orc-json.js");
+            if ("error" in serializer && serializer.error) {
+                const err = ctx.dump(serializer.error);
+                serializer.error.dispose();
+                throw new Error(`failed to install JSON serializer: ${String(err)}`);
+            }
+            vm.jsonSerialize = serializer.value;
+            runtime.setInterruptHandler(() => {
+                vm.stepsRemaining -= 1;
+                if (vm.stepsRemaining < 0) {
+                    vm.interrupted = true;
+                    return true;
+                }
+                return false;
+            });
+            vm.installHostFunctions();
+            vm.evalOrThrow(BOOTSTRAP, "orc-bootstrap.js");
+            vm.evalOrThrow(bundle, "program.bundle.js");
+            vm.evalOrThrow(INVOKE, "orc-invoke.js");
+            vm.drain(); // initial turn: run the program to its first quiescent point
+            return vm;
+        }
+        catch (err) {
+            if (vm)
+                vm.dispose();
+            else
+                runtime.dispose();
+            throw err;
+        }
+    }
+    installHostFunctions() {
+        const { ctx } = this;
+        const dispatchFn = ctx.newFunction("__orc_dispatch", (specHandle) => {
+            const specJson = ctx.getString(specHandle);
+            const spec = JSON.parse(specJson);
+            const seq = this.nextSeq++;
+            // Record only — never re-enter the VM from a host callback.
+            this.hooks.onCall(seq, spec);
+            const deferred = ctx.newPromise();
+            this.deferreds.set(seq, deferred);
+            // Returned to the program as its awaited promise; the handle is owned by
+            // the deferred and freed via deferred.dispose() (see deliver/dispose).
+            return deferred.handle;
+        });
+        ctx.setProp(ctx.global, "__orc_dispatch", dispatchFn);
+        dispatchFn.dispose();
+        const logFn = ctx.newFunction("__orc_log", (msgHandle) => {
+            this.hooks.onLog(ctx.getString(msgHandle));
+        });
+        ctx.setProp(ctx.global, "__orc_log", logFn);
+        logFn.dispose();
+        const phaseFn = ctx.newFunction("__orc_phase", (nameHandle) => {
+            this.hooks.onPhase(ctx.getString(nameHandle));
+        });
+        ctx.setProp(ctx.global, "__orc_phase", phaseFn);
+        phaseFn.dispose();
+    }
+    evalOrThrow(code, filename) {
+        this.resetBudget();
+        const result = this.ctx.evalCode(code, filename);
+        if ("error" in result && result.error) {
+            const err = this.ctx.dump(result.error);
+            result.error.dispose();
+            throw new Error(`program error in ${filename}: ${typeof err === "object" ? JSON.stringify(err) : String(err)}`);
+        }
+        result.value.dispose();
+        if (this.interrupted)
+            throw new PolicyError(`step budget exceeded in ${filename}`);
+    }
+    resetBudget() {
+        this.stepsRemaining = this.policy.stepBudgetPerTurn;
+        this.interrupted = false;
+    }
+    /** Drain the VM job queue to quiescence. One turn = one step budget. */
+    drain() {
+        this.resetBudget();
+        // executePendingJobs runs queued promise jobs; loop defensively.
+        for (;;) {
+            const res = this.runtime.executePendingJobs();
+            if ("error" in res && res.error) {
+                const err = this.ctx.dump(res.error);
+                res.error.dispose();
+                throw new Error(`program job error: ${typeof err === "object" ? JSON.stringify(err) : String(err)}`);
+            }
+            const executed = "value" in res ? res.value : 0;
+            if (this.interrupted)
+                throw new PolicyError("step budget exceeded");
+            if (executed === 0)
+                return;
+        }
+    }
+    /**
+     * Deliver exactly one completion, then drain to quiescence.
+     * This one-per-drain policy is replay-visible and frozen (§5.3).
+     */
+    deliver(seq, outcome) {
+        const deferred = this.deferreds.get(seq);
+        if (!deferred)
+            throw new Error(`no pending call with seq ${seq}`);
+        this.deferreds.delete(seq);
+        this.resetBudget();
+        if (outcome.status === "ok") {
+            const bytes = canonicalJson(outcome.value);
+            const source = this.ctx.newString(bytes);
+            const parsed = this.ctx.callFunction(this.jsonParse, this.ctx.undefined, source);
+            source.dispose();
+            if ("error" in parsed && parsed.error) {
+                const err = this.ctx.dump(parsed.error);
+                parsed.error.dispose();
+                deferred.dispose();
+                if (this.interrupted) {
+                    throw new PolicyError(`step budget exceeded materializing result for call ${seq}`);
+                }
+                throw new Error(`failed to materialize result for seq ${seq}: ${JSON.stringify(err)}`);
+            }
+            deferred.resolve(parsed.value);
+            parsed.value.dispose();
+        }
+        else {
+            const error = this.ctx.newError(outcome.error);
+            deferred.reject(error);
+            error.dispose();
+        }
+        deferred.dispose(); // frees the deferred's resolve/reject/handle
+        if (this.interrupted)
+            throw new PolicyError(`step budget exceeded materializing result for call ${seq}`);
+        this.drain();
+    }
+    /** Sequence numbers of calls made but not yet delivered. */
+    pendingSeqs() {
+        return [...this.deferreds.keys()].sort((a, b) => a - b);
+    }
+    state() {
+        const stateHandle = this.ctx.getProp(this.ctx.global, "__orc_state");
+        const state = this.ctx.dump(stateHandle);
+        stateHandle.dispose();
+        if (state === "pending")
+            return { state: "pending" };
+        const handle = this.ctx.getProp(this.ctx.global, "__orc_result");
+        if (state === "ok") {
+            this.resetBudget();
+            const serialized = this.ctx.callFunction(this.jsonSerialize, this.ctx.undefined, handle);
+            handle.dispose();
+            if ("error" in serialized && serialized.error) {
+                const err = this.ctx.dump(serialized.error);
+                serialized.error.dispose();
+                return {
+                    state: "error",
+                    error: `program result is not valid JSON: ${String(err?.message ?? err)}`,
+                };
+            }
+            const json = this.ctx.getString(serialized.value);
+            serialized.value.dispose();
+            if (this.interrupted)
+                return { state: "error", error: "step budget exceeded materializing program result" };
+            return { state: "ok", result: JSON.parse(json) };
+        }
+        const value = this.ctx.dump(handle);
+        handle.dispose();
+        return { state: "error", error: String(value) };
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        // Undelivered deferreds (e.g. validate previews, deadlocks): free them so
+        // the runtime disposes cleanly (avoids the QuickJS gc_obj_list assertion).
+        for (const d of this.deferreds.values()) {
+            try {
+                d.dispose();
+            }
+            catch {
+                /* already consumed */
+            }
+        }
+        this.deferreds.clear();
+        this.jsonParse?.dispose();
+        this.jsonSerialize?.dispose();
+        try {
+            this.ctx.dispose();
+        }
+        catch {
+            /* leaked handles on release builds are silent; best effort */
+        }
+        try {
+            this.runtime.dispose();
+        }
+        catch {
+            /* ditto */
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./contracts.js";
+export * from "./canonical.js";
+export * from "./rundir.js";
+export * from "./status.js";
+export * from "./compile.js";
+export * from "./engine.js";
+export * from "./supervisor.js";
+export * from "./config.js";
+export * from "./cost.js";
+export * from "./jsonschema.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+export * from "./contracts.js";
+export * from "./canonical.js";
+export * from "./rundir.js";
+export * from "./status.js";
+export * from "./compile.js";
+export * from "./engine.js";
+export * from "./supervisor.js";
+export * from "./config.js";
+export * from "./cost.js";
+export * from "./jsonschema.js";

package/dist/jsonschema.d.ts

@@ -0,0 +1,3 @@
+import type { Json } from "./contracts.js";
+/** Validate a JSON value against the caller's JSON Schema. */
+export declare function validateAgainstSchema(value: Json, schema: Json, path?: string): string | null;

package/dist/jsonschema.js

@@ -0,0 +1,31 @@
+import { Ajv } from "ajv";
+import { Ajv2019 } from "ajv/dist/2019.js";
+import { Ajv2020 } from "ajv/dist/2020.js";
+const options = {
+    allErrors: false,
+    strict: false,
+    validateFormats: false,
+};
+/** Validate a JSON value against the caller's JSON Schema. */
+export function validateAgainstSchema(value, schema, path = "$") {
+    try {
+        const dialect = schema !== null && typeof schema === "object" && !Array.isArray(schema)
+            ? schema.$schema
+            : undefined;
+        // A schema belongs to one call. A fresh validator keeps caller-owned $ids
+        // and generated validators from accumulating across runs.
+        const ajv = typeof dialect === "string" && dialect.includes("2020-12")
+            ? new Ajv2020(options)
+            : typeof dialect === "string" && dialect.includes("2019-09")
+                ? new Ajv2019(options)
+                : new Ajv(options);
+        const validate = ajv.compile(schema);
+        if (validate(value))
+            return null;
+        const error = validate.errors?.[0];
+        return `${path}${error?.instancePath ?? ""}: ${error?.message ?? "schema validation failed"}`;
+    }
+    catch (err) {
+        return `${path}: invalid schema: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}

package/dist/rundir.d.ts

@@ -0,0 +1,53 @@
+import type { Json, JournalRecord, RunManifest, TraceRecord, ControlMessage } from "./contracts.js";
+/** State home: ~/.orc or $ORC_HOME. One run = one directory under runs/. */
+export declare function orcHome(): string;
+export declare function runsDir(): string;
+export declare function runDir(runId: string): string;
+export declare function newRunId(name?: string): string;
+/**
+ * Append-only JSONL file with an explicit fsync mode.
+ * The journal uses fsync-per-append (the WAL); the trace sidecar fsyncs only
+ * on leaf close records.
+ */
+export declare class JsonlAppender<T> {
+    readonly filePath: string;
+    private fd;
+    constructor(filePath: string);
+    append(record: T, opts?: {
+        fsync?: boolean;
+    }): void;
+    close(): void;
+}
+/** Read a JSONL file tolerating a torn final line (crash-during-append). */
+export declare function readJsonl<T>(filePath: string): T[];
+export interface RunPaths {
+    dir: string;
+    manifest: string;
+    program: string;
+    journal: string;
+    traces: string;
+    control: string;
+    results: string;
+    report: string;
+    lock: string;
+}
+export declare function runPaths(runId: string): RunPaths;
+export declare function createRunDir(manifest: RunManifest, programBundle: string): RunPaths;
+export declare function readManifest(runId: string): RunManifest;
+export declare function listRuns(): RunManifest[];
+/** Content-addressed result body storage. */
+export declare function writeResult(paths: RunPaths, body: Json): {
+    sha: string;
+    sizeBytes: number;
+};
+export declare function readResult(paths: RunPaths, sha: string): Json;
+export declare function readJournal(runId: string): JournalRecord[];
+export declare function readTraces(runId: string): TraceRecord[];
+export declare function readControl(runId: string): ControlMessage[];
+export declare function appendControl(runId: string, msg: ControlMessage): void;
+export declare function acquireLock(paths: RunPaths): Promise<{
+    release(): Promise<void>;
+    beat(): void;
+    lost: Promise<never>;
+    holderPid: number;
+}>;