@zackbart/connecta 0.26.0 → 0.26.1

package/documentation/architecture.md

@@ -287,14 +287,24 @@ answers only `{ ok }`), log its text, and the page picks a sentence by outcome
 without ever rendering what the server sent. 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
-with `color-mix`, so `branding.theme` only has to append a `:root` block after
-that stylesheet. The five tokens it accepts are gated in `src/branding.ts`, each
-by a narrow syntactic check: deployment config reaches a `<style>` element here,
-and an unvalidated value would be CSS injection. The dark palette is the same
-tokens under `prefers-color-scheme`; `colorScheme` pins one with a `data-scheme`
-attribute on the page.
+Its appearance is one token layer, and it is not the UI's alone: every page
+connecta shows a person — the operator shell, the OAuth callback, a browser's
+404, the artifact frame and Markdown pages — reads it. `src/operator-ui/tokens.css`
+resolves every color, radius, and font through a custom property and mixes the
+rest from those with `color-mix`; `page.css` holds the base typography and the
+primitives (shell, masthead, buttons, badges, messages, the one-message status
+page). The UI's `browser.css` imports both, and the build writes the same CSS,
+minified, into `src/page-styles.ts`, a module of two strings that core imports
+without the UI bundle, so an OAuth callback still renders with the UI omitted.
+`renderPage` in `src/branding.ts` is the one layout: head, favicon (the default
+is linked only when the UI serves it), `data-scheme`, the tokens with the theme
+after them, and the masthead. So `branding.theme` only has to append a `:root`
+block after the stylesheet. The five tokens it accepts are gated in
+`src/branding.ts`, each by a narrow syntactic check: deployment config reaches a
+`<style>` element here, and an unvalidated value would be CSS injection. The
+dark palette is the same tokens under `prefers-color-scheme`; `colorScheme` pins
+one with a `data-scheme` attribute on the page, and the artifact viewer passes
+the same attribute into a Markdown page, never into authored HTML.
 
 The artifacts module — `artifacts()` from `/artifacts`, implemented in
 `src/artifacts/` — is the one module that contributes a connector. Core

package/documentation/auth.md

@@ -250,6 +250,87 @@ 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.
 
+## Starting, restarting, and retiring an OAuth epoch
+
+Every downstream OAuth value lives under an **epoch**, the value of
+`oauth:generation`. A restart or disconnect publishes a new one before it
+deletes anything, and a write from a flow that captured an older epoch lands
+in that epoch's own key namespace, where no reader looks. The fence is what
+keeps a retired grant out of use; deleting the old keys is hygiene on top.
+
+The operator's `POST /ui/oauth/<id>` takes a `mode` query parameter:
+
+| Request | What it does |
+| --- | --- |
+| `POST /ui/oauth/<id>` or `?mode=restart` | `startAuth(ctx, { force: true })`: a new epoch, with tokens, the registered client, discovery, and any pending flow wiped, so the next flow registers a client again. |
+| `?mode=continue` | `startAuth(ctx, { force: false })`: hand back the pending authorization URL if it was written in the last ten minutes; otherwise start a flow in the current epoch, reusing the stored client registration. A disconnected connector still gets its new epoch first. |
+| `DELETE /ui/oauth/<id>` | Disconnect: a disconnected epoch that passive reads never turn back into a consent flow. |
+
+Any other `mode`, or more than one, is a 400 before anything starts; the
+management permission, visibility, and principal checks are the same for
+both modes, and a personal connector continues only the caller's own flow.
+A 200 answers `{ state, authorizationUrl?, reused? }`, with `reused` present
+beside every URL: `true` when an earlier start's URL came back unchanged. A
+continue that reused a URL or found the connection healthy changed nothing,
+so it leaves the cached catalog alone; every other start invalidates it. The
+ten minutes are `PENDING_AUTHORIZATION_MAX_AGE_MS`. Connecta never expires
+its own half of a URL, but authorization servers expire theirs, and a fresh
+start that keeps the registration costs one authorization request. A URL
+stored without a write time — by an earlier release, or by a connector never
+reset since epochs arrived — is stale by definition. `authorize_connector`
+without `force` follows the same rule.
+
+Continue trusts the stored registration, which carries the `redirect_uris`
+it was registered with. After a `publicUrl` change the authorization server
+refuses that client's new callback at consent. Restart registers a client
+for the current URL and recovers.
+
+A restart cannot know which retired epochs a late write reached, so it
+publishes a **cleanup lineage** under the new epoch before activating it:
+the retired epochs, as the same plain list of names every release reads, and
+beside it a record of when each retired. A published lineage is never
+rewritten. A stale writer whose own cleanup fails appends to the live
+lineage, and a restart that rewrote the list it had read could drop that
+append. An epoch leaves the lineage only by being left out of its
+successor's.
+
+A restart does the same storage work however many came before it. After the
+fence it deletes the one epoch it retired: six values, then that epoch's own
+lineage records. An epoch's manifest outlives its values only when their
+deletion failed, so the restart also reads the manifests of the eight most
+recently retired epochs (`RETRY_PROBES`) and cleans up again any that still
+have one. A Disconnect or Restart that reported a failed cleanup therefore
+deletes the old grant when the operator retries it. Before publishing, it
+sweeps up to 16 epochs retired more than `CLEANUP_GRACE_MS` (24 hours) ago,
+oldest first, and leaves out only those whose values and records were all
+deleted. A failed sweep is carried and tried again later, and never fails
+the restart. Any other epoch inside its grace is not deleted again. A late write into it is unreadable behind the fence,
+and the late writer deletes it itself. If that delete fails, the writer
+records the epoch again as retired at that moment, appending it or, when it
+is already listed, moving only its time. A restart that swept it re-reads the
+lineage before publishing and keeps it. Whatever remains is swept once the
+grace has passed. Two such writers racing can lose one time update, which
+leaves the earlier time; a time missing altogether reads as retired at the
+moment of the restart that reads it, which only lengthens a grace.
+
+**The assumption:** no request holds a retired epoch for a day. The writers
+that can land late are OAuth flows, refreshes, and readers whose Workers KV
+replica still serves the old generation for a minute or more; none of them
+run that long. If it fails, only a writer that dies between its write and
+its own cleanup leaves residue no restart tracks, and that residue is never
+readable.
+
+The lineage holds at most 5,000 epochs, the ones retired within the last day
+plus any the sweep has not reached. A restart that would exceed that is
+refused before the fence moves, which takes more than 4,000 restarts of one
+connector in a day on top of the 1,000 an earlier release allowed. A
+connector that reached that release's 1,000 wall restarts again the day it
+upgrades, and its old entries drain 16 per restart a day later. An older
+release ignores the times, so a rollback still restarts unless a lineage has
+grown past its own 1,000 cap. Deletes run six at a time, the Workers limit
+on simultaneous connections, and catalog invalidation deletes its chunks
+concurrently under the registry's chunk I/O bound.
+
 ## Refresh failures
 
 A failed token refresh means one of two things, and connecta decides which
