@zackbart/connecta 0.15.1 → 0.16.1

package/dist/ui.js

@@ -369,6 +369,11 @@ export async function buildUiData(registry, baseUrl, serverInfo, credentialVault
                 : {}),
             toolCount: tools.length,
             tools,
+            // Counts only, and only when a refresh in this runtime produced them.
+            // `Registry.statusFor` already rebuilt the report through
+            // `boundedCatalogDrift`, so what lands here cannot carry a name or a
+            // schema even if the plugin seam returned one.
+            ...(status.catalogDrift ? { catalogDrift: status.catalogDrift } : {}),
             ...(c.disconnectAuth && c.startAuth ? { oauth: true } : {}),
             ...(credential ? { credential } : {}),
         };
@@ -477,147 +482,18 @@ ${clerkScript}
   ${owner}
   <div class="mast-nav">
     ${product}
-    <div id="appNav" class="mast-actions hidden">
-      <nav class="page-nav" aria-label="Operator pages">
-        <a id="connectionsNav" class="navlink" href="/"
-          data-operator-page="connections"${page === "connections" ? ' aria-current="page"' : ""}>Connections</a>
-        <a id="credentialsNav" class="navlink hidden" href="/credentials"
-          data-operator-page="credentials"${page === "credentials" ? ' aria-current="page"' : ""}>Credentials</a>
-        <a id="tokensNav" class="navlink hidden" href="/tokens"
-          data-operator-page="tokens"${page === "tokens" ? ' aria-current="page"' : ""}>Access tokens</a>
-        <a id="activityNav" class="navlink hidden" href="/activity"
-          data-operator-page="activity"${page === "activity" ? ' aria-current="page"' : ""}>Activity</a>
-      </nav>
-      <div class="session-actions" aria-label="Session actions">
-        <button id="change" class="navlink hidden" type="button">Change token</button>
-        <button id="signout" class="navlink hidden" type="button">Sign out</button>
-      </div>
-    </div>
+    <div id="operatorNav"></div>
   </div>
 </header>
 
 <main id="operatorContent" class="page shell" tabindex="-1">
