@zackbart/connecta 0.24.4 → 0.25.0

package/dist/version.js

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.24.4";
+export const CONNECTA_VERSION = "0.25.0";

package/documentation/architecture.md

@@ -43,7 +43,7 @@ channel, `ctx.waitUntil`, threaded through `fetch(request, env, ctx)` — activi
 writes use it, as does a stale-window catalog refresh, which owns a fresh scope
 and deadline rather than carrying the inbound one past the request. And a fresh
 `McpServer` per request is what makes the deployment stateless: no sessions, no
-server push, no resumability, scope resolved rather than remembered.
+server push, no stream resumability, scope resolved rather than remembered.
 
 ## Request lifecycle
 
@@ -77,7 +77,8 @@ An admitted non-preflight `/mcp` request then takes five steps in
 
 1. **Admit.** One permit from the deployment-wide pool, taken before auth so an
    unauthenticated flood costs a permit rather than a Clerk lookup, and held
-   until the response *body* completes, not until the handler returns.
+   until the response *body* completes or the caller leaves, not until the
+   handler returns.
 2. **Authorize.** Each `InboundAuth` provider's `authorize` in order, bearer
    before interactive. First `ok` admits; if all fail, the last provider's
    challenge is returned. No providers means open — development only, and it
@@ -104,9 +105,9 @@ or hands out, and a change usually belongs in exactly one of them:
 | Module | Owns |
 | --- | --- |
 | `src/registry.ts` | The connector set, identity-scoped views, personal storage partitions, address resolution, catalog TTL/persistence/completeness, refresh single-flight, connector health, per-connector call limiters, and drift. Construction-time refusals live here. |
-| `src/catalog-service.ts` | Request-local listing, search, and describe. Coalesces reads inside one request and opts agent reads into the runtime's deferred catalog channel when one exists. |
+| `src/catalog-service.ts` | Request-local listing, search, and describe. Caches catalogs inside one request, fans discovery probes out under deadlines, and opts agent reads into the runtime's deferred catalog channel when one exists. |
 | `src/invocation.ts` | One tool call: argument validation, call admission, one-attempt timeout, provider retry hints, result unwrapping, size capping, and the activity record. |
-| `src/catalog.ts` | Ranking, description summarizing, and the compact schema renderer discovery shows. |
+| `src/catalog.ts` | Ranking, description summarizing, and the compact and TypeScript schema renderers discovery shows. |
 | `src/result-shapes.ts` | Bounded runtime-only inference and merging for output shapes learned from successful read-only calls whose providers declared none. |
 
 `src/meta-tools.ts` and `src/execute.ts` are two front doors onto the same two
@@ -144,9 +145,19 @@ accounting error a budget exists to prevent. Both layers are pinned by
 connector state, catalogs, and result paging — a 15-minute TTL with one
 runtime-wide accounting of stash bytes and entries, where a full stash returns the
 successful call's preview and a paging-unavailable notice rather than a result id.
-Adapters: `src/storage/memory.ts`, `src/storage/file.ts` (Node), and the
-Cloudflare KV/D1 pair in `examples/worker/`, copyable reference source and
-deliberately not an importable subpath.
+A second optional method, `compareAndSet(key, expected, next)`, is an atomic
+claim: `null` means absent (expired counts) on the way in and delete on the way
+out. Nothing in core requires it yet. Downstream OAuth uses it where the store
+has it, so resealing legacy plaintext and discarding a refused grant cannot
+overwrite a consent that landed in between, and falls back to a read and a
+write where it does not. A subsystem that needs an exactly-once claim will
+require it explicitly rather than emulate it that way.
+Adapters: `src/storage/memory.ts` and `src/storage/file.ts` (Node) both provide
+it, and the namespaced views core hands connectors forward it only when the
+underlying store has it. `examples/worker/` carries two more: Cloudflare KV,
+eventually consistent and so declaring none, and a D1 store that provides it —
+copyable reference source beside the D1 activity store, deliberately not an
+importable subpath. The shared cases live in `test/storage-contract.ts`.
 
 `src/credentials.ts` is the AES-GCM vault behind the root-exported
 `CredentialVault` contract, selected through the `vault` slot. It binds connector
