@zackbart/connecta 0.41.0 → 0.42.0

package/dist/validate.js

@@ -190,7 +190,7 @@ function receivedType(value) {
  * No caller values are used to invent an example, and a writeOnly position or
  * anything inside one never renders a schema literal. A candidate must validate.
  */
-function exampleCandidate(schema, root, depth = 0, budget = { remaining: 128, active: new Set() }, secret = false) {
+function exampleCandidate(schema, root, depth = 0, budget = { remaining: 128, active: new Set(), placeholders: false }, secret = false, key) {
     if (--budget.remaining < 0)
         throw new Error("Example synthesis budget exhausted");
     if (depth > 12 || schema === false)
@@ -224,7 +224,7 @@ function exampleCandidate(schema, root, depth = 0, budget = { remaining: 128, ac
             candidate = Object.fromEntries(required
                 .filter((key) => typeof key === "string")
                 .slice(0, 30)
-                .map((key) => [key, exampleCandidate(properties[key], root, depth + 1, budget, secret)]));
+                .map((key) => [key, exampleCandidate(properties[key], root, depth + 1, budget, secret, key)]));
             if (Array.isArray(node.allOf)) {
                 for (const branch of node.allOf.slice(0, 20)) {
                     candidate = mergeExample(candidate, exampleCandidate(branch, root, depth + 1, budget, secret));
@@ -258,7 +258,7 @@ function exampleCandidate(schema, root, depth = 0, budget = { remaining: 128, ac
             // Branches may declare required keys while their types live on the parent.
             for (const key of Object.keys(schemaObject(candidate))) {
                 if (schemaObject(candidate)[key] === undefined) {
-                    schemaObject(candidate)[key] = exampleCandidate(properties[key], root, depth + 1, budget, secret);
+                    schemaObject(candidate)[key] = exampleCandidate(properties[key], root, depth + 1, budget, secret, key);
                 }
             }
         }
@@ -290,10 +290,11 @@ function exampleCandidate(schema, root, depth = 0, budget = { remaining: 128, ac
                 uri: "https://example.com",
                 uuid: "00000000-0000-4000-8000-000000000000",
             };
+            const named = budget.placeholders && !secret && key !== undefined ? namedPlaceholder(key, node) : undefined;
             candidate =
                 typeof node.format === "string" && formats[node.format]
                     ? formats[node.format]
-                    : "x".repeat(Math.min(typeof node.minLength === "number" ? node.minLength : 0, 128));
+                    : (named ?? "x".repeat(Math.min(typeof node.minLength === "number" ? node.minLength : 0, 128)));
         }
         return candidate;
     }
@@ -301,6 +302,19 @@ function exampleCandidate(schema, root, depth = 0, budget = { remaining: 128, ac
         budget.active.delete(node);
     }
 }
+/**
+ * `<id>` for a plain string argument: an empty string would satisfy local
+ * validation and reach the downstream looking like a real value. A secret
+ * position, an odd key, and a length bound it misses keep the plain sample.
+ */
+function namedPlaceholder(key, node) {
+    if (!/^[\w.-]{1,64}$/.test(key))
+        return undefined;
+    const text = `<${key}>`;
+    const min = typeof node.minLength === "number" ? node.minLength : 0;
+    const max = typeof node.maxLength === "number" ? node.maxLength : Infinity;
+    return text.length >= min && text.length <= max ? text : undefined;
+}
 function mergeExample(a, b) {
     if (a !== null &&
         b !== null &&
@@ -501,12 +515,17 @@ function validationIssues(schema, args, units) {
 export function schemaExample(schema) {
     try {
         const validator = validators.get(schema) ?? new Validator(schema, "2020-12", false);
-        // Serialization makes the validation cover exactly what the agent receives.
-        const example = JSON.parse(JSON.stringify(exampleCandidate(schema, schema)));
-        if (validator.validate(example).valid) {
-            minimizeExample(example, validator);
-            if (validator.validate(example).valid)
-                return { example };
+        // Named placeholders first; a schema that refuses them, such as one with a
+        // pattern, falls back to the plain sample rather than losing its example.
+        for (const placeholders of [true, false]) {
+            const budget = { remaining: 128, active: new Set(), placeholders };
+            // Serialization makes the validation cover exactly what the agent receives.
+            const example = JSON.parse(JSON.stringify(exampleCandidate(schema, schema, 0, budget)));
+            if (validator.validate(example).valid) {
+                minimizeExample(example, validator);
+                if (validator.validate(example).valid)
+                    return { example };
+            }
         }
     }
     catch {

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CONNECTA_VERSION = "0.41.0";
+export declare const CONNECTA_VERSION = "0.42.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated from package.json by scripts/generate-version.mjs.
 // Workers-safe: no runtime filesystem read or deployment override.
-export const CONNECTA_VERSION = "0.41.0";
+export const CONNECTA_VERSION = "0.42.0";

package/dist/worker.js

@@ -7,6 +7,7 @@ import { awaitExecutorLease, provideExecutorProgram, executorProgram } from "./r
 import { DynamicWorkerExecutor, normalizeCode } from "@cloudflare/codemode";
 import { AdmissionController, ExecutorExecutionError } from "./executor-admission.js";
 import { brandExecutor } from "./executor-contract.js";
+import { TOKEN_END } from "./errors.js";
 import { InvocationFailure } from "./invocation.js";
 import { parse } from "acorn";
 import { guestInitializer, guestPrelude, guestPromiseInitializer, isolateGuestProgram } from "./guest-runtime.js";
@@ -43,15 +44,25 @@ function routeGuestImports(source) {
     }
     return source;
 }
+/**
+ * The guest deadline when `timeout` is unset: below `execute.watchdogMs`, and
+ * so below the 60 s MCP clients give one request. Upstream's own default is
+ * that 60 s, which races them.
+ */
+const DEFAULT_TIMEOUT_MS = 50_000;
+const DEFAULT_QUEUE_TIMEOUT_MS = 40_000;
 /** Loader-only upstream sandbox whose lease disposes handles at run end. */
 export function workerExecutor(options) {
-    // One pool per executor, so per isolate. A queued run may wait out one
+    const timeoutMs = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    // One pool per executor, so per isolate. A queued run may wait most of a
     // default guest deadline: programs spend it awaiting host calls, and a
-    // five-second wait refused nearly every run queued behind one.
+    // five-second wait refused nearly every run queued behind one. The wait
+    // spends the request's response ceiling, so it stops short enough to leave
+    // the run time to work and the refusal time to reach the client.
     const admission = new AdmissionController(options.admission ?? {
         concurrency: 2,
         maxQueueSize: 8,
-        queueTimeoutMs: 60_000,
+        queueTimeoutMs: DEFAULT_QUEUE_TIMEOUT_MS,
         retryAfterMs: 1_000,
     });
     const active = new Set();
@@ -177,19 +188,27 @@ export function workerExecutor(options) {
                         isolated = isolated.replace("setTimeout(() => reject(timeoutError)", "nativeSetTimeout(() => reject(timeoutError)");
                         isolated = isolated.replace("return { result: undefined, error: err.message, logs: __logs };", `
       const failureId = lookup(failures, err);
+      // tokenPrefix, for text the host redacts after this cut.
+      const tokenEnd = (unit) => ${[...TOKEN_END].map((unit) => `unit === ${unit}`).join(" || ")};
+      const prefix = (text, units) => {
+        if (units >= text.length) return text;
+        let end = units;
+        while (end > 0 && !tokenEnd(charCodeAt(text, end))) end--;
+        return slice(text, 0, end);
+      };
       let name = "Error", message = "Program threw a value.", stack = "";
       try {
-        if (typeof err === "string") message = slice(err, 0, 1000);
+        if (typeof err === "string") message = prefix(err, 1000);
         else if (err) {
-          if (typeof err.name === "string") name = slice(err.name, 0, 64);
-          if (typeof err.message === "string") message = slice(err.message, 0, 1000);
+          if (typeof err.name === "string") name = prefix(err.name, 64);
+          if (typeof err.message === "string") message = prefix(err.message, 1000);
           if (typeof err.stack === "string") stack = slice(err.stack, 0, 1000);
         }
       } catch {}
       const location = exec(/connecta-guest\\.js:(\\d+):\\d+/, stack);
       return { result: undefined, error: message, logs: __logs, failure: {
         name, ...(failureId ? { failureId } : {}), ...(location ? { line: toNumber(location[1]) - 1 } : {}),
-        ...(err === timeoutError ? { timeout: { elapsedMs: ${options.timeout ?? 60_000}, deadlineMs: ${options.timeout ?? 60_000} } } : {})
+        ...(err === timeoutError ? { timeout: { elapsedMs: ${timeoutMs}, deadlineMs: ${timeoutMs} } } : {})
       } };`);
                         const preludes = [];
                         let firstInitializer;
@@ -362,7 +381,7 @@ const {
                         try: () => {
                             const upstream = new DynamicWorkerExecutor({
                                 loader,
-                                ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
+                                timeout: timeoutMs,
                             }).execute(code, detached);
                             // The SDK's own result, which settles only after endUpstream(),
                             // carries nothing; the native evaluation below owns the outcome.
@@ -463,6 +482,7 @@ const {
     const acquireShell = (request) => runEdge(acquire(request));
     const executor = {
         name: "DynamicWorkerExecutor",
+        deadlineMs: timeoutMs,
         acquire: acquireShell,
         execute: (code, providers) => runEdge(execute(code, providers)),
         admissionSnapshot: () => admission.snapshot(),

package/documentation/architecture.md

@@ -240,7 +240,7 @@ An admitted non-preflight `/mcp` request then takes five steps in
 5. **Serve.** Refuse `?toolkit=` with a 404 — the toolkits are gone
    ([#178](https://github.com/zackbart/connecta/issues/178)) but their URLs were
    handed out, and retiring a scoping boundary into fail-open is worse than any
-   404 — then register the six meta-tools on a fresh `McpServer`
+   404 — then register the meta-tools on a fresh `McpServer`
    (`test/server.test.ts`).
 
 ### Modern request metadata and transport refusals
@@ -358,6 +358,13 @@ reader. `program-result.ts` owns executor-independent byte limits;
 values through provider preludes. Cursors hold only an ID and offset for the
 current run. Result bytes, expiry, authority and capacity charges stay in the
 existing storage and ledger; no executor-specific store or storage key is added.
+`result-seal.ts` keeps a run's results unreadable to other requests until they pass
+its final secret set ([`R4a`](./code-mode.md#results-and-projection)): chunk 0 waits in a
+request-owned ledger, and absence of chunk 0 is the refusal, so every exit leaves
+unpublished entries unreadable with no further write. Sealing waits for the work that can
+add to the set (`HeldResults.track` for the run's host calls, `RequestOwner.credentialReads`
+for credential reads, which outlast a caller that stopped waiting), then publishes each
+entry that passes. Stored bytes are never rewritten.
 
 ## Admission, in two places
 
@@ -749,8 +756,8 @@ the search returns, never raced or detached, since a storage write cannot be
 withdrawn once sent. The budget bounds when health work starts, not when it
 finishes, so slow storage can carry a search past it by one operation's
 latency. A scoped search,
-`connecta.describe`, native `tools/list` and tool calls keep the full
-`discovery.probeTimeoutMs`. A probe that times out on its own deadline, or a
+`connecta.describe` and tool calls keep the full `discovery.probeTimeoutMs`,
+as does a native `tools/list` for a connector with no stale catalog. A probe that times out on its own deadline, or a
 retryable failure that itself took at least one second or named its own wait,
 writes a record in the `connector-health:v1:` family: the connecta
 classification code, observation time, retry time (60 seconds later, or the
@@ -800,7 +807,56 @@ retain a complete private fallback, and static catalogs remain
 in configuration. After a transient first-page tool listing failure, ordinary calls
 may use a complete catalog for up to five minutes after its expiry in the same
 auth partition. Partial walks, permission and auth failures do not use this
-fallback. Resources require unexpired inventories. There is no deferred refresh.
+fallback, and a refusal keeps later failures from using it until a listing succeeds.
+Resources require unexpired inventories.
+
+**Stale listings.** Discovery alone may list a tool catalog up to 24 hours past
+its expiry (`STALE_DISCOVERY_MS`), so chunks and manifests keep that storage TTL
+and a publish deletes the revision it supersedes. Each discovery first peeks the
+entry without a connection (`Connector.peekCatalog`, or the retained custom
+catalog once its listing has failed): storage reads only, through the listing's
+address, fingerprint, generation and credential fences (INV-5, INV-8, INV-10). A
+peek takes no probe slot, and a listing that follows it in the request takes what
+it read, so a resolver still runs once and the entry is read once. A current peek
+skips the probe queue. A stale one stands in for a probe that did not answer, on
+the failures [meta-tools](./meta-tools.md#lexical-discovery) lists, marked in host-only
+provenance (`markCatalogStale`). It stays out of the request's retained catalogs,
+so `resolve` and every call read the live one. A probe that exhausts its own
+deadline hands one refresh to `defer`: a listing in a new request scope, with its
+own signal and transport, closed in that scope and settling the health record it
+leased. Nothing of the original request reaches it (INV-7). One clock, started as
+it is scheduled, bounds its whole tail at 20 seconds, inside Workers' `waitUntil`:
+queueing and the claim spend it, the listing gets what remains less a second for
+settlement and two for cleanup, and a claim that spends it all dispatches nothing.
+Only the request whose settlement wrote the health record takes that refresh;
+settlement and the claim are compare-and-set against the record the request read,
+including creating an absent one, so concurrent failures start one refresh.
+
+A peek read before a wait is not served after it. Once a probe or a slot has kept
+the request waiting, the entry is read again through every fence, so an invalidation
+or a refusal in the meantime retires it, in this isolate or another.
+
+**Refusal fences.** `auth_required`, `downstream_oauth_required` or
+`provider_permission_denied` from a listing or its handshake writes one key
+(`fenceTools`) in the namespace of the catalog's current generation, addressed by
+the owner partition and credential identity, or by the auth partition alone on a
+shared connector, whose credential gets one answer whoever asks. A tool listing that
+sees it misses, fresh or stale, so `peekTools` and the five-minute fallback have
+nothing to serve; both also read it fresh before serving an expired entry. A listing
+that succeeds lifts by compare-and-set only the fence it first saw, so a refusal
+that lands while it runs stays. The key outlives every entry it guards
+(`CATALOG_FENCE_TTL_SECONDS`) and the generation's rotation discards it with them.
+It adds no round trip to a read: it travels in the catalog snapshot or the manifest
+read. Timeouts and retryable failures write nothing here, and neither does a
+caller-local refusal repeated within one request.
+
+The 24-hour limit stays because of these. Everything that can end a caller's access
+and that Connecta can observe (a refusal, a credential change, a disconnect, an
+invalidation) now retires the catalog at once. What remains is a revocation behind a
+connector that has not answered since: tool names and schemas that caller was
+already shown, marked stale, granting nothing, for at most a day. The first answer
+ends it.
+
 Host-only provenance carries each catalog's original fetch time, TTL and expiry,
 and whether it was a fallback, through classification and request-local copies.
 Zero TTL and stale fallbacks cannot authorize post-entry auth recovery.
@@ -808,8 +864,8 @@ Zero TTL and stale fallbacks cannot authorize post-entry auth recovery.
 A manifest is published by CAS only after every UTF-8 chunk is written. It
 records the original fetch time, absolute expiry, revision, fingerprint, and
 monotonic stamp. Readers verify all chunks and fingerprint before accepting it.
-Freshness expires at the bounded TTL; tool facts remain for the five-minute
-fallback window, and generations expire after 48 hours; invalidation
+Freshness expires at the bounded TTL; tool facts remain for the 24-hour stale
+listing limit, of which calls may use five minutes, and generations expire after 48 hours; invalidation
 rotates the generation, and old chunks expire without becoming reachable
 again. Remote clients pin that generation before listing, including SDK cache
 refreshes. Each new listing pins the current generation, so a live client can
@@ -1352,15 +1408,15 @@ guide (G) violations before writing. It derives `drift.json` version 2's
 `generated` block from kit operations and evidence digests, and the guide's
 `## Conventions` from definition declarations into `skill.generated.ts`.
 The generator requires `fixtures.ts` to export `createAuthored()` with a
-nonempty offline `staticTools` catalog. Its input/output schemas derive one
-paging convention, including `get_*`, hatch search and details, excluding
-tools whose `page.hasMore` is always false. The convention distinguishes
-top-level `cursor` from `query[page.param]` or `body[page.param]` continuation
-and tells agents to return `page.nextCursor` before the call that would exceed
-the per-program call limit, then continue in the next program. The Hatch line
-reports a nonzero explicit refusal count with singular/plural wording and
-points to the actual prefixed details tool with method/path lookup; it never
-embeds the refusal table. Unreviewed operations remain refused.
+nonempty offline `staticTools` catalog, which the installed inventory lists.
+Conventions render only provider-specific declarations: the vendor envelope
+root, the hatch's tools and refusal count, the `idempotencyKey` rule where a
+provider has one, and the Errors line. Paging, `fields`, withheld-value and
+write-once rules live at the agent's point of use, and
+`test/provider-conventions.test.ts` asserts each paged tool's continuation there.
+The Hatch line reports a nonzero explicit refusal count with singular/plural
+wording and points to the actual prefixed details tool with method/path lookup;
+it never embeds the refusal table. Unreviewed operations remain refused.
 `ProviderContext.usageGuide` selects a guide's `<!-- when: <key> -->` blocks
 with the definition's `blocks`. Maintained drift records use version 2;
 `providers:check` retains version-1 endpoint/manual record parsing for historical
@@ -1720,9 +1776,13 @@ a table.
 Remote MCP tools classify from server annotations and deployment policy.
 Only `readOnlyHint === true` with `destructiveHint !== true` establishes a
 source read; missing or contradictory hints mean write. Deployment overrides
-in `ConnectaConfig.classification` choose effective `read`, `write`, or `hidden`.
-They cannot relax source replay safety. Effective or source write makes a call
-write-like on every resend and recovery path. Source classifications travel in
+in `ConnectaConfig.classification` choose effective `read`, `write`, or `hidden`,
+except that `read` cannot change a tool the source explicitly declares a write:
+a host may resend a read-annotated call, so that tool stays a write unless the
+deployment accepts that with `read-repeatable`. They cannot
+relax source replay safety. Effective or source write makes a call
+write-like on every resend and recovery path. Source facts, including whether a
+source write was declared or only silent, travel in
 private metadata with host-owned tool clones and stay out of persisted catalogs.
 A leftover `classify` throws and names `ConnectaConfig.classification`.
 There are no hosted review maps, pins, drift comparisons or review UI fields.
@@ -2013,18 +2073,18 @@ storage is the root's namespaced to its principal.
 
 ### 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, when its admitted-request lifetime ends in that request, or at once if the handler fails first. If workerd runs none of those callbacks, the next request reclaims only the expired admission record; it cannot close another request's Scope. 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. Public executor methods stay Promise-shaped; registered built-in execution composes directly as an Effect under the signal and `execute.watchdogMs`. Queued acquisition retains its Promise request handoff. Each guest host call is a fiber of its own.                                                                                                                                                                     |
-| Discovery (`catalog-service.ts`)                                       | A request-scoped cache: one shared read per connector (`runtime/shared-read.ts`), settled by the read itself and carrying its own signal and the probe timeout whichever asker starts it. Each asker waits under its own deadline and signal, so one that times out or is cancelled fails alone, and the read is cancelled only once every asker has gone. Fan-out is `Effect.forEach` under the discovery concurrency; unscoped search adds the discovery budget and health record (`discovery-health.ts`).                                                                                               |
-| Registry (`registry.ts`)                                               | The result stash is a program over `Storage`. Same-request catalog loads share one read the way discovery's do. Remote MCP caching uses the SDK ResponseCacheStore adapter over SQL-backed KV, with no cross-request catalog flight.                                                                                                                                                                                                                                                                                                                                                                       |
-| Remote MCP (`connectors/remote-mcp.ts`, `connectors/remote-mcp/`)      | 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*`, `auth/static-oauth.ts`)    | A refresh flight is a Deferred. Before the first durable coordinator write (claim CAS) is submitted, call/request closure stops preparation without a CAS, token request or state change. Submission transfers renewal to the storage coordinator under its own 35-second preparation deadline and 20-second token-request/body deadline, followed by the fenced rotation commit through the runtime deferred-work hook. A closed caller promptly fails without consuming the result, marking its ledger renewed or sending/resending a resource request.                                                  |
-| 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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| 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, when its admitted-request lifetime ends in that request, or at once if the handler fails first. If workerd runs none of those callbacks, the next request reclaims only the expired admission record; it cannot close another request's Scope. 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. Public executor methods stay Promise-shaped; registered built-in execution composes directly as an Effect under the signal and `execute.watchdogMs`. Queued acquisition retains its Promise request handoff. Each guest host call is a fiber of its own.                                                                                                                                                                                                            |
+| Discovery (`catalog-service.ts`)                                       | A request-scoped cache: one shared read per connector (`runtime/shared-read.ts`), settled by the read itself and carrying its own signal and the probe timeout whichever asker starts it. Each asker waits under its own deadline and signal, so one that times out or is cancelled fails alone, and the read is cancelled only once every asker has gone. Fan-out is `Effect.forEach` under the discovery concurrency, which an unscoped search or native listing applies only to connectors it must ask; those add a cached-catalog peek and stale listing, and unscoped search the discovery budget and health record (`discovery-health.ts`). |
+| Registry (`registry.ts`)                                               | The result stash is a program over `Storage`. Same-request catalog loads share one read the way discovery's do. Remote MCP caching uses the SDK ResponseCacheStore adapter over SQL-backed KV, with no cross-request catalog flight.                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Remote MCP (`connectors/remote-mcp.ts`, `connectors/remote-mcp/`)      | 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*`, `auth/static-oauth.ts`)    | A refresh flight is a Deferred. Before the first durable coordinator write (claim CAS) is submitted, call/request closure stops preparation without a CAS, token request or state change. Submission transfers renewal to the storage coordinator under its own 35-second preparation deadline and 20-second token-request/body deadline, followed by the fenced rotation commit through the runtime deferred-work hook. A closed caller promptly fails without consuming the result, marking its ledger renewed or sending/resending a resource request.                                                                                         |
+| 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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
 ### Native registry and request services (contributor)
 
@@ -2344,8 +2404,11 @@ late publication from an invalidated request unreachable. Missing chunks,
 expired entries, storage errors, or a failed page trigger a fresh complete
 listing. A transient first-page tool-listing failure may use a complete catalog
 within five minutes of expiry in the same auth partition. Partial walks and
-auth or permission failures refuse fallback; resources require unexpired
-inventories, and stale fallback cannot authorize post-entry auth recovery.
+auth or permission failures refuse fallback, and a refusal fences later fallback
+until a listing succeeds; resources require unexpired inventories, and stale
+fallback cannot authorize post-entry auth recovery.
+Discovery's [stale listing](#storage-credentials-and-connectors) reads the same
+entries and answers no call.
 
 **Repeated reads share one request's memo.** `src/runtime/request-reads.ts`
 gives each request owner a memo of storage reads, emptied when the request
@@ -2604,11 +2667,9 @@ this declaration keep parameter-based continuation.
 An explicit initialAnchor adapter on parameter-based paging can retain a numeric
 timestamp as a first-page time-window anchor; opaque string continuations still
 require a signed token.
-The generated Paging convention follows the read tool's input schema: tools
-that take `cursor` restore `page.nextCursor` as that top-level argument; tools
-without it restore the token in `query[page.param]` or `body[page.param]`, as
-`page.in` specifies. `kit.hatch.paging` still validates declared mode values as
-a sanity check; it does not select the generated continuation instruction.
+A read tool's input schema states how to continue: tools that take `cursor`
+restore `page.nextCursor` as that top-level argument; tools without it restore
+the token in `query[page.param]` or `body[page.param]`, as `page.in` specifies.
 An unsafe continuation keeps the safe page data with `hasMore: true` and no
 `nextCursor`.
 A reviewed `HatchBinding` can supply vendor encoding/origin routing through
@@ -2657,7 +2718,8 @@ contracts, `Summary` annotations and lenient success schemas become the
 index's parameters, bodies, summaries and declared fields (optional
 `OpenApiData.fields`). Kit facts carry the vendor's declared
 `VendorErrors.meanings` and an `idempotencyKey` checked against the write
-builders at construction, which the generated Conventions state.
+builders at construction; the generated Conventions state the key rule only where
+a provider has one, and the Errors line always.
 
 Hatch request paths and query keys/values refuse any containment of the shared
 `[redacted]` marker, including decoded spellings. Body fields and kit write
@@ -2668,8 +2730,7 @@ Admission iteratively visits keys and values before the write program runs;
 it checks agent arguments, not whole bodies later composed from internal
 reads. The kit connection also checks actual typed path parameters and query
 values before transport. Legacy non-kit tools retain their link-only admission;
-arbitrary binary/base64 bytes are not decoded by this scalar rule. The kit
-sets `refusesWithheld` for the standard hatch, enabling the generated convention.
+arbitrary binary/base64 bytes are not decoded by this scalar rule.
 Declared error-code facts use the closed `ConnectorCallErrorCode` set at
 construction (INV-11); classification callbacks are not run at construction.
 
@@ -3370,7 +3431,7 @@ compiling and configuring the real thing.
   is not a declared refusal standing for the whole call makes the call
   unknown, never retryable, with no wait and no resend or key-reuse advice;
   while any such 401 is unrenewed the verdict keeps an authorization code,
-  so invocation keeps the `authorize_connector` handoff and picks its
+  so invocation keeps the authorization handoff and picks its
   reconcile-first words. Its code and words are the failure's when that is an
   authorization verdict, else the 401's own recorded verdict, else
   `auth_required`, with a sentence saying the write was sent before the
@@ -3926,7 +3987,8 @@ physical-attempt and body/admission suites remain compatibility evidence.
 
 The standard hatch privately registers bounded vendor operation text against its
 ApiTool identity; `apiConnector` transfers those facts to the constructed
-connector. `operation-vocabulary.ts` contains only pure lexical/cache logic and
+connector, and a provider that wraps that connector carries them to its outer
+object with `carryConnectorVocabulary`. `operation-vocabulary.ts` contains only pure lexical/cache logic and
 types. Catalog discovery consumes those facts after loading and classifying a
 complete visible catalog. It never imports a provider or an operation index,
 parses operation contracts, invokes a handler, or authenticates. Matching requires

package/documentation/auth.md

@@ -980,8 +980,8 @@ admitted.
 | Scope        | `/mcp/<pool>` and `/agent/<pool>` serve exactly the pool's `tools` (connector ids or exact `connector.tool` addresses), with the pool's `readOnly`, to its member people and member agents respectively. Plain `/mcp` serves the whole catalog to maintainers and the unique member pool to other people. Neither intersects with or widens anything.                                                                                                                                                |
 | Refusal      | A person with zero or several memberships at `/mcp`, a non-member, and an undeclared pool get an identical 404 status, body, and headers, after auth. The operator log records `not_maintainer` (zero memberships), `ambiguous_pool` (several memberships), `not_pool_member`, or `pool_not_declared`. Names are not anonymously enumerable; valid credentials cannot distinguish these cases by content.                                                                                            |
 | Agents       | An agent member reaches its pools only at `/agent/<pool>`, with its `cta_` token. Human endpoints refuse `cta_`; see [agent endpoints](#agent-endpoints).                                                                                                                                                                                                                                                                                                                                            |
-| Surface      | From 0.35.0, optional `surface`: `"meta"` (default) serves the six meta-tools; `"native"` lists each of the pool's downstream tools directly, for clients with their own tool search, with optional `executeCode: false` to replace `execute_code` with `read_result` (invalid on meta pools). Calls take the same paths either way. See the [native tool surface](./meta-tools.md#native-tool-surface).                                                                                             |
-| Description  | Optional `description`: plain text telling the model what this endpoint is for. `/mcp/<pool>` and `/agent/<pool>` prefix the MCP instructions with `Use skills. ` and the description before routing rules; a maintainer at plain `/mcp` and a pool without one serve the shared instructions unchanged. A routed person receives their pool description. It grants, hides, and refuses nothing, and changes no tool or tool description.                                                            |
+| Surface      | From 0.35.0, optional `surface`: `"meta"` (default) serves the meta-tools; `"native"` lists each of the pool's downstream tools directly, for clients with their own tool search, with optional `executeCode: false` to replace `execute_code` with `read_result` (invalid on meta pools). Calls take the same paths either way. See the [native tool surface](./meta-tools.md#native-tool-surface).                                                                                                 |
+| Description  | Optional `description`: plain text telling the model what this endpoint is for. `/mcp/<pool>` and `/agent/<pool>` place the description before the rest of the MCP instructions; a maintainer at plain `/mcp` and a pool without one serve none. A routed person receives their pool description. It grants, hides, and refuses nothing, and changes no tool or tool description.                                                                                                                    |
 | Construction | Malformed names, unknown options or connectors, empty pools, empty or missing `members`, mixed people and agent membership (a `ConfigError` naming the pool), unresolvable member references, a non-boolean `readOnly`, an `owner` that is not a Workspace email address, a `description` that is not 1 to 500 UTF-16 code units of one-line text after trimming, a retired `trust` or `grant`, and addresses absent from an `api()` static catalog throw. Remote catalogs are checked at lazy load. |
 | Discovery    | Clerk's pool 401 names `/.well-known/oauth-protected-resource/mcp/<pool>` with the pool URL as `resource`, matching RFC 9728. Cloudflare Managed OAuth is application-level and needs no pool setup.                                                                                                                                                                                                                                                                                                 |
 | Drift        | No wildcards; pool tools are exact names. Missing live tools are unreachable and warned once while in a bounded 1,024-entry FIFO.                                                                                                                                                                                                                                                                                                                                                                    |
@@ -1442,7 +1442,7 @@ longer live; one left behind cannot complete and expires with its link.
 `authorize_connector` issues the same browser link, with `force` carried in the
 signed handoff. On hosts without URL elicitation, direct and program auth
 failures and search/describe catalog failures include the same authorization
-handoff. The admitted registry and management permission govern issuance.
+handoff. A declined or cancelled URL elicitation returns it too. The admitted registry and management permission govern issuance.
 Each call or program run shares at most one handoff per connector; errors never
 request a forced restart. Signed links retain their fifteen-minute expiry,
 initiating-user and owner binding, origin check, and single-use browser nonce.
@@ -1681,7 +1681,7 @@ If the refresh fails instead, whatever it met (a dead grant, a waiter
 deadline, the caller leaving), or hands back the token the API just
 rejected, the 401's verdict stays:
 `downstream_oauth_required`, never retryable, with `reconciliationRequired`
-and `writeOutcome: "unknown"`, and an `authorize_connector` handoff that says
+and `writeOutcome: "unknown"`, and a handoff that says
 to re-read the target before any fresh call. A read is refreshed and sent
 once more. MCP sends a tool only once when either its effective classification
 or its original server hints say write. A deployment write-to-read override
@@ -2012,9 +2012,14 @@ any registered form is still withheld, however short.
 Identifiers sent beside a credential are matched whole only, because consent
 URLs and vendor metadata carry their parts by design: a confidential OAuth
 client's ID, a Basic username beside a password of at least eight characters,
-and credential-slot fields named as identifiers (ending in `id`, `user`,
-`username`, `login`, or `email`, or starting with `public`). A Basic username
-beside a shorter or empty password is the credential itself and is fully
+credential-slot fields named as identifiers (ending in `id`, `user`,
+`username`, `login`, or `email`, or starting with `public`), and the two headers
+maintained providers declare public from their vendors' contracts: Cloudflare's
+Global API Key `X-Auth-Email` and Overflow's `x-client-id`. A value in either
+that holds whitespace, as an auth scheme's framing does, is a credential. Any
+other header or query parameter is never public by name: `remoteMcp()` and
+`api()` auth headers under any name are credentials, fully matched. A Basic
+username beside a shorter or empty password is the credential itself and is fully
 matched. Query parameters named as continuation cursors (`pageToken`,
 `nextPageToken`, `next_token`, `continuationToken`, `syncToken`) are public
 result state and are not registered. Header values a connector adds to token
@@ -2610,6 +2615,30 @@ survives every round. Rotation invalidates outstanding states.
 Each state admits one retry through a connector-scoped storage CAS, including
 decline and cancel. Concurrent or repeated consumption is refused before
 dispatch, so retries cannot fork into sibling forced connection links.
+A decline or cancel returns one fresh link, issued only after that state verifies
+and the same management check as the prompt passes, so a refusal offers nothing
+this caller could not already request. The link is sealed like the prompt's and
+keeps the prompt's force.
+
+URL `accept` is consent to the interaction, not evidence that a browser navigated:
+the retry normally reaches Connecta before any visit does. So every link a flow
+issues stays live until it is visited or expires, whichever round or refusal
+issued it. A `force: true` flow resets once, through one atomic claim on an identity
+its links share:
+
+| A verified visit finds the reset | The visit                                                                       |
+| -------------------------------- | ------------------------------------------------------------------------------- |
+| Unclaimed                        | Claims it and runs `startAuth({ force: true })`                                 |
+| Still running in another visit   | Returns 409 and spends nothing, so reloading the same link retries              |
+| Started                          | Spends its link and runs `startAuth({ force: false })`, continuing that consent |
+| Failed                           | Claims it again and starts afresh, so a failure never reuses the old grant      |
+
+A failed link is spent, but the flow is not: its other links, or the next prompt's,
+take over. The record outlives every link the flow can issue. If the process holding
+the claim dies, nothing settles it, so the flow's links keep returning 409 for up to
+thirty minutes, and that response says to start a new connection request. A new
+`force: true` call is a new flow with its own reset, so it recovers at once. Each link still works
+once. An unforced flow's links stay independent and never reset.
 The host records each entered call's classification, catalog freshness and
 classification digest in private invocation state, along with auth failure origins. Writes may elicit only
 when Connecta's own credential resolution fails before invoking the connector:
@@ -2644,14 +2673,11 @@ reads this key; connector contexts and guest APIs cannot reach the vault.
 Explicit authorization retries require a completed browser start (including
 its reset and consent binding), valid stored credential fields where declared,
 and a healthy passive connector status where available before completing.
-An in-progress start cannot complete against an old grant. A forced flow switches to
-Continue after that visit, so another prompt cannot restart pending consent.
-Failed starts remain single-use but do not block a later successful attempt.
-Before checking completion, unspent links in the retry flow are atomically
-retired so an older forced link cannot begin a reset during the status check.
-A Continue link issued during a pending forced start is bound to that
-predecessor and cannot be consumed unless the predecessor starts successfully.
-If it fails, the next prompt requests a fresh restart instead of reusing the old grant.
+An in-progress start cannot complete against an old grant: only a link whose start
+finished counts toward completion, and the next prompt carries the same flow, so it
+cannot restart pending consent. Failed starts remain single-use but do not block a later
+successful attempt. A link visited during the completion check continues the
+attempt that check is judging, and cannot reset it.
 
 The `/connect` link issued by the elicitation boundary encrypts its browser
 handoff with the vault's `seal`/`open` methods before signing it. The URL carries
@@ -2720,12 +2746,13 @@ still serve configured credentials. Both routes accept only GET, otherwise retur
 `form_post` is unsupported. Clerk's session-only policy applies regardless of method.
 
 The fifteen-minute signed handoff carries connector ownership, initiating principal, deployment origin, nonce,
-restart mode, and any predecessor link binding. New links use versioned, length-prefixed fields instead of
+restart mode, and, for a forced flow's later links, the flow they share a reset with. New links use versioned, length-prefixed fields instead of
 JSON, with unpadded base64url payload and signature segments. Ordinary handoffs use an opaque wire encoding,
 not encryption; URL elicitation also seals those fields as described above. Copy the complete URL unchanged.
 The signature authenticates the exact version and payload text. Tampered or re-encoded links return
 `Invalid or expired connection link. Request a new link from connecta.` Pre-upgrade signed JSON and sealed
-v2 links still verify against their original text and expire after their original fifteen minutes.
+v2 links still verify against their original text and expire after their original fifteen minutes. A link from
+an earlier version that names a predecessor link, in any format, returns the same refusal, and a new link replaces it.
 
 Configure `vault: encryptedCredentialVault(storage, key)`, which derives its HMAC key with HKDF. Custom vaults need `signOAuthHandoff` and `verifyOAuthHandoff`; without a signing vault, links cannot be
 issued or accepted. A link grants no identity. After identity and permissions pass, its nonce is consumed
@@ -2962,12 +2989,12 @@ owner's access token as `Authorization: Bearer` with these rules:
 - Whatever that recovery meets, a write's failure is never retryable and its
   outcome is unknown. Until a refresh succeeds the 401's verdict stands:
   `downstream_oauth_required`, which the invocation marks
-  `reconciliationRequired`, with the `authorize_connector` handoff, whether
+  `reconciliationRequired`, with the authorization handoff, whether
   the refresh was [dead](#refresh-failures), lost after it was sent, raced
   by a disconnect or reset, failed in storage or contention, or handed back
   the token the API just rejected, which renews nothing.
 - No grant, a second 401, or a [dead refresh](#refresh-failures) means
-  `downstream_oauth_required`, directing `authorize_connector`. Refresh waiter deadlines
+  `downstream_oauth_required`, carrying the authorization handoff. Refresh waiter deadlines
   return retryable `unavailable` for a read. Latch second 401s for the request scope,
   preventing repeated refreshes by later program calls.
 - Handlers can name no storage, sealing, or owner partition; the registry owns them.