@zackbart/connecta 0.24.4 → 0.25.0

package/documentation/meta-tools.md

@@ -12,24 +12,29 @@ credential administration belong to [auth](./auth.md).
 ## The seven tools
 
 Every deployment requires an executor, so `tools/list` is exactly seven. No
-configuration adds an eighth or removes one.
+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.
 
 | Tool | Arguments | Returns |
 | --- | --- | --- |
 | `execute_code` | `code`, `diagnostics?` | the program's reduced return value, plus a `diagnostics` block when asked |
-| `search_tools` | `query?`, `connector?`, `safety?`, `limit?`, `offset?`, `fullDescriptions?`, `includeSchemas?: "compact" \| "json"` | `{ connectors: [{ id, tools }], total, offset, limit, hasMore }`, plus `queryAnalysis` on a partial or failed search |
+| `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 |
 | `authorize_connector` | `connector`, `force?` | the class-specific handoff in [authorization recovery](#authorization-recovery) |
-| `get_result` | `id`, `offset?`, `maxBytes?` | `{ offset, nextOffset?, totalBytes, text }` |
+| `get_result` | `id`, `offset?`, `maxBytes?` | a one-line JSON header `{ resultId, offset, bytes, totalBytes, hasMore, nextAction? }`, a newline, then the page as raw text ([paging](#paging-with-get_result)) |
 | `skills` | `name?` | the listing when `name` is absent, that skill's markdown when it is present |
 
 `limit` defaults to 8 and is capped at 100, as is one `connecta.describe` batch.
 `get_result.offset` is a whole number of bytes ≥ 0 defaulting to 0 and
-`maxBytes` a whole number ≥ 1 defaulting to the deployment result cap — itself
-50,000 bytes unless `calls.maxResultBytes` or a per-connector override says
-otherwise. Both are validated rather than clamped: a bad value is an input
-error. `reason` is at most 500 characters of context for the host's human
+`maxBytes` a whole number ≥ 1 that defaults to, and is clamped to, the inline
+cap of the call that stashed the result — 24,000 bytes unless
+`calls.maxResultBytes` or a per-connector override says otherwise
+([why 24,000](#truncated-direct-call-results)). A value outside those domains is
+an input error; a valid `maxBytes` above the cap is an upper bound, not an
+error ([why](#paging-with-get_result)). `reason` is at most 500 characters of context for the host's human
 approval view; Connecta neither treats it as authority nor sends it downstream,
 and an empty or whitespace-only one reads as no reason rather than as grounds to
 refuse a consequential call.
@@ -106,7 +111,7 @@ discovery. Both take the same arguments.
 | `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 |
 | `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 |
+| `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 |
 
 Neither `connector` nor `safety` grants authority or changes invocation
@@ -141,6 +146,43 @@ act on is the flag: any cap sets `inputSchemaTruncated` or
 `outputSchemaTruncated`, and that means repeat with `includeSchemas: "json"`, or
 describe, when the exact constraints matter.
 