@@ -187,8 +198,12 @@ material code explicitly permitted; it never edits the connector set, catalog,
 annotations, scopes, or permission rules. Two invariants shape it: a status read
 never starts authorization, since OAuth begins with an explicit authorized POST,
 and each lazy details request owns a bounded downstream scope, so one failing
-provider leaves the other connections usable. Credential handoff URLs exist only
-while the UI is mounted; OAuth callbacks never need it.
+provider leaves the other connections usable. A connector's status message
+never reaches the page: it can quote a downstream error body, and that body can
+quote the secret it rejected, so the details payload carries only a classified
+`problem` — which picks fixed on-screen copy and a fixed fix prompt — and the raw
+text goes to the server log. Credential handoff URLs exist only while the UI is
+mounted; OAuth callbacks never need it.
 
 Its appearance is one token layer. `src/operator-ui/browser.css` resolves every
 color, radius, and font through a custom property and mixes the rest from those
@@ -218,6 +233,165 @@ boundary in the published tarball. The failure mode is not theoretical: one
 convenience import of `node:crypto` in a shared helper stops the whole Worker
 shape from building, in someone else's repository rather than this one.
 
+## Effect inside
+
+The core runs on Effect v4; no API a deployment touches does. `createConnecta`,
+`remoteMcp()`, `api()`, the `Connector` contract, and every shipped `.d.ts`
+are Promise-shaped and name no Effect type, so a connector author never meets a
+second async paradigm. The reason for the rewrite is the first section of this
+guide: the bugs here are lifetime bugs, and Effect makes a lifetime a value —
+a Scope that closes on every exit, an interrupt that reaches whatever a fiber
+is waiting on, a Deferred that one party completes and any number join. The
+conversion found and closed a dozen of them, each with a test that fails on the
+code before it: permits and leases held after their caller left, waits with no
+bound, and races between requests.
+
+### Shell and core
+
+Each converted module is a shell and a core. The shell keeps its exported class
+or function exactly — same members, same error classes, same `.d.ts`, private
+member names included, because TypeScript ships those too. The core is an
+Effect program behind it. In a published class it lives in a `static` block,
+the one place that can read private state without adding a member to the
+declarations; elsewhere it lives in an unexported function or in
+`src/runtime/`, which no `exports` target reaches. Errors keep their classes
+(`ConnectorCallError`, `ExecutorAdmissionError`, `CallAdmissionError`) because
+callers and tests check `instanceof`, `name`, and `message`.
+
+Effect callers skip the Promise and take the program: `admit` and
+`acquireScoped` for request admission (`src/runtime/admission.ts`), `admitCall`
+and `acquireCallScoped` for call admission, `closeScope` and `closeScopeOnExit`
+for a connector scope, `withDeadlineEffect` where Promise code has
+`withDeadline`. The build prunes every declaration no `exports` target reaches,
+and `npm run check:declarations` fails if what remains names an Effect type.
+
+### One runner
+
+`src/runtime/run.ts` is the only place a fiber starts, and
+`test/purity.test.ts` fails if any other file calls `Effect.run*`, `runFork`,
+`forkDaemon`, or `ManagedRuntime.make`. It exports two ways out:
+
+- **`runEdge(effect, { signal, runtime? })`** runs an effect at a Promise
+  boundary. It rethrows the original failure or defect, never a wrapper. It
+  turns an interrupt into the caller's `signal.reason` rather than Effect's
+  "All fibers interrupted without error". And it runs every fiber on a
+  scheduler that yields through microtasks: Effect's default yields through
+  `setImmediate`, which vitest's fake timers freeze and Workers never had. The
+  price is that a fiber never yields to I/O, so CPU-heavy work stays out of
+  Effect loops.
+- **`detach(effect, ctx)`** is the only fire-and-forget, and it hands the work
+  to `ctx.waitUntil` when there is one.
+
+Beside them sit `withDeadlineEffect`, which aborts the operation's own signal
+with the labelled timeout error *before* interrupting it, so work that honors
+the signal sees the same reason the caller does, and `fromSignal`, which turns
+an `AbortSignal` into a failure to race against. Nothing runs Effect at module
+scope, where a Worker may not start work, and nothing logs through
+`Effect.log`: logging goes through the configured `Logger`, which is what
+honors `logger: "silent"`.
+
+Each Connecta also gets a runtime of its own (`src/runtime/services.ts`):
+`Storage`, `Vault`, `ActivityRecorder` (one that records nothing when the module
+is omitted), `Logger`, and `ResolvedConfig`. Creating it builds nothing, since
+a Worker constructs its Connecta at global scope; the first run that needs the
+services builds them, and `close()` disposes the runtime last. Two things
+deliberately do not run on it. The request pipeline runs on no runtime, so
+`/health` and a closed deployment's 503 keep answering after `close()`. And a
+registry provides its own storage and logger to its programs
+(`runOnPartition` in `src/runtime/storage.ts`), because a personal registry's
+storage is the root's namespaced to its principal and the runtime's `Storage`
+would be another partition's.
+
+### What runs on Effect
+
+| Area | Shape |
+| --- | --- |
+| Requests (`src/server.ts`, `src/routes/mcp.ts`, `src/routes/oauth.ts`) | One fiber per `fetch`, tied to `request.signal`. An `/mcp` request's admission permit and every `McpServer` it builds live in a Scope the response carries out, closed when the body ends, fails, or is cancelled, when the signal aborts, or at once if the handler fails first. The OAuth callback is uninterruptible: a single-use code's exchange and catalog invalidation are one commitment. |
+| Admission (`executor-admission.ts`, `call-admission.ts`) | Queued waiters are Deferreds settled by whoever removes them from the queue; a wait is one flat race of grant, Clock timeout, and signal. The uncontended path stays synchronous. Two controllers, as [#453](https://github.com/zackbart/connecta/issues/453) requires. |
+| One tool call (`invocation.ts`) | One fiber: resolution, the read-only and schema refusals, admission, and the downstream attempt sit under a single `withDeadlineEffect`, whose expiry interrupts the call wherever it is. The permit is an `acquireRelease`; the connector call is `Effect.tryPromise` over the unchanged `Connector`. |
+| `execute_code` (`execute.ts`) | One fiber whose Scope owns the run's signal and executor lease, so a result, a throw, the watchdog, and cancellation all release the lease and abort the signal the same way. The executor's `acquire()` and `execute()` stay Promises raced against the signal and `execute.watchdogMs`. Each guest host call is a fiber of its own. |
+| Discovery (`catalog-service.ts`) | A request-scoped cache: one Deferred per connector, completed by the first asker's read from that read's own settlement, so a probe deadline ends one asker's wait and never the read the others share. Fan-out is `Effect.forEach` under the discovery concurrency. |
+| Registry (`registry.ts`) | Catalog persistence and the result stash are programs over `Storage`. A refresh flight is a Deferred its publishing request completes; persisted-catalog writes take per-connector turns, each a Deferred its own request completes. |
+| Remote MCP (`connectors/remote-mcp.ts`) | Each request scope's state holds a Scope, each connection is a lease forked from it, and a connect in flight is a Deferred carrying the client it connected. Closing a session and the transport are each bounded to a second. |
+| Downstream OAuth (`auth/downstream-oauth.ts`) | A refresh flight is a Deferred; the owner's redemption is a fiber its abort interrupts, and committing an answer that already exists is uninterruptible. |
+| Operator and activity data (`routes/operator.ts`) | Each JSON route is one program run by `serveOperator` behind the Promise `handle()`. Reads run under the request's signal; writes do not, so a vault write or OAuth disconnect that started reaches its cache invalidation. |
+| QuickJS pool (`executors/quickjs.ts`, Node only) | Each child is a scoped resource whose release sends SIGTERM, then SIGKILL after a second; crash respawn backoff is a `Schedule`. |
+
+### What stays plain
+
+- **Everything a deployment writes against.** The `Connector` contract,
+  `api()`, the providers, custom connectors, storage adapters, and the vault
+  are Promises. A connector is called with `Effect.tryPromise`, never asked to
+  return an Effect.
+- **Inbound authorization.** `authorize` in `src/routes/shared.ts` ships in
+  the declarations and in the `./activity` bundle; converting it cost 32 KB
+  gzip there for nothing a caller could see.
+- **Pure synchronous code.** Ranking, schema rendering, classification,
+  `validateToolInput`, the host-call budget, the emit collector, failure
+  framing, and result shaping. The microtask scheduler never yields to I/O, so
+  wrapping them would buy nothing and could starve a request.
+- **The MCP edges.** `@modelcontextprotocol/server` upward and the SDK client
+  downstream; Effect's own `McpServer` is not used.
+- **The Node and browser leaves.** `node.ts`, `fileStorage`, the QuickJS
+  child, runtime, and protocol, and the operator UI's browser app.
+
+### Across requests
+
+Work shared across requests meets only through a Deferred that the owning
+request completes, never through a fiber that outlives its request. Two
+workerd rules follow, and both have bitten.
+
+**Waiting on a shared Deferred is its own edge.** Deferred resumes a waiting
+fiber synchronously, inside the call that completed it, which on Workers means
+inside the completing request's I/O context. A waiter that goes on to touch its
+own body, transport, or storage there fails with "Cannot perform I/O on behalf
+of a different request", or hangs until its deadline. So the wait runs through
+`runEdge`, and the waiter does its own I/O after awaiting that promise, which
+workerd resumes in the waiter's request as it does any promise resolved from
+another. The same holds one level out for every queue: a queued call, a queued
+`execute_code`, and a queued `/mcp` request are each handed their permit from
+inside the request that released one, so each awaits the controller's
+Promise-shaped `acquire` rather than yielding its Effect program, and does its
+own work only once that promise resolves. Effect's `Semaphore` is not used
+across requests for the same reason, and because a same-tick newcomer can take
+a released permit ahead of a waiter that queued earlier.
+
+**Never read another request's signal.** On workerd, reading `aborted` or
+`reason`, or calling `abort()`, on a signal that belongs to another request
+throws; adding and removing listeners does not. Code that runs from another
+request's completion — a queue handing out a permit, `close()` — must not look
+at a waiter's signal. A waiter whose signal aborts leaves the queue from its
+own listener, in its own request.
+
+One corollary is easy to break by tidying. Workerd cancels a request as hung
+when its only pending work is waiting on another request and it has no timer or
+I/O of its own. Connecta's deadline timers are what keep a waiting request
+alive and bounded, so no wait may lose its timer.
+
+### Why not Schema or HttpApi
+
+Both were measured and both lost. `effect` is imported through its barrel,
+which defeats tree-shaking: the first conversion step measured about +20 ms
+of Worker cold start for it, and that cost was accepted over deep imports at
+every call site. The catch is that a module the barrel reaches is paid for in
+full, however little of it is used. Effect Schema for config validation and the
+meta-tool inputs came to about +62 KB gzip and +13 ms of cold start in the
+root, for a validator no clearer than the hand-written `CONFIG_SCHEMA`; the
+meta-tool inputs stay zod, which the MCP SDK bundles regardless. `HttpApi` for
+the operator and activity routes cost about +100 KB gzip on `./ui` and +130 KB
+on `./activity`, and matching the wire format meant opting out of most of what
+it does: unowned paths fall through rather than 404, a wrong method is a JSON
+405, and the content-type and size checks run before a body is read. The root
+entry may import only `effect` itself (`test/purity.test.ts`); nothing in
+`src/` uses `effect/unstable/*`, which would have to stay behind a subpath.
+
+The core's cost is recorded rather than guessed. Against 0.24.4 the root entry
+grew from 235,346 to 279,526 bytes gzip, the Worker example from 263,949 to
+314,336, and each provider by about 36 KB, since each reaches Effect through
+`remoteMcp()`; `npm run check:bundle` caps every entry against
+`scripts/bundle-budget.json`. An install carries about 53 MB of `effect`, with
+no dependencies of its own.
+
 ## Where else to look
 
 Beyond the modules already named:
@@ -250,7 +424,7 @@ compiling and configuring the real thing.
   `OPTIONS` opts it into CORS preflight; reordering admission after auth makes
   the cheapest possible attack the most expensive request.
 - **`close()` is idempotent and ordered.** Both admission pools, then the
-  connector limiters, then the executor; Node's `listen()` calls it on
+  connector limiters, then the executor, then the Connecta's runtime; Node's `listen()` calls it on
   SIGTERM/SIGINT.
 - **Structural mistakes throw at construction.** A duplicate connector id, an
   invalid admission rule, the removed `accessTokens` option, a missing executor:

package/documentation/auth.md

@@ -149,6 +149,86 @@ partitions. Literal `auth: { type: "headers" }` cannot be personal, because its
 secret lives in deployment code; `remoteMcp()` refuses that combination at
 construction.
 
+## Downstream OAuth state at rest
+
+With a vault configured, a `remoteMcp()` OAuth connector's tokens, dynamically
+registered client (secret included), and PKCE verifier are sealed with the
+vault's AES-GCM key before they reach storage. The additional authenticated data
+names the connector, the owner partition, and the physical key, which carries
+the authorization epoch, so ciphertext copied to another connector, principal,
+or epoch does not open. Anything that fails to open — a tampered value, a
+rotated key — reads as absent: the connector reports `auth_required` and logs a
+warning. The flow bookkeeping stays plaintext: `state`, the pending URL,
+discovery metadata, and the generation. The callback route reads `state`
+directly, and none of it authenticates anything by itself.
+
+Plaintext left by an older release is read, then sealed where it lies through
+the same generation fence as any write, so an upgrade keeps the grant. Sealing
+is one-way. An older release reads sealed state as unusable, so rolling back
+means authorizing again. A vault without the optional `seal`/`open` members
+keeps these values plaintext and draws a startup warning. Without any vault,
+nothing changes: the state is plaintext, as it always was.
+
+## Refresh failures
+
+A failed token refresh means one of two things, and connecta decides which
+from the token endpoint's answer, not the SDK's reading of it. A **dead grant**
+is any 4xx except 408, 425, and 429, or a 2xx carrying an OAuth `error` (GitHub
+answers `200 {"error":"bad_refresh_token"}`). It ends as `auth_required`, and
+the refused tokens are deleted on the spot, so no later request or isolate
+sends them again and the next `authorize_connector` goes straight to consent.
+An **outage** is a 5xx, 408, 425, 429, a network failure, or a 2xx that is not
+a token response. It ends as retryable `unavailable`, or `rate_limited` for a
+429, with `retryAfterMs` when the server sent `Retry-After`. The grant is kept,
+and a passive call writes no consent URL. Every request joined on the same
+in-flight refresh gets the same verdict, even when the request that sent the
+refresh is cancelled after the answer arrives: the refused tokens are deleted
+before anyone waiting is released, so a request arriving meanwhile joins the
+refusal instead of sending the dead token again.
+
+The SDK needs this help. On a refresh failure it cannot parse, or one marked
+`server_error`, it falls through to starting authorization, which reports a
+healthy grant as needing consent. It rethrows every other OAuth error
+untouched, which reports a dead grant as a generic outage and keeps re-sending
+it. So the refresh coordinator hands the SDK an answer it classifies correctly,
+and the provider hooks it calls next finish the job. The pinned SDK behavior is
+spelled out beside `refreshResponseOutcome`. An explicit authorization during
+an outage still falls through to consent, since that is what it asked for.
+
+## URLs a downstream advertises
+
+A `remoteMcp()` OAuth connector learns most of the URLs it fetches from the
+downstream itself: the `resource_metadata` in its 401 challenge, the
+`authorization_servers` in that metadata, and the token and registration
+endpoints the authorization server publishes. Connecta fetches every one of
+them server-side, so a compromised downstream could otherwise aim a Node or
+Docker host at its own network — cloud metadata at `169.254.169.254`, an admin
+panel on the LAN. Config is the security model, so the rule splits on it:
+
+- A URL on the connector's configured origin is trusted. The operator wrote it
+  down.
+- Any other URL must be `https` and must not name a private host: `localhost`
+  and `*.localhost`, `127/8`, `10/8`, `172.16/12`, `192.168/16`, `169.254/16`,
+  `100.64/10`, `0/8`, `::`, `::1`, `fc00::/7`, `fe80::/10`, or an IPv4-mapped
+  IPv6 form of any of those.
+- A connector configured on a loopback host may also learn loopback URLs, over
+  `http` too, so a local MCP server with a local authorization server keeps
+  working. LAN and link-local addresses stay refused.
+
+A refused URL is never requested. Discovery, registration, and code exchange
+fail with a non-retryable `connector_call_failed` that names the host and
+nothing else from the URL. A refused refresh never reaches the token endpoint,
+so there is no verdict to act on: the grant is kept, and the SDK falls through
+to consent as it does for any refresh it could not complete. Redirects cannot
+route around the rule, because the redirect policy only follows same-origin
+hops.
+
+The check is syntactic. It reads the host after the WHATWG URL parser has
+folded `2130706433` and `0x7f.1` into `127.0.0.1`, and it never resolves a
+name, because the Workers-safe core has no DNS. A public name that resolves to
+a private address, or rebinds to one after the check, is out of scope; a host
+that must stop that runs connecta behind an egress policy that does.
+
 ## Management permissions
 
 Visibility alone grants no authentication-management permission. Two independent

package/documentation/code-mode.md

@@ -90,7 +90,9 @@ Connecta passes exactly one provider, named `connecta`. An executor must:
 5. **Capture `console.log`, `console.warn`, and `console.error`** into `logs` in
    call order (`R5`), bounding what it retains.
 6. **Bound the guest**: wall clock, memory, stack, and CPU (`L3`, `L5`), staying
-   inside the tested `P2`/`X5` boundary.
+   inside the tested `P2`/`X5` boundary. Settle `execute()` on your own
+   deadline: connecta stops waiting at `execute.watchdogMs` and reports the
+   sandbox unresponsive (`L3`).
 7. **Grant no ambient authority of its own.** Never back this with `eval` or
    `node:vm`: the sandbox is a containment layer on top of connecta's boundary,
    not a replacement for it, and every capability arrives through `fns`.
@@ -106,10 +108,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. 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.
+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.
 
 **P2.** The only capabilities in the contract are `connecta.search`,
 `connecta.describe`, `connecta.call`, `connecta.emit`, and `console.log` /
@@ -129,7 +136,9 @@ 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.
+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.
 
 **P5.** Plain JavaScript only; TypeScript syntax is a syntax error. Portable
 code does not import: QuickJS blocks imports, Dynamic Workers expose the `X5`
@@ -164,7 +173,7 @@ const page = await connecta.search({
   limit: 8,                         // 1–100, default 8
   offset: 0,
   fullDescriptions: false,
-  includeSchemas: "compact",        // or "json"
+  includeSchemas: "compact",        // or "json" / "typescript"
   includeSchemaKeys: true,          // default true in code mode
 });
 ```
@@ -211,6 +220,18 @@ truncation flag; `$dynamicRef` resolves a same-named definition like `$ref`, and
 an unresolved one becomes `unknown` with the flag. For omitted exact constraints
 use `format: "json"` or JSON search.
 
+`includeSchemas: "typescript"` spends those same bounds on a different
+rendering: one `signature` string in place of `inputSchema` and
+`outputSchema`, reading `(args: { runId: number }) => Promise<Run>` for the
+value `connecta.call` returns. It is documentation for the program's author —
+the program itself is still JavaScript, and a type annotation copied into it
+is a syntax error (`P5`). Truncation keeps compact's flags and
+turns what compact would print as a name or raw JSON into a marked `unknown`;
+an observed output opens with `/* observed, not declared */`. The dialect and
+its degradation rules are specified once, under
+[TypeScript signatures](./meta-tools.md#typescript-signatures), and the
+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
@@ -249,7 +270,7 @@ hint and the stable `code`, `retryable`, and `details` fields (`E1`).
 const one = await connecta.describe({ address: "ci.get_run" });
 const many = await connecta.describe({
   addresses: ["ci.get_run", "ci.get_job_logs"],  // ≤ 100
-  format: "compact",                             // or "json"
+  format: "compact",                             // or "json" / "typescript"
   fullDescriptions: false,
 });
 ```
@@ -265,8 +286,11 @@ canonical addresses. More than 100 addresses is `invalid_args`, and the same
 256,000-byte ceiling applies. Compact describe keeps property prose within a
 separate 8,192-byte UTF-8 shape cap and shares search's 2,000-visit budget; a
 capped shape sets `inputSchemaTruncated` or `outputSchemaTruncated`, and
-`format: "json"` gives the exact schema. A success whose output shape came from
-`S9` carries `outputSchemaSource: "observed"`.
+`format: "json"` gives the exact schema. `format: "typescript"` returns a
+`signature` instead of both schema fields, under the same 8,192-byte cap per
+half with property prose as JSDoc. A success whose output shape came from
+`S9` carries `outputSchemaSource: "observed"`, and a TypeScript signature also
+says so inside its `Promise<…>`.
 
 ### connecta.call
 
@@ -385,12 +409,15 @@ and let the failure reach the model.
 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.
+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.
 
 **E5.** Failures of the *execution*, not of a call, never appear inside the
 guest: admission rejection (`executor_overloaded`, retryable, with
 `retryAfterMs`), cancellation (`executor_cancelled`), shutdown
-(`executor_closed`), deadline expiry, and sandbox crashes end the run and reach
+(`executor_closed`), deadline expiry, an executor that never settles (`L3`),
+and sandbox crashes end the run and reach
 the model as an error result. One seam: a host call still in flight when the run
 is cancelled fails with `cancelled`, catchable on the way out but never worth
 acting on (`Y3`). When shutdown tears down a program that had already started,
@@ -582,12 +609,25 @@ block runs — a cancelled QuickJS child is terminated outright. Write programs
 that need no cleanup.
 
 **L2.** What cancellation guarantees: in-flight host calls abort, no further
-host call is admitted, the admission lease is released, and nothing
-request-bound survives the request.
+host call is admitted — `search` and `describe` included, which fail
+`cancelled` rather than go on loading catalogs — the response returns
+`executor_cancelled` without waiting for the executor to settle, or for an
+`acquire()` that ignores the signal to grant, the admission lease is released
+(a lease granted after the run gave up is released on arrival), and nothing
+request-bound survives the request. Whether the program itself stops is the
+executor's (`X3`).
 
 **L3.** Every execution runs under a wall-clock deadline that includes time
 spent waiting on host calls. Expiry ends the run with an execution error and no
-partial result; the deadline's length is executor configuration (`X1`).
+partial result; the deadline's length is executor configuration (`X1`). Above
+it sits a ceiling connecta enforces outside the sandbox, `execute.watchdogMs`
+(120 s by default, above both executors' own deadlines), because an executor's
+deadline may live inside the sandbox it is meant to stop: a wedged Dynamic
+Worker never fires its in-isolate timer. A run whose executor has not settled
+by the ceiling ends as a non-retryable `executor_failed` whose message calls
+the sandbox unresponsive, with no partial result, and its admission lease is
+released, so wedged runs cannot fill the code pool. Raising an executor's
+deadline past the ceiling means raising the ceiling too.
 
 **L4.** Per-execution bounds that are contract, identical in both executors
 because connecta enforces them above the sandbox:
@@ -688,10 +728,15 @@ and guest-CPU limits (`L5`); the Dynamic Worker has no such knobs, so workerd's
 isolate limits apply untuned. A specific heap ceiling is a Node-only option.
 
 **X3. Mid-flight cancellation.** The QuickJS pool receives the request's
-`AbortSignal` and kills the child. The Dynamic Worker executor's `execute()`
-takes no signal, so a cancelled request's program runs on until its host calls
-fail or the deadline expires. `L2` holds either way — the calls abort, the
-response does not wait — but "the run ends" is best-effort on Workers.
+`AbortSignal` and kills the child — SIGTERM, then SIGKILL if it has not exited
+within a second — and releasing a lease whose child is still running recycles
+that child, so a run the watchdog abandons (`L3`) ends too.
+The Dynamic Worker executor's `execute()` takes no signal, so a cancelled or
+abandoned program runs on in its isolate until its host calls fail or its own
+deadline expires. `L2` and `L3` hold either way — the calls abort, connecta
+stops awaiting the executor and frees the admission slot — but "the run ends"
+is best-effort on Workers, and for that tail the code pool bounds what
+connecta is waiting on, not what the platform is still running.
 
 **X4. Log rendering and capture.** QuickJS JSON-stringifies non-string arguments
 and captures `log`, `info`, `warn`, `error`, and `debug`; the Dynamic Worker
@@ -776,12 +821,12 @@ 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), `test/quickjs-executor.test.ts` (`normalizeCode`) |
+| `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) |
 | `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) |
 | `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) |
+| `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) |
 | `S4` | both guest-contract executors (ordered mixed describe results with unknown-address, unknown-tool suggestion, and catalog-failure details), `test/meta-tools-search.test.ts` (top-level routing, no-suggestion, catalog-failure, and hostile-input bounds) |
 | `S5`, `S6` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`unwrapMcpResult`, fail-closed annotations, activity parity) |
