@zackbart/connecta 0.18.3 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 All notable changes to this package are documented here.
 
+## 0.19.0 — 2026-08-25
+
+This release is a smaller, simpler package with no behavioral change for a
+deployment. A deployment can ignore everything here. The one packaging change
+is to maintainer history: six finished design records now live in the repository
+at their GitHub URLs instead of shipping in the npm package, cutting 91 KB from
+the package. The constitution is a fifth of its former size and keeps the same
+decisions. The core shrank from 28,756 to 27,417 lines and the tests from 42,341
+to 40,375 before the final pure-suite splits, which put 198 lines back — a
+copied preamble the next pass moves into a fixture (#479). Two dead paths
+finally left with the rest: write-only health accessors on `RegistryView`,
+residue from #179, and the v1 persisted-catalog reader, unreachable since
+2026-07-28.
+
+### Changed
+
+- **Providers.** Every Cloudflare tool is built through `cfTool()` and
+  `compact()`, so the repeated schema headers, scope properties, and
+  conditional-spread projections are written once; the paged-list, delete-ack,
+  and passthrough handlers are shared while every tool keeps its own literal
+  name, description, annotations, and schemas; the authentication `Symbol` is
+  gone because the scheme is fixed per connector (#465, #467). Cloudflare and
+  Notion share one Retry-After parser and one guarded JSON accessor, and
+  `callCloudflareContent` still classifies an unreadable error body by status
+  (#468). The hosted providers' comment blocks point at their guides instead of
+  restating them, and `api()` omits undefined options once (#463).
+- **Core.** Internal option types accept `undefined`, so `createConnecta` and
+  the registration helpers forward configuration directly (#462). One deadline,
+  sleep, and message helper serve the whole call path; `invocation.ts` lost its
+  hand-rolled controller, timer, and listener choreography with Retry-After,
+  per-phase timing, and health exclusion unchanged (#466). The catalog,
+  execution, remote-MCP, and operator-data paths share their failure envelopes,
+  close helpers, and result shapers (#472).
+- **Package and docs.** Six finished design records moved to
+  [`records/`](https://github.com/zackbart/connecta/tree/main/records), outside
+  the published files, and packed-link validation folded into the documentation
+  checker: −1,342 shipped lines, −91 KB (#464). `ethos.md` is the constitution
+  again — refusals, invariants, and what this is, at 1,188 words instead of
+  3,174, with every decision intact and a word cap replacing the line cap
+  (#471).
+- **Tests.** Shared fixtures replace 122 hand-rolled connector literals, five
+  fake downstream MCP servers, four fake Clerk auths, and the per-suite JSON-RPC
+  readers, deferreds, and logger spies (#473, #474, #475); the six
+  provider-registry suites are one `describe.each` and the provider error
+  mappings are tables (#476); repeated cases are `it.each` tables and the
+  duplicated assertion layers are gone (#477); the two largest suites are split
+  by subject (#460). Every `it()` and `expect()` that pins behavior survived —
+  3,400 fewer lines, no assertion dropped.
+- **Declined with numbers**, so nobody re-runs the experiment: a shared bounded
+  queue under both admission controllers measured −17 lines for a
+  hook-parameterised abstraction (#453); Effect as the core effect system
+  measured −4% of the core for +75 KB gzip and a second async paradigm (#470).
+
+### Removed
+
+- The write-only `HealthLog` and its `RegistryView` accessors: `healthFor`,
+  `hasObservedSuccess`, `observedSuccessAt`, and `peekTools`. `refreshTools` is
+  now private. This was residue from the removed proactive credential-liveness
+  design (#179).
+- The v1 persisted-catalog reader, unreachable since 2026-07-28. Its fixtures
+  now use the v2 manifest-and-chunks format.
+
 ## 0.18.3 — 2026-08-25
 
 This change gives code mode memory where downstream MCP catalogs are usually
@@ -29,6 +91,13 @@ one or several real results from masquerading as a provider contract.
   live deployment audits: BePresent had 246/378 tools without output schemas,
   while OneMany's maintained connectors declared all 90 (#442).
 
+### Changed
+
+- Removed the write-only per-connector call health log. Payload-free call
+  outcomes remain available through the activity sink.
+- Persisted catalog reads now require the version 2 manifest-and-chunks shape;
+  version 1 single-value catalogs are ignored and refreshed.
+
 ## 0.18.2 — 2026-08-18
 
 This patch closes the gap the RevenueCat rollout exposed on the same day 0.18.1
@@ -752,7 +821,7 @@ it back byte-identical after each operator mutation.
   constructor, schemas, validation path, handlers, and catalog service run, and
   only `fetch` is a probe that records the request (#350).
 - **Five provider audit reports** in
-  [`documentation/provider-audit.md`](./documentation/provider-audit.md), with
+  [`records/provider-audit.md`](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md), with
   a verdict per convention, the fix for every miss, and every accepted
   exception recorded with its argument (#342).
 - **A convention test over the shipped surface.**
@@ -1535,7 +1604,7 @@ The channel is additive — a program that never calls `connecta.ui` produces th
 byte-for-byte prior response, no executor changed to carry it, and there is no
 new budget knob. Deployments do gain a `resources` capability and one extension
 declaration, both of which the design requires before any host will render.
-The design record is `documentation/mcp-ui-design.md` (#266); the contract is
+The design record is [`records/mcp-ui-design.md`](https://github.com/zackbart/connecta/blob/main/records/mcp-ui-design.md) (#266); the contract is
 `code-mode.md`'s "Rendered output" clauses (#277).
 
 ### Added
@@ -1611,7 +1680,7 @@ that cannot be projected, like a screenshot a downstream tool returned. The
 channel is additive: a program that never emits produces the byte-for-byte
 prior response, no executor changed to carry it, and deployments that do
 nothing get sensible budgets. The design record is
-`documentation/rich-output-design.md` (#267); the contract is `code-mode.md`'s
+[`records/rich-output-design.md`](https://github.com/zackbart/connecta/blob/main/records/rich-output-design.md) (#267); the contract is `code-mode.md`'s
 "Emitted output" clauses (#270).
 
 Agent recovery is now executable data instead of prose at the remaining local
@@ -2024,7 +2093,7 @@ tests confirm SDK v2 client close does not make it redundant.
   advances the existing generation fence before the SDK starts a fresh grant;
   pre-upgrade credentials bind in place on their first validated read.
 - **A complete in-repo disposition of the revision** in
-  [`documentation/mcp-2026-07-28.md`](./documentation/mcp-2026-07-28.md),
+  [`records/mcp-2026-07-28.md`](https://github.com/zackbart/connecta/blob/main/records/mcp-2026-07-28.md),
   including the declined and gated surfaces.
 
 ### Changed

package/dist/catalog-service.d.ts

@@ -151,13 +151,13 @@ export declare class CatalogService {
     private readonly loaded;
     private readonly loading;
     constructor(registry: RegistryView, baseUrl: string, options?: {
-        requestScope?: object;
-        probeTimeoutMs?: number;
-        concurrency?: number;
+        requestScope?: object | undefined;
+        probeTimeoutMs?: number | undefined;
+        concurrency?: number | undefined;
         /** The discovery route recovery records name. Default `search_tools`. */
-        searchRoute?: SearchRoute;
+        searchRoute?: SearchRoute | undefined;
         /** Runtime-owned tail for stale-while-revalidate catalog reads. */
-        defer?: DeferredWork;
+        defer?: DeferredWork | undefined;
     });
     /**
      * Send a caller back to discovery through the surface it can actually reach.
@@ -177,6 +177,9 @@ export declare class CatalogService {
     loadConnector(id: string, callOptions?: ConnectorOperationOptions): Promise<ToolDef[]>;
     private loadForDiscovery;
     private outputSchema;
+    private unknownAddressFailure;
+    private catalogLoadFailure;
+    private unknownToolFailure;
     resolveTool(address: string, callOptions?: ConnectorOperationOptions): Promise<CatalogResolution>;
     /**
      * Resolve the JavaScript-safe property used by a lazy code-mode namespace
@@ -206,6 +209,10 @@ export declare function groupedSearchResult(page: CatalogSearchPage): {
     };
     matchMode?: "partial";
     nextOffset?: number;
+    total: number;
+    offset: number;
+    limit: number;
+    hasMore: boolean;
     connectors: {
         id: string;
         title?: string;
@@ -213,10 +220,6 @@ export declare function groupedSearchResult(page: CatalogSearchPage): {
         guideSummary?: string;
         tools: CatalogSearchEntry["tool"][];
     }[];
-    total: number;
-    offset: number;
-    limit: number;
-    hasMore: boolean;
 };
 export declare function flatSearchResult(page: CatalogSearchPage): {
     queryAnalysis?: {
@@ -237,6 +240,10 @@ export declare function flatSearchResult(page: CatalogSearchPage): {
     };
     matchMode?: "partial";
     nextOffset?: number;
+    total: number;
+    offset: number;
+    limit: number;
+    hasMore: boolean;
     tools: {
         guideSummary?: string;
         guide?: string;
@@ -255,9 +262,5 @@ export declare function flatSearchResult(page: CatalogSearchPage): {
         guideRequired?: true;
         guideRequiredReasons?: GuideRequiredReason[];
     }[];
-    total: number;
-    offset: number;
-    limit: number;
-    hasMore: boolean;
 };
 export {};

package/dist/catalog-service.js

@@ -2,7 +2,7 @@ import { compactDiscoverySchema, compactSchema, lexicalCorpusStatistics, lexical
 import { mapSettledWithConcurrency, resolveDiscoveryConcurrency, } from "./concurrency.js";
 import { boundedEchoText, classifyCallError, framingError, } from "./errors.js";
 import { connectorGuide, connectorGuideRequired, connectorGuideSummary, connectorSkillName, } from "./skills.js";
-import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, withAbortableTimeout, } from "./timeout.js";
+import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, withDeadline, } from "./timeout.js";
 import { isExplicitlyReadOnly } from "./tool-safety.js";
 export const DEFAULT_SEARCH_LIMIT = 8;
 export const MAX_SEARCH_LIMIT = 100;
@@ -261,10 +261,13 @@ export class CatalogService {
         return loading;
     }
     loadForDiscovery(id, label) {
-        return withAbortableTimeout((signal) => this.loadConnector(id, {
+        return withDeadline((signal) => this.loadConnector(id, {
             signal,
             timeoutMs: this.probeTimeoutMs,
-        }), this.probeTimeoutMs, label);
+        }), {
+            timeoutMs: this.probeTimeoutMs,
+            timeoutError: new Error(`${label} timed out after ${this.probeTimeoutMs}ms`),
+        });
     }
     outputSchema(connectorId, tool) {
         if (tool.outputSchema)
@@ -274,17 +277,42 @@ export class CatalogService {
             ? { schema: observed, source: "observed" }
             : {};
     }
+    unknownAddressFailure(address, query) {
+        return {
+            ok: false,
+            error: {
+                ...framingError("unknown_address", `Unknown address "${boundedEchoText(address)}"`),
+                nextAction: this.searchRecovery({ query: recoveryQuery(query) }, "Find the configured canonical address before retrying."),
+            },
+            catalogMs: 0,
+        };
+    }
+    catalogLoadFailure(cause, started, connector, toolName) {
+        return {
+            ok: false,
+            error: classifyCallError(cause, "catalog_lookup_failed"),
+            catalogMs: Date.now() - started,
+            connector,
+            toolName,
+            cause,
+        };
+    }
+    unknownToolFailure(toolName, connector, started) {
+        return {
+            ok: false,
+            error: {
+                ...framingError("unknown_tool", `Unknown tool "${boundedEchoText(toolName)}" on connector "${connector.id}"`),
+                nextAction: this.searchRecovery({ query: recoveryQuery(toolName), connector: connector.id }, "Find the connector's current canonical tool address."),
+            },
+            catalogMs: Date.now() - started,
+            connector,
+            toolName,
+        };
+    }
     async resolveTool(address, callOptions = {}) {
         const resolved = this.registry.resolveAddress(address);
         if (!resolved) {
-            return {
-                ok: false,
-                error: {
-                    ...framingError("unknown_address", `Unknown address "${boundedEchoText(address)}"`),
-                    nextAction: this.searchRecovery({ query: recoveryQuery(address) }, "Find the configured canonical address before retrying."),
-                },
-                catalogMs: 0,
-            };
+            return this.unknownAddressFailure(address, address);
         }
         const started = Date.now();
         let tools;
@@ -292,30 +320,11 @@ export class CatalogService {
             tools = await this.loadConnector(resolved.connector.id, callOptions);
         }
         catch (cause) {
-            return {
-                ok: false,
-                error: classifyCallError(cause, "catalog_lookup_failed"),
-                catalogMs: Date.now() - started,
-                connector: resolved.connector,
-                toolName: resolved.toolName,
-                cause,
-            };
+            return this.catalogLoadFailure(cause, started, resolved.connector, resolved.toolName);
         }
         const definition = tools.find((tool) => tool.name === resolved.toolName);
         if (!definition) {
-            return {
-                ok: false,
-                error: {
-                    ...framingError("unknown_tool", `Unknown tool "${boundedEchoText(resolved.toolName)}" on connector "${resolved.connector.id}"`),
-                    nextAction: this.searchRecovery({
-                        query: recoveryQuery(resolved.toolName),
-                        connector: resolved.connector.id,
-                    }, "Find the connector's current canonical tool address."),
-                },
-                catalogMs: Date.now() - started,
-                connector: resolved.connector,
-                toolName: resolved.toolName,
-            };
+            return this.unknownToolFailure(resolved.toolName, resolved.connector, started);
         }
         return {
             ok: true,
@@ -335,14 +344,7 @@ export class CatalogService {
     async resolveToolAlias(connectorId, alias, aliasFor, callOptions = {}) {
         const connector = this.registry.getConnector(connectorId);
         if (!connector) {
-            return {
-                ok: false,
-                error: {
-                    ...framingError("unknown_address", `Unknown address "${boundedEchoText(`${connectorId}.${alias}`)}"`),
-                    nextAction: this.searchRecovery({ query: recoveryQuery(alias) }, "Find the configured canonical address before retrying."),
-                },
-                catalogMs: 0,
-            };
+            return this.unknownAddressFailure(`${connectorId}.${alias}`, alias);
         }
         const started = Date.now();
         let tools;
@@ -350,27 +352,11 @@ export class CatalogService {
             tools = await this.loadConnector(connector.id, callOptions);
         }
         catch (cause) {
-            return {
-                ok: false,
-                error: classifyCallError(cause, "catalog_lookup_failed"),
-                catalogMs: Date.now() - started,
-                connector,
-                toolName: alias,
-                cause,
-            };
+            return this.catalogLoadFailure(cause, started, connector, alias);
         }
         const [definition, ...collisions] = tools.filter((tool) => aliasFor(tool.name) === alias);
         if (!definition) {
-            return {
-                ok: false,
-                error: {
-                    ...framingError("unknown_tool", `Unknown tool "${boundedEchoText(alias)}" on connector "${connector.id}"`),
-                    nextAction: this.searchRecovery({ query: recoveryQuery(alias), connector: connector.id }, "Find the connector's current canonical tool address."),
-                },
-                catalogMs: Date.now() - started,
-                connector,
-                toolName: alias,
-            };
+            return this.unknownToolFailure(alias, connector, started);
         }
         if (collisions.length > 0) {
             const names = [definition, ...collisions]
@@ -494,18 +480,19 @@ export class CatalogService {
                 a.order - b.order);
         });
         const pageMatches = matches.slice(offset, offset + limit);
+        const withSchemas = args.includeSchemas;
         const entries = pageMatches.map((match) => {
-            const output = args.includeSchemas
+            const output = withSchemas
                 ? this.outputSchema(match.connector.id, match.tool)
                 : {};
             const input = match.tool.inputSchema ?? { type: "object" };
-            const renderedInput = args.includeSchemas
-                ? renderSearchSchema(input, args.includeSchemas)
+            const renderedInput = withSchemas
+                ? renderSearchSchema(input, withSchemas)
                 : undefined;
-            const renderedOutput = args.includeSchemas && output.schema
-                ? renderSearchSchema(output.schema, args.includeSchemas)
+            const renderedOutput = withSchemas && output.schema
+                ? renderSearchSchema(output.schema, withSchemas)
                 : undefined;
-            const schemaKeys = args.includeSchemas && args.includeSchemaKeys
+            const schemaKeys = withSchemas && args.includeSchemaKeys
                 ? schemaKeyMetadata(input, output.schema)
                 : undefined;
             const description = summarizeDiscoveryDescription(match.tool.description, args.fullDescriptions === true);
@@ -523,7 +510,7 @@ export class CatalogService {
                     name: match.tool.name,
                     address: `${match.connector.id}.${match.tool.name}`,
                     ...(description !== undefined ? { description } : {}),
-                    ...(args.includeSchemas
+                    ...(withSchemas
                         ? {
                             inputSchema: renderedInput?.schema,
                         }
@@ -531,12 +518,12 @@ export class CatalogService {
                     ...(renderedInput?.truncated
                         ? { inputSchemaTruncated: true }
                         : {}),
-                    ...(args.includeSchemas && output.schema
+                    ...(withSchemas && output.schema
                         ? {
                             outputSchema: renderedOutput?.schema,
                         }
                         : {}),
-                    ...(args.includeSchemas && output.source
+                    ...(withSchemas && output.source
                         ? { outputSchemaSource: output.source }
                         : {}),
                     ...(renderedOutput?.truncated
@@ -671,41 +658,46 @@ export class CatalogService {
             (queryTerms.length > 0
                 ? matchMode === "partial"
                 : unknownConnectorGuidance !== undefined || unavailableCatalogs > 0);
-        const guidance = unsearchableQuery
-            ? (unknownConnectorGuidance ??
-                (scopedConnector && unavailableCatalogs > 0
+        const searchGuidance = () => {
+            if (unknownConnectorGuidance)
+                return unknownConnectorGuidance;
+            if (unsearchableQuery) {
+                return scopedConnector && unavailableCatalogs > 0
                     ? `Connector "${scopedConnector.id}" could not be searched because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`
-                    : "The query contained no searchable lexical terms. Use 2–4 ASCII action/object terms, or browse with an empty query."))
-            : queryTerms.length === 0
-                ? // A browse has no terms to advise about, so it stays silent unless
-                    // the scope itself failed: the guidance on a scoped miss recommends
-                    // browsing with an empty query, and that advice must not lead into a
-                    // dead end that looks like a connector with no tools.
-                    (unknownConnectorGuidance ??
-                        (unavailableCatalogs === 0
-                            ? undefined
-                            : scopedConnector
-                                ? `Connector "${scopedConnector.id}" could not be browsed because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`
-                                : `${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable, so this browse is incomplete. Scope by connector to see the typed reason.`))
-                : matches.length === 0
-                    ? (unknownConnectorGuidance ??
-                        (scopedConnector
-                            ? unavailableCatalogs > 0
-                                ? `Connector "${scopedConnector.id}" could not be searched because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`
-                                : scopedGuide?.required
-                                    ? `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Fetch queryAnalysis.guide before calling, then refine terms or browse with an empty query.${filterRecovery}`
-                                    : `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Refine terms or browse it with an empty query.${filterRecovery}`
-                            : (identityGuidance ??
-                                (unavailableCatalogs === 0
-                                    ? `No matching ${safetyLabel}capability is configured in this deployment. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`
-                                    : `No matching ${safetyLabel}capability was found in the catalogs that answered; ${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`))))
-                    : matchMode === "partial"
-                        ? scopedConnector
-                            ? `No single tool on connector "${scopedConnector.id}" matched every term. Split distinct intents into separate searches.`
-                            : unavailableCatalogs === 0
-                                ? "No single tool matched every term. Split distinct intents into separate searches."
-                                : "No single tool matched every term in the catalogs that answered. Split distinct intents into separate searches."
-                        : undefined;
+                    : "The query contained no searchable lexical terms. Use 2–4 ASCII action/object terms, or browse with an empty query.";
+            }
+            if (queryTerms.length === 0) {
+                if (unavailableCatalogs === 0)
+                    return undefined;
+                return scopedConnector
+                    ? `Connector "${scopedConnector.id}" could not be browsed because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`
+                    : `${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable, so this browse is incomplete. Scope by connector to see the typed reason.`;
+            }
+            if (matches.length === 0) {
+                if (scopedConnector) {
+                    if (unavailableCatalogs > 0) {
+                        return `Connector "${scopedConnector.id}" could not be searched because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`;
+                    }
+                    return scopedGuide?.required
+                        ? `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Fetch queryAnalysis.guide before calling, then refine terms or browse with an empty query.${filterRecovery}`
+                        : `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Refine terms or browse it with an empty query.${filterRecovery}`;
+                }
+                if (identityGuidance)
+                    return identityGuidance;
+                return unavailableCatalogs === 0
+                    ? `No matching ${safetyLabel}capability is configured in this deployment. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`
+                    : `No matching ${safetyLabel}capability was found in the catalogs that answered; ${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`;
+            }
+            if (matchMode !== "partial")
+                return undefined;
+            if (scopedConnector) {
+                return `No single tool on connector "${scopedConnector.id}" matched every term. Split distinct intents into separate searches.`;
+            }
+            return unavailableCatalogs === 0
+                ? "No single tool matched every term. Split distinct intents into separate searches."
+                : "No single tool matched every term in the catalogs that answered. Split distinct intents into separate searches.";
+        };
+        const guidance = searchGuidance();
         return {
             entries,
             total: matches.length,
@@ -859,6 +851,17 @@ export class CatalogService {
         });
     }
 }
+function pageTail(page) {
+    return {
+        total: page.total,
+        offset: page.offset,
+        limit: page.limit,
+        hasMore: page.hasMore,
+        ...(page.nextOffset !== undefined ? { nextOffset: page.nextOffset } : {}),
+        ...(page.matchMode ? { matchMode: page.matchMode } : {}),
+        ...(page.queryAnalysis ? { queryAnalysis: page.queryAnalysis } : {}),
+    };
+}
 export function groupedSearchResult(page) {
     const groups = [];
     const byConnector = new Map();
@@ -884,13 +887,7 @@ export function groupedSearchResult(page) {
     }
     return {
         connectors: groups,
-        total: page.total,
-        offset: page.offset,
-        limit: page.limit,
-        hasMore: page.hasMore,
-        ...(page.nextOffset !== undefined ? { nextOffset: page.nextOffset } : {}),
-        ...(page.matchMode ? { matchMode: page.matchMode } : {}),
-        ...(page.queryAnalysis ? { queryAnalysis: page.queryAnalysis } : {}),
+        ...pageTail(page),
     };
 }
 export function flatSearchResult(page) {
@@ -902,12 +899,6 @@ export function flatSearchResult(page) {
                 ? { guideSummary: entry.guideSummary }
                 : {}),
         })),
-        total: page.total,
-        offset: page.offset,
-        limit: page.limit,
-        hasMore: page.hasMore,
-        ...(page.nextOffset !== undefined ? { nextOffset: page.nextOffset } : {}),
-        ...(page.matchMode ? { matchMode: page.matchMode } : {}),
-        ...(page.queryAnalysis ? { queryAnalysis: page.queryAnalysis } : {}),
+        ...pageTail(page),
     };
 }