@zackbart/connecta 0.33.0 → 0.34.1

package/dist/types.d.ts

@@ -252,12 +252,15 @@ export interface ReviewedTool {
     /** Why the verdict holds when the name or downstream annotations do not say. */
     readonly reason?: string;
     /**
-     * `sha256:<hex>` digest of the input and output schemas the review read.
+     * `sha256-sets-v1:<hex>` digest of the reviewed input/output schemas.
+     * Legacy `sha256:<hex>` pins retain literal array ordering.
      * Omit until a review has actually read them; an invented digest reports
      * drift that never happened. When the live schema no longer matches it, or
      * it cannot be checked, the verdict lapses and the tool is served as a write.
      */
     readonly schemaDigest?: string;
+    /** Absence is expected under plan, feature, or permission gating. */
+    readonly optional?: boolean;
 }
 /**
  * A reviewed classification of a downstream MCP catalog, keyed by exact tool
@@ -287,7 +290,7 @@ export interface CatalogDriftCounts {
     droppedTools?: number;
     /** Live tools no release classified. Each one fails closed at call time. */
     unclassifiedTools: number;
-    /** Classified names this catalog no longer serves — plan gating included. */
+    /** Required reviewed names this catalog no longer serves. */
     unservedTools: number;
     /** Explicit downstream annotations that contradict a vetted verdict. */
     annotationConflicts: number;
@@ -296,6 +299,15 @@ export interface CatalogDriftCounts {
 }
 /** One drift observation, taken while serving a catalog refresh. */
 export interface CatalogDriftReport extends CatalogDriftCounts {
+    /** False when this listing has no reviewed classification to compare. */
+    reviewedBaseline?: boolean;
+    /** Whether all pinned schemas could be checked on this observation. */
+    verification?: "complete" | "unavailable";
+    /** Live reviewed tools with and without recorded schema digests. */
+    schemaCoverage?: {
+        pinned: number;
+        unpinned: number;
+    };
     /** When the observation was taken; never when a probe was scheduled. */
     observedAt: string;
 }
