@zackbart/connecta 0.28.0 → 0.29.0

package/dist/registry.d.ts

@@ -1,7 +1,6 @@
+import type { CatalogDriftActivityContext } from "./activity.js";
 import type { CredentialVault } from "./credential-contract.js";
-import type { CatalogDriftReport, Connector, ConnectorContext, ConnectorStatus, KVStorage, Logger, ToolDef } from "./types.js";
-import { type DeferredWork } from "./connector-scope.js";
-import { type CatalogDriftActivityContext } from "./activity.js";
+import type { Connector, ConnectorContext, ConnectorStatus, KVStorage, Logger, ToolDef } from "./types.js";
 import { type CallAdmissionPermit, type ConnectorCallAdmissionSnapshot } from "./call-admission.js";
 import { type ConnectorCaller } from "./connector-caller.js";
 /**
@@ -26,7 +25,7 @@ export declare const MIN_MAX_RESULT_BYTES = 1;
 /**
  * The one definition of a usable `maxResultBytes`: a finite whole number of at
  * least {@link MIN_MAX_RESULT_BYTES} bytes. Shared by all three intake points
- * — `calls.maxResultBytes`, the per-connector override, and `get_result`'s
+ * — `calls.maxResultBytes`, the per-connector override, and `connecta.result`'s
  * `maxBytes` argument — so a value that is valid at one is valid at all.
  *
  * Everything else is rejected rather than coerced, because each rejected shape
@@ -38,14 +37,17 @@ export declare const MIN_MAX_RESULT_BYTES = 1;
 export declare function isValidMaxResultBytes(value: number): boolean;
 /**
  * Resolve a configured cap against the value it inherits, dropping anything
- * `isValidMaxResultBytes` rejects. Operator-facing surfaces pair this with a
- * startup warning (see `Registry.checkResultCaps`) so the fallback is never
- * silent; the resolution itself stays total so no call site has to cope with
- * a broken cap.
+ * `isValidMaxResultBytes` rejects. Construction already refuses an unusable
+ * cap (`Registry.assertResultCaps`); the resolution stays total so no call
+ * site has to cope with a broken one.
  */
 export declare function resolveMaxResultBytes(value: number | undefined, inherited: number): number;
 export interface RegistryOptions {
+    publicUrl?: string | undefined;
+    oauthClientName?: string | undefined;
+    classification?: Readonly<Record<string, Readonly<Record<string, "read" | "write">>>> | undefined;
     storage: KVStorage;
+    catalogStorage?: KVStorage;
     logger: Logger;
     credentialVault?: CredentialVault | undefined;
     credentialUi?: boolean | undefined;
@@ -53,33 +55,22 @@ export interface RegistryOptions {
     credentialOwner?: string | undefined;
     /** Internal child registries skip deployment-wide construction warnings. */
     constructionChecks?: boolean | undefined;
+    catalogDriftActivity?: Omit<CatalogDriftActivityContext, "logger"> | undefined;
     toolCacheTtlSeconds?: number | undefined;
-    persistToolCatalog?: boolean | undefined;
-    toolCatalogStaleSeconds?: number | undefined;
+    catalogMinTtlSeconds?: number | undefined;
+    catalogMaxTtlSeconds?: number | undefined;
     /**
-     * Cap on inline result size before truncation + get_result paging. Must be a
-     * whole number of bytes >= 1; anything else warns at startup and falls back
-     * to the default 24_000.
+     * Cap on inline result size before truncation + connecta.result paging. Must be a
+     * whole number of bytes >= 1; anything else throws at construction. Default
+     * 24_000.
      */
     maxResultBytes?: number | undefined;
     results?: {
         maxStashBytes?: number;
         maxStashEntries?: number;
     } | undefined;
-    /**
-     * Where payload-free catalog-drift observations go. Present only when the
-     * deployment configured an activity store; drift is reported through
-     * connector status either way.
-     */
-    catalogDriftActivity?: Omit<CatalogDriftActivityContext, "logger"> | undefined;
-}
-export type ConnectorOperationOptions = Pick<ConnectorContext, "signal" | "timeoutMs">;
-/** Agent-only catalog behavior. This never enters a ConnectorContext. */
-export interface CatalogReadOptions {
-    defer?: DeferredWork;
-    /** Fresh deadline for a deferred refresh; never an inbound signal. */
-    refreshTimeoutMs: number;
 }
+export type ConnectorOperationOptions = Pick<ConnectorContext, "signal" | "timeoutMs" | "defer">;
 /**
  * The registry surface a per-connection MCP server consumes: every meta-tool
  * (`src/meta-tools.ts`) and the `execute_code` sandbox bridge (`src/execute.ts`)
@@ -89,17 +80,28 @@ export interface CatalogReadOptions {
  * consume registry behavior without depending on the concrete implementation
  * or its construction-only methods.
  */
+/** Host-admitted identity and endpoint bindings for result paging. */
+export interface ResultIdentity {
+    subject: string | null;
+    principal: string | null;
+    endpoint: string;
+    origin: string | null;
+}
 export interface RegistryView {
     credentialUiAvailable(): boolean;
     /** Deployment-wide result-size cap threaded to the meta-tools. */
     readonly maxResultBytes: number;
     listConnectors(): Connector[];
+    /** Whole-connector permission for downstream skill files, which have no tool grants. */
+    canReadConnectorSkills(id: string): boolean;
     getConnector(id: string): Connector | undefined;
+    /** Only whole-connector grants authorize resource reads. */
+    getResourceConnector(id: string): Connector | undefined;
     resolveAddress(address: string): {
         connector: Connector;
         toolName: string;
     } | null;
-    getTools(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions, readOptions?: CatalogReadOptions): Promise<ToolDef[]>;
+    getTools(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions): Promise<ToolDef[]>;
     contextFor(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions): ConnectorContext;
     /** Acquire the connector's shared downstream-call permit. */
     admitCall(id: string, input: {
@@ -108,18 +110,23 @@ export interface RegistryView {
         signal?: AbortSignal;
     }): Promise<CallAdmissionPermit>;
     resultsStorage(): KVStorage;
-    /** Reserve runtime-wide capacity before writing a paging envelope's chunks. */
-    stashResult(key: string, chunks: readonly string[], ttlSeconds: number): Promise<boolean>;
+    resultIdentity(): ResultIdentity;
+    /** Recheck live auth/grants and pool admission before exposing stored data. */
+    recheckResultAccess(address: string, classification: "read" | "write", signal?: AbortSignal): Promise<boolean>;
+    /** Reserve deployment-wide capacity before writing a paging envelope's chunks. */
+    stashResult(id: string, chunks: readonly string[], ttlSeconds: number): Promise<boolean>;
     /** Local declared-vs-stored credential mismatch, with no downstream I/O. */
     credentialDriftFor(id: string): Promise<string | undefined>;
     /** Value-free shape learned from successful calls, never a provider declaration. */
     observedOutputSchema(connectorId: string, definition: ToolDef): ToolDef["outputSchema"] | undefined;
     /** Passively learn one successful unwrapped result; failures stay isolated. */
     observeOutputShape(connectorId: string, definition: ToolDef, value: unknown): void;
+    /** Age of the complete cached catalog; null for static or unobserved catalogs. */
+    catalogAgeMs(id: string): number | null;
     statusFor(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions): Promise<ConnectorStatus>;
     invalidateStored(id: string): Promise<void>;
-    /** Bind returned OAuth state to this view's personal storage partition. */
-    bindOAuthHandoff(id: string, authorizationUrl: string): Promise<void>;
+    /** Bind returned OAuth state to its initiating user for either owner scope. */
+    bindOAuthHandoff(id: string, authorizationUrl: string, principalKey?: string): Promise<void>;
 }
 /**
  * Connector id → the only tool names this view may see on it. A connector
@@ -133,42 +140,37 @@ export interface RegistryScope {
     guardedToolAccess?: ToolAccess;
     subjectKey?: string;
     principalKey?: string;
+    endpoint?: string;
+    origin?: string | null;
+    currentResultAccess?: (address: string, classification: "read" | "write", signal?: AbortSignal) => Promise<boolean>;
     /** The admitted caller, readable only by built-in connectors; see connector-caller.ts. */
     caller?: ConnectorCaller;
 }
 /**
- * Holds the connector set, resolves addresses, and caches per-connector tool
- * lists in memory with a TTL. Connector failures are isolated: a broken
+ * Holds the connector set, resolves addresses, and coalesces tool listings
+ * within one request. Remote MCP clients own persisted response caching. Connector failures are isolated: a broken
  * connector surfaces status "error"; the rest keep working.
  */
 export declare class Registry implements RegistryView {
     private readonly opts;
     private readonly connectors;
     private readonly callAdmission;
-    private readonly cache;
-    private readonly invalidated;
-    /** Per-connector epoch preventing a pre-invalidation refresh from publishing. */
-    private readonly catalogGenerations;
-    /** Serialize persisted catalog set/delete operations within this isolate. */
-    private readonly catalogMutations;
-    /** Same-request cold loads share one read without retaining the request.
-     * See documentation/architecture.md#the-two-lifetimes. */
+    /** Coalesce listings only within one request and authorization partition. */
     private readonly requestCatalogLoads;
-    /** One live refresh per connector across agent and operator requests. */
-    private readonly catalogRefreshes;
+    private readonly catalogObservedAt;
     /** Last payload-free agent catalog access in this runtime. */
     private readonly catalogAccess;
-    /** Last drift counts reported to activity, per connector, in this runtime. */
-    private readonly reportedDrift;
+    /** Count-only intake findings, including catalogs loaded from storage. */
+    private droppedToolNames;
+    /**
+     * Schema digest verification per reviewed facts array. Only the registry's
+     * own deep-frozen arrays are keys, so an entry stays true while they live.
+     */
+    private readonly verifiedFacts;
     private readonly observedOutputSchemas;
-    private readonly ttlMs;
-    private readonly staleMs;
-    private readonly persistToolCatalog;
     /** Result-size guard cap threaded to the meta-tools. */
     readonly maxResultBytes: number;
-    /** Only keys, byte counts, and expiry survive requests; never write promises. */
-    private readonly resultStash;
-    private resultStashBytes;
+    private readonly classification;
     private readonly configuredConnectors;
     private readonly personalRegistries;
     private readonly oauthPartition;
@@ -187,22 +189,20 @@ export declare class Registry implements RegistryView {
      * cannot check it, and a catalog that drifts later cannot widen a grant.
      */
     noteAbsentGrant(connectorId: string, toolName: string): void;
-    private oauthHandoffKey;
     storeOAuthHandoff(connectorId: string, state: string, principalKey: string): Promise<void>;
     oauthCallbackView(connectorId: string, state: string | null): Promise<{
         registry: RegistryView;
         principalKey?: string;
     } | null>;
-    clearOAuthHandoff(connectorId: string, state: string | null): Promise<void>;
+    consumeOAuthHandoff(connectorId: string, state: string | null, principalKey: string): Promise<boolean>;
     /**
-     * Warn once per unusable result cap, at construction time — the same
-     * "runs fine but is surely unintended" channel as the insecure-config
-     * warnings in `createConnecta`. A rejected cap can't be honoured, and
-     * honouring it *approximately* is exactly the inversion issue #32 is about,
-     * so the value is dropped in favour of what it inherits and the operator is
-     * told which one is actually in force.
+     * Refuse an unusable result cap at construction, like every other
+     * structural mistake (INV-11). A rejected cap can't be honoured, and
+     * honouring it *approximately* is exactly the inversion issue #32 is about;
+     * falling back with a warning let a deployment boot on a value nobody
+     * chose.
      */
-    private checkResultCaps;
+    private assertResultCaps;
     /**
      * Warn once per convention violation at construction time. Static only —
      * never calls listTools() (remote connectors are lazy/network); tool-level
@@ -211,7 +211,9 @@ export declare class Registry implements RegistryView {
     private checkConventions;
     listConnectors(): Connector[];
     getConnector(id: string): Connector | undefined;
-    contextFor(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions): ConnectorContext;
+    getResourceConnector(id: string): Connector | undefined;
+    canReadConnectorSkills(id: string): boolean;
+    contextFor(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions, scope?: RegistryScope): ConnectorContext;
     admitCall(id: string, input: {
         toolName: string;
         args: unknown;
@@ -220,48 +222,39 @@ export declare class Registry implements RegistryView {
     /** Connector totals across root and personal controllers; health removes ids. */
     callAdmissionSnapshot(): Record<string, ConnectorCallAdmissionSnapshot>;
     /**
-     * Payload-free drift counts for the open health endpoint, so `connecta
-     * doctor` can report a stale allowlist without asking any downstream
-     * anything. Only connectors that ship a vetted manifest *and* have already
-     * served a refresh *in this runtime* appear — a process or isolate that has
-     * answered no catalog request yet honestly reports nothing, and drift is not
-     * persisted the way the catalog itself is.
-     *
-     * Every report is rebuilt by {@link boundedCatalogDrift} on the way out:
-     * `Connector.catalogDrift()` is the open plugin seam, and this snapshot is
-     * serialized into an unauthenticated response.
+     * The drift a connector last showed in this runtime: the registry's own
+     * observation against a connector's `classification`, otherwise whatever
+     * the connector's `catalogDrift()` seam reports, bounded either way.
      */
-    catalogDriftSnapshot(): Record<string, CatalogDriftReport>;
-    /**
-     * Turn the observation a refresh just took into at most one activity event.
-     *
-     * Emitted on change rather than on every refresh: an identical report every
-     * TTL is a heartbeat, not news, and the current counts are already on
-     * connector status. A first observation that is clean is not an event
-     * either — nothing moved — but a later return to clean is, because "the
-     * drift is gone" is exactly what an operator watching the timeline is
-     * waiting for.
-     */
-    private observeCatalogDrift;
+    private catalogDriftOf;
     /** Reject queued/future downstream admission; active permits release safely. */
     closeCallAdmission(): void;
     /**
-     * Reserve capacity and write one ASCII paging envelope in this runtime.
+     * Reserve capacity and write one ASCII paging envelope.
+     *
+     * `chunks[n]` lands on `resultKeys.chunk(id, n)` inside `partition` — the
+     * layout connecta.result reads back, so a page fetches only the chunks it covers
+     * instead of the whole stored result (issue #540). Chunking is a read-cost
+     * decision, not a capacity one: however many keys an envelope occupies, it
+     * is one stash entry charged its total ASCII length.
      *
-     * `chunks[0]` lands on `<prefix><key>` and `chunks[n]` on `<prefix><key>#<n>`
-     * — the layout get_result reads back, so a page fetches only the chunks it
-     * covers instead of the whole stored result (issue #540). Chunking is a
-     * read-cost decision, not a capacity one: however many keys an envelope
-     * occupies, it is one stash entry charged its total ASCII length.
+     * The bounds are the deployment's, not this isolate's. Every charge is a
+     * row in one ledger record in storage, booked by compare-and-set before any
+     * chunk is written, so every isolate and process sharing the store sees the
+     * same entries and bytes. A charge leaves the ledger just after its
+     * result's deadline, which every chunk's TTL ends by; the storage TTL
+     * reclaims the rows themselves.
      */
-    stashResult(key: string, chunks: readonly string[], ttlSeconds: number, prefix?: string): Promise<boolean>;
+    stashResult(id: string, chunks: readonly string[], ttlSeconds: number, partition?: string): Promise<boolean>;
     /**
-     * Storage namespaced to the meta-tool result store (`results:` prefix), kept
-     * separate from any connector's `conn:<id>:` namespace. Backs get_result.
+     * Storage namespaced to the root result partition, kept separate from any
+     * connector's namespace. Backs connecta.result.
      */
+    resultIdentity(): ResultIdentity;
+    recheckResultAccess(_address: string, _classification: "read" | "write", _signal?: AbortSignal): Promise<boolean>;
     resultsStorage(): KVStorage;
     credentialUiAvailable(): boolean;
-    bindOAuthHandoff(): Promise<void>;
+    bindOAuthHandoff(id: string, authorizationUrl: string, principalKey?: string): Promise<void>;
     observedOutputSchema(connectorId: string, definition: ToolDef): ToolDef["outputSchema"] | undefined;
     observeOutputShape(connectorId: string, definition: ToolDef, value: unknown): void;
     /** Resolve "<connectorId>.<toolName>" → connector + tool name. */
@@ -269,89 +262,33 @@ export declare class Registry implements RegistryView {
         connector: Connector;
         toolName: string;
     } | null;
-    private catalogKey;
-    private catalogChunkKey;
-    private validCatalogTools;
-    private validCatalogManifest;
-    private parseCatalogManifest;
-    private splitCatalogChunks;
-    private readCatalog;
-    private storeCatalog;
-    private deleteCatalog;
-    private catalogGeneration;
-    private advanceCatalogGeneration;
+    /** Compare only the fingerprints accepted in this exact cache partition. */
+    private recordCatalogDrift;
+    private loadDownstreamTools;
+    /** The served catalog excludes control-character names; raw caches stay complete. */
+    private acceptToolNames;
+    /** Observe intake once, never while serving an older cached listing. */
+    private observeDroppedToolNames;
     /**
-     * Keep this isolate's writes and invalidations ordered. Without the queue, an
-     * old refresh can finish its storage.set after a credential change deletes
-     * the catalog and resurrect the pre-change listing.
+     * One connector's catalog as served: the cached downstream facts, classified
+     * on every read by the connector's `classification`, into fresh objects.
+     * Safety is derived here and nowhere else, so no cache layer can carry a
+     * stale verdict — from an older review, an older release, or a stale
+     * fallback — and nothing a caller or decorator does to a served tool reaches
+     * the next read.
      */
-    private enqueueCatalogMutation;
-    private refreshToolsWithContext;
-    /**
-     * Whether a refresh may still enter the shared cache layers: its generation
-     * is current, and the flight it runs in has been neither abandoned nor
-     * outlived its bound. Asked at each publication point, since listing and
-     * snapshotting both yield, and a late result must never overwrite the one a
-     * fresh attempt published in the meantime.
-     */
-    private mayPublish;
-    /**
-     * Publish one shared refresh before starting its connector work. The first
-     * caller owns the scope and signal, and the flight lives `boundMs` from now
-     * at most; every later caller joins the result without gaining access to
-     * that context. A flight found past its bound is abandoned here, and this
-     * caller starts the fresh attempt.
-     */
-    private startCatalogRefresh;
-    /**
-     * Give up on a flight that outlived its bound. Later readers start a fresh
-     * attempt, its joiners are told to, and nothing its owner lists from now on
-     * reaches a cache. The owner's work is left alone: it belongs to another
-     * request, which nothing here may reach into, and it can no longer publish.
-     */
-    private abandonCatalogRefresh;
-    /**
-     * Wait on another caller's flight, no longer than its bound. Succeeds with
-     * its tools, or with `undefined` when it will not answer for this caller —
-     * past its bound, when this waiter abandons it, or failed for its owner
-     * alone — so the caller makes a fresh attempt. The timer is this waiter's
-     * own: on workerd it is what keeps a request that waits on another alive,
-     * and bounded.
-     */
-    private joinCatalogRefresh;
-    /** Force a live listTools refresh and replace both catalog cache layers. */
-    private refreshTools;
-    private observeCatalogAccess;
-    /**
-     * Start or join one shared refresh. A newly deferred task owns its scope,
-     * deadline, and teardown; no inbound signal or request scope crosses into it.
-     */
-    private deferCatalogRefresh;
-    /** Cached listTools with in-memory + persisted serializable catalog layers. */
     private loadTools;
-    /**
-     * Coalesce one connector's catalog traversal inside one inbound request. The
-     * WeakMap neither roots the request scope nor lets its connector context
-     * escape into another request; settled entries are also removed eagerly.
-     *
-     * The read owns its signal, and each caller waits under its own: one that
-     * is cancelled while others wait leaves with its own failure, and the read
-     * is cancelled only when every caller has gone (src/runtime/shared-read.ts).
-     *
-     * The deployment-wide flight below this layer coalesces the actual live
-     * refresh across requests. Its owner's context governs the listing, and its
-     * owner's deadline bounds it; later callers join only its result, never its
-     * request scope, and a failure that was the owner's alone sends them to a
-     * fresh attempt rather than to them.
-     */
-    getTools(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions, readOptions?: CatalogReadOptions): Promise<ToolDef[]>;
+    private publishUnreviewedTool;
+    /** Construction-only view for the secret-free static config description. */
+    describeStaticTools(id: string): ToolDef[] | undefined;
+    private validateClassification;
+    getTools(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions, scope?: RegistryScope): Promise<ToolDef[]>;
     credentialDriftFor(id: string): Promise<string | undefined>;
+    /** Age of a complete cache entry; reads never refresh it. */
+    catalogAgeMs(id: string): number | null;
     /** Best-effort connector status for the operator UI. */
-    statusFor(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions): Promise<ConnectorStatus>;
-    private markCatalogInvalid;
-    private deleteStoredCatalog;
-    /** Drop a connector's cached tool list (e.g. after auth completes). */
+    statusFor(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions, scope?: RegistryScope): Promise<ConnectorStatus>;
+    /** Rotate the storage generation; in-flight old readers cannot republish it. */
     invalidate(id: string): void;
-    /** Drop both in-memory and persisted tool catalogs. */
     invalidateStored(id: string): Promise<void>;
 }