+### TypeScript signatures
+
+`includeSchemas: "typescript"` replaces both schema fields with one
+`signature`: the function `connecta.call(address, args)` resolves to, written
+as a TypeScript type because agents write code against types more reliably
+than against JSON Schema ([executor](https://github.com/UsefulSoftwareCo/executor)'s
+discovery made the same bet).
+
+```ts
+(args: { team: string; limit?: number /* <= 250 */ }) => Promise<unknown>
+(args?: {}) => Promise<{ accounts: { stripe_context: string; livemode: boolean; name?: string }[] }>
+(args: { team: string }) => Promise</* observed, not declared */ { cursor?: string; issues?: { id?: string }[] }>
+```
+
+It is something to read, not something that runs: programs stay JavaScript,
+and the refusal of erasable TypeScript in `execute_code` stands
+([ethos](../ethos.md#decisions)). The output half is the provider's declared
+schema, else an `S9` observation that opens with the
+`/* observed, not declared */` marker and keeps the `outputSchemaSource`
+field, else `unknown` — runtime evidence never reads as a contract, even when
+the signature is lifted out of its entry. A tool without parameters takes
+`args?: {}`.
+
+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.
+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
+depth four or an exhausted budget. `inputKeys` and friends come from the
+declared schema exactly as they do for compact.
+
 ## Connector guides and skills
 
 A connector may attach a deployment-owned guide as markdown, keeping the
@@ -202,7 +244,8 @@ text block carrying its compact JSON and then applies the same content size
 guard, which preserves structured-only results including `null`, arrays, and
 scalars. An existing text mirror stays unchanged; Connecta adds no second copy.
 Newly stashed JSON and downstream content envelopes use compact serialization,
-so `get_result` offsets and totals describe that exact compact text.
+and a lone text block stashes as its own text, so `get_result` offsets and
+totals describe exactly that text.
 
 | Bound | Value |
 | --- | --- |
@@ -244,30 +287,124 @@ original UTF-8 text, not the envelope. A supplied offset inside a character
 moves back to its start; page ends also align to character boundaries, and a
 page smaller than one character widens just enough to make progress.
 
-A successfully stashed `call_tool` truncation notice carries both the historical
-`resultId` and an exact
-`nextAction: { tool: "get_result", arguments: { id, offset: 0 } }`, so the handle
-is actionable without copying an identifier out of prose. Program results and
-oversized discovery responses carry no such route: paging a program's return
-value is a refused shape, because a program can shrink anything before it
-returns.
-
-A refused or failed stash write cannot undo a downstream success. Both call tools
-then return a truncated preview where one is usable, with a paging-unavailable
-notice and no `resultId` or paging action; an envelope carrying non-text blocks
-gets the notice alone, because the head of a half-written base64 image helps
-nobody. Activity records success, and the operator logger receives a fixed
-warning naming the connector and tool without storage error prose. For read-only
-work, reduce the result inside `execute_code` — repeating an approved write is
-not a way to recover its output. Other result-processing failures use a fixed
-`result_processing_failed` message and are never retryable.
-
 A per-call `timeoutMs` covers catalog resolution, admission, and connector
 execution under one deadline. The admission queue's own timeout may expire
 sooner but cannot extend the call deadline. Result processing happens after that
 deadline ends, because a completed downstream call must not turn into a
 retryable timeout while Connecta prepares its response.
 
+### Truncated direct-call results
+
+A `call_tool` or `call_destructive_tool` result over its cap — the connector's
+`maxResultBytes`, else `calls.maxResultBytes`, else 24,000 bytes — comes back
+as one text block. Its first line is the truncation notice, one line of compact
+JSON; everything after the first newline is the preview:
+
+```text
+{"truncated":true,"resultId":"…","totalBytes":161420,"hint":"This write already ran: do not call it again to see its result. Bytes 0-24000 of 161420 follow; page the rest with get_result using nextAction.","nextAction":{"tool":"get_result","arguments":{"id":"…","offset":24000}}}
+{"ts":"2026-09-16T21:31:11.759Z","actor":"sam.ortiz@example.com",…
+```
+
+The notice leads because clients cut oversized results from the end, and a
+notice at the tail is the part they drop. Claude Code (measured on 2.1.280, from
+its bundled source and with `claude -p` against a probe server) passes an MCP
+result through untouched while its text blocks total at most 50,000 characters.
+One character more and it replaces the whole result with a pointer to a spill
+file plus the first 2,000 characters of `JSON.stringify(content, null, 2)`,
+whatever `MAX_MCP_OUTPUT_TOKENS` says. Once the characters exceed twice
+`MAX_MCP_OUTPUT_TOKENS` (25,000 by default, so again 50,000) it also counts real
+tokens against that limit, and a result over it arrives as an error carrying no
+content at all — no preview, no notice. The old layout — a
+50,000-byte preview, then the notice — crossed the first line every time, so an
+agent without file tools never saw the handle; in the eval's write task two of
+three models re-ran a billable export three times trying to read its result.
+
+The default cap sits under both lines with room to spare. Preview plus notice
+stays under 25,000 bytes, which is under 50,000 characters for any text, because
+a character is at least one UTF-8 byte, and under 25,000 tokens for any text,
+because a token covers at least one byte. A `get_result` page obeys the same
+cap, and 24,000 matches the program result boundary in
+[code mode](./code-mode.md). A deployment whose
+clients take more can raise the cap, and one whose clients take less can lower
+it, per connector if need be; a result between 24,000 and 50,000 bytes that
+used to arrive whole now pages. A client that spills rather than rejects keeps
+the notice whatever its threshold, since the notice is the first few hundred
+characters. One that rejects outright — Claude Code with
+`MAX_MCP_OUTPUT_TOKENS` set below 12,500 — needs a cap under twice its limit.
+
+The preview is the head of what `get_result` pages, cut on a character
+boundary, so `nextAction.arguments.offset` continues exactly where it stops. A
+lone text block — including the one synthesized from `structuredContent` — is
+measured, stashed, previewed, and paged as its text: wrapping it in a content
+envelope added nothing but a second layer of JSON escaping, so a JSON payload
+used to preview as `[{"type":"text","text":"{\"ts\":…` and every page carried
+the escaping twice. Several text blocks keep the serialized envelope as the one
+string measured, stashed, and paged, because their boundaries live there; they
+preview as their text joined by newlines, and their next action starts at
+offset 0. A content array carrying non-text blocks returns the notice alone,
+because the head of a half-written base64 image helps nobody. In value mode the
+notice is `data` itself, with no preview and a next action at offset 0.
+
+The hint says what to do next. For a call not explicitly annotated read-only it
+opens with “This write already ran: do not call it again to see its result.”
+The approved write happened; repeating it to look again is how one export
+becomes three. For an explicitly read-only call, repeating is the better route,
+so the hint offers it first: to find something specific, repeat the read inside
+`execute_code` with `connecta.call` and filter or search the result there; to
+read it in full, page with `get_result`. Inside a program the inline cap does
+not apply to a host call's result, only to what the program returns (`L6` in
+[code mode](./code-mode.md) bounds a host call far higher), so the reduction
+sees the whole result at once. When the hint named paging alone, the eval's
+weakest model read a 185 KB CI log in 24,000-byte pages, skipped the range
+holding the real failure, and named the flaky test near the top; before the
+notice was visible, it had reduced the log in a program and found the failure.
+`nextAction` stays the page handle for either kind of call, because paging is
+the one next step connecta can spell out exactly, while a reduction is a
+program the agent has to write. `resultId` stays beside the exact `nextAction`,
+so the handle is actionable without copying an identifier out of prose.
+Program results and oversized discovery responses carry no such route: paging a
+program's return value is a refused shape, because a program can shrink
+anything before it returns.
+
+### Paging with get_result
+
+A page is the truncated result's shape again: one text block whose first line
+is a JSON header and whose remainder is the page, raw.
+
+```text
+{"resultId":"…","offset":24000,"bytes":24000,"totalBytes":161420,"hasMore":true,"nextAction":{"tool":"get_result","arguments":{"id":"…","offset":48000}}}
+{"ts":"2026-09-17T23:42:55.357Z","actor":"noor.haddad@example.com",…
+```
+
+`bytes` is what this page returned; `hasMore` is false on the last page, which
+carries no `nextAction`. The page is the stashed text as-is — a lone text
+block's own text, a value's compact JSON, several blocks' serialized content
+array — and never a JSON string holding it. Pages used to arrive as
+`{ offset, nextOffset?, totalBytes, text }`, which escaped every quote and
+newline in the page: a second layer over JSON payloads that made them hard to
+read and swelled a 20,000-byte page of JSON lines to 25,000 characters or more.
+
+`maxBytes` is an upper bound clamped to the inline cap of the call that stashed
+the result — the connector's override when it had one, recorded in the stash
+entry — and a clamped request is answered, not refused, with `bytes` saying how
+much came back. Clients cut an oversized page exactly as they cut the original
+result. In the eval, agents that could finally see the handle asked for pages of
+50,000 bytes and more, and Claude Code rejected every one of those answers
+outright, leaving an agent that had just been told not to repeat a write with
+nothing to read. So no response to a truncated call or to a page request
+exceeds the cap plus a header of a few hundred bytes. Value mode's unpageable
+preview is cut short enough that its JSON escaping still fits. Entries stashed
+before the cap was recorded page at the deployment cap.
+
+A refused or failed stash write cannot undo a downstream success. Both call tools
+then return the same layout with a paging-unavailable notice and no `resultId`
+or paging action — the notice first, then the preview where one is usable, and
+for a write the same warning not to repeat it. Activity records success, and
+the operator logger receives a fixed warning naming the connector and tool
+without storage error prose. For read-only work, reduce the result inside
+`execute_code` — repeating an approved write is not a way to recover its output. Other result-processing failures use a fixed
+`result_processing_failed` message and are never retryable.
+
 ## Lexical discovery
 
 `search_tools` tokenizes tool names and descriptions at punctuation and

package/ethos.md

@@ -4,92 +4,89 @@ Connecta’s scope, refusals, and invariants. Contradictions require a design de
 
 ## What this is
 
-- **One MCP endpoint.** Agents reach configured connectors through JavaScript
-  and seven meta-tools. Every deployment requires an executor.
-- **Config-as-code.** One tenant and connector set; identities receive
-  config-derived views. Maintained providers, `remoteMcp()`, and `api()` obey
-  the same connector contract.
-- **Safe by default.** Only explicitly read-only tools run inside a program.
-  Others cross `call_destructive_tool`; the host owns human approval.
-- **One fetch-native core.** Web APIs support Node and Workers. Platform code
-  and optional features use explicit subpath imports.
+- **One MCP endpoint.** Agents reach configured connectors through JavaScript,
+  a required executor, and seven meta-tools, eight planned.
+- **Config-as-code.** One tenant and connector set; identities get
+  config-derived views. Maintained providers, `remoteMcp()`, and `api()` share
+  one connector contract.
+- **Safe by default.** Programs run only explicitly read-only tools unasked;
+  others cross `call_destructive_tool` or, planned, pause. The host owns approval.
+- **One fetch-native core.** Web APIs on Node and Workers; platform code and
+  optional features behind explicit subpaths; Effect inside, Promises outside.
 - **Human auth management.** Optional pages show status and payload-free history.
   Explicit permissions allow credential changes and OAuth. Capabilities stay in code.
 
 ## What this isn't
 
-No runtime registration, admin-editable capabilities, policy engine, approvals,
-or pauses. No schema ingestion, accounts, groups, protocol sessions, or server
-push. Inbound providers own identity; personal state remains within one tenant.
-Credentials fail at use, without background probes. Breaking changes remain
-acceptable; version numbers signal change, not stability.
+No runtime registration, admin-editable capabilities, or policy engine; config
+may only exempt a tool from asking. No schema ingestion, accounts, or groups;
+personal state remains within one tenant. Breaking changes remain acceptable;
+version numbers signal change, not stability.
 
 ## Decisions
 
 Revisiting a verdict requires a new argument. Accepted designs live in
-subsystem guides and the CHANGELOG.
+subsystem guides and the CHANGELOG; `planned` ones bind review before either
+carries them.
 
 | Decision | Verdict | Why |
 | --- | --- | --- |
-| OpenAPI / GraphQL ingestion | refused | the disease is a tool nobody chose — a document authored it; hand-written literals, even through a shared factory, are still authorship |
+| OpenAPI / GraphQL ingestion | refused | the disease is a document-authored tool nobody chose; hand-written literals, even through a shared factory, are still authorship |
 | Multi-tenancy / account model | refused | one deployment per tenant; inbound auth owns identity |
-| Policy engine, approvals, pauses | refused | the host asks the human; connecta only annotates |
+| Approvals and pauses | planned | a program pauses host-side at its first unapproved write until the destructive-annotated `resume_execution` repeats that exact call, the host's prompt approving it or its tool; an expiring journal replays the run, never re-sending unknown outcomes |
 | Runtime connector registration | refused | config-as-code is the security model |
-| Optional deployment modules | accepted | explicit imports and typed config slots select UI, activity history, credential vault, and inbound auth; discovery, execution, invocation, and enforcement stay in core |
-| Generic plugin lifecycle or marketplace | refused | modules organize deployment code; runtime installation and discovery add no required behavior |
-| Connecta-issued access tokens | removed | inbound identity providers own client authentication; configured bearer auth remains an optional adapter |
-| Provider registry / marketplace | refused | prebuilt connections are imports; discovery happens in docs ([#297](https://github.com/zackbart/connecta/issues/297)) |
+| Optional deployment modules | accepted | typed slots select UI, activity, vault, and inbound auth; core keeps discovery, execution, invocation, and enforcement |
+| Artifacts module | planned | a built-in connector, not a meta-tool: team-only sandboxed pages over stored JSON, never calling tools. Immutable versions let writes skip approval. Supersedes [#287](https://github.com/zackbart/connecta/issues/287) on executor's artifacts |
+| Plugin lifecycle, provider registry, or marketplace | refused | modules are deployment code, not runtime installs; prebuilt connections are imports, discovered in docs ([#297](https://github.com/zackbart/connecta/issues/297)) |
+| Connecta-issued access tokens | removed | inbound providers authenticate clients; bearer auth stays an optional adapter |
 | Expanded Notion page create/update options | refused | different workflows, not missing fields; use `api()` ([#408](https://github.com/zackbart/connecta/issues/408)) |
-| Protocol sessions & server push | refused | stateless per request |
-| Resources & prompts aggregation | refused | tools only; clients own presentation ([#266](https://github.com/zackbart/connecta/issues/266)) |
-| Elicitation passthrough | refused | no route through a stateless aggregator |
+| Resources, prompts, and downstream MCP Apps templates | refused | tools only; clients own presentation ([#266](https://github.com/zackbart/connecta/issues/266)) |
+| Protocol sessions, server push, elicitation passthrough | refused | stateless per request; elicitation has no route |
 | Repository formatter | refused | style is authored, not enforced |
-| Host-side projection of program results | refused | a program projects; a heuristic drops fields invisibly ([#223](https://github.com/zackbart/connecta/issues/223)) |
-| `get_result` paging for program results | refused | paging rewards the unprojected return code mode exists to remove ([#223](https://github.com/zackbart/connecta/issues/223)) |
+| Host-side projection or paging of program results | refused | a program projects: heuristics drop fields invisibly, paging rewards unprojected returns ([#223](https://github.com/zackbart/connecta/issues/223)) |
 | Native Tasks for oversized results | refused | tasks solve duration, `get_result` solves size ([#176](https://github.com/zackbart/connecta/issues/176)) |
 | Widening the `Executor` result contract | refused | `{ result, error?, logs? }` is the `@cloudflare/codemode` parity guarantee ([#267](https://github.com/zackbart/connecta/issues/267)) |
-| Erasable TypeScript in `execute_code` | refused | 24 MB dependency in the core, no measured agent benefit ([#419](https://github.com/zackbart/connecta/issues/419)) |
-| Guest-minted `resource` / `resource_link` blocks | refused | a program can never mint a URI a client may dereference ([#266](https://github.com/zackbart/connecta/issues/266)) |
+| Erasable TypeScript in `execute_code` | refused | a 24 MB core dependency, no measured agent benefit ([#419](https://github.com/zackbart/connecta/issues/419)) |
+| Guest-minted `resource` / `resource_link` blocks | refused | no program mints a URI a client may dereference ([#266](https://github.com/zackbart/connecta/issues/266)) |
 | Provenance tracking for emitted content | refused | everything a program emits is program output ([#267](https://github.com/zackbart/connecta/issues/267)) |
-| Result sampling on the catalog surface | refused | sampling is execution and cannot ride a catalog read ([#282](https://github.com/zackbart/connecta/issues/282)) |
+| Result sampling on the catalog surface | refused | sampling is execution, not a catalog read ([#282](https://github.com/zackbart/connecta/issues/282)) |
 | Legacy embedded `UIResource` delivery | refused | superseded upstream, rendered by no client we face ([#266](https://github.com/zackbart/connecta/issues/266)) |
-| Effect as the core effect system | refused | −4% of the core for +75 KB gzip and a second async paradigm; re-measure at v4 stable ([#470](https://github.com/zackbart/connecta/issues/470)) |
-| Shared bounded queue under both admission controllers | refused | built and measured −17 lines for a hook-parameterised abstraction ([#453](https://github.com/zackbart/connecta/issues/453)) |
+| Effect as the core effect system | accepted | lifetimes held the bugs: the rewrite closed leaked permits, hung waits, and cross-request races. Overturns [#470](https://github.com/zackbart/connecta/issues/470) |
+| Shared bounded queue under both admission controllers | refused | built: −17 lines bought a hook-parameterised abstraction ([#453](https://github.com/zackbart/connecta/issues/453)) |
 | MCP Apps rendering and `connecta.ui` | removed | clients render returned data |
 | Connector shortcut globals | removed | canonical addresses need no sanitization |
 | `connecta.batch` | removed | JavaScript promises suffice |
 | Automatic direct-call retries | removed | callers own retry timing |
-| Connector HTTP routes | removed | deployments own custom routes |
-| Caller-selected toolkits | removed | config derives every view; config-declared, grant-gated pools at `/mcp/<pool>` are not caller-selected ([#178](https://github.com/zackbart/connecta/issues/178), [#531](https://github.com/zackbart/connecta/issues/531)) |
+| Connector HTTP routes | removed | deployments own custom routes; artifact viewing is the planned exception |
+| Caller-selected toolkits | removed | config derives every view, grant-gated `/mcp/<pool>` pools included ([#178](https://github.com/zackbart/connecta/issues/178), [#531](https://github.com/zackbart/connecta/issues/531)) |
 | Proactive credential liveness | removed | fail-at-use is enough ([#179](https://github.com/zackbart/connecta/issues/179)) |
 | Classic (executor-free) surface | removed | an executor is mandatory ([#273](https://github.com/zackbart/connecta/issues/273)) |
-| Per-result lexical query coverage | removed | did not earn its response bytes in a precommitted gate ([#323](https://github.com/zackbart/connecta/issues/323)) |
-| Stabilized workflows | gated | needs programs that actually recur ([#225](https://github.com/zackbart/connecta/issues/225)) |
+| Per-result lexical query coverage | removed | failed a precommitted response-bytes gate ([#323](https://github.com/zackbart/connecta/issues/323)) |
+| Stabilized workflows | planned | only as artifact refresh: scheduled read-only programs, shared credentials ([#225](https://github.com/zackbart/connecta/issues/225)) |
 | Semantic tool search | gated | keyword search has not been shown to fail ([#27](https://github.com/zackbart/connecta/issues/27)) |
 | MRTR / `input_required` passthrough | gated | relayable statelessly; no host or downstream emits it yet ([#176](https://github.com/zackbart/connecta/issues/176)) |
 | Downstream `ttlMs` cache hints | gated | needs refresh-churn evidence ([#206](https://github.com/zackbart/connecta/issues/206)) |
-| Downstream MCP Apps template passthrough | refused | clients own presentation; Connecta serves tools and data |
 | Worker Access inbound auth | provisional | Managed OAuth and Clerk migration need production evidence ([#506](https://github.com/zackbart/connecta/issues/506)) |
 | Program UI tool calls | removed | duplicated calls without improving retrieval ([#287](https://github.com/zackbart/connecta/issues/287), [#484](https://github.com/zackbart/connecta/issues/484)) |
 
 ## Invariants
 
-Tests beside subsystem documentation enforce these invariants. Breaking one
-requires a design decision.
+Tests beside subsystem documentation enforce these; breaking one requires a
+design decision.
 
 - **Fail-closed read-only.** A missing, false, or contradictory annotation never gets the benefit of the doubt.
 - **Generated code cannot mint capabilities.** Admission, credentials, and classification are enforced below the sandbox.
-- **Only explicitly read-only work runs inside the sandbox.** Everything else crosses `call_destructive_tool`.
-- **Nothing request-bound survives a request.** No transport, stream, signal, or awaited promise outlives it.
-- **A downstream catalog is complete or it is a failure.** A partial catalog is never cached, persisted, or served.
+- **Only explicitly read-only work runs unasked in the sandbox.** Everything else crosses `call_destructive_tool` or, planned, `resume_execution` or a config exemption.
+- **Nothing request-bound survives a request.** No transport, stream, signal, or awaited promise outlives it; a paused journal is data, not a request.
+- **A downstream catalog is complete or it is a failure.** A partial one is never cached, persisted, or served.
 - **Activity is payload-free by construction.** The event type has nowhere to put arguments, results, code, or raw errors.
 - **An observed shape is never a declaration.** Names and broad types only, labeled, and gone behind any declared schema.
-- **Credentials never leave the host.** Encrypted at rest, readable only by the owning connector and, for personal auth, its owning principal; rendered by nothing.
-- **Import-graph purity.** Nothing reachable from the root entry imports a `node:` builtin.
-- **The published surface is a boundary.** Heavyweight or platform-bound code goes behind an optional-peer subpath.
-- **Human routes manage auth, never capability.** Visibility grants use, not credential administration. Shared and personal auth mutations require separate config-derived permissions, both denied by default. Activity has its own read permission.
-- **Omitted modules do no work.** Core imports no UI bundle, encrypted vault implementation, activity implementation, or bearer adapter. OAuth callbacks remain available without UI.
-- **Status reads do not start authorization.** OAuth starts through an explicit authorized action; loading the UI never creates a consent flow.
+- **Credentials never leave the host.** Encrypted at rest, readable only by the owning connector (and principal, for personal auth), rendered by nothing.
+- **Import-graph purity.** Nothing reachable from the root entry imports a `node:` builtin or `effect/testing`.
+- **The published surface is a boundary.** Heavyweight or platform-bound code goes behind an optional-peer subpath; Effect is the one hard dependency, named by no published type.
+- **Human routes manage auth, never capability.** Visibility grants use, not administration. Shared and personal auth mutations need separate config-derived permissions, both denied by default, and activity reads their own. Planned: viewing artifacts.
+- **Omitted modules do no work.** Core imports no UI bundle, vault, activity, or bearer implementation. OAuth callbacks work without UI.
+- **Status reads do not start authorization.** Only an explicit authorized action starts OAuth, never a page load.
 - **Structural mistakes throw at construction.** Booting into the wrong shape is worse than not booting.
 
 Connecta simplifies [executor](https://github.com/UsefulSoftwareCo/executor).

package/examples/worker/README.md

@@ -16,15 +16,17 @@ migrations, and secrets.
 | --- | --- |
 | `src/index.ts` | the Worker entrypoint — connector and auth configuration |
 | `src/cloudflare-kv.ts` | `KVStorage` over Workers KV (deployment-owned, not a package export) |
+| `src/d1-storage.ts` | `KVStorage` over D1 with atomic compare-and-set (optional; see below) |
 | `src/d1-activity.ts` | `ActivityStore` over D1 (deployment-owned; see below) |
 | `src/d1-activity-row.ts` | the row ↔ event mapping `d1-activity.ts` uses, including friction derived from `error_code` for rows written before that column existed |
 | `wrangler.jsonc` | Worker name, vars, bindings, `compatibility_flags` |
 
-`cloudflare-kv.ts` and `d1-activity.ts` deliberately live here rather than in
-the package: storage backends are deployment-owned, so the package ships only
-the generic `KVStorage` and `ActivityStore` contracts. Workers KV is eventually
-consistent across locations; use a strongly consistent `KVStorage` adapter when
-OAuth disconnect or credential rotation must become globally visible
+`cloudflare-kv.ts`, `d1-storage.ts`, and `d1-activity.ts` deliberately live
+here rather than in the package: storage backends are deployment-owned, so the
+package ships only the generic `KVStorage` and `ActivityStore` contracts.
+Workers KV is eventually consistent across locations; use a strongly consistent
+`KVStorage` adapter, such as [`d1-storage.ts`](#strongly-consistent-storage-optional),
+when OAuth disconnect or credential rotation must become globally visible
 immediately.
 
 ## Deploy
@@ -214,6 +216,50 @@ serves the seven-tool surface. Do not add `bindings`, `modules`, or
 owns the package install — see
 [copied into its own repository](#copied-into-its-own-repository).
 
+## Strongly consistent storage (optional)
+
+`KVStorage` has an optional atomic `compareAndSet`, for a subsystem that must
+claim a key exactly once. **Workers KV cannot provide it.** It is eventually
+consistent: two locations can each read a key as absent and both write, so
+`cloudflare-kv.ts` declares no `compareAndSet` rather than fake one with a read
+followed by a write. `src/d1-storage.ts` is a complete `KVStorage` over D1
+that does provide it, one SQL statement per claim, with TTLs honored at read
+time. It replaces the KV namespace rather than sitting beside it: every piece
+of connecta state lives in one store.
+
+1. Create the database and uncomment the `STORAGE_DB` entry of the
+   `d1_databases` binding in `wrangler.jsonc`, pasting in the id it prints:
+
+   ```sh
+   wrangler d1 create connecta-storage
+   ```
+
+2. Apply the schema (keep it in a deployment-owned `migrations/` directory):
+
+   ```sql
+   CREATE TABLE IF NOT EXISTS connecta_kv (
+     key           TEXT PRIMARY KEY,
+     value         TEXT NOT NULL,
+     expires_at_ms INTEGER
+   );
+
+   CREATE INDEX IF NOT EXISTS connecta_kv_expiry
+     ON connecta_kv (expires_at_ms);
+   ```
+
+3. In `src/index.ts`, add `STORAGE_DB: D1Database` to `Env` and build the store
+   from it:
+
+   ```ts
+   import { d1Storage } from "./d1-storage.js";
+
+   const storage = d1Storage(env.STORAGE_DB);
+   ```
+
+   Switching an existing deployment starts from empty state: downstream OAuth
+   connections must be re-authorized and vault credentials re-entered, because
+   nothing copies them out of the KV namespace.
+
 ## Activity history (optional)
 
 `src/d1-activity.ts` is a complete `ActivityStore` over D1 — keyset paging on

package/examples/worker/src/d1-storage.ts

@@ -0,0 +1,116 @@
+import type { KVStorage } from "@zackbart/connecta";
+
+/**
+ * KVStorage over a D1 database, with the atomic `compareAndSet` that Workers
+ * KV cannot offer. Apply the `connecta_kv` schema in README.md § "Strongly
+ * consistent storage" before first use.
+ *
+ * Every compare-and-set is a single SQL statement. D1 runs one database's
+ * statements one at a time against its primary, so the comparison and the
+ * write cannot interleave with another request's: of fifty concurrent claims
+ * on an absent key, exactly one changes a row.
+ *
+ * Expiry is judged by the Worker's clock at each call, the same `Date.now()`
+ * the core uses. An expired row reads as absent immediately and is removed
+ * physically by later writes, a bounded batch at a time, so no request starts
+ * a background job and no cron is required.
+ */
+export function d1Storage(db: D1Database): KVStorage {
+  // Every statement that tests liveness binds the current time as ?2.
+  const live = "(expires_at_ms IS NULL OR expires_at_ms > ?2)";
+  const expiresAt = (now: number, ttlSeconds?: number) =>
+    ttlSeconds ? now + ttlSeconds * 1000 : null;
+  const changed = (result: D1Result) => result.meta.changes > 0;
+  return {
+    async get(key) {
+      const row = await db
+        .prepare(`SELECT value FROM connecta_kv WHERE key = ?1 AND ${live}`)
+        .bind(key, Date.now())
+        .first<{ value: string }>();
+      return row?.value ?? null;
+    },
+    async set(key, value, opts) {
+      const now = Date.now();
+      await db.batch([
+        db
+          .prepare(
+            `DELETE FROM connecta_kv WHERE key IN (
+              SELECT key FROM connecta_kv WHERE expires_at_ms <= ?1 LIMIT 16
+            )`,
+          )
+          .bind(now),
+        db
+          .prepare(
+            `INSERT INTO connecta_kv (key, value, expires_at_ms)
+             VALUES (?1, ?2, ?3)
+             ON CONFLICT (key) DO UPDATE SET
+               value = excluded.value, expires_at_ms = excluded.expires_at_ms`,
+          )
+          .bind(key, value, expiresAt(now, opts?.ttlSeconds)),
+      ]);
+    },
+    async delete(key) {
+      await db.prepare("DELETE FROM connecta_kv WHERE key = ?1").bind(key).run();
+    },
+    async list(prefix) {
+      const { results } = await db
+        .prepare(
+          `SELECT key FROM connecta_kv
+           WHERE key >= ?1 AND substr(key, 1, length(?1)) = ?1 AND ${live}`,
+        )
+        .bind(prefix, Date.now())
+        .all<{ key: string }>();
+      // Sort in JavaScript: SQLite orders UTF-8 bytes, the contract orders
+      // the UTF-16 code units every other adapter sorts by.
+      return results.map((row) => row.key).sort();
+    },
+    async compareAndSet(key, expected, next, opts) {
+      const now = Date.now();
+      if (next === null && expected === null) {
+        // Nothing to write; the claim holds exactly when no live row exists.
+        const row = await db
+          .prepare(`SELECT 1 AS present FROM connecta_kv WHERE key = ?1 AND ${live}`)
+          .bind(key, now)
+          .first();
+        return row === null;
+      }
+      if (next === null) {
+        return changed(
+          await db
+            .prepare(
+              `DELETE FROM connecta_kv WHERE key = ?1 AND ${live} AND value = ?3`,
+            )
+            .bind(key, now, expected)
+            .run(),
+        );
+      }
+      const expiry = expiresAt(now, opts?.ttlSeconds);
+      if (expected === null) {
+        // Insert, or take over a row that has expired. A live row makes the
+        // upsert's WHERE false, so nothing changes and the claim is refused.
+        return changed(
+          await db
+            .prepare(
+              `INSERT INTO connecta_kv (key, value, expires_at_ms)
+               VALUES (?1, ?3, ?4)
+               ON CONFLICT (key) DO UPDATE SET
+                 value = excluded.value, expires_at_ms = excluded.expires_at_ms
+               WHERE connecta_kv.expires_at_ms IS NOT NULL
+                 AND connecta_kv.expires_at_ms <= ?2`,
+            )
+            .bind(key, now, next, expiry)
+            .run(),
+        );
+      }
+      return changed(
+        await db
+          .prepare(
+            `UPDATE connecta_kv SET value = ?4, expires_at_ms = ?5
+             WHERE key = ?1 AND ${live} AND value = ?3`,
+          )
+          .bind(key, now, expected, next, expiry)
+          .run(),
+      );
+    },
+  };
+}

package/examples/worker/src/index.ts

@@ -50,8 +50,8 @@ interface Env {
   CONNECTA_KV: KVNamespace;
   /**
    * Base64 32-byte AES key encrypting operator-managed credentials in KV.
-   * Unset means no vault: /credentials stays read-only and connecta says so at
-   * startup. Never put it in KV — it is what protects KV.
+   * Unset means no vault: credential management is unavailable in the operator
+   * UI. Never put it in KV, since it is what protects KV.
    */
   CREDENTIAL_ENCRYPTION_KEY: string;
   DOWNSTREAM_TOKEN: string;
@@ -121,8 +121,8 @@ function build(env: Env) {
           type: "headers",
           headers: { Authorization: `Bearer ${env.DOWNSTREAM_TOKEN}` },
           // The vault-backed alternative for a downstream that authenticates
-          // with a static key: the operator pastes it at /credentials and
-          // rotates it there, so no Worker secret holds it.
+          // with a static key: the operator manages it inside its connection
+          // in the operator UI, so no Worker secret holds it.
           //   type: "credential",
           //   credential: { label: "Notion internal integration token" },
         },
@@ -132,8 +132,8 @@ function build(env: Env) {
       }),
       api("echo", {
         description: "Echo — text transforms",
-        // What a vault-backed connector adds — an operator edits this slot at
-        // /credentials and the handler reads it with
+        // What a vault-backed connector adds — an operator edits this slot
+        // inside its connection in the operator UI and the handler reads it with
         // `await ctx.credential?.get()`, so the secret never lives in source
         // or in a Worker variable:
         //   credential: { label: "API token" },