@@ -429,6 +510,28 @@ instead of a base64 stack on every route.
 
 ## Human authentication management
 
+An operator's OAuth Connect or Restart request gives the start and its handoff
+30 seconds. The request's abort signal and that deadline reach downstream OAuth
+fetches, including metadata discovery and dynamic registration. If the deadline
+expires, the route returns `504` with `OAuth authorization start timed out` after
+an already-started reset finishes. Storage has no cancellation contract: its
+generation write must drain before a response, or it could publish an old epoch
+over a newer flow. Catalog invalidation and connector scope close also finish
+outside the deadline. Those storage and cleanup waits can extend the click past
+30 seconds; the bound is on downstream work, where a hung authorization server
+was the failure. The OAuth provider checks its signal before writing and removes
+a cancelled value write that finishes late. An operator Disconnect keeps its
+existing commit-through behavior even if the browser leaves.
+
+Restart retains a dynamically registered client only when its stored issuer and
+the connector's URL, redirect URI, client metadata, auth scope, transport settings,
+and owner partition still match. It drops the grant and one-shot flow state,
+selects the authorization server again, and re-seals the retained client under
+the replacement epoch key. A different issuer registers a new client. Disconnect
+and issuer-mismatch recovery discard it. The SDK has no client-validation
+exchange while constructing a fresh consent URL; a provider that revokes a
+retained client may refuse it only at consent or callback, after this request.
+
 Credential and OAuth mutation require an admitted interactive human, connector
 visibility, the appropriate shared or personal permission, and an exact
 same-origin `Origin` for browser requests. A configured MCP bearer never becomes

package/documentation/code-mode.md

@@ -504,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:
@@ -528,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).** 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.
+**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.
+
+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
@@ -833,6 +832,7 @@ 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

package/documentation/meta-tools.md

@@ -69,10 +69,14 @@ 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.
+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
@@ -81,8 +85,11 @@ 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. `approval: "tool"` covers the rest of the
-run's calls to that tool, so thirty closes cost one prompt. One known write
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.26.0",
+  "version": "0.26.1",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of eight meta-tools.",

package/templates/node/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.26.0",
+    "@zackbart/connecta": "0.26.1",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {