@smthrs/harness 0.0.0-stage → 1.0.0-rc.3

package/dist/cjs/Relevance.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Relevance.ts"],
+  "sourcesContent": ["/**\n * What a run is shown of the human-provided items it could be shown.\n *\n * Memory rows, catalog flows and skills, and chunks of instruction files such\n * as `AGENTS.md` are items. {@link judge} asks Jev one question about each:\n * is it unnecessary for the task as stated? An item is withheld only when Jev\n * says so with probability at or above {@link withholdAt}; everything else is\n * kept. An item longer than {@link itemBytes} is sent head-kept and always\n * kept: Jev cannot be confident about text it was not shown. A reading that\n * cannot be judged keeps everything, and the caller\n * journals `decision-unjudged` for it: keeping is the rule, withholding is\n * the exception Jev must be confident of.\n *\n * Nothing here journals or filters a live catalog. {@link settled} is the row\n * a caller writes for a reading, and {@link render} the instruction block a\n * caller builds from what was kept.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as Digest from \"@smthrs/core/Digest\"\nimport * as Classifier from \"@smthrs/model/Classifier\"\nimport type * as Evaluator from \"@smthrs/model/Evaluator\"\nimport type * as Descriptor from \"@smthrs/registry/Descriptor\"\nimport * as Duration from \"effect/Duration\"\nimport * as Effect from \"effect/Effect\"\nimport * as Option from \"effect/Option\"\nimport * as Schema from \"effect/Schema\"\nimport * as AgentEvent from \"./AgentEvent.ts\"\nimport * as bytes from \"./internal/bytes.ts\"\nimport * as elide from \"./internal/elide.ts\"\nimport { untrustedData } from \"./internal/untrustedData.ts\"\nimport * as Judgement from \"./Judgement.ts\"\n\n/**\n * What an item is.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport const Kind = AgentEvent.RelevanceKind\n\n/**\n * The decoded form of {@link Kind}.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type Kind = typeof Kind.Type\n\n/**\n * One human-provided item a run could be shown.\n *\n * @category schemas\n * @since 1.0.0-rc.0\n */\nexport const Item = Schema.Struct({ kind: Kind, id: Schema.String, text: Schema.String })\n\n/**\n * The decoded form of {@link Item}.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type Item = typeof Item.Type\n\n/**\n * What every reading is told beside its items.\n *\n * @category schemas\n * @since 1.0.0-rc.0\n */\nexport const Context = Schema.Struct({\n  task: Schema.String,\n  query: Schema.optionalKey(Schema.String),\n  recent: Schema.optionalKey(Schema.String)\n})\n\n/**\n * The decoded form of {@link Context}.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type Context = typeof Context.Type\n\n/**\n * The probability of \"unnecessary\" at or above which an item is withheld.\n *\n * @category constants\n * @since 1.0.0-rc.0\n */\nexport const withholdAt = 0.9\n\n/**\n * The `Classifier.confident` floor that is {@link withholdAt} for a boolean:\n * its confidence is its distance from even odds, doubled.\n */\nconst confidentAt = (withholdAt - 0.5) * 2\n\n/**\n * The most of one item's text a reading carries, in UTF-8 bytes; the head\n * kept.\n *\n * @category constants\n * @since 1.0.0-rc.0\n */\nexport const itemBytes = 1024\n\n/** The most of a flow's description an item carries, in UTF-8 bytes. */\nconst descriptionBytes = 512\n\nconst recall = \"the rest is not shown\"\n\n/** `text` within `limit` bytes, its head kept and the cut stated. */\nconst headKept = (text: string, limit: number): string => {\n  const whole = bytes.size(text)\n  if (whole <= limit) return text\n  // The notice names at most `whole` dropped bytes.\n  return elide.head(text, limit - bytes.size(`\u2026 [+${whole}b, ${recall}]`), recall)\n}\n\n/**\n * The reading: one question per item, `unnecessary_${index}`.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const reader = Judgement.perItem({\n  id: \"relevance/unnecessary\",\n  description: \"Decide which provided items an agent run does not need\",\n  context: Context,\n  item: Item,\n  questions: {\n    unnecessary: (i) =>\n      Classifier.boolean({\n        instructions:\n          `Is items[${i}] unnecessary for the task as stated? Read context.task, and context.query or context.recent when present.`,\n        criteria: {\n          true: \"nothing the task, context.query, or a step they plainly imply uses it, needs it, or must follow it\",\n          false: \"the task, context.query, or a step they plainly imply may use it, need it, or must follow it\"\n        }\n      })\n  }\n})\n\n/**\n * Jev's verdict on one item. `p` is the probability it is unnecessary.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Verdict {\n  readonly item: Item\n  /** `Digest.digest` of the item's whole text. */\n  readonly digest: string\n  readonly p: number\n  readonly withheld: boolean\n}\n\n/**\n * One reading: a verdict per item in input order, and the record of asking.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Reading {\n  readonly verdicts: ReadonlyArray<Verdict>\n  readonly asked: ReadonlyArray<Judgement.Asked>\n  /** Wall-clock milliseconds the reading took. */\n  readonly latencyMs: number\n  /** Token usage summed over every request, absent when none reported any. */\n  readonly usage?: Evaluator.Usage | undefined\n}\n\n/**\n * Asks Jev which of `items` the run does not need. Each item's text is sent\n * head-kept to {@link itemBytes}, and an item that was cut is never withheld.\n * No items ask nothing.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const judge = (context: Context, items: ReadonlyArray<Item>): Effect.Effect<Reading, Judgement.Unjudged> =>\n  Effect.gen(function*() {\n    const sent = items.map((item) => ({ ...item, text: headKept(item.text, itemBytes) }))\n    const [elapsed, read] = yield* reader.read(context, sent).pipe(Effect.timed)\n    const verdicts = items.map((item, index): Verdict => {\n      const answer = read.answers[index]!.unnecessary\n      return {\n        item,\n        digest: Digest.digest(item.text),\n        p: answer.probability,\n        withheld: bytes.size(item.text) <= itemBytes &&\n          Option.getOrElse(Classifier.confident(answer, confidentAt), () => false)\n      }\n    })\n    const usages = read.asked.flatMap((asked) => asked.usage === undefined ? [] : [asked.usage])\n    return {\n      verdicts,\n      asked: read.asked,\n      latencyMs: Math.round(Duration.toMillis(elapsed)),\n      ...(usages.length === 0 ? {} : {\n        usage: {\n          inputTokens: usages.reduce((sum, usage) => sum + usage.inputTokens, 0),\n          outputTokens: usages.reduce((sum, usage) => sum + usage.outputTokens, 0)\n        }\n      })\n    }\n  })\n\n/**\n * The `relevance-settled` row for a reading: ids and digests, never text.\n *\n * @category conversions\n * @since 1.0.0-rc.0\n */\nexport const settled = (\n  reading: Reading,\n  at: { readonly scope: string; readonly frame: number; readonly source: AgentEvent.RelevanceSettled[\"source\"] }\n): AgentEvent.RelevanceSettled => {\n  const row = (verdict: Verdict) => ({\n    kind: verdict.item.kind,\n    id: verdict.item.id,\n    digest: verdict.digest,\n    p: verdict.p\n  })\n  return new AgentEvent.RelevanceSettled({\n    eventType: AgentEvent.eventType.relevanceSettled,\n    scope: at.scope,\n    frame: at.frame,\n    source: at.source,\n    withholdAt,\n    kept: reading.verdicts.filter((verdict) => !verdict.withheld).map(row),\n    withheld: reading.verdicts.filter((verdict) => verdict.withheld).map(row),\n    latencyMs: reading.latencyMs,\n    ...(reading.usage === undefined ? {} : { usage: reading.usage })\n  })\n}\n\n/**\n * A catalog entry as an item: a `skill` when its body is markdown, else a\n * `flow`. Its description is untrusted data.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const flowItem = (descriptor: Descriptor.FlowDescriptor): Item => {\n  const description = untrustedData(\n    headKept(descriptor.description, descriptionBytes),\n    `description of ${descriptor.name}`\n  )\n  const capabilities = descriptor.capabilities.length === 0\n    ? \"\"\n    : `\\ncapabilities: ${[...descriptor.capabilities].sort().join(\",\")}`\n  return {\n    kind: descriptor.body._tag === \"Markdown\" ? \"skill\" : \"flow\",\n    id: descriptor.name,\n    text: `${descriptor.name}\\n${description}${capabilities}`\n  }\n}\n\n/**\n * One human-provided instruction file.\n *\n * @category schemas\n * @since 1.0.0-rc.0\n */\nexport const Document = Schema.Struct({ path: Schema.String, text: Schema.String })\n\n/**\n * The decoded form of {@link Document}.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type Document = typeof Document.Type\n\n/**\n * One piece of an instruction file, as {@link chunks} splits it.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Chunk {\n  /** `${path}#${n}`, `n` counting from 0 within the file. */\n  readonly id: string\n  readonly path: string\n  readonly text: string\n}\n\nconst heading = /^#{1,6}(?:[ \\t]|$)/\nconst listItem = /^(?:[-*+] |\\d+\\. )/\nconst fence = /^[ \\t]*```/\nconst blank = /^[ \\t]*\\r?$/\nconst indented = /^[ \\t]/\n\nconst split = (document: Document): ReadonlyArray<Chunk> => {\n  const pieces: Array<string> = []\n  let fenced = false\n  // A list item's chunk runs over its indented and wrapped lines, and ends at\n  // the first unindented line after a blank one.\n  let item = false\n  let afterBlank = false\n  for (const line of document.text.match(/[^\\n]*\\n|[^\\n]+$/g) ?? []) {\n    const bare = line.endsWith(\"\\n\") ? line.slice(0, -1) : line\n    const starts = !fenced && pieces.length > 0 && (heading.test(bare) || listItem.test(bare) ||\n      (item && afterBlank && !blank.test(bare) && !indented.test(bare)))\n    if (!fenced && (heading.test(bare) || listItem.test(bare))) item = listItem.test(bare)\n    else if (starts) item = false\n    if (starts || pieces.length === 0) pieces.push(line)\n    else pieces[pieces.length - 1] += line\n    if (fence.test(bare)) fenced = !fenced\n    afterBlank = !fenced && blank.test(bare)\n  }\n  return pieces.map((text, n) => ({ id: `${document.path}#${n}`, path: document.path, text }))\n}\n\n/**\n * Splits instruction files into the chunks a reading judges, in order.\n *\n * A chunk starts at each markdown heading and at each top-level list item,\n * whose indented and wrapped lines are its own. Every other line, blank lines\n * included, joins the chunk before it, and nothing inside a fence is split.\n * A file's chunks concatenate back to the file.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const chunks = (documents: ReadonlyArray<Document>): ReadonlyArray<Chunk> => documents.flatMap(split)\n\n/**\n * The project-instructions block of every chunk not in `withheld`, in order.\n * A file whose every chunk is withheld is left out, and `\"\"` is returned when\n * nothing is left.\n *\n * @category conversions\n * @since 1.0.0-rc.0\n */\nexport const render = (documents: ReadonlyArray<Document>, withheld: ReadonlySet<string>): string => {\n  const blocks = documents.flatMap((document) => {\n    const all = split(document)\n    const kept = all.filter((chunk) => !withheld.has(chunk.id))\n    if (all.length > 0 && kept.length === 0) return []\n    return [\n      `<project_instructions path=\"${document.path}\">\\n${\n        kept.map((chunk) => chunk.text).join(\"\")\n      }\\n</project_instructions>`\n    ]\n  })\n  return blocks.length === 0 ? \"\" : \"Project-specific instructions and guidelines:\\n\\n\" + blocks.join(\"\\n\\n\")\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/Sandbox.d.ts

@@ -0,0 +1,637 @@
+/**
+ * The deterministic script sandbox port.
+ *
+ * A cell is arbitrary agent-authored JavaScript, so it never runs in the host
+ * realm. It runs behind this port, which grants exactly one effectful
+ * primitive — flow invocation against the capability-narrowed catalog the run
+ * was given — and returns a serializable {@link Cell.Outcome}.
+ *
+ * The port opens a {@link Realm}, and a realm is the whole surface: it is
+ * acquired once per run and every cell of that run is evaluated in it, so a
+ * name one cell binds is still bound in the next. There is no per-cell
+ * evaluation beside it. One binding ships — `QuickJSSandbox`, the QuickJS-WASM
+ * binding that isolates a real separate realm in both Node and browsers — and a
+ * composition that offers none is refused with {@link realmUnsupported}.
+ *
+ * Cancellation is fiber interruption and teardown is scope finalization; a
+ * sandbox never installs a host abort signal.
+ *
+ * @since 0.1.0
+ */
+import { Context, Effect, Layer, Schema, type Scope } from "effect";
+import * as Cell from "./Cell.ts";
+import type { HarnessError } from "./HarnessError.ts";
+import type * as VariablesPanel from "./VariablesPanel.ts";
+/**
+ * Stable failures raised by a sandbox binding itself, as opposed to failures
+ * of the cell it was asked to run.
+ *
+ * A cell that throws is a {@link Cell.Raised} outcome, not a sandbox error.
+ * These codes describe the sandbox being unable to do its job at all.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export declare const SandboxErrorCode: Schema.Literals<readonly ["unavailable", "unsupported", "runtime_failed"]>;
+/**
+ * Stable failures raised by a sandbox binding itself.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type SandboxErrorCode = typeof SandboxErrorCode.Type;
+declare const SandboxError_base: Schema.Class<SandboxError, Schema.TaggedStruct<"flows/harness/SandboxError", {
+    readonly code: Schema.Literals<readonly ["unavailable", "unsupported", "runtime_failed"]>;
+    readonly message: Schema.String;
+    readonly cause: Schema.optional<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A failure of the sandbox binding.
+ *
+ * @category errors
+ * @since 0.1.0
+ * @slop
+ */
+export declare class SandboxError extends SandboxError_base {
+}
+/**
+ * One flow invocation requested from inside a running cell.
+ *
+ * `ordinal` is the zero-based execution order of the call within the cell. It
+ * is the replay anchor: re-executing the same source reaches the same ordinal
+ * with the same declaration, which is what lets a settled boundary replay
+ * instead of re-running.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export interface Invocation {
+    readonly ordinal: number;
+    readonly flow: string;
+    readonly input: Schema.Json;
+    /**
+     * Whatever the cell passed as the call's `at` option, undecoded.
+     *
+     * It arrives as the raw JSON the cell wrote rather than as an id because the
+     * boundary, not the realm, decides whether it is a checkpoint: a cell that
+     * passes a string, a failure envelope, or last frame's result gets an
+     * resolved `invalid_input` failure naming what `at` takes. Throwing from inside
+     * the sandbox would lose the calls the cell had already paid for.
+     */
+    readonly at?: Schema.Json | undefined;
+}
+/**
+ * One request to pin the workspace, issued from inside a running cell.
+ *
+ * It carries only its ordinal because that is the whole of its identity: the
+ * cell source and the frame are the boundary's, and the ordinal is what makes
+ * the pin land where the cell wrote it. See {@link Minter}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Mint {
+    readonly ordinal: number;
+}
+/**
+ * Pins the workspace on behalf of a running cell.
+ *
+ * A mint travels the same queue as a flow call and is settled by the same drive
+ * loop, in issue order, one at a time. That ordering is the whole contract:
+ * `ctx.checkpoint()` promises the tree as it stands *at the line it is written
+ * on*, and the only way a cell can move the tree is by issuing a call, so a
+ * queue that settles in issue order pins exactly the tree the cell was looking
+ * at. A mint that runs on its own schedule — a side channel, a host callback,
+ * anything the queue does not order — would pin whichever tree happened to be
+ * there when it got round to it.
+ *
+ * The result is a {@link Cell.CallResult} like any other, so a host with no
+ * store, a run past its checkpoint bound, and a store that failed are all
+ * resolved `{ ok: false, error }` refusals rather than teardown.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Minter = (mint: Mint) => Effect.Effect<Cell.CallResult, HarnessError>;
+/**
+ * The refusal a binding answers `ctx.checkpoint()` with when the caller wired
+ * no minter.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const mintUnavailable: Minter;
+/**
+ * Resolves one invocation on behalf of a running cell.
+ *
+ * A {@link Cell.CallResult} of `failure` resolves in the cell as
+ * `{ ok: false, error }`, where `error` contains `code`, `message`, and `hint`;
+ * it does not throw. Success resolves with the flow's own value, unwrapped.
+ * Branch on `.ok === false` and `.error.code` to recover. For a flow whose
+ * successful result has a `stdout` field, a cell can retry a timed-out call:
+ *
+ * ```ts
+ * let result = await ctx.call("bash", { command: "find . -name '*.ts'" })
+ * if (result.ok === false && result.error.code === "timeout") {
+ *   result = await ctx.call("bash", { command: "find src -name '*.ts'" })
+ * }
+ * console.log(result.ok === false ? result.error.code : result.stdout)
+ * ```
+ *
+ * Anything the cell must not observe, such as a permission park, an abort,
+ * or an engine failure, travels in the effect's error channel and tears the
+ * cell down.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export type Handler = (invocation: Invocation) => Effect.Effect<Cell.CallResult, HarnessError>;
+/**
+ * Realm memory ceiling and default execution limits for its evaluations.
+ *
+ * Bindings fill every ceiling they can enforce from {@link defaultLimits} when
+ * the caller omits it. A binding that cannot honour an explicitly requested
+ * limit fails with `unsupported` rather than silently ignoring it.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export interface Limits {
+    /**
+     * Maximum number of flow calls one cell may make; a non-negative safe integer.
+     * A checkpoint mint settles on the same channel and counts against this budget.
+     */
+    readonly calls?: number | undefined;
+    /** Maximum sandbox heap, in bytes; at least {@link minimumMemoryBytes}. */
+    readonly memoryBytes?: number | undefined;
+    /**
+     * Maximum interpreter steps before the cell is stopped.
+     *
+     * A step is one interrupt check, not one bytecode operation: an interpreter
+     * polls its budget periodically, so this bounds work rather than counting
+     * individual operations. The limit is a safe integer of at least
+     * {@link minimumSteps}.
+     */
+    readonly steps?: number | undefined;
+    /**
+     * Maximum cell-compute time in milliseconds; a safe integer of at least
+     * {@link minimumTimeMs}.
+     *
+     * This bounds the cell's own JavaScript execution. Time spent suspended in
+     * an outstanding `ctx.call` or `ctx.checkpoint()` does not count: host work
+     * belongs to the boundary that runs it, and charging it here rejected every cell that
+     * awaited a real test run — 57 of the 62 rejected frames in the first
+     * SWE-bench benchmark were legitimate long `bash` calls hitting this clock.
+     */
+    readonly timeMs?: number | undefined;
+    /**
+     * Maximum whole-evaluation time in milliseconds, host calls included; a
+     * non-negative safe integer.
+     *
+     * The backstop for a host call that never settles. Generous on purpose: a
+     * cell awaiting a ten-minute test suite is working, not stuck.
+     */
+    readonly totalMs?: number | undefined;
+    /** Flow names whose pending call time does not spend the frame backstop. */
+    readonly pauseTotalMsFor?: ReadonlyArray<string> | undefined;
+    /**
+     * Maximum wall-clock time one flow call may take, in milliseconds; a
+     * non-negative safe integer.
+     *
+     * The per-call budget {@link totalMs} cannot supply. `totalMs` is the frame's
+     * last resort, and a call that overruns it takes the whole frame down with a
+     * `limit_exceeded` rejection the model never sees as an answer: on the
+     * SWE-bench django instance one broad `grep` held its cell for the entire
+     * 900,000 ms ceiling, 75% of a 1,204-second run. This ceiling settles that
+     * same call as an ordinary resolved failure instead, so the cell observes a
+     * timeout it can narrow and retry inside the frame it is already in.
+     */
+    readonly callMs?: number | undefined;
+}
+/**
+ * Per-frame overrides of a realm's opening limits. Omitted or undefined fields
+ * inherit the realm defaults. The memory ceiling remains fixed for the run.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type EvaluationLimits = Omit<Limits, "memoryBytes">;
+/**
+ * Which limits a binding can actually enforce.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export interface Capabilities {
+    readonly calls: boolean;
+    readonly memoryBytes: boolean;
+    readonly steps: boolean;
+    readonly timeMs: boolean;
+}
+/**
+ * The execution ceilings a cell runs under when the caller declares none.
+ *
+ * Agent-authored source must never acquire an unbounded frame merely because a
+ * host omitted configuration. These values are deliberately generous for a
+ * cell, whose work is choosing flow calls and shaping JSON between them. There
+ * is no spelling for "no ceiling": a host that needs more raises the relevant
+ * finite value explicitly.
+ *
+ * @category constants
+ * @since 0.1.0
+ * @slop
+ */
+export declare const defaultLimits: Readonly<{
+    calls: 64;
+    memoryBytes: number;
+    steps: 1000;
+    timeMs: 30000;
+    totalMs: 900000;
+    callMs: 120000;
+}>;
+/**
+ * Smallest interpreter-step budget a binding can enter a realm under.
+ *
+ * A zero budget interrupts the binding's own scaffolding before any cell source
+ * runs, which escapes as a crash rather than a ceiling report, so the sandbox
+ * boundary refuses it as `unsupported`.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const minimumSteps = 1;
+/**
+ * Smallest wall-clock budget, in milliseconds, a binding can enter a realm under.
+ *
+ * A zero budget interrupts the binding's own scaffolding before any cell source
+ * runs, which escapes as a crash rather than a ceiling report, so the sandbox
+ * boundary refuses it as `unsupported`.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const minimumTimeMs = 1;
+/**
+ * Smallest heap ceiling the QuickJS binding can initialize and tear down
+ * safely.
+ *
+ * QuickJS needs space for its runtime and context before cell source runs.
+ * Lower ceilings can leave a partially initialized context that aborts during
+ * disposal, so they are refused at the sandbox boundary.
+ *
+ * @category constants
+ * @since 0.1.0
+ * @slop
+ */
+export declare const minimumMemoryBytes: number;
+export { printFrameBytes, printRetainedBytes, printStatementFloor } from "./internal/printChannel.ts";
+/**
+ * Fills omitted ceilings from {@link defaultLimits} for limits a binding can
+ * enforce.
+ *
+ * Capability gating applies only to defaults. An explicit unsupported limit is
+ * passed through so the binding can refuse it instead of silently widening the
+ * caller's authority.
+ *
+ * @category constructors
+ * @since 0.1.0
+ * @slop
+ */
+export declare const withDefaults: (capabilities: Capabilities, limits: Limits | undefined) => Limits;
+/**
+ * Merges and validates one frame's limits without changing the realm defaults.
+ * Only per-frame ceilings can be overridden; memory belongs to the realm.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const evaluationLimits: (defaults: Limits, overrides: EvaluationLimits | undefined) => Effect.Effect<EvaluationLimits, SandboxError>;
+/**
+ * What a REPL cell asked the controller to do.
+ *
+ * A cell runs as a global async script in a persistent realm. Top-level
+ * `await` is supported; top-level `return` is invalid. The first `ctx.done`
+ * or `ctx.park` that records an intent seals the frame. Later `ctx.done` and
+ * `ctx.park` calls do nothing. Ordinary JavaScript continues running, but later
+ * `ctx.call` and `ctx.checkpoint` calls resolve with a `run_completed` failure
+ * envelope without dispatching host work.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Intent = {
+    readonly _tag: "Done";
+    readonly output: string;
+    readonly value?: Schema.Json | undefined;
+} | {
+    readonly _tag: "Park";
+    readonly reason: "waiting-input" | "waiting-event" | "waiting-quota";
+    readonly message: string;
+};
+/**
+ * Builds the durable transition one cell settled.
+ *
+ * A cell states its intent by calling, so this is the only place a
+ * {@link Cell.Transition} is constructed. The realm is the run's memory and the
+ * print buffer is what the next turn reads, so nothing is filed on the way out:
+ * the transition carries only the current intent.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const replTransition: (intent: Intent | undefined, justification: string | undefined) => Cell.Transition;
+/**
+ * One cell evaluated inside a realm that outlives it.
+ *
+ * `frame` names the evaluation for the realm's own stack traces, so a throw
+ * reported in frame 7 says which cell threw.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface RealmEvaluation {
+    /** Reconstruct a timed-out frame only through its recorded bridge prefix. */
+    readonly replay?: {
+        readonly boundary: typeof FrameBoundary.Type;
+        readonly outcome: Cell.Outcome;
+    } | undefined;
+    /** Replaces ctx.flows with this frame's frozen catalog; omitted keeps the current catalog. */
+    readonly flows?: Readonly<Record<string, Cell.FlowProjection>> | undefined;
+    readonly cell: Cell.Source;
+    /**
+     * The program the controller's boundary parse already compiled from `cell`.
+     *
+     * A binding evaluates this verbatim when it is present, because the parse it
+     * would do is the parse the boundary already did: a controller runs
+     * {@link compile} before it commits a frame, so a binding that parses the
+     * cell again parses every cell of the run twice. Omitted means the binding
+     * compiles the cell itself, which is what a host driving a realm directly
+     * does.
+     */
+    readonly program?: string | undefined;
+    readonly frame: number;
+    readonly call: Handler;
+    /**
+     * Settles a `ctx.checkpoint()` issued by this cell.
+     *
+     * Optional, and absent means the caller pins no trees — which the cell is
+     * told through a resolved failure envelope at the line it asked. It is a
+     * separate collaborator from `call` because a checkpoint is not a flow:
+     * it is neither in the catalog nor
+     * subject to the capability envelope, and the run's own bound on how many
+     * trees it may pin is the controller's, not any flow's.
+     */
+    readonly mint?: Minter | undefined;
+    /**
+     * Whether the caller bounds each settlement itself.
+     *
+     * The loop's own {@link Limits.callMs} ceiling is a clock race it synthesizes
+     * a failure from, and that failure is journaled nowhere: the call it
+     * interrupted never settled, so nothing downstream holds a result for it. A
+     * re-executed cell runs the same call again against a world that has moved
+     * on, gets an answer this time, and takes a branch the original attempt never
+     * took — with every irreversible effect below the fork bought twice.
+     *
+     * A caller that journals its settlements applies the same ceiling itself, in
+     * front of the boundary that records what the ceiling produced, and sets this
+     * so the loop adds none of its own — because two clocks racing one call means
+     * the unrecorded one wins: the loop's starts first.
+     */
+    readonly bounded?: boolean | undefined;
+    /** Validated overrides for this frame only; memory is fixed when the realm opens. */
+    readonly limits?: EvaluationLimits | undefined;
+}
+/**
+ * The bridge frontier at a frame limit. Ordinals are zero-based;
+ * minus one means no dispatch or settlement occurred. A dispatched call may
+ * have been interrupted before its settlement was delivered to JavaScript.
+ * `timeout` requires truncating replay; `settled` identifies a limit the
+ * interpreter completed itself, such as its step or call budget.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const FrameBoundary: Schema.Struct<{
+    readonly terminal: Schema.Literals<readonly ["timeout", "settled"]>;
+    readonly dispatched: Schema.Int;
+    readonly settled: Schema.Int;
+}>;
+/**
+ * Everything one REPL frame produced.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface RealmFrame {
+    /** Present when evaluation ended at a frame limit. */
+    readonly boundary?: typeof FrameBoundary.Type | undefined;
+    readonly outcome: Cell.Outcome;
+    /** What the cell printed, already bounded; empty when it printed nothing. */
+    readonly prints: string;
+    /** Every name the realm holds after the cell ran. */
+    readonly bindings: ReadonlyArray<VariablesPanel.Binding>;
+}
+/**
+ * A JavaScript realm that persists across the cells of one run.
+ *
+ * Teardown is scope closure, so a realm is acquired by the loop that uses it and
+ * cancellation is still fiber interruption.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export interface Realm {
+    readonly evaluate: (evaluation: RealmEvaluation) => Effect.Effect<RealmFrame, SandboxError | HarnessError>;
+}
+/**
+ * The initial catalog and limits a realm is opened with.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface RealmOptions {
+    readonly flows: Readonly<Record<string, Cell.FlowProjection>>;
+    /**
+     * The ceilings the realm enforces. `memoryBytes` becomes a **run** budget once
+     * a realm outlives a cell, judged at each frame's start against what the
+     * realm's own names weigh; a frame that opens over it runs nothing and is told
+     * which names to free. Every other ceiling stays per-frame, because they are
+     * counters the interrupt handler reads rather than properties of the runtime.
+     */
+    readonly limits?: Limits | undefined;
+}
+/**
+ * The deterministic script sandbox.
+ *
+ * @category services
+ * @since 0.1.0
+ * @slop
+ */
+export interface Sandbox {
+    readonly capabilities: Capabilities;
+    /**
+     * Opens the realm the run's cells share.
+     *
+     * Absent on a binding that has no persistent realm to offer, which is what a
+     * host composing such a binding is told when the run opens rather than in the
+     * middle of a frame. A realm is the only way a cell runs: there is no
+     * per-frame evaluation beside it, because a cell that could not see what the
+     * cell before it bound was the surface this harness deleted.
+     */
+    readonly openRealm?: (options: RealmOptions) => Effect.Effect<Realm, SandboxError, Scope.Scope>;
+}
+/**
+ * Context service for the selected sandbox binding.
+ *
+ * @category services
+ * @since 0.1.0
+ * @slop
+ */
+export declare const Sandbox: Context.Service<Sandbox, Sandbox>;
+/**
+ * Constructs a sandbox from an implementation.
+ *
+ * @category constructors
+ * @since 0.1.0
+ * @slop
+ */
+export declare const make: (implementation: Sandbox) => Sandbox;
+/**
+ * Provides a sandbox implementation.
+ *
+ * @category layers
+ * @since 0.1.0
+ * @slop
+ */
+export declare const layer: (implementation: Sandbox) => Layer.Layer<Sandbox>;
+/**
+ * Constructs an unavailable sandbox stub, optionally overriding operations.
+ *
+ * It offers no realm, which is what a run composed against it is told: see
+ * {@link realmUnsupported}.
+ *
+ * @category constructors
+ * @since 0.1.0
+ * @slop
+ */
+export declare const makeNoop: (overrides?: Partial<Sandbox>) => Sandbox;
+/**
+ * Provides an unavailable sandbox stub.
+ *
+ * @category layers
+ * @since 0.1.0
+ * @slop
+ */
+export declare const layerNoop: (overrides?: Partial<Sandbox>) => Layer.Layer<Sandbox>;
+/**
+ * Refuses a run on a binding that has no persistent realm.
+ *
+ * Stated rather than silently downgraded: a realm is the whole surface, so a
+ * binding without one cannot run a cell at all and saying so at the open is the
+ * only honest answer.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const realmUnsupported: SandboxError;
+/**
+ * Settles one overrunning flow call as a resolved failure envelope in the cell.
+ *
+ * The message is written for the model, because the model is who reads it: it
+ * names the flow, the budget it spent, and the one action that recovers the
+ * frame. A rejection at the whole-evaluation ceiling teaches the model nothing
+ * — the frame is already gone by the time it could act.
+ *
+ * Exported so a caller that bounds its own settlements
+ * ({@link RealmEvaluation.bounded}) synthesizes the same refusal the loop would
+ * have: one ceiling means one sentence, whichever clock enforced it.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const callTimedOut: (flow: string, callMs: number) => Cell.CallResult;
+/**
+ * Erases type-only syntax from a cell without evaluating or resolving modules.
+ *
+ * Only Node's strip-safe TypeScript subset is accepted. Constructs that need
+ * JavaScript emit are refused instead of being silently transformed into new
+ * runtime behaviour.
+ *
+ * The parse itself belongs to `CellValidation`, which the controller already
+ * runs at the boundary before it commits a frame; this is the same answer, for
+ * a binding that only needs the program or the reason there is none.
+ *
+ * @category conversions
+ * @since 0.1.0
+ * @slop
+ */
+export declare const compile: (cell: Cell.Source) => string | Cell.Rejected;
+/**
+ * A queued call awaiting resolution by a binding's driver.
+ *
+ * @category models
+ * @since 0.1.0
+ * @slop
+ */
+export interface PendingCall {
+    readonly ordinal: number;
+    readonly flow: string;
+    readonly input: Schema.Json;
+    /** Undecoded `at` option; see {@link Invocation.at}. */
+    readonly at?: Schema.Json | undefined;
+    /**
+     * Whether this entry is a flow call or a request to pin the tree.
+     *
+     * Both ride one queue because both have to be ordered against each other: a
+     * mint that overtook an edit, or an edit that overtook a mint, would pin the
+     * wrong tree. Absent means `call`, so every binding that queues an ordinary
+     * call is unchanged.
+     */
+    readonly kind?: "call" | "checkpoint" | undefined;
+    readonly settle: (result: Cell.CallResult) => void;
+    readonly abort: (message: string) => void;
+}
+/**
+ * Drives one externally compiled cell to settlement: settle queued calls one at
+ * a time, in the order the cell issued them, until the cell settles.
+ *
+ * One at a time is deliberate. Data-dependent calls are the normal case, and a
+ * deterministic execution ordinal is what makes a mid-cell crash replayable.
+ *
+ * Bindings differ only in how a cell is compiled and how its promises are
+ * settled, so the interleaving lives here once rather than in each of them.
+ *
+ * @category constructors
+ * @since 0.1.0
+ * @slop
+ */
+export declare const driveCell: (options: {
+    readonly replay?: RealmEvaluation["replay"];
+    readonly progress?: ((dispatched: number, settled: number) => void) | undefined;
+    readonly pending: Array<PendingCall>;
+    /** Called after each resolved call so a binding may flush its job queue. */
+    readonly flush: () => void;
+    readonly finished: () => Cell.Outcome | undefined;
+    readonly abort: (message: string) => void;
+    readonly handler: Handler;
+    /** Settles a `ctx.checkpoint()`; omitted means the run pins none. */
+    readonly mint?: Minter | undefined;
+    /** Whether the caller bounds each settlement itself; see {@link RealmEvaluation.bounded}. */
+    readonly bounded?: boolean | undefined;
+    readonly limits?: Limits | undefined;
+}) => Effect.Effect<Cell.Outcome, SandboxError | HarnessError>;
+/**
+ * Projects a thrown value into a stable serializable cell outcome.
+ *
+ * @category conversions
+ * @since 0.1.0
+ * @slop
+ */
+export declare const raisedOutcome: (error: unknown) => Cell.Raised;
+//# sourceMappingURL=Sandbox.d.ts.map