-  <section id="gate" class="hidden">
-    <div class="lead pgrid">
-      <h1 id="gateHeading" class="pcap" tabindex="-1">${OPERATOR_PAGE_LABELS[page]}</h1>
-      <div class="pbody lead-copy">
-        <p>${escapeHtmlAttr(brand.description)}</p>
-        <p id="gateCopy" class="meta"></p>
-        <div id="tokenGate" class="row gate-actions hidden">
-          <input id="token" type="password" placeholder="Bearer token" autocomplete="off"
-            aria-label="Bearer token">
-          <button id="save" class="linklike" type="button">Open operator pages</button>
-        </div>
-        <div id="clerkGate" class="actions gate-actions hidden">
-          <button id="signin" class="linklike" type="button">Team sign in</button>
-          <button id="gateSignout" class="linklike hidden" type="button">Sign out</button>
-        </div>
-        <p id="err" role="alert"></p>
-      </div>
-    </div>
-  </section>
-
-  <div id="app" class="hidden">
-  <section id="connectionsView"${page === "connections" ? "" : ' class="hidden"'}>
-    <div class="lead pgrid">
-      <h1 id="connectionsHeading" class="pcap" tabindex="-1">Connections</h1>
-      <div class="pbody lead-copy">
-        <p>Use this endpoint to give an MCP client access to the tools below.</p>
-        <div class="endpoint">
-          <div class="endpoint-row">
-            <code id="mcpUrl" class="mono"></code>
-            <button id="copyMcpUrl" class="linklike" type="button">Copy URL</button>
-          </div>
-        </div>
-        <p class="cap" id="serverInfo">${escapeHtmlAttr(brand.productName)} operator</p>
-        <p id="oauthNotice" class="meta" role="status" aria-live="polite" tabindex="-1"></p>
-      </div>
-    </div>
-    <section class="section pgrid" aria-labelledby="connectorLedgerHeading">
-      <h2 class="pcap" id="connectorLedgerHeading">Connectors</h2>
-      <div class="pbody">
-        <div class="row toolbar">
-          <input id="filter" type="search" placeholder="Filter connectors or tools…"
-            aria-label="Filter connectors or tools">
-        </div>
-        <div id="list" class="connector-tools" aria-busy="false"></div>
-      </div>
-    </section>
-  </section>
-
-  <section id="credentialsView"${page === "credentials" ? "" : ' class="hidden"'}>
-    <div class="lead pgrid">
-      <h1 id="credentialsHeading" class="pcap" tabindex="-1">Credentials</h1>
-      <div class="pbody">
-        <p class="activity-copy">Rotate operator-managed connector credentials. Stored values are never returned or displayed.</p>
-        <p id="credentialNotice" class="meta" role="status" aria-live="polite"
-          tabindex="-1"></p>
-        <div id="credentialUnavailable" class="unavailable hidden"></div>
-        <div id="credentialList" class="credential-ledger" aria-busy="false"></div>
-      </div>
-    </div>
-  </section>
-
-  <section id="tokensView"${page === "tokens" ? "" : ' class="hidden"'}>
-    <div class="lead pgrid">
-      <h1 id="tokensHeading" class="pcap" tabindex="-1">Access tokens</h1>
-      <div class="pbody">
-        <p class="activity-copy">Create named Bearer tokens for MCP clients. Each secret is shown once; revoke it when that client should lose access.</p>
-        <p id="tokenNotice" class="meta" role="status" aria-live="polite"
-          tabindex="-1"></p>
-        <div id="tokenUnavailable" class="unavailable hidden"></div>
-        <div id="tokenAvailable" class="hidden">
-          <form id="tokenCreateForm" class="token-create">
-            <label for="tokenName">Client name</label>
-            <div class="row">
-              <input id="tokenName" type="text" maxlength="80"
-                placeholder="Claude desktop, ChatGPT production…"
-                autocomplete="off">
-              <button id="createToken" class="linklike" type="submit">Create token</button>
-            </div>
-          </form>
-          <section id="tokenReveal" class="token-reveal hidden"
-            aria-labelledby="tokenRevealHeading">
-            <div class="token-reveal-head">
-              <h2 id="tokenRevealHeading" tabindex="-1">Copy this token now</h2>
-              <span class="cap">Shown once</span>
-            </div>
-            <p class="meta">Store it in the MCP client before leaving this page. It cannot be displayed again.</p>
-            <div class="endpoint-row token-secret">
-              <code id="createdToken" class="mono"></code>
-              <button id="copyCreatedToken" class="linklike" type="button">Copy token</button>
-            </div>
-            <button id="dismissCreatedToken" class="linklike" type="button">I stored it</button>
-          </section>
-          <div id="tokenList" class="token-ledger" aria-busy="false"></div>
-        </div>
-      </div>
-    </div>
-  </section>
-
-  <section id="activityView"${page === "activity" ? "" : ' class="hidden"'}>
-    <div class="lead pgrid">
-      <h1 id="activityHeading" class="pcap" tabindex="-1">Activity</h1>
-      <div class="pbody">
-        <p class="activity-copy" id="activitySummary">Arguments and results are never stored.</p>
-        <div id="activityUnavailable" class="unavailable hidden">
-          Activity history is not configured. Add an <span class="mono">activity.store</span>
-          with a list reader to enable this page.
-        </div>
-        <div id="activityAvailable">
-          <div class="row activity-controls">
-            <input id="activitySearch" type="search"
-              placeholder="Search user, tool, or outcome…"
-              aria-label="Search loaded activity">
-            <button id="refreshActivity" class="linklike" type="button">Refresh</button>
-          </div>
-          <p id="activityNotice" class="meta" role="status" aria-live="polite"></p>
-          <div id="activityList" class="activity-ledger" aria-busy="false"></div>
-          <button id="moreActivity" class="linklike activity-more hidden" type="button">Load older</button>
-        </div>
-      </div>
+  <div class="lead pgrid">
+    <h1 class="pcap">${OPERATOR_PAGE_LABELS[page]}</h1>
+    <div class="pbody lead-copy">
+      <p>${escapeHtmlAttr(brand.description)}</p>
+      <noscript><p class="msg">The operator pages need JavaScript. Nothing else here
+      does — agents reach this deployment through <span class="mono">/mcp</span>.</p></noscript>
     </div>