@@ -364,6 +376,8 @@ export type ConnectorSkillResourceContents = {
 });
 /** The whole plugin contract — the one open seam. */
 export interface Connector {
+    /** Serve only read-classified tools on every endpoint. Defaults to false. */
+    readOnly?: boolean;
     id: string;
     /**
      * Who owns this connector's downstream authentication. `shared` keeps one
@@ -398,7 +412,7 @@ export interface Connector {
      * cross-operation sequencing rule).
      *
      * Served as `skill://connecta/connectors/<slug>/SKILL.md`, with generated
-     * frontmatter followed by the unchanged guide body. `connector:<id>` is a
+     * frontmatter, a read-only policy notice when configured, and the guide body. `connector:<id>` is a
      * one-release lookup alias. The guide remains deployment-owned configuration;
      * no runtime registration or shared mutable copy exists.
      */
@@ -605,7 +619,7 @@ export interface ConnectorDescription {
     tools?: ConnectorToolDescription[];
 }
 export interface ConnectorUsageGuide {
-    /** Markdown returned verbatim by `skills({ name: "connector:<id>" })`. */
+    /** Markdown served by `skills`, with a policy notice when the connector is read-only. */
     content: string;
     /**
      * Discovery hint describing the conventions the guide covers. Whitespace is
@@ -822,7 +836,7 @@ export interface ConnectaBranding {
     description?: string;
     /**
      * Browser tab title and page meta name. Defaults to
-     * `"<productName> — <ownerName>"`, or just `productName` when no owner is set.
+     * `"<productName> · <ownerName>"`, or just `productName` when no owner is set.
      */
     pageTitle?: string;
     /**
@@ -832,14 +846,18 @@ export interface ConnectaBranding {
      * elsewhere (it replaces the `/favicon.svg` link in the page head; the
      * `/favicon.*` routes still serve whatever `svg`/`ico` provide). `href` must
      * be an absolute `http(s)` URL or a root-relative path; anything else falls
-     * back to the default mark.
+     * back to the default mark. With `svg` set, the top bar shows it beside the
+     * name; the drawn mark shows only when no branding is set.
      */
     favicon?: {
         svg?: string;
         ico?: Uint8Array;
         href?: string;
     };
-    /** `theme-color` meta value. Defaults to "#ffffff". */
+    /**
+     * `theme-color` meta value. Unset, pages follow the page background:
+     * `#f6f4ef` in light and `#12110f` in dark.
+     */
     themeColor?: string;
     /**
      * Operator-page appearance. Every field is optional, and a rejected value
@@ -860,18 +878,25 @@ export interface ConnectaBranding {
 export interface ConnectaTheme {
     /**
      * The brand color: links, focus rings, primary actions, the active nav item.
-     * Hex only (`#rgb`, `#rrggbb`, or `#rrggbbaa`). Defaults to `#2f5fe0`.
+     * Hex only (`#rgb`, `#rrggbb`, or `#rrggbbaa`). Defaults to `#4c44e0`
+     * (`#8c86ff` in dark). Text on it and accent text in dark derive from it.
      */
     accent?: string;
     /**
      * Corner rounding for cards, inputs, and buttons. A CSS length (`10px`,
      * `0.5rem`) or a bare number read as pixels. `0` restores square corners.
-     * Defaults to `10px`.
+     * Defaults to `14px`.
      */
     radius?: string | number;
-    /** Body font stack. A plain CSS font-family list. Defaults to a system stack. */
+    /**
+     * Body font stack. A plain CSS font-family list. Defaults to Hanken
+     * Grotesk, served with the operator UI, then a system stack.
+     */
     fontFamily?: string;
-    /** Monospace font stack for addresses, ids, and the endpoint URL. */
+    /**
+     * Monospace font stack for addresses, ids, and the endpoint URL. Defaults
+     * to JetBrains Mono, served with the operator UI, then a system stack.
+     */
     monoFamily?: string;
     /**
      * `"system"` (the default) follows the operator's OS setting; `"light"` and

package/dist/ui.js

@@ -6,9 +6,10 @@ import { uiData } from "./routes/ui-data.js";
 import { runEdge } from "./runtime/run.js";
 import { OPERATOR_UI_STYLE_PATH, OPERATOR_UI_SCHEME_PATH, OPERATOR_UI_SCRIPT_PATH, OPERATOR_UI_NOTICES_PATH, } from "./operator-ui/generated.js";
 export { filterUiConnectors, } from "./operator-ui/model.js";
-import { escapeHtml, isSafeHttpsUrl, renderPage, resolveBranding } from "./branding.js";
+import { brandMark, escapeHtml, isSafeHttpsUrl, renderPage, resolveBranding } from "./branding.js";
 export { CONNECTA_FAVICON_SVG, resolveBranding, isSafeHttpUrl, isSafeHttpsUrl, isSafeIconHref } from "./branding.js";
 const OPERATOR_PAGE_LABELS = {
+    overview: "Overview",
     endpoints: "Endpoints",
     connections: "Connectors",
     connector: "Connector",
@@ -18,6 +19,8 @@ const OPERATOR_PAGE_LABELS = {
 };
 export function operatorPageForPath(path) {
     if (path === "/")
+        return "overview";
+    if (path === "/endpoints")
         return "endpoints";
     if (path === "/connectors")
         return "connections";
@@ -36,7 +39,7 @@ export function operatorPageForPath(path) {
     return undefined;
 }
 export function operatorPageTitle(page, configuredTitle) {
-    return `${OPERATOR_PAGE_LABELS[page]} — ${configuredTitle}`;
+    return `${OPERATOR_PAGE_LABELS[page]} · ${configuredTitle}`;
 }
 /** Report the verdict the registry stored, independent of whether an endpoint is read-only. */
 export function uiToolSafety(definition) {
@@ -146,8 +149,8 @@ _nonce, page = "endpoints") {
     <h1>${OPERATOR_PAGE_LABELS[page]}</h1>
     <div class="lead-copy">
       <p>${escapeHtml(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>
+      <noscript><p class="msg">Operator pages need JavaScript. Agents connect at
+      <span class="mono">/mcp</span>.</p></noscript>
     </div>
   </div>
 </main>
@@ -159,6 +162,7 @@ _nonce, page = "endpoints") {
             schemePinned: brand.theme.colorScheme !== "system",
             titleSuffix: brand.pageTitle,
             productName: brand.productName,
+            brandMark: brandMark(branding, true),
             productDescription: brand.description,
             productOperatorLabel: brand.productName + " operator",
         })}</script><script defer src="${OPERATOR_UI_SCRIPT_PATH}"></script>`,
@@ -182,6 +186,7 @@ export function operatorUi(options = {}) {
     options = assertKnownOptions(options, "operatorUi()", OPERATOR_UI_OPTIONS);
     const reservedPaths = [
         "/",
+        "/endpoints",
         "/connectors",
         "/connectors/*",
         "/tools",

package/dist/usage-guide.js

@@ -77,7 +77,7 @@ async () => {
 
 Host-call budget exhaustion ends the run with budget_exceeded. Catch and
 allSettled cannot recover it or return partial output. Bound batches before
-starting them; search, describe, call, result, and skill spend host calls.
+starting them; every guest call except emit spends host calls.
 Split remaining reads. Never replay writes for their output.
 
 ## Per-connector guides

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CONNECTA_VERSION = "0.33.0";
+export declare const CONNECTA_VERSION = "0.34.1";

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.33.0";
+export const CONNECTA_VERSION = "0.34.1";

package/documentation/README.md

@@ -11,7 +11,7 @@ For a new deployment, start with [Deploying Connecta](./deploying.md).
 | Task                                     | Self-contained procedure                                                                                                            |
 | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
 | Add or remove a connector                | [Change the connector roster](./integrating.md#add-or-remove-a-connector)                                                           |
-| Organize an agent's pools                | [Organizing an agent's pools](./auth.md#organizing-an-agents-pools)                                                                 |
+| Organize an agent's pools and tiers      | [Organizing an agent's pools](./auth.md#organizing-an-agents-pools)                                                                 |
 | Add a person (maintainer or pool member) | [Add a person](./auth.md#add-a-person), [member page](./operator-ui.md#use-the-member-page)                                         |
 | Connect a shared credential              | [Connect a shared credential](./auth.md#connect-a-shared-credential)                                                                |
 | Issue, rotate, or revoke an agent token  | [Manage an agent token](./auth.md#issue-rotate-or-revoke-an-agent-token)                                                            |
@@ -71,7 +71,7 @@ own scoped change procedures. Each [provider folder](https://github.com/zackbart
 owns its maintained `SKILL.md`, options, tests, fixtures, and review data.
 Use those details instead of copying provider catalogs into general guides.
 The provider list in the human README is generated; preserve its marker pair
-and run `npm run check:providers-generated` after edits.
+and run `pnpm run check:providers-generated` after edits.
 
 When changing behavior, update its owning contract and task guide in the same
 change. Check examples against current source and point to the tests that

package/documentation/architecture.md

@@ -148,6 +148,7 @@ An admitted non-preflight `/mcp` request then takes five steps in
    (`src/membership.ts`, `admitsMaintainer`, `memberPool`, and `agentPool` in
    `src/routes/shared.ts`). Nothing intersects or widens either view; every
    refusal is one 404 naming no pool.
+   Connector `readOnly` is enforced by catalog discovery and invocation before dispatch: effective read-only is endpoint OR connector, including on plain `/mcp`. Maintained provider construction carries the policy through the shared factory.
    The endpoint's `readOnly` is the pool's own value, else the deployment's;
    plain `/mcp` uses the deployment's. It travels to the meta-tools and the
    program as one boolean that drops writes from `CatalogService` search and
@@ -158,7 +159,7 @@ An admitted non-preflight `/mcp` request then takes five steps in
    narrower slice, and the subject and principal keys. Personal connectors use
    the principal partition and result paging the subject partition with principal,
    endpoint/pool, origin, connector, and tool bindings. Paging re-admits the
-   caller at its endpoint and rechecks the endpoint's `readOnly`; no caller parameter selects a partition (`test/identity-scope.test.ts`).
+   caller at its endpoint and rechecks endpoint OR connector `readOnly`; no caller parameter selects a partition (`test/identity-scope.test.ts`).
 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
@@ -174,7 +175,7 @@ never select an identity, grant, connector view, or pool. Direct and program
 activity records retain only the self-declared `clientName` and `clientVersion`,
 validated by one ASCII grammar at the record builder, SQL write/read boundaries,
 and authenticated activity read route. Names match
-`[A-Za-z0-9][A-Za-z0-9 ._@/+-]{0,63}`; versions match
+`[A-Za-z0-9@][A-Za-z0-9 ._@/+-]{0,63}`; versions match
 `[A-Za-z0-9][A-Za-z0-9._+-]{0,31}`, each as a whole string. Names allow up to
 64 characters, versions up to 32. `__proto__`, `constructor`, and `prototype`
 are reserved. Invalid values are absent, never truncated or escaped. Capabilities and other client metadata never enter activity.
@@ -970,7 +971,7 @@ manual review evidence instead of claiming a machine-checkable JSON pin.
 
 The generic REST connector (`src/providers/_shared/rest/`) serves
 `<vendor>_api_search`, `_api_details`, `_api_read`, and `_api_write` over an
-`OperationIndex` that `npm run providers:spec` compiles offline from the
+`OperationIndex` that `pnpm run providers:spec` compiles offline from the
 provider's pinned `openapi.source.json` into `openapi.generated.ts`.
 Each call is matched to an operation and checked against its parameters before
 transport; `_api_read` admits GET and the vendor's reviewed read-only POSTs in
@@ -1062,7 +1063,7 @@ every vendor ships one reviewed table through one mechanism
    message/error and raw string/object source payloads in both events and
    invocation maps. The shared review harness rejects embedded-URL operation
    keys absent from each vendor's pinned index and invalid path syntax.
-   Vercel's unavailable full pin remains a review limitation.
+   The current Vercel pin was reviewed from its full response document; its unversioned URL does not retain older documents.
    Generic parameters in descriptions, metadata, nicknames, billing footers,
    notes, DNS TXT, KV values and operator HTML retain their original bytes,
    including whole URL strings. Ordinary code/key URLs can be false positives
@@ -1165,7 +1166,7 @@ a table.
 
 `remoteMcp({ classify })` is the public way to declare what a downstream's
 tools do: `{ tools: { name: "read" | "write" | "destructive" | { verdict,
-reason?, schemaDigest? } }, unlisted?: "hide" }`, validated at construction. It fails closed
+reason?, schemaDigest?, optional? } }, unlisted?: "hide" }`, validated at construction. It fails closed
 (INV-1): a reviewed read fills silence but yields to an explicit write
 annotation, a reviewed write stays a write whatever the downstream claims, an
 unlisted tool is a read only when it says so, and a reviewed tool whose
@@ -1191,8 +1192,50 @@ receives a separate deep copy of its definition, so mutations cannot change
 classification, schemas, or write accounting later in the same program.
 A restart applies the current review to cached SDK facts. Retired registry
 manifest versions 2 and 3 are ignored and expire on their original TTL.
-During successful listings the registry counts drift against the same record, and `scripts/drift-check.mjs` compares
-its names with published inventories. The internal `withVettedCatalog()`
+During listings the registry counts drift against the same record. Optional
+reviewed tools do not count as unserved when gated out. Reports carry an explicit
+reviewed-baseline fact, counts of live reviewed tools with and without schema
+pins, and complete/unavailable schema verification. A digest failure replaces
+the previous observation rather than retaining a stale clean result (INV-1,
+INV-6). Observation and classification share the same verification result for each
+listing; classification still fails closed.
+
+Reports are in-memory only, weakly keyed by connector and a registry-owned
+catalog partition token. The partition uses the same admitted principal,
+subject, caller identity, authenticated flag and pool as catalog caching, plus
+connector id and endpoint URLs. Personal registries do not share tokens with
+each other or the root. Each registry retains at most 1,024 tokens; eviction or
+restart yields no observation, never another subject's counts. No new storage
+key or durable catalog record is introduced.
+
+New schema pins use `sha256-sets-v1:<hex>`. Canonicalization sorts object keys
+and schema `required`, `enum`, and `type` arrays, including schema-valued
+legacy dependencies. Tuple arrays and JSON data
+inside defaults, constants, enum members and examples retain order. Existing
+`sha256:<hex>` pins continue using the original key-sorted, literal-array
+algorithm; their reviewed digests are unchanged. Migrating a legacy pin requires
+reviewing the complete schemas and recording a new versioned digest. Legacy
+pins may still report conservative drift for array reordering until migrated.
+The iterative digest retains the whole-schema node ceiling in both formats.
+
+Contributor evidence: `test/provider-schema-pins.test.ts` checks every provider
+construction case in the generated roster. Every pinned digest requires a
+complete captured schema that passes runtime verification; changed input or
+output schemas must fail it. The guard also exercises both digest prefixes.
+
+The maintainer `scripts/drift-check.mjs` compares published inventories with
+provider evidence. Table inventories can require `inventory.accessColumn` and
+record `reviewedAccess` (`read` or `write`, with destructive verdicts recorded
+as write). These access snapshots must agree with the provider's runtime
+classification. A documented access change or disappearance of a reviewed explicit Access
+value is advisory drift, never an
+automatically accepted verdict. An explicit access value makes an
+`acknowledgedUnclassified` entry stale: report it and resume reporting that
+unreviewed tool as an addition. Missing tools and already reviewed names also
+invalidate such acknowledgements. Duplicate explicit access values must agree;
+a blank duplicate does not erase an explicit value elsewhere. Missing required
+columns in any tool table, unknown access values and conflicting rows are provider-local parser
+findings. The internal `withVettedCatalog()`
 helper has been removed. Public provider `*_VETTED_CATALOG` exports remain
 deprecated aliases derived from each definition
 (`test/classified-decorators.test.ts`, `test/hosted-presets.test.ts`).
@@ -1236,10 +1279,13 @@ connecta shows a person — the operator shell, the OAuth callback, a browser's
 404 — 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
+pieces server-rendered pages share (top bar, buttons, badges, messages, the
+one-message status page). The UI's `browser.css` imports both, then one file
+per area under `src/operator-ui/styles/` (fonts, shared components, shell, and
+each page). The build writes the shared CSS, minified, into
+`src/page-styles.ts`, with the hashed font paths, a module that core imports
 without the UI bundle, so an OAuth callback still renders with the UI omitted.
+Those pages link the fonts only when the UI module serves them.
 `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`
@@ -1253,14 +1299,16 @@ Maintained providers act as the caller downstream. `src/connector-caller.ts`
 attaches the admitted identity beside the request-scoped context, readable only
 by in-repo code and set from authorization, never arguments. Google Workspace
 domain-wide delegation
-(`src/providers/google/`, first consumed by `./providers/gmail`) hands the
+(`src/providers/_shared/google/`, first consumed by `./providers/gmail`) hands the
 admitted identity to a deployment-config `subject` function and mints a
 service-account token as whatever Workspace address it returns. The caller
 carries whether an inbound provider _authenticated_ it: an open deployment
 admits everyone as the anonymous actor, and the function is never asked about
 them. It also carries the admitted pool's `owner`, which core copies from
-config: an agent acts as it, before and instead of the function, and an agent
-in a pool without one fails closed. A fixed `subject` address is every
+config: an agent acts as it, before and instead of the function. In a pool
+without one, the scoped registry view omits a mapping-subject connector for an
+agent (`src/registry.ts`, keyed on the tag in `src/workspace-subject.ts`), as it
+omits a personal connector, and the provider still fails closed if reached. A fixed `subject` address is every
 caller's. No caller, an unauthenticated one, or no address fails
 `auth_required` before any request leaves. The provider never chooses the account and a
 deployment's own connector still cannot read the caller (PRINCIPLES.md, INV-3; `test/google-workspace-delegation.test.ts`). Its tokens live in a
@@ -1321,7 +1369,7 @@ Effect callers skip the Promise and take the program: `admit` and
 and `acquireCallScoped` for call admission, `closeScope` and `closeScopeOnExit`
 for a connector scope, `withDeadlineEffect` where Promise code has
 `withDeadline`. The build prunes every declaration no `exports` target reaches,
-and `npm run check:declarations` fails if what remains names an Effect type.
+and `pnpm run check:declarations` fails if what remains names an Effect type.
 
 ### One runner
 
@@ -1456,7 +1504,7 @@ resolve a single copy. Adopting an unstable subpath is its own pull request.
 
 The stable `4.0.0` release was re-evaluated on 2026-10-01 with
 [`scripts/probes/effect-v4-evaluation.mjs`](https://github.com/zackbart/connecta/blob/main/scripts/probes/effect-v4-evaluation.mjs).
-Run `npm run build`, then `node scripts/probes/effect-v4-evaluation.mjs output.json`.
+Run `pnpm run build`, then `node scripts/probes/effect-v4-evaluation.mjs output.json`.
 The [raw observations](https://github.com/zackbart/connecta/blob/main/scripts/probes/effect-v4-evaluation-2026-10-01.json)
 are synthetic Node requests and neutral esbuild bundles, not live-client or
 workerd lifetime verification. Bundle figures add representative prototypes
@@ -1494,7 +1542,7 @@ replacement's benefit or compatibility.
 The core's cost is recorded rather than guessed. Against 0.24.4 the root entry
 grew from 235,346 to 279,526 bytes gzip, the Worker example from 263,949 to
 314,336, and each provider by about 36 KB, since each reaches Effect through
-`remoteMcp()`; `npm run check:bundle` caps every entry against
+`remoteMcp()`; `pnpm run check:bundle` caps every entry against
 `scripts/bundle-budget.json`. An install carries about 53 MB of `effect`, with
 no dependencies of its own.
 
@@ -1510,7 +1558,7 @@ src/
   catalog-drift.ts    reviewed classifications and the drift counts a refresh produces
   provider.ts         defineProvider(): the one maintained-provider shape
   activity.ts         optional history factory and best-effort recorder
-  auth/               bearer, Cloudflare Access, clerk (optional peer), downstream OAuth (remote and static)
+  auth/               Cloudflare Access, clerk (optional peer), downstream OAuth (remote and static)
   executors/          the QuickJS pool and child (Node only)
   node.ts             listen() (Node only)
   d1.ts, sqlite.ts    the two storage drivers; storage/ holds the SQL core and key families
@@ -1518,7 +1566,7 @@ src/
 
 There are exactly two deployment shapes — `templates/node/`, which
 `connecta init` copies with its container files, and `examples/worker/` — and
-`test/deployment-shapes.node.test.ts` with `npm run check:examples` keeps both
+`test/deployment-shapes.node.test.ts` with `pnpm run check:examples` keeps both
 compiling and configuring the real thing.
 
 ## Sharp edges