@zackbart/connecta 0.25.0 → 0.26.1

package/documentation/code-mode.md

@@ -16,10 +16,16 @@ identifiers (`A1`, `E3`, …) are stable and cited by [Verification](#verificati
 ## Deploy-time capability
 
 The `executor` passed to `createConnecta()` is required. `tools/list` is exactly
-seven — `execute_code`, `search_tools`, `call_tool`, `call_destructive_tool`,
-`authorize_connector`, `get_result`, and `skills`. Construction fails when the
-executor is missing, and the removed `surface` option is rejected rather than
-ignored ([#273](https://github.com/zackbart/connecta/issues/273)).
+eight — `execute_code`, `resume_execution`, `search_tools`, `call_tool`,
+`call_destructive_tool`, `authorize_connector`, `get_result`, and `skills`.
+Construction fails when the executor is missing, and the removed `surface`
+option is rejected rather than ignored
+([#273](https://github.com/zackbart/connecta/issues/273)).
+
+[Resumable writes](#pausing-and-resuming) need storage with `compareAndSet`:
+omitted, `execute.resumableWrites` is on exactly when the storage has it (not
+Cloudflare KV, which warns once at startup), `true` without it refuses to
+construct, and `/health` reports which.
 
 On Node, install the optional `quickjs-emscripten` peer and use the package's
 QuickJS subpath:
@@ -107,16 +113,15 @@ is just another provider function (`M8`).
 
 ## The program
 
-**P1.** A program is one JavaScript `async` arrow-function expression, evaluated
-once; its resolved value is the result. The expression may end with a `;`, and
-with whitespace or comments after it: `execute_code` drops those terminators
-before either executor sees the program, because both evaluate it inside
-parentheses, where `};` was a syntax error on QuickJS and on a Dynamic Worker
-either the same error or a program that quietly returned `undefined`. Only
-semicolons that trail the expression go; `async () => 1; 2` is still more than
-one expression. Both executors also accept markdown-fenced code and a bare
-statement body, normalizing those differently — a courtesy to model output,
-not contract, so anything else may be accepted, rejected, or reinterpreted.
+**P1.** A program is one JavaScript `async` arrow expression, evaluated once;
+its resolved value is the result. Before either executor sees it, `execute_code`
+removes trailing semicolons (and retains comments) so parenthesized evaluation
+works on both. `async () => 1; 2` is still more than one expression. The host
+also recovers one JavaScript fence, even when prose surrounds it, `export default`
+around an async arrow, or one named `async function` declaration with simple
+parameters. The result remains one async arrow. Multiple fences, extra
+statements, and bare statement bodies are outside host recovery. QuickJS may
+wrap a bare body when driven directly; that is outside the portable contract.
 
 **P2.** The only capabilities in the contract are `connecta.search`,
 `connecta.describe`, `connecta.call`, `connecta.emit`, and `console.log` /
@@ -136,14 +141,34 @@ storage carried to the next program, and no request-bound object outliving its
 request. Within one execution, host calls share one downstream request scope.
 `S9`'s output observation is host-owned catalog metadata, not guest memory — a
 later program receives a labeled field/type schema through discovery, never a
-prior value or object. Planned resumable writes
-([ethos](../ethos.md#decisions)) will let a paused run's journal survive,
-bounded and expiring; the program still gets no state of its own.
+prior value or object. A run paused at a write leaves a bounded, expiring
+journal (`W3`) for `resume_execution` to replay — host-owned data, not guest
+state: the replay gets back exactly the answers the first play got.
 
 **P5.** Plain JavaScript only; TypeScript syntax is a syntax error. Portable
 code does not import: QuickJS blocks imports, Dynamic Workers expose the `X5`
 runtime modules, and neither exposes `require`.
 
+**P6.** A run's clock and randomness are pinned. `Date.now()`, `new Date()`,
+and `Date()` read one instant the host takes at run start, and it does not
+advance; `Date` with arguments, `Date.parse`, and `Date.UTC` are the native
+ones. `Math.random()` is sfc32 seeded from the host's CSPRNG per run. On a
+Dynamic Worker (QuickJS has neither, `X5`), `crypto.getRandomValues` and
+`randomUUID` draw from the same stream and `performance.now()` stays at 0, on
+the objects and their prototypes — so a Workers-only program replays too,
+which makes none of them contract (`P2`). An `Intl` formatter asked for "now"
+formats the pinned instant, and local time is UTC on both executors (the
+QuickJS child runs with `TZ=UTC`). The replacements are trusted prelude,
+locked like `Error` (`X11`), and the native constructor's `now` and prototype
+`constructor` read the same instant; QuickJS lets `defineProperty` replace a
+locked *global* binding, but the replacement is the program's own code. The
+reason is replay (`W6`): a program that branched on a moving clock would take
+another branch the second time and diverge (`W8`), and pinning every run means
+none can tell whether it is replayed. A program cannot time itself; `R7`
+measures from the host. The pin is best-effort beyond these: a program that
+depends on a source it misses, such as the order Workers timers fire in, is
+not portable (`P2`) and fails a replay as divergence.
+
 ## Addressing
 
 **A1.** A tool has one canonical address, `<connectorId>.<toolName>`, exactly as
@@ -201,6 +226,7 @@ bounds:
 
 | Bound | Value |
 | --- | --- |
+| `execute_code` source | ≤ 65,536 UTF-8 bytes, checked before executor admission; over-limit source returns `invalid_args` |
 | Rendered shape | 1,024 UTF-8 bytes each |
 | Work per shape | 2,000 visits across schema nodes, property and required names, literal values, any constraint-free retry, and its key-only fallback |
 | Each enum node | 256 of those bytes |
@@ -234,11 +260,13 @@ signature is byte-identical to the one `search_tools` returns.
 
 **S1a.** `connector` loads only the named catalog; omit it only when the
 integration is ambiguous, because an unscoped search fans out across every
-configured connector. `safety: "readOnly"` returns exactly the tools available
-through `connecta.call`; `"approvalRequired"` returns the complementary
-fail-closed class, including false, missing, and contradictory annotations;
-omitted or `"all"` preserves the complete catalog. These filters grant no
-authority and change no admission decision.
+configured connector. `safety: "readOnly"` returns exactly the tools
+`connecta.call` runs unasked; `"approvalRequired"` returns the complementary
+fail-closed class, false, missing, and contradictory annotations included,
+whose calls pause (`W1`) unless config exempts them (`W12`), which a row marks
+with `approval: "exempt"` without moving it out of that class; omitted or
+`"all"` preserves the complete catalog, as a program that means to write needs.
+These filters grant no authority and change no admission decision.
 
 **S2.** A requested object schema carries `inputKeys`, `requiredInputKeys`
 (declared properties only), and `outputKeys`: the names the rendered schema
@@ -306,7 +334,9 @@ is treated as `{}`.
 
 **S6.** Every call goes through the same catalog, fail-closed read-only
 predicate, admission, credential containment, timeout classification, health
-accounting, and activity recording as an ordinary meta-tool call. The sandbox is
+accounting, and activity recording as an ordinary meta-tool call. The predicate
+decides whether a call runs or pauses (`W1`); nothing a program does decides
+it. The sandbox is
 an additional containment layer, not a second implementation of the boundary,
 and nothing a program does widens what it can reach.
 
@@ -383,10 +413,11 @@ caller what to do next, and never invents a cause it was not told.
 | --- | --- | --- |
 | `unknown_address` | no connector owns the address | false |
 | `unknown_tool` | the connector has no such tool | false |
-| `destructive_tool_requires_approval` | the tool is not explicitly read-only | false |
+| `destructive_tool_requires_approval` | the tool is not explicitly read-only and the deployment has no resumable writes (`E4`) | false |
 | `auth_required` | the credential is missing, expired, or rejected | false |
 | `invalid_args` | arguments or discovery bounds were rejected | false |
 | `not_found` | the downstream answered and the resource is not there — the one code that says skip this id rather than stop, raised only where the provider tells absence from a permission gap | false |
+| `conflict` | the write named a base version someone else already moved past; nothing changed. `details.current` says where things stand (at most 20 whole-number entries) — re-read, reapply, retry with that base | false |
 | `input_required_unsupported` | a downstream asked for mid-call input | false |
 | `rate_limited` | the downstream reported a rate limit | true |
 | `unavailable` | the downstream is down or unreachable; optional sanitized `details.host` and `details.code` describe the transport failure without paths, queries, credentials, or provider prose | true |
@@ -396,7 +427,20 @@ caller what to do next, and never invents a cause it was not told.
 | `catalog_lookup_failed` | the connector's catalog could not be loaded | per cause |
 | `result_processing_failed` | the result could not be prepared | per message |
 | `result_too_large` | a discovery response exceeded its byte bound | false |
-| `budget_exceeded` | the run exhausted a host-call or emitted-output budget | false |
+| `budget_exceeded` | the run exhausted a host-call, write, or emitted-output budget | false |
+| `execution_paused` | the run already stopped at a write that needs approval; no further call is made (`W1`) | false |
+| `pending_write_too_large` | a write's arguments are over 16 KiB serialized, too large to hold for approval (`W2`) | false |
+| `journal_too_large` | the run's source and recorded calls are over 4 MiB, too much to pause (`W3`) | false |
+| `write_outcome_unknown` | a write was sent and no answer came back; it is never sent again (`W9`) | false |
+| `execution_interrupted` | a resumed play sent writes and then ended without pausing, or storage failed under it; the run cannot be resumed (`W5`) | false |
+| `execution_diverged` | a replay stopped matching its journal (`W8`) | false |
+| `execution_claim_lost` | another `resume_execution` took the run over mid-play (`W5`) | false |
+| `approval_mismatch` | `resume_execution` did not repeat the paused write exactly (`W4`) | false |
+| `execution_token_stale` | the token names an earlier pause of a run that has moved on (`W4`) | false |
+| `execution_in_progress` | another `resume_execution` is playing the run (`W5`) | true |
+| `execution_expired` | the paused run outlived `execute.pausedRunTtlSeconds`, or reached another write after it (`W3`) | false |
+| `execution_not_found` | no paused run matches the token in this caller's partition and pool (`W3`) | false |
+| `resumable_writes_unavailable` | the deployment has no resumable writes, so nothing can be resumed (`W11`) | false |
 
 **E3.** `auth_required` carries the same recovery envelope as `call_tool`:
 `connector`, `operation`, `recovery` (`oauth`, `operator_config`, or
@@ -404,14 +448,14 @@ caller what to do next, and never invents a cause it was not told.
 sentence. A program cannot recover credentials — only an operator can — so stop
 and let the failure reach the model.
 
-**E4.** An unannotated, write-capable, or destructive tool stays refused with
-`destructive_tool_requires_approval`; `nextAction` carries its canonical address
-to `call_destructive_tool`, plus the original arguments when they fit the
-512-byte echo budget — whole or not at all, since a clipped copy is a different
-call. The model's short `reason` for the human reviewer grants no authority,
-never goes downstream, and generated code cannot mint the capability. Planned
-resumable writes ([ethos](../ethos.md#decisions)) replace this refusal with a
-pause the host approves; until they ship, it stands as written.
+**E4.** An unannotated, write-capable, or destructive tool never runs unasked:
+it pauses the run (`W1`), or, without resumable writes, is refused with
+`destructive_tool_requires_approval`, `nextAction` carrying its canonical
+address to `call_destructive_tool` plus the original arguments when they fit
+the 512-byte echo budget — whole or not at all, since a clipped copy is a
+different call. The model's short `reason` grants no authority and never goes
+downstream, and generated code can neither mint the capability nor approve its
+own write.
 
 **E5.** Failures of the *execution*, not of a call, never appear inside the
 guest: admission rejection (`executor_overloaded`, retryable, with
@@ -460,13 +504,11 @@ provider prose remains `connector_call_failed`.
 
 ## Results and projection
 
-**R1 (verdict: projection stays explicit).** A program's return value reaches
-the model unchanged except for the size guard in `R2`. Connecta does not
-summarize, reshape, or field-select it, and there is no automatic projection
-mode: the measured byte win came from *program-authored* projection, while a
-host heuristic would drop deliberately returned fields invisibly. Helpers earn
-their way in only if [#222](https://github.com/zackbart/connecta/issues/222)
-shows programs failing to project on their own.
+**R1 (verdict: projection stays explicit).** A program's return reaches the model
+unchanged except for `R2`'s size guard. Connecta does not summarize or select
+fields. Program-authored projection saved bytes; host heuristics could drop
+deliberately returned fields. Helpers need [#222](https://github.com/zackbart/connecta/issues/222)
+evidence that programs fail to project.
 
 **R2.** The boundary is 24,000 serialized characters (~6k tokens). A value over
 it is replaced by exactly one envelope:
@@ -484,15 +526,16 @@ The envelope is itself bounded as serialized, so `totalChars` is always the true
 size of what the program returned and truncation happens exactly once no matter
 how many hops the value takes.
 
-**R3.** Truncation is a *successful* result, not an error: the program ran, and
-the honest report is that its answer was too large. The fix is a program that
-returns less, which is why the envelope says so.
+**R3.** Truncation is a *successful* result: the program ran but returned too
+much. Run a program that returns less; that is why the envelope says so.
+
+**R4 (verdict: no result paging for programs).** Program results have no
+`get_result` handle. A program can shrink its return; paging would reward
+unprojected data.
 
-**R4 (verdict: no result paging for programs).** A truncated program result
-carries no `get_result` handle, unlike `call_tool`. `get_result` exists so a
-model can page a *downstream payload* it could not shrink; a program can shrink
-anything, so paging its result would reward the behavior code mode exists to
-remove.
+For non-repeatable writes, inspect and reduce the full result before return,
+or page a direct `call_destructive_tool` result with `get_result`. Sampling a
+program result may discard the only copy.
 
 **R5.** `console.log`, `console.warn`, and `console.error` are captured in call
 order and returned as one `logs` string, capped at 4,000 characters with a
@@ -635,6 +678,7 @@ because connecta enforces them above the sandbox:
 | Bound | Value |
 | --- | --- |
 | Host calls per execution, shared by `search`, `describe`, and `call` | 20 by default, `execute.maxHostCalls` |
+| Writes per run, on top of the host calls they also spend (`W10`) | 10 by default, `execute.maxWrites` |
 | Deadline per host call | 15 s, `execute.hostCallTimeoutMs`; one deadline covers catalog resolution, admission, and the connector call |
 | Discovery page | ≤ 100 tools, ≤ 256,000 serialized bytes |
 | `describe` addresses | ≤ 100 |
@@ -649,7 +693,10 @@ unknown tools, catalog failures, and other pre-dispatch refusals cost what a
 successful call costs; catching a refusal does not refund it. `search` and
 `describe` likewise spend on entry. Exhausting the budget fails that call with
 non-retryable `budget_exceeded` (`E2`) and a message naming the budget. No
-connector is reached, and the budget does not refill inside one execution.
+connector is reached, and the budget does not refill inside one execution. A
+replay (`W6`) spends both budgets again for every call it answers from the
+journal, so one play's totals are the run's totals and nothing is counted
+twice.
 
 **L5.** The guest is memory-, stack-, and CPU-bounded, and a program that
 exhausts a bound ends the run with an error instead of degrading the host. The
@@ -691,9 +738,12 @@ refuses that attempt above the invocation path, so it is charged but records no
 event.
 
 **V2.** Each event carries `connectorId`, `toolName`, `address`, `source`,
-`outcome` (`success`, `error`, `timeout`, `cancelled`), `durationMs`,
-`attempts`, and `errorCode` when the call *failed* — plus request, actor, and
-server identity. Typed codes derive an optional `friction`: `tool_not_found`,
+`outcome` (`success`, `error`, `timeout`, `cancelled`, `paused`, `approved`),
+`durationMs`, `attempts`, and `errorCode` when the call *failed* — plus
+request, actor, and server identity. `paused` and `approved` name the write a
+run stopped at and the one `resume_execution` approved, with zero attempts;
+an approval adds `approval: "call" | "tool"`, never the arguments. A resumed
+play's live calls carry `source: "resume_execution"`. Typed codes derive an optional `friction`: `tool_not_found`,
 `schema_retry`, `destructive_reroute`, or `auth_required`. The fifth class,
 `result_too_large`, cannot reach an `execute_code` event: it belongs to a
 `call_tool` result too large to return inline, and a program's own return is
@@ -714,6 +764,115 @@ payload-free *by construction* means the event has nowhere to put a payload.
 distinctive artifact is the program source — exactly what a payload-free history
 must never keep.
 
+**V5.** A replayed call records nothing: it was recorded when it happened, and
+a second event would count one call twice. Nor does a call refused because its
+run had already stopped, which was never an attempt.
+
+## Pausing and resuming
+
+A program pauses host-side at its first write needing approval;
+`resume_execution` repeats that write to approve it, and the run replays from a
+journal to send it and carry on. A paused run is data, not a held program, so a
+restart loses nothing
+([#565](https://github.com/zackbart/connecta/issues/565)); `ExecuteResult` and
+the executor duties are unchanged.
+
+**W1.** A call to a tool not explicitly read-only reaches the run's write gate
+after validation and before admission, so nobody approves arguments the schema
+rejects and a pause costs no permit. Unless an approval covers it, it is not
+sent: it rejects `execution_paused`, as does every later host call —
+unjournaled, unrecorded — while calls in flight finish and are journaled; one
+of those turning unknown fails the run instead (`W9`). The program's result is
+discarded, and a write that reaches the gate after it settles is not sent.
+Calls are numbered in issue order and a write decides only after every
+lower-numbered call has, so the pause point is reproducible.
+
+**W2.** The pause is a success: `{ paused: { address, args, token, expiresAt,
+nextAction, hint } }`, `address` canonical and `args` whole, because the host
+shows the human exactly those; `nextAction` is the resume call. Arguments over
+16 KiB stop the run `pending_write_too_large`, nothing journaled; non-object
+arguments keep `E4`; a `__proto__` key is refused `invalid_args`, since a layer
+between program, host, and human could drop it and approve a different write.
+
+**W3.** The journal lives in the caller's result storage — the `get_result`
+stash's partition and trust level — and records the `/mcp/<pool>`: source,
+every host call and its answer, the `P6` clock and seed, and one header, the
+only key compared-and-set. Over 4 MiB fails `journal_too_large`. It expires
+`execute.pausedRunTtlSeconds` (default 1,800) after the first pause, and later
+pauses keep that deadline, so no replay mixes old reads with new. Another
+subject or pool finds no run.
+
+**W4.** `resume_execution` takes `token`, `address`, `args`, optional
+`approval`, and a dropped `reason`. Address and args must match the pending
+write as JSON, key order aside, with no `__proto__` key; otherwise it returns
+`approval_mismatch`. That, `execution_token_stale` (current pause),
+`execution_in_progress` (live claim), `execution_expired` (counts if writes
+were sent), and `execution_not_found` refuse before the claim, spending nothing.
+A repeat returns the ended run's answer past expiry; oversized text or emitted blocks get a completion receipt instead.
+
+**W5.** An approved write is sent at most once. Resuming claims the run by
+compare-and-set; a racing resume gets `execution_in_progress`. Each live write
+is first marked `sending` on the header, and a claim found moved sends nothing
+further and stops `execution_claim_lost`. The header outlives `expiresAt` while
+a claim is live, and by 30 minutes once a write was sent. A storage call over
+its deadline (the host call's, at least 5 s) fails: before dispatch nothing is
+sent, after it the run stops with the write counted. Replay picks up only at a
+pause: a play ended otherwise — executor failure (admission, cancellation, the
+`L3` watchdog) or a lapsed claim — returns to its pause only if it sent no
+write; a write left `sending` fails `write_outcome_unknown`, and sent writes
+fail `execution_interrupted`, the reads after them never journaled.
+
+**W6.** A replay runs from the top on the journal's clock and seed. A recorded
+call — matched by operation, address as written, and canonical arguments, in
+first issue order per key — is answered before the rest of the call path: no
+catalog, permit, connector, or activity (`V5`). A hit is never the pending
+call, which is not journaled. The approved write and everything after it go
+live. `emit` is not journaled; only the completing play delivers.
+
+**W7.** `approval: "call"`, the default, covers that one write; `"tool"` covers
+every later call to that canonical address for the run. Approvals live in the
+header, a retry's replacing one that sent nothing; nothing else grants one.
+Keep an authorized batch in one program; use tool scope for repeated calls to that address, while other addresses still need their own approval.
+
+**W8.** A replay fails `execution_diverged`, never replayed again, when (a) a
+call has no record before the approved write is repeated, (b) the program
+finishes without repeating it, or (c) without repeating a write already sent.
+
+**W9.** A write sent and never answered fails the run `write_outcome_unknown`
+wherever it is found — beside a pause, after the program returned, at a
+takeover — with its address, its args within the 512-byte echo budget, and
+`writes: { succeeded, failed, unknown }`; a failed run is never replayed. Only
+a refusal (`auth_required`, `invalid_args`, `not_found`, `rate_limited`,
+`conflict`) or the
+tool's own `isError` answers; an `isError` reading as a timeout does not, and
+`connector_call_failed` — an oversized body, a refused redirect — may come
+after the write landed. Every error from a resumed play carries `writes`, and
+once one landed or may have, `nextAction` says to check first; a program that
+throws after writing ends the run `failed` with them.
+
+**W10.** `execute.maxWrites` (default 10) bounds a run's writes beyond the host
+calls they spend, checked at the gate — so an over-budget write fails
+`budget_exceeded` instead of asking — and spent at dispatch.
+
+**W11.** Without resumable writes — storage without `compareAndSet`, or
+`execute.resumableWrites: false` — `E4` stands and `resume_execution` answers
+`resumable_writes_unavailable`.
+
+**W12.** Config may exempt a write from asking, and nothing else may
+([#566](https://github.com/zackbart/connecta/issues/566)). `execute.approval`
+maps connector ids and `connector.tool` addresses to `"never"` or `"ask"`; the
+address wins over the connector entry, which wins over a connector's own
+built-in default (reserved for connectors connecta ships), which wins over
+`"ask"`. An exempt call is decided at the same gate as `W1` and dispatches
+instead of pausing, with everything else an approved write gets: the write
+budget (`W10`), the write-ahead mark (`W5`), the journal, a `V1` event. Without
+resumable writes, other writes keep `E4`; an exempt one still finishes after
+the program returns, never hiding an unknown outcome (`W9`). Exempt is never
+read-only: no read-only tool is reported exempt, discovery keeps an exempt tool
+approval-required, `call_tool` refuses it, and no annotation grants it, or a
+downstream could exempt itself. Unknown connectors and `api()` addresses its
+tools lack refuse to construct; an unserved remote address never matches.
+
 ## Executor exceptions
 
 Documented divergences, with reasons. Everything else must match.
@@ -753,8 +912,8 @@ starts has no guest logs to recover.
 
 **X5. Leftover authority.** QuickJS blocks imports and has no `fetch`,
 `process`, timers, `crypto`, or `WebSocket`, and its Node child starts with an
-explicitly empty process environment rather than inheriting deployment variables
-or `NODE_OPTIONS`. A Dynamic Worker has those globals plus a non-contract set of
+explicit environment holding only `TZ=UTC` (`P6`) rather than inheriting
+deployment variables or `NODE_OPTIONS`. A Dynamic Worker has those globals plus a non-contract set of
 runtime builtins through `import()` and `process.getBuiltinModule()`, including
 `node:path`, `node:crypto`, `node:net`, `node:tls`, `node:dns`, `node:module`,
 and `cloudflare:workers`; the upstream set drifts, so that is not an allowlist.
@@ -798,6 +957,12 @@ none, because that boundary is an isolate-to-isolate call rather than a
 one tool call therefore fails on Node and may succeed on Workers — reduce inside
 the program either way (`R1`).
 
+**X12. A paused sandbox.** QuickJS stops: releasing the lease with the child
+still running recycles it (`X3`). A Dynamic Worker cannot be interrupted, so a
+paused program runs on until it settles or its deadline expires, every host
+call failing `execution_paused`. Connecta stops awaiting it at the pause and
+discards whatever it returns.
+
 **X11. Typed host rejection.** Both executors rebuild Connecta's authenticated
 host-failure frame as a thrown guest `Error` (`E1`). The per-run secret stays in
 the trusted prelude closure and the prelude locks `globalThis.Error`, so guest
@@ -821,10 +986,11 @@ passing one table is also the check on the executor duties above, with
 
 | Clauses | Test |
 | --- | --- |
-| `P1`, `P5` | `test/guest-api-contract.test.ts` (TypeScript syntax, trailing terminators), `test/program-source.test.ts` (which semicolons are terminators), `test/quickjs-executor.test.ts` (`normalizeCode`) |
-| `P2`, `X5` | `test/guest-api-contract.test.ts` (Dynamic globals plus loader-only filesystem, HTTP, environment, egress, DNS, and local `data:` boundaries), `test/guest-api-contract-quickjs.test.ts` (exact absent globals and blocked imports), `test/quickjs-child-stderr.test.ts` (empty child-process environment), `test/deployment-shapes.test.ts` (loader-only Worker construction) |
+| `P1`, `P5` | both guest-contract executors (TypeScript syntax, trailing terminators, wrapper recovery), `test/program-source.test.ts` (which semicolons and wrappers are recovered), `test/quickjs-executor.test.ts` (`normalizeCode`) |
+| `P2`, `X5` | `test/guest-api-contract.test.ts` (Dynamic globals plus loader-only filesystem, HTTP, environment, egress, DNS, and local `data:` boundaries), `test/guest-api-contract-quickjs.test.ts` (exact absent globals and blocked imports), `test/quickjs-child-stderr.test.ts` (a child-process environment holding only `TZ=UTC`), `test/deployment-shapes.test.ts` (loader-only Worker construction) |
 | `P3`, `X9` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` |
 | `P4` | `test/guest-api-contract.test.ts` (no cross-run leakage), `test/execute.test.ts` (one catalog load per connector per execution) |
+| `P6` | `test/guest-api-contract.test.ts` (a frozen clock across host calls, the seeded sfc32 stream against a reference, locked replacements, Workers `crypto` and `performance` pinned directly and through their prototypes, `Intl` "now" and UTC local time on both executors, a fresh pair per run, and a replay drawing the same values), `test/resumable-restart.test.ts` (the same draws after a restart) |
 | `A1`, `A2` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (canonical addressing), `test/server.test.ts` (bounded live connector inventory) |
 | `S1`, `S1a`, `S2` | `test/guest-api-contract.test.ts` (flat page, connector guides, schema keys, unfiltered browse), `test/execute.test.ts` (guide pagination/partial/no-match behavior and `$ref`/`allOf`), `test/meta-tools-search.test.ts` (mixed complete/partial ranking, stable pagination, the two safety classes), `test/typescript-signatures.test.ts` (the TypeScript format over provider and pathological schemas, search/describe parity, observed labeling), `test/typescript-signatures-parse.test.ts` (every rendering parses) |
 | `S3` | `test/guest-api-contract.test.ts` (typed uncaught bound), `test/execute.test.ts` (count limits, fan-out bound) |
@@ -833,8 +999,8 @@ passing one table is also the check on the executor duties above, with
 | `S7` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (parallel calls and shared admission) |
 | `S8`, `E1`, `X11` | both guest-contract executors (caught call, discovery, utility, budget, removed-function, and forgery cases; typed promise rejections), `test/quickjs-executor.test.ts` (oversized messages, private transport, forged frames) |
 | `S9` | `test/result-shapes.test.ts` (value exclusion, bounds, merging, LRU and time expiry, runtime isolation, read-only admission, declared precedence, definition invalidation, unwrapped MCP results, discovery provenance, copy isolation, failure isolation) |
-| `E2`, `E8` | `test/guest-api-contract.test.ts` (code → `retryable`, caught, parallel, and uncaught validation recovery), `test/meta-tools-call.test.ts` (direct, destructive, provider fallback), `test/validate.test.ts` (bounded payload-free findings), `test/errors.test.ts` |
-| `E3`, `E4` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`auth_required`, destructive reroute) |
+| `E2`, `E8` | `test/guest-api-contract.test.ts` (code → `retryable`, caught, parallel, and uncaught validation recovery, a conflict's bounded `current`), `test/meta-tools-call.test.ts` (direct, destructive, provider fallback), `test/validate.test.ts` (bounded payload-free findings), `test/errors.test.ts` |
+| `E3`, `E4` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`auth_required`, destructive reroute), `test/resumable.test.ts` (the refusal without resumable writes) |
 | `E5` | `test/guest-api-contract.test.ts` (execution-failure channel, in-flight `cancelled`), `test/execute.test.ts` (admission), `test/executor-admission.test.ts`, `test/quickjs-executor.test.ts` (mid-run shutdown) |
 | `E6`, `X8` | `test/guest-api-contract.test.ts` (unknown and inherited members, wrapped-message precedence), `test/quickjs-executor.test.ts` |
 | `E7` | `test/guest-api-contract.test.ts` (refusals about a `503`-named connector), `test/errors.test.ts` |
@@ -849,7 +1015,16 @@ passing one table is also the check on the executor duties above, with
 | `L4`, `L8` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (shared discovery/call budgets) |
 | `L5`, `L7`, `X2` | `test/quickjs-executor.test.ts` (CPU, heap), `test/execute.test.ts` and `test/executor-admission.test.ts` (bounded admission and queue) |
 | `L6`, `X10` | `test/quickjs-executor.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message), `test/quickjs-child-stderr.test.ts` (outer reply serialization failure settles the call) |
-| `V1`–`V4` | `test/guest-api-contract.test.ts` (dispatched calls, every refusal class including an address no connector owns, the friction each derives, no event for the execution itself), `test/activity.test.ts` (the shared code → friction table, the identity clamp) |
+| `V1`–`V4` | `test/guest-api-contract.test.ts` (dispatched calls, every refusal class including an address no connector owns, the friction each derives, no event for the execution itself, `paused` and `approved` events), `test/activity.test.ts` (the shared code → friction table, the identity clamp, zero-attempt pauses and approvals) |
+| `V5` | `test/resumable.test.ts` (replay adds only the approval and the live write), `test/guest-api-contract.test.ts` |
+| `W1`, `W2` | `test/guest-api-contract.test.ts` (nothing after a pause gets through, a `__proto__` write refused, on both executors), `test/resumable.test.ts` (the pause shape, reproducible pause points, oversized pending writes, a write gated after the program returned), `test/invocation-pipeline.test.ts` (the gate after validation) |
+| `W3`, `W4` | `test/resumable.test.ts` (header layout, byte bound, expiry, not-found, pool isolation, exact-match refusals that consume nothing, a `__proto__` repetition through the MCP schema, a repeated resume and emitted-content receipt, an expired run's counts) |
+| `W5` | `test/resumable.test.ts` (two resumes racing for a pause, a crashed claimant's `sending` write never sent, a lapsed claim taken over, a claim lost mid-play and the write it sent reported, executor failure returning to the pause, a cut-short or lapsed play that sent writes failing `execution_interrupted`, a claim outliving `expiresAt`, a live or lapsed claim checked before expiry, a failed takeover's answer stored with it, storage that never answers before and after dispatch, a deadline between mark and dispatch) |
+| `W6`, `W7` | `test/guest-api-contract.test.ts` (replay on both executors), `test/resumable.test.ts` (no catalog, connector, or activity traffic for replayed calls; call and tool scope, a retry's scope replacing an unused approval, a hit never taken for the pending call), `test/resumable-restart.test.ts` (across a restart) |
+| `W8`–`W10` | `test/resumable.test.ts` (divergence (a)–(c), each unknown-outcome path never re-sent — beside a concurrent pause, after the program returned, a post-response connector error — a known failure the program handles, the classification table, check-first advice once a write landed, the write budget) |
+| `W11` | `test/code-first-surface.test.ts`, `test/resumable.test.ts` (construction, the default, `/health`, the unavailable answer) |
+| `W12` | `test/resumable.test.ts` (an exempt write runs where the same program otherwise pauses, precedence and a connector default switched off, the write budget, resumable writes off, an unawaited exempt write finished and its unknown outcome reported, journaled and never re-sent, an exempt write's count past expiry, `call_tool` still refusing, search and describe markers, construction refusals), `test/operator-ui-model.test.ts`, `test/browser/operator-ui.spec.ts` (the badge) |
+| `X12` | `test/guest-api-contract.test.ts` (a program that keeps calling after the pause, on both executors) |
 | `M1` | `test/guest-api-contract.test.ts` (invalid emits throw catchably, accept nothing), `test/execute-emit.test.ts` (every rejected shape) |
 | `M2`, `M3` | `test/guest-api-contract.test.ts` (delivery order, truncated return plus delivered blocks), `test/execute-emit.test.ts` (envelope, `structuredContent`, byte-for-byte no-emit path) |
 | `M4` | `test/guest-api-contract.test.ts` (discard is visible), `test/execute-emit.test.ts` (structured and plain paths), `test/quickjs-executor.test.ts` (mid-run shutdown) |
@@ -860,7 +1035,5 @@ passing one table is also the check on the executor duties above, with
 | `X3`, `X6` | `test/quickjs-executor.test.ts` (cancels a running child, never-settling await), `test/execute.test.ts` (a wedged executor stops being awaited) |
 | `X7` | `P3`'s tests; the Workers superset is deliberately unused |
 
-The surface itself is checked by `test/server.test.ts` (the exact seven-tool
-list) and `test/code-first-surface.test.ts` (the fold's construction rules, the
-required executor, the refusals a removed top-level tool now gets, copy, and
-measured size).
+The surface itself is checked by `test/server.test.ts` (the exact eight-tool list) and
+`test/code-first-surface.test.ts` (construction, executor, removed tools, copy, and size).

package/documentation/meta-tools.md

@@ -2,24 +2,28 @@
 
 Connecta keeps one small tool surface in model context and resolves downstream
 tools behind it. `search_tools` finds addresses, the call tools enforce safety
-annotations, `execute_code` runs read-only work as a program, and `get_result`
-pages bounded results.
+annotations, `execute_code` runs work as a program that pauses at each write
+until `resume_execution` approves it, and `get_result` pages bounded results.
 
 This guide is the contract an MCP client sees. The in-program `connecta.*` API
 those tools imply belongs to [code mode](./code-mode.md); inbound identity and
 credential administration belong to [auth](./auth.md).
 
-## The seven tools
+## The eight tools
 
-Every deployment requires an executor, so `tools/list` is exactly seven. No
-configuration adds an eighth or removes one. Resumable writes plan an
-unconditional eighth, the destructive-annotated `resume_execution`
-([ethos](../ethos.md#decisions)); `execute_code` keeps its read-only hint,
-because writes will run only there or for config-exempt tools.
+Every deployment requires an executor, so `tools/list` is exactly eight. No
+configuration adds a ninth or removes one — not even turning resumable writes
+off, which changes what `resume_execution` answers and nothing about whether it
+is listed, so a client's cached tool list never depends on the storage behind
+the deployment. `execute_code` keeps its read-only hint although its programs
+may now reach writes, because no write runs there: a program stops before
+sending one, and the write runs only inside the destructive-annotated
+`resume_execution` that repeats it ([code mode](./code-mode.md#pausing-and-resuming)).
 
 | Tool | Arguments | Returns |
 | --- | --- | --- |
-| `execute_code` | `code`, `diagnostics?` | the program's reduced return value, plus a `diagnostics` block when asked |
+| `execute_code` | `code`, `diagnostics?` | the program's reduced return value, plus a `diagnostics` block when asked; or, when it reached a write, `{ paused: { address, args, token, expiresAt, nextAction, hint } }` |
+| `resume_execution` | `token`, `address`, `args`, `approval?: "call" \| "tool"`, `reason?` | what `execute_code` would have returned had the write been approved: the result, the next pause, or a typed failure |
 | `search_tools` | `query?`, `connector?`, `safety?`, `limit?`, `offset?`, `fullDescriptions?`, `includeSchemas?: "compact" \| "json" \| "typescript"` | `{ connectors: [{ id, tools }], total, offset, limit, hasMore }`, plus `queryAnalysis` on a partial or failed search |
 | `call_tool` | `address`, `args?`, `resultMode?: "mcp" \| "value"`, `timeoutMs?`, `diagnostics?` | the downstream result, bounded as [result representation](#result-representation) describes |
 | `call_destructive_tool` | the same, plus `reason?` | the same |
@@ -48,9 +52,13 @@ credentials, logs, or raw error text.
 
 Connecta's own tools carry the annotations it demands of downstream tools:
 read-only hints on all but `authorize_connector`, which mutates stored auth
-state, and `call_destructive_tool`. Otherwise a host that gates on annotations
-would prompt for every search, and a connecta aggregated behind another connecta
-would be refused by its own policy.
+state, and the two that send writes, `call_destructive_tool` and
+`resume_execution`, both destructive. Otherwise a host that gates on
+annotations would prompt for every search, and a connecta aggregated behind
+another connecta would be refused by its own policy. `resume_execution` is
+where the prompt belongs: its arguments are the exact write, so the human
+approves what will be sent rather than a program that might send anything.
+Its `reason`, like `call_destructive_tool`'s, is dropped before anything runs.
 
 ## Routing between the call surfaces
 
@@ -61,17 +69,33 @@ an earlier result, or several operations. A program keeps discovery, calls, and
 reduction together when the schemas and result shapes suffice, and gives each
 distinct operation its own short `connecta.search` query. That is cheaper than it
 looks: discovery inside the program returns no candidate schema to the model and
-costs no round trip. One exception — an unfamiliar provider result may come back
-as a small sample for inspection before continuing in another call, which avoids
+costs no round trip. One exception — an unfamiliar read result may come back as
+a small sample for inspection before continuing in another call, which avoids
 repeated guesses at text formats and collection roots without restoring a
-mandatory discovery-only round trip.
-
-That covers read-only work, because that is the only work a program can do.
-Anything unannotated, write-capable, or destructive is inadmissible inside the
-sandbox, so multi-step destructive work discovers at the top level and runs each
-step through `call_destructive_tool`, where the host can put the question to a
-human. Telling an agent never to search at the top level for multiple calls
-would close the only route that work has.
+mandatory discovery-only round trip. A one-time write can return the only copy
+of its result. Inspect and reduce the full value before a program returns, or
+use a direct `call_destructive_tool` result and page it with `get_result` after
+the write runs once. A program return has no page handle; sampling or slicing
+a write's output there can discard the answer.
+
+Writes take the same route. A program that reaches a tool not explicitly
+annotated read-only stops before sending it — unless the deployment's config
+exempts that tool, and then it runs unasked — and returns the exact call with a
+token; `resume_execution` repeating it is the approval, and the program
+replays from a journal to send it and carry on — to its answer, or to its next
+write. So "close the stale issues and post a summary" is one program and a few
+approvals, not one program and thirty-one top-level calls, and the program's
+reasoning survives between them. Keep the entire authorized batch in that
+program, including its final post. The default `approval: "call"` covers only
+the pending write. Choosing `approval: "tool"` when the batch repeats an
+address covers later calls to that tool in this run, so thirty closes cost one
+prompt; the summary post still needs its own approval. One known write
+still goes straight to `call_destructive_tool`, and top-level discovery stays
+for catalog inspection. On a deployment without resumable writes (storage
+without `compareAndSet`), a program cannot write at all: the call fails
+`destructive_tool_requires_approval`, multi-step writes discover at the top
+level and run each step through `call_destructive_tool`, and the MCP
+instructions say so.
 
 The three discovery routes use deliberately different envelopes. These are their
 smallest successful one-tool shapes:
@@ -109,7 +133,7 @@ discovery. Both take the same arguments.
 | --- | --- |
 | `query` | two to four action/object terms; empty or whitespace-only browses |
 | `connector` | scopes to one id, loading that catalog alone instead of fanning out across every configured connector. Set it when the integration is obvious, omit it when the right one is genuinely ambiguous |
-| `safety` | `"readOnly"` for what generated code may call, `"approvalRequired"` for the complementary set that must cross `call_destructive_tool`, omitted or `"all"` for the complete configured catalog |
+| `safety` | `"readOnly"` for what runs unasked, `"approvalRequired"` for the complementary set that pauses a program or crosses `call_destructive_tool`, omitted or `"all"` for the complete configured catalog. A config-exempt write stays `"approvalRequired"` and its row says `approval: "exempt"`: a program calls it without pausing, and `call_tool` still refuses it ([code mode](./code-mode.md#pausing-and-resuming) `W12`) |
 | `limit` / `offset` | page the ranked results; omit `limit` initially so the default eight-result page stays small |
 | `includeSchemas` | `"compact"` for the rendered routing view, `"json"` for the exact schema, `"typescript"` for a function signature ([below](#typescript-signatures)) |
 | `fullDescriptions` | unabridged tool purposes, at the obvious cost |
@@ -173,10 +197,11 @@ The walk, byte budgets, and truncation flags are compact's, each half
 separately, and search, describe, and every discovery route share them, so the
 same tool renders the same signature from `search_tools` and `connecta.search`.
 What changes is the dialect: `number` for `integer`, `;` between members,
-quoted non-identifier keys, `T[]` over a parenthesized union, `| null` for
-OpenAPI `nullable` and type lists, index signatures for schema-valued
-`additionalProperties`, `Record<string, unknown>` for an open object with no
-declared properties, and JSDoc for property prose where describe keeps it.
+quoted non-identifier keys, `| null` for OpenAPI `nullable` and type lists,
+index signatures for schema-valued `additionalProperties`,
+`Record<string, unknown>` for an open object with no declared properties, and
+JSDoc for property prose where describe keeps it. Both dialects parenthesize a
+union or intersection before an array suffix, `(A | B)[]`.
 Where compact would print a bare definition name or raw JSON, the signature
 prints `unknown` with a marker and sets the flag: `/* recursive */` for a
 `$ref` cycle, `/* unresolved */` for a missing target, `/* truncated */` past
@@ -515,9 +540,10 @@ attempted tool name; an unknown tool scopes the same query to the connector that
 answered. The suggested route follows the route the caller took:
 `tool: "search_tools"` for a top-level call, `function: "connecta.search"` with
 the same arguments when the miss happened inside `execute_code`, which has no
-way to call a tool. A read path that reaches an unannotated, write-capable, or
+way to call a tool. `call_tool` reaching an unannotated, write-capable, or
 destructive tool returns `nextAction` for `call_destructive_tool` with the
-canonical address. Nothing is executed by these records.
+canonical address; inside a program the same call pauses, and the pause result
+names `resume_execution` instead. Nothing is executed by these records.
 
 `connecta.describe` keeps its failures inline instead, so one miss cannot
 discard the other schemas; each failed entry carries a human `error`, typed