@@ -799,8 +844,8 @@ passing one table is also the check on the executor duties above, with
 | `R6`–`R8` | `test/guest-api-contract.test.ts` (normal result keys), `test/execute.test.ts` (opt-in operation aggregates, failure paths, payload exclusion) |
 | `Y1`, `Y2`, `Y3` | `test/guest-api-contract.test.ts` (one attempt per call, retryable flags by code) |
 | `Y4` | `test/meta-tools-call.test.ts`, `test/call-admission.test.ts` (one attempt, retry hints, caller reissue) |
-| `L1`, `L2` | `test/guest-api-contract.test.ts` (in-flight call fails `cancelled`), `test/execute.test.ts` (cancels outstanding host calls) |
-| `L3`, `X1` | `test/guest-api-contract.test.ts` (short-deadline executors) |
+| `L1`, `L2` | `test/guest-api-contract.test.ts` (in-flight call fails `cancelled`), `test/execute.test.ts` (cancels outstanding host calls, discovery included, and refuses discovery after the run; a cancelled wedged executor, or one whose `acquire()` ignores the signal, returns promptly and releases its lease) |
+| `L3`, `X1` | `test/guest-api-contract.test.ts` (short-deadline executors), `test/execute.test.ts` (the watchdog ends a never-settling executor, frees the default pool, spares a slow run, and falls back from an unusable value) |
 | `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) |
@@ -812,7 +857,7 @@ passing one table is also the check on the executor duties above, with
 | `M8` | two arms passing one case table, `test/codemode-compat.test.ts` |
 | `M10` | `test/execute-emit.test.ts` (aggregate present, numbers only, absent when nothing emitted) |
 | `X4` | `test/guest-api-contract.test.ts` (string logs only), `test/quickjs-executor.test.ts` (logs before cancellation), `test/quickjs-child-stderr.test.ts` (crash, shutdown, deadline, IPC failure, bounded parent retention), `test/quickjs-log-limits.test.ts` (unchanged successful logs) |
-| `X3`, `X6` | `test/quickjs-executor.test.ts` (cancels a running child, never-settling await) |
+| `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