-  </section>
   </div>
 </main>
 
@@ -627,9 +503,9 @@ const MCP_URL = ${jsonForInlineScript(mcpUrl)};
 const INITIAL_PAGE = ${jsonForInlineScript(page)};
 const TITLE_SUFFIX = ${jsonForInlineScript(brand.pageTitle)};
 const PRODUCT_NAME = ${stringForInlineScript(brand.productName)};
+const PRODUCT_DESCRIPTION = ${stringForInlineScript(brand.description)};
 const PRODUCT_OPERATOR_LABEL = ${stringForInlineScript(brand.productName + " operator")};
 ${OPERATOR_UI_SCRIPT}</script>
 </body>
 </html>`;
 }
-//# sourceMappingURL=ui.js.map

package/dist/validate.d.ts

@@ -21,17 +21,12 @@ export interface ValidateToolInputOptions {
      */
     failClosed?: boolean;
 }
-export interface PrecompileValidatorOptions {
+export interface CompileValidatorOptions {
     /**
-     * Tool address used in the warning text, conventionally
+     * Tool address used in the error text, conventionally
      * `"connectorId.toolName"`.
      */
     address: string;
-    /**
-     * Destination for the warning emitted when the schema cannot be compiled.
-     * Default console.
-     */
-    logger?: Logger;
 }
 /**
  * Validate call arguments against a tool's JSON Schema.
@@ -60,12 +55,15 @@ export interface PrecompileValidatorOptions {
  */
 export declare function validateToolInput(schema: JsonSchema, args: unknown, opts: ValidateToolInputOptions): ConnectorCallError | null;
 /**
- * Eagerly compile and cache a tool's inputSchema so a schema the validator
- * cannot use surfaces once at connector construction rather than silently on
- * the first call. Reuses the same module-level cache `validateToolInput` reads,
- * so the runtime path hits the cache. Warning-only: it never throws and never
- * changes call behavior. A schema that only fails on first `validate()` (e.g.
- * an unresolvable `$ref`) still slips through here and is caught at call time.
+ * Eagerly compile and cache a tool's inputSchema, throwing when the validator
+ * cannot use it. Reuses the same module-level cache `validateToolInput` reads,
+ * so the runtime path hits the cache.
+ *
+ * This is the construction-time half of the contract hand-written tools sign:
+ * a schema connecta cannot enforce is the author's bug, and a deployment that
+ * boots with one is a deployment quietly promising validation it will not do.
+ * A schema that only fails on first `validate()` (an unresolvable `$ref`, say)
+ * still slips through here — the validator resolves those lazily — and is
+ * caught at call time by the caller's `failClosed`.
  */
-export declare function precompileValidator(schema: JsonSchema, opts: PrecompileValidatorOptions): void;
-//# sourceMappingURL=validate.d.ts.map
+export declare function compileValidator(schema: JsonSchema, opts: CompileValidatorOptions): void;

package/dist/validate.js

@@ -186,6 +186,11 @@ function validationDetails(schema, units) {
 function unevaluableSchema(address) {
     return new ConnectorCallError("invalid_args", `Cannot validate arguments for "${address}": its inputSchema could not be evaluated`);
 }
+function unusableSchema(address, detail) {
+    return new Error(`Tool "${address}" has an inputSchema the validator cannot use ` +
+        `(${detail}) — fix the schema or drop it; a schema that cannot be ` +
+        "enforced must not ship as one that can.");
+}
 function disableValidation(schema, address, logger, err) {
     validators.set(schema, null);
     logger.warn(`[connecta] tool "${address}" has an inputSchema the validator cannot use (${err instanceof Error ? err.message : String(err)}) — arguments are not validated`);
@@ -254,22 +259,30 @@ export function validateToolInput(schema, args, opts) {
     return null;
 }
 /**
- * Eagerly compile and cache a tool's inputSchema so a schema the validator
- * cannot use surfaces once at connector construction rather than silently on
- * the first call. Reuses the same module-level cache `validateToolInput` reads,
- * so the runtime path hits the cache. Warning-only: it never throws and never
- * changes call behavior. A schema that only fails on first `validate()` (e.g.
- * an unresolvable `$ref`) still slips through here and is caught at call time.
+ * Eagerly compile and cache a tool's inputSchema, throwing when the validator
+ * cannot use it. Reuses the same module-level cache `validateToolInput` reads,
+ * so the runtime path hits the cache.
+ *
+ * This is the construction-time half of the contract hand-written tools sign:
+ * a schema connecta cannot enforce is the author's bug, and a deployment that
+ * boots with one is a deployment quietly promising validation it will not do.
+ * A schema that only fails on first `validate()` (an unresolvable `$ref`, say)
+ * still slips through here — the validator resolves those lazily — and is
+ * caught at call time by the caller's `failClosed`.
  */
-export function precompileValidator(schema, opts) {
-    if (validators.has(schema))
+export function compileValidator(schema, opts) {
+    const cached = validators.get(schema);
+    if (cached)
         return;
-    const logger = opts.logger ?? console;
+    // null marks a schema an earlier call already found unusable; recompiling it
+    // into a working validator would be the fail-open behavior wearing a hat.
+    if (cached === null) {
+        throw unusableSchema(opts.address, "an earlier call could not evaluate it");
+    }
     try {
         validators.set(schema, new Validator(schema, "2020-12", false));
     }
     catch (err) {
-        disableValidation(schema, opts.address, logger, err);
+        throw unusableSchema(opts.address, err instanceof Error ? err.message : String(err));
     }
 }
-//# sourceMappingURL=validate.js.map

package/dist/version.d.ts

@@ -4,5 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.15.1";
-//# sourceMappingURL=version.d.ts.map
+export declare const CONNECTA_VERSION = "0.16.1";

package/dist/version.js

@@ -4,5 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.15.1";
-//# sourceMappingURL=version.js.map
+export const CONNECTA_VERSION = "0.16.1";

package/documentation/architecture.md

@@ -1,7 +1,188 @@
 # Architecture
 
-> **Stub.** The old manual was retired in the phase-1 docs restructure. This
-> document will be rewritten as an agent-facing guide — what the subsystem is
-> for, how to work on it, and what it must never do — once the ideas in
-> [ethos.md](../ethos.md) settle. The prior text lives in git history as
-> `docs/architecture.md`.
+One Web-standard `fetch(request) => Promise<Response>` handler, a long-lived
+registry behind it, and a strict rule about what may be imported. Everything
+else in this repository is a detail of those three things.
+
+Read [`ethos.md`](../ethos.md) first. This guide says how the shape it
+describes is actually assembled, and where a change is likely to break it.
+
+## The two lifetimes
+
+Almost every bug in this codebase is a lifetime mistake, so the split is worth
+stating before anything else.
+
+**Per isolate, built once.** `createConnecta(config)` returns
+`{ fetch, registry, close }`. The `Registry` owns the connector set, address
+resolution, catalog caches, connector health, and the per-connector call
+limiters. It is constructed once and lives as long as the isolate or process —
+on Workers that means a lazy module-scope singleton, which is why both
+deployment shapes build it outside the request handler.
+
+**Per request, and no longer.** The MCP server, its transport, downstream MCP
+clients, abort signals, and the connector scope a probe opens all belong to the
+request that created them. `Nothing request-bound survives a request` is an
+ethos invariant, not a style preference: a client retained across requests on
+Workers is a cross-request capability leak, and a promise awaited after the
+response is work the runtime may have already torn down. Deferred work has one
+sanctioned channel — `ctx.waitUntil`, threaded through `fetch(request, env,
+ctx)` and used for best-effort activity writes.
+
+The registry is deliberately on the long side of that line and the MCP server
+deliberately on the short side. A fresh `McpServer` per request is what makes
+the deployment stateless: no sessions, no server push, no resumability, and
+scope resolved from the request rather than remembered.
+
+## Request lifecycle
+
+`src/server.ts` is the composition root. It does three things in order: upgrade
+the scheme when it must, run the route table, then wrap whatever came back in
+security headers. Route *order* is the contract — several routes would behave
+differently if they were reachable in another order — so the table below is
+read top to bottom.
+
+| Order | Route | Notes |
+| --- | --- | --- |
+| 0 | HTTPS upgrade | 308 to `publicUrl` when it is HTTPS and the request arrived over HTTP. Path and query are *assigned* onto the configured URL, never resolved against it, so a `//host` pathname cannot replace the deployment origin. `/health` is exempt: a loopback container probe must not depend on public DNS and TLS. `/ui` is canonicalized to `/` while upgrading. |
+| 1 | `/ui/access-tokens[/<id>]`, `/ui/credentials/<id>[/<action>]`, `/ui/oauth/<id>` | Private mutation routes, matched **first** so nothing can shadow them and so they own their own `OPTIONS` — they answer it with a refusal rather than inheriting the wildcard CORS preflight. |
+| 2 | `OPTIONS` | Each auth provider's `handleMetadata` gets a chance (CORS preflight for browser MCP clients); otherwise 204 with MCP CORS. |
+| 3 | `/.well-known/*` | Auth providers' `handleMetadata`, open. 404 when none handles it. |
+| 4 | `/health` | Open JSON: status, connector count, `serverInfo`, the configured executor's sanitized name when it has one, catalog-drift counts, admission snapshots, reserved route names, and `deployment` when `deploymentInfo` is set. Payload-free by construction, and it never joins the MCP queue. |
+| 5 | `/oauth/callback/<connectorId>` | Downstream-OAuth completion, open, `verifyState` before `finishAuth`. |
+| 6 | `/favicon.*`, `/ui` → `/`, the operator shells, `/ui/data` | The operator surface ([operator UI](./operator-ui.md)). The shells are open and data-free; `/ui/data` behind them is gated. Built-ins are matched before connector routes, so a connector cannot shadow a page. |
+| 7 | `/ui/activity` | Gated, plus the optional `activity.readGate`. `GET` only; 404 with no `activity.store.list`. |
+| 8 | `/mcp` | **Admission before auth**, then the auth gate, then a fresh MCP server. |
+| 9 | connector `handleRequest` | Registration order, open. Dispatched only after every built-in misses, so a connector can *add* a route and never shadow one of connecta's. First non-null response wins; a throw is a 500, not a fall-through. |
+| 10 | — | 404. |
+
+Every response leaves through `withSecurityHeaders`: `nosniff`, a no-referrer
+policy, HSTS on HTTPS, and — on the operator shells — a nonce-based script CSP
+and framing denial. `test/server-route-contracts.test.ts` pins this ordering
+and the exact refusal bodies; it exists because the ordering is invisible in
+any one file and a reordering reads like a harmless refactor.
+
+`/mcp` itself is four steps, in this order and for these reasons:
+
+1. **Admit.** One permit from the deployment-wide FIFO pool, taken before auth
+   so an unauthenticated flood costs a permit rather than a Clerk lookup
+   ([request admission](./request-admission.md)). The permit is held until the
+   response *body* completes, not until the handler returns.
+2. **Authorize.** Each `InboundAuth` provider's `authorize` in order, bearer
+   before Clerk. First `ok` admits; if all fail, the last provider's challenge
+   response is returned. No providers configured means open — development
+   only, and it warns at construction.
+3. **Refuse `?toolkit=`.** Toolkits were removed ([#178](https://github.com/zackbart/connecta/issues/178))
+   but the URLs naming them were handed out, so the parameter is a 404 rather
+   than silently serving the full registry. Retiring a scoping boundary into
+   fail-open is the one outcome worse than the 404.
+4. **Serve.** A fresh `McpServer` per request, the seven meta-tools registered
+   against the registry, the Apps shell resource registered (and
+   `resources/list` deliberately answering with nothing), and the response
+   handed back.
+
+## Layers below the meta-tools
+
+The meta-tool handlers are thin. The work sits in four services the registry
+owns or hands out, and a change usually belongs in exactly one of them:
+
+| Module | Owns |
+| --- | --- |
+| `src/registry.ts` | The connector set, id validation, address resolution, connector health, per-connector call limiters, and the drift snapshot. Construction-time refusal of structural mistakes lives here. |
+| `src/catalog-service.ts` | Tool listing: cold-load coalescing, TTL, persistence as manifest plus revision-addressed chunks, stale fallback, and the completeness rule — a partial catalog is a failure, never a cache write. |
+| `src/invocation.ts` | One tool call: argument validation, call admission, per-attempt timeout, retry with the connector's own `Retry-After` honoured exactly or declined, result unwrapping, size capping, and the activity record. |
+| `src/catalog.ts` | Ranking, description summarizing, and the compact schema renderer discovery shows. |
+
+`src/meta-tools.ts` and `src/execute.ts` are two front doors onto the same
+three services. That is the point: a program's `connecta.call` and a top-level
+`call_tool` reach `InvocationService.invoke` by different routes and get the
+same admission, the same credential resolution, and the same fail-closed
+read-only check. `test/execute.test.ts` asserts that parity directly, because
+the alternative — a sandbox path that quietly diverges — is how generated code
+would mint a capability.
+
+## Import-graph purity
+
+Nothing reachable from `src/index.ts` may import a `node:` builtin. The core is
+Web-API only so the same code runs unchanged in workerd and in Node.
+
+The Node-touching paths are `src/node.ts` (the `node:http` adapter),
+`src/storage/file.ts`, and the QuickJS process pool
+(`src/executors/quickjs.ts` and its child entry). Each lives behind an explicit
+subpath export — `@zackbart/connecta/node`, `@zackbart/connecta/quickjs` — and
+must stay unreachable from the root entry. The optional Clerk adapter is behind
+`./auth/clerk` for the adjacent reason: `@clerk/backend` is an optional peer,
+not a dependency.
+
+`test/purity.test.ts` walks the relative-import graph from `src/index.ts` and
+fails on (a) any `node:` specifier in a reachable file and (b) the Node
+adapter, file storage, QuickJS parent or child, or the Clerk adapter being
+reachable at all. `test/package-surface.test.ts` and
+`scripts/check-package.mjs` guard the other half — that the published tarball
+matches the same boundary.
+
+The failure mode this prevents is not theoretical: a single convenience import
+of `node:crypto` in a shared helper makes the whole Worker deployment shape
+stop building, and it will do so in someone else's repository rather than
+this one.
+
+## Where things live
+
+```
+src/
+  index.ts            createConnecta + the public re-exports (Workers-clean)
+  server.ts           route ordering, HTTPS upgrade, security wrapper
+  routes/             one file per surface; shared.ts holds the auth gate
+  meta-tools.ts       the six non-execute meta-tools over the registry
+  execute.ts          execute_code, the sandbox host bridge, emit and ui
+  apps-shell.ts       the one build-time MCP Apps template
+  skills.ts           MCP instructions, the usage skill, connector guides
+  registry.ts         connector set, addresses, health, call limiters
+  catalog-service.ts  catalog loading, caching, persistence, stale fallback
+  catalog.ts          ranking, summaries, compact schema rendering
+  invocation.ts       one tool call, end to end
+  catalog-drift.ts    vetted manifests and the counts a refresh produces
+  credentials.ts      the AES-GCM connector vault over KVStorage
+  access-tokens.ts    operator-issued MCP bearer tokens
+  activity.ts         payload-free event contracts + best-effort recorder
+  call-admission.ts   connector-partitioned downstream permits and budgets
+  executor-admission.ts  the portable bounded queue both pools use
+  ui.ts               the served operator shell and /ui/data payload
+  operator-ui/        the Preact app, its pure rules, and the built bundle
+  connectors/         remote-mcp.ts, api.ts, guarded-fetch.ts
+  providers/          the maintained prebuilt connections
+  auth/               bearer, clerk (optional peer), downstream OAuth
+  executors/          the QuickJS pool and child (Node only)
+  storage/            memory.ts, file.ts (Node only)
+  node.ts             listen() + fileStorage re-export (Node only)
+```
+
+## Sharp edges
+
+- **The registry is shared; the request is not.** Anything you cache on the
+  registry is visible to every later request in that isolate. Anything you
+  cache per request dies with it. Putting a downstream client on the wrong side
+  of that line is the highest-severity mistake available here.
+- **Route order is behavior.** Moving a built-in below the connector dispatch
+  hands a connector the ability to shadow it. Moving a mutation route below the
+  wildcard `OPTIONS` opts it into CORS preflight.
+- **Admission runs before auth, on purpose.** Reordering them to "authenticate
+  first" makes the cheapest possible attack the most expensive request.
+- **`close()` is idempotent and ordered.** It closes both admission pools and
+  the connector limiters, then the executor. Node's `listen()` calls it on
+  SIGTERM/SIGINT.
+- **Structural mistakes throw at construction.** A duplicate connector id, an
+  invalid admission rule, `accessTokens` without a Clerk provider, a missing
+  executor: all refuse to boot. A deployment that starts in the wrong shape is
+  worse than one that does not start.
+
+## Tests that enforce this
+
+| Invariant | Suite |
+| --- | --- |
+| The core imports no `node:` builtin and reaches no Node-only module | `test/purity.test.ts` |
+| The published surface matches the same boundary | `test/package-surface.test.ts`, `scripts/check-package.mjs` |
+| Route order, per-route auth, and byte-exact refusals | `test/server-route-contracts.test.ts` |
+| `/mcp` end to end, the open routes, exactly seven tools | `test/server.test.ts`, `test/code-first-surface.test.ts` |
+| Construction-time refusals and the grouped config boundary | `test/config.test.ts`, `test/registry.test.ts` |
+| Program and top-level calls take the same enforced path | `test/execute.test.ts` |
+| Both deployment shapes still compile and configure the real thing | `test/deployment-shapes.test.ts`, `npm run check:examples` |

package/documentation/auth.md

@@ -4,6 +4,17 @@ Inbound auth decides who may reach the MCP endpoint. A deployment may admit a
 static bearer, operator-issued access tokens, Clerk identities, or a mixture.
 Static bearers are checked first.
 
+## Clerk configuration is checked at construction
+
+`clerkAuth` reads its Frontend API origin out of `publishableKey`, so a key that
+is not `pk_test_`/`pk_live_` followed by the base64-encoded domain cannot
+produce one. That throws where `allowedDomains` throws — when `clerkAuth` is
+called — with a message naming the option, never quoting the rejected value
+back: the usual way to land here is pasting the *secret* key into the
+publishable slot, and a startup error is a log line. A deployment that builds
+per request, as the Workers shape does, sees the same error on its first
+request instead of a base64 stack on every route.
+
 ## Operator-issued access tokens
 
 Set `accessTokens: {}` to let eligible Clerk operators create named Bearer