@zackbart/connecta 0.34.1 → 0.35.0

package/dist/provider-call.d.ts

@@ -0,0 +1,112 @@
+import { type ProviderRequest, type CallTool } from "./provider-call-facts.js";
+import type { ConnectorContext } from "./types.js";
+export interface ProviderCall {
+    requests: ProviderRequest[];
+    classification?: "read" | "write" | undefined;
+    /** The handler settled: its outcome may be reported, so nothing more leaves. */
+    closed: boolean;
+    /** The calls of api() boundaries entered beneath this one's handler. */
+    nested: ProviderCall[];
+    /** The call whose handler entered this one; undefined for the outermost. */
+    parent?: ProviderCall;
+}
+export interface LogicalCall {
+    target: object;
+    entered: CallTool;
+    boundaries: object[];
+    /** Every resource request dispatched under it, once per dispatch, from any ledger. */
+    sent: ProviderRequest[];
+    /** Auxiliary GET/HEAD dispatches without method overrides, apart from resource writes and auth POSTs. */
+    auxiliaryReads: ProviderRequest[];
+    /** A kit auxiliary declared as a read dispatched without physical read proof. */
+    nonReadAuxiliaryDispatched: boolean;
+}
+export declare function providerCallContext(ctx: ConnectorContext, classification?: "read" | "write"): ConnectorContext;
+/** Whether `ctx`'s call was entered by another api() boundary's handler. */
+export declare function nestedProviderCall(ctx: ConnectorContext): boolean;
+export declare function providerRequests(ctx: ConnectorContext): readonly ProviderRequest[] | undefined;
+/**
+ * Every request the ledgers of api() boundaries nested beneath `ctx`'s call
+ * recorded, at any depth: an inner call's 401 still decides the outer's
+ * write (Q8), whatever the outer handler made of the inner's failure.
+ */
+export declare function nestedProviderRequests(ctx: ConnectorContext): ProviderRequest[];
+/**
+ * End the call's ledger before its outcome is decided. A request still in
+ * flight already counts as dispatched; one that has not left yet (a sibling
+ * still reading its credential, say) is refused by {@link dispatchProviderRequest}
+ * and never leaves after the failure is reported.
+ */
+export declare function closeProviderCall(ctx: ConnectorContext): void;
+/**
+ * Refuse every request after its request scope ends, before credential reads
+ * and again immediately before dispatch. Resource requests also require an
+ * open call. Auxiliary requests (token mints, lookups) may outlive that call,
+ * but never their request.
+ */
+export declare function assertProviderCallOpen(ctx: ConnectorContext, provider: string, auxiliary: boolean): void;
+/** Record that a request leaves now; synchronous with the send that follows it. */
+export declare function dispatchProviderRequest(ctx: ConnectorContext | undefined, request: ProviderRequest, headers?: HeadersInit, method?: string | undefined): void;
+export declare function recordingFetch<T extends object>(send: T): T;
+export declare function isRecordingFetch(send: object | undefined): boolean;
+export declare function handoffProviderRequest(init: RequestInit, request: ProviderRequest): void;
+export declare function takeProviderHandoff(init: RequestInit): ProviderRequest | undefined;
+export declare function bindProviderResponse(response: object, request: ProviderRequest, owner: ProviderRequest | undefined): void;
+export declare function responseProviderRequest(response: object, owner: ProviderRequest): ProviderRequest | undefined;
+export declare function providerRequest(ctx: ConnectorContext, auxiliary: boolean, provider: string, sent?: {
+    method?: string;
+    key?: string;
+    classification?: "read" | "write";
+}): ProviderRequest;
+/**
+ * The invocation opens one logical call on the context it hands a connector,
+ * naming the exact object and `callTool` function it is about to invoke.
+ */
+export declare function openLogicalCall(ctx: ConnectorContext, target: object, entered: CallTool): LogicalCall;
+/**
+ * An api() or remoteMcp() boundary was entered under `ctx`'s logical call.
+ * `boundary` is the object it was built as, from its own closure, never `this`.
+ */
+export declare function enterProviderBoundary(ctx: ConnectorContext, boundary: object): void;
+/**
+ * Whether a failure's known mark holds for its whole logical call (INV-9).
+ * A boundary marks a write known only when every request it dispatched is
+ * proven unapplied, so the mark stands when that boundary owned the call
+ * ({@link ownsLogicalCall}) and at most one boundary was entered. A wrapper
+ * that composed several calls, or could send around them, never inherits an
+ * inner verdict.
+ */
+export declare function knownCallFailure(call: LogicalCall | undefined, error: unknown): boolean;
+/**
+ * Positive proof that a complete tracked call dispatched only auxiliaries,
+ * including a recorded resource read (positive GET/HEAD evidence). An
+ * authentication POST alone is not evidence of that call's resource work:
+ * token mints can be shared with callers whose ledgers did not send them.
+ * An empty resource ledger is not this proof: even a declared api() entry
+ * can report a timeout and recovery facts without recording any dispatch.
+ * Keep those calls conservative rather than inferring an auxiliary failure
+ * from the absence of a resource request. Wrappers and untracked boundaries
+ * cannot borrow an inner call's observations.
+ */
+export declare function onlyAuxiliaryRequests(call: LogicalCall | undefined): boolean;
+/**
+ * Whether reusing `key` with the exact original arguments cannot repeat any
+ * write of `ctx`'s logical call, the one basis for key-reuse advice (INV-9).
+ * It holds only when the call entered exactly one boundary, which owned it
+ * and tracks every request, and sent exactly one write, carrying `key`. A
+ * request counts as a read only with positive classification and a recorded
+ * GET or HEAD ({@link readRequest}). An inner request's key never speaks for a composite,
+ * a wrapper, a second write, or an earlier unrelated request.
+ */
+export declare function keyProtectsCall(call: LogicalCall | undefined, key: string | undefined): boolean;
+/** Positive read evidence, with GET/HEAD as #902's additional conservative bound. */
+export declare function readRequest(request: Pick<ProviderRequest, "classification" | "method">, headers?: HeadersInit): boolean;
+export declare function providerFetch(ctx: ConnectorContext, provider: string, auxiliary: boolean, send: typeof fetch): typeof fetch;
+/** Whether an invocation opened the logical call `ctx` belongs to; it then settles Q8 itself. */
+export declare function inLogicalCall(ctx: object): boolean;
+/**
+ * Every resource request dispatched under `ctx`'s logical call, from any
+ * ledger, nested ones included; undefined outside one.
+ */
+export declare function logicalCallRequests(ctx: object | undefined): readonly ProviderRequest[] | undefined;
+export { recordProviderResponse, tracksEveryRequest, tracksRequests, delegatesEachCall, providerBoundary, refusedStatus, vendorRefusal, authorizationFailure, unauthorizedAnswer, renewedAfterUnauthorized, refusalRequest, knownProviderFailure, isKnownProviderFailure, forgetProviderFailure, explainedUnauthorizedVerdict, explainsUnauthorized, settledWrite, isSettledWrite, type ProviderRequest, } from "./provider-call-facts.js";

package/dist/provider-call.js

@@ -0,0 +1,271 @@
+import { boundaryFor, delegatorFor, recordRequestField, recordProviderResponse, tracksRequests, isKnownProviderFailure, } from "./provider-call-facts.js";
+// One API call's request ledger in call services, and private failure
+// provenance. Each api() entry installs fresh services even if a direct caller
+// reuses its context concurrently. No request facts escape into agent or
+// operator records.
+import { Classification, ProviderLedger, LogicalLedger, recordedService, requestClosed, viewClosed, setViewService, callFromContext, contextView, viewLease, settleOnClose, } from "./runtime/call.js";
+import { callClassification } from "./call-classification.js";
+import { ConnectorCallError } from "./errors.js";
+export function providerCallContext(ctx, classification) {
+    const parent = recordedService(ctx, ProviderLedger);
+    const call = { requests: [], classification, closed: false, nested: [], ...(parent ? { parent } : {}) };
+    parent?.nested.push(call);
+    let view;
+    const lease = callFromContext(ctx, classification ?? callClassification(ctx) ?? "write", {
+        providerLedger: call,
+        ledger: {
+            open: ({ auxiliary, provider, method, key }) => providerRequest(view, auxiliary, provider, { method, ...(key === undefined ? {} : { key }) }),
+            dispatch: (request, headers, method) => dispatchProviderRequest(view, request, headers, method),
+        },
+    });
+    view = contextView(lease, ctx);
+    return view;
+}
+/** Whether `ctx`'s call was entered by another api() boundary's handler. */
+export function nestedProviderCall(ctx) {
+    return recordedService(ctx, ProviderLedger)?.parent !== undefined;
+}
+export function providerRequests(ctx) {
+    return recordedService(ctx, ProviderLedger)?.requests;
+}
+/**
+ * Every request the ledgers of api() boundaries nested beneath `ctx`'s call
+ * recorded, at any depth: an inner call's 401 still decides the outer's
+ * write (Q8), whatever the outer handler made of the inner's failure.
+ */
+export function nestedProviderRequests(ctx) {
+    const found = [];
+    const visit = (call) => {
+        for (const inner of call.nested) {
+            found.push(...inner.requests);
+            visit(inner);
+        }
+    };
+    const call = recordedService(ctx, ProviderLedger);
+    if (call)
+        visit(call);
+    return found;
+}
+/**
+ * End the call's ledger before its outcome is decided. A request still in
+ * flight already counts as dispatched; one that has not left yet (a sibling
+ * still reading its credential, say) is refused by {@link dispatchProviderRequest}
+ * and never leaves after the failure is reported.
+ */
+export function closeProviderCall(ctx) {
+    const call = recordedService(ctx, ProviderLedger);
+    if (call) {
+        const close = (current) => {
+            current.closed = true;
+            for (const child of current.nested)
+                close(child);
+        };
+        close(call);
+    }
+    viewLease(ctx)?.close();
+}
+/**
+ * Refuse every request after its request scope ends, before credential reads
+ * and again immediately before dispatch. Resource requests also require an
+ * open call. Auxiliary requests (token mints, lookups) may outlive that call,
+ * but never their request.
+ */
+export function assertProviderCallOpen(ctx, provider, auxiliary) {
+    if (requestClosed(ctx))
+        throw new ConnectorCallError("connector_call_failed", `This ${provider} request belongs to a request that has already ended, so it was not sent.`, { retryable: false });
+    if (auxiliary || (recordedService(ctx, ProviderLedger)?.closed !== true && !viewClosed(ctx)))
+        return;
+    throw new ConnectorCallError("connector_call_failed", `This ${provider} request belongs to a call that has already ended, so it was not sent.`, { retryable: false });
+}
+/** Record that a request leaves now; synchronous with the send that follows it. */
+export function dispatchProviderRequest(ctx, request, headers, method = request.method) {
+    if (ctx)
+        assertProviderCallOpen(ctx, request.provider, request.auxiliary);
+    if (request.dispatched)
+        throw new Error("Provider request already dispatched.");
+    if (hasMethodOverride(headers))
+        request.classification = "write";
+    recordRequestField(request, "method", method);
+    recordRequestField(request, "dispatched", true);
+    const logical = ctx && recordedService(ctx, LogicalLedger);
+    if (logical) {
+        if (!request.auxiliary)
+            logical.sent.push(request);
+        // Auxiliary ownership is the provider's read declaration; the served
+        // classification may still be write. Bind method/header evidence now,
+        // so token POSTs and overridden GETs cannot supply this proof later.
+        else if (method !== undefined && readRequest({ classification: "read", method }, headers))
+            logical.auxiliaryReads.push(request);
+        else if (request.blocksAuxiliaryProof)
+            logical.nonReadAuxiliaryDispatched = true;
+    }
+}
+// Only a fetch that records physical sends may accept an unsent handoff.
+const recordingFetches = new WeakSet();
+export function recordingFetch(send) {
+    recordingFetches.add(send);
+    return send;
+}
+export function isRecordingFetch(send) {
+    return send !== undefined && recordingFetches.has(send);
+}
+const handoffs = new WeakMap();
+export function handoffProviderRequest(init, request) {
+    if (request.dispatched)
+        throw new Error("Provider request already dispatched.");
+    handoffs.set(init, request);
+}
+export function takeProviderHandoff(init) {
+    // Consume before any await: a read replay or another call cannot take it.
+    const request = handoffs.get(init);
+    handoffs.delete(init);
+    return request?.dispatched ? undefined : request;
+}
+// Observation only: a mapper must name the physical reply it actually received.
+const responseRequests = new WeakMap();
+export function bindProviderResponse(response, request, owner) {
+    if (owner)
+        responseRequests.set(response, { request, owner });
+}
+export function responseProviderRequest(response, owner) {
+    const answer = responseRequests.get(response);
+    return answer?.owner === owner ? answer.request : undefined;
+}
+/** Override presence invalidates read evidence, whatever value the header carries. */
+function hasMethodOverride(headers) {
+    const sent = new Headers(headers);
+    return ["x-http-method-override", "x-http-method", "x-method-override"].some((name) => sent.has(name));
+}
+export function providerRequest(ctx, auxiliary, provider, sent = {}) {
+    const request = {
+        dispatched: false,
+        auxiliary,
+        provider,
+        classification: recordedService(ctx, ProviderLedger)?.classification ??
+            recordedService(ctx, Classification) ??
+            callClassification(ctx),
+        ...sent,
+    };
+    recordedService(ctx, ProviderLedger)?.requests.push(request);
+    return request;
+}
+/**
+ * The invocation opens one logical call on the context it hands a connector,
+ * naming the exact object and `callTool` function it is about to invoke.
+ */
+export function openLogicalCall(ctx, target, entered) {
+    const call = {
+        target,
+        entered,
+        boundaries: [],
+        sent: [],
+        auxiliaryReads: [],
+        nonReadAuxiliaryDispatched: false,
+    };
+    setViewService(ctx, LogicalLedger, call);
+    return call;
+}
+/**
+ * An api() or remoteMcp() boundary was entered under `ctx`'s logical call.
+ * `boundary` is the object it was built as, from its own closure, never `this`.
+ */
+export function enterProviderBoundary(ctx, boundary) {
+    recordedService(ctx, LogicalLedger)?.boundaries.push(boundary);
+}
+/**
+ * Whether a failure's known mark holds for its whole logical call (INV-9).
+ * A boundary marks a write known only when every request it dispatched is
+ * proven unapplied, so the mark stands when that boundary owned the call
+ * ({@link ownsLogicalCall}) and at most one boundary was entered. A wrapper
+ * that composed several calls, or could send around them, never inherits an
+ * inner verdict.
+ */
+export function knownCallFailure(call, error) {
+    return call !== undefined && isKnownProviderFailure(error) && call.boundaries.length <= 1 && ownsLogicalCall(call);
+}
+/**
+ * Positive proof that a complete tracked call dispatched only auxiliaries,
+ * including a recorded resource read (positive GET/HEAD evidence). An
+ * authentication POST alone is not evidence of that call's resource work:
+ * token mints can be shared with callers whose ledgers did not send them.
+ * An empty resource ledger is not this proof: even a declared api() entry
+ * can report a timeout and recovery facts without recording any dispatch.
+ * Keep those calls conservative rather than inferring an auxiliary failure
+ * from the absence of a resource request. Wrappers and untracked boundaries
+ * cannot borrow an inner call's observations.
+ */
+export function onlyAuxiliaryRequests(call) {
+    const [boundary, ...others] = call?.boundaries ?? [];
+    return (call !== undefined &&
+        boundary !== undefined &&
+        others.length === 0 &&
+        tracksRequests(boundary) &&
+        ownsLogicalCall(call) &&
+        call.auxiliaryReads.some((request) => request.dispatched) &&
+        !call.nonReadAuxiliaryDispatched &&
+        !call.sent.some((request) => request.dispatched && !request.auxiliary));
+}
+/**
+ * Whether reusing `key` with the exact original arguments cannot repeat any
+ * write of `ctx`'s logical call, the one basis for key-reuse advice (INV-9).
+ * It holds only when the call entered exactly one boundary, which owned it
+ * and tracks every request, and sent exactly one write, carrying `key`. A
+ * request counts as a read only with positive classification and a recorded
+ * GET or HEAD ({@link readRequest}). An inner request's key never speaks for a composite,
+ * a wrapper, a second write, or an earlier unrelated request.
+ */
+export function keyProtectsCall(call, key) {
+    const [boundary, ...others] = call?.boundaries ?? [];
+    if (!call || key === undefined || boundary === undefined || others.length > 0 || !tracksRequests(boundary))
+        return false;
+    const writes = call.sent.filter((request) => !readRequest(request));
+    return ownsLogicalCall(call) && writes.length === 1 && writes[0]?.key === key;
+}
+/**
+ * The call's invoked object owns it: a boundary object invoked with the
+ * function recorded for it at construction, and that boundary was the one
+ * entered; or a declared delegator object, likewise. Only identities captured
+ * at construction, dispatch and entry decide it, so a wrapper that reassigns
+ * `callTool` mid-call, or a copy that shares a boundary's function, cannot
+ * borrow its standing.
+ */
+function ownsLogicalCall(call) {
+    const boundary = boundaryFor(call.target);
+    return ((boundary?.own === call.entered && boundary.boundary === call.boundaries[0]) ||
+        delegatorFor(call.target) === call.entered);
+}
+/** Positive read evidence, with GET/HEAD as #902's additional conservative bound. */
+export function readRequest(request, headers) {
+    const method = request.method?.toUpperCase();
+    return (request.classification === "read" &&
+        (method === "GET" || method === "HEAD") &&
+        (headers === undefined || !hasMethodOverride(headers)));
+}
+export function providerFetch(ctx, provider, auxiliary, send) {
+    return (input, init) => settleOnClose(ctx, async (signal) => {
+        const method = init?.method ?? (input instanceof Request ? input.method : "GET");
+        const request = providerRequest(ctx, auxiliary, provider, { method });
+        dispatchProviderRequest(ctx, request, init?.headers ?? (input instanceof Request ? input.headers : undefined));
+        const signals = [signal, init?.signal ?? (input instanceof Request ? input.signal : undefined)].filter((signal) => signal !== undefined && signal !== null);
+        const sent = signals.length ? { ...init, signal: AbortSignal.any(signals) } : init;
+        const response = await send(input, sent);
+        recordProviderResponse(request, response.status);
+        if (signal.aborted) {
+            void response.body?.cancel().catch(() => { });
+            throw signal.reason;
+        }
+        return response;
+    }, auxiliary);
+}
+/** Whether an invocation opened the logical call `ctx` belongs to; it then settles Q8 itself. */
+export function inLogicalCall(ctx) {
+    return recordedService(ctx, LogicalLedger) !== undefined;
+}
+/**
+ * Every resource request dispatched under `ctx`'s logical call, from any
+ * ledger, nested ones included; undefined outside one.
+ */
+export function logicalCallRequests(ctx) {
+    return ctx ? recordedService(ctx, LogicalLedger)?.sent : undefined;
+}
+export { recordProviderResponse, tracksEveryRequest, tracksRequests, delegatesEachCall, providerBoundary, refusedStatus, vendorRefusal, authorizationFailure, unauthorizedAnswer, renewedAfterUnauthorized, refusalRequest, knownProviderFailure, isKnownProviderFailure, forgetProviderFailure, explainedUnauthorizedVerdict, explainsUnauthorized, settledWrite, isSettledWrite, } from "./provider-call-facts.js";

package/dist/provider.d.ts

@@ -1,12 +1,6 @@
 import { type Field } from "./config-schema.js";
-import type { Connector, ConnectorCallAdmissionPolicy, ConnectorUsageGuide, ToolClassification } from "./types.js";
-/**
- * How a provider reaches its vendor: the vendor's hosted MCP server, an
- * `api()` connector over the vendor's HTTP API, one connector composing both
- * with an explicit operation ownership map, or `"dual"`: configuration selects the implementation, usually by `auth.type`. Mixpanel
- * uses explicit `via` because service accounts reach both implementations.
- */
-export type ProviderKind = "mcp" | "api" | "composed" | "dual";
+import { type ConnectorCallErrorCode } from "./errors.js";
+import type { Connector, ConnectorCallAdmissionPolicy, ConnectorUsageGuide } from "./types.js";
 /** Options every provider accepts, validated before `create` runs. */
 export interface ProviderOptions {
     /** What this connection is for and which decisions it answers. Required. */
@@ -96,15 +90,18 @@ export declare const PROVIDER_COMMON: {
     instructions: Field<unknown, unknown, true>;
     title: Field<unknown, unknown, true>;
     authScope: Field<unknown, unknown, true>;
-    maxResultBytes: Field<unknown, unknown, true>;
     purpose: Field<unknown, unknown, true>;
+    maxResultBytes: Field<unknown, unknown, true>;
 };
 /** The provider's maintained, connection-independent usage guide. */
 export interface ProviderSkill {
     /**
      * Markdown rendered after the heading and the connection context. It states
      * conventions the vendor's schemas cannot carry, and never varies by
-     * deployment.
+     * deployment. A standard guide (decision 0011, G) is `SKILL.md`'s body
+     * followed by its generated `## Conventions`; text that differs by
+     * implementation or option stands in `<!-- when: <key> -->` …
+     * `<!-- end -->` blocks the definition's `blocks` selects.
      */
     content: string;
     /** Heading for deployment instructions, such as `"Workspace instructions"`. */
@@ -112,6 +109,56 @@ export interface ProviderSkill {
     /** Exact generated guide fragments used by existing renderers. */
     fragments?: Readonly<Record<string, string>>;
 }
+/**
+ * The closed key set of a guide's `<!-- when: <key> -->` blocks and the pure
+ * selector that picks a connection's keys from its options (decision 0011,
+ * G2). Select only the blocks this API configuration uses.
+ */
+export interface ProviderGuideBlocks<O> {
+    readonly keys: readonly string[];
+    /** The keys whose blocks this connection renders, in any order. */
+    select(options: Readonly<O>): readonly string[];
+}
+/**
+ * Facts the provider kit (decision 0010) declares for `providers:generate`:
+ * `drift.json`'s `generated.operations` and the guide's Conventions. Plain
+ * data, never read at runtime. The kit's `defineApiProvider` sets them.
+ */
+export interface ProviderKitFacts {
+    /** `manifest(vendor)`: every operation the provider's tools send, as `"METHOD /path"`. */
+    readonly operations: readonly string[];
+    /** The `limit` default and maximum every paged read declares. */
+    readonly pageSize?: {
+        readonly default: number;
+        readonly max: number;
+    };
+    /** The hatch's tool prefix and its reviewed verdict per `"METHOD /path"`. */
+    readonly hatch?: {
+        readonly name: string;
+        readonly verdicts: Readonly<Record<string, "read" | "write" | "destructive" | "refuse">>;
+        /** Separate-cursor paging opts into the generated hatch paging convention. */
+        readonly paging?: "argument" | "parameter";
+        readonly fieldsRoot?: string;
+    };
+    /**
+     * The vendor's declared error meanings, for the Errors convention: the code
+     * an unknown id fails with, whether it proves absence, and each documented
+     * conflict source.
+     */
+    readonly errors?: {
+        readonly unknownId: ConnectorCallErrorCode;
+        readonly provesAbsence: boolean;
+        readonly conflicts: readonly string[];
+    };
+    /** Whether a write takes an idempotency key the vendor honors, checked against the built tools. */
+    readonly idempotencyKey?: boolean;
+    /**
+     * Set only when the hatch refuses a write carrying a withheld placeholder
+     * value; the Withheld values convention promises exactly that. The kit sets
+     * it for its standard hatch; kit write builders refuse the same markers.
+     */
+    readonly refusesWithheld?: true;
+}
 /** Connection facts a provider renders around its maintained guide. */
 export interface ProviderGuideInput {
     /**
@@ -128,8 +175,6 @@ export interface ProviderGuideInput {
 }
 /** What `defineProvider()` hands `create` after validating its options. */
 export interface ProviderContext {
-    /** The definition's reviewed classification, for `remoteMcp({ classify })`. */
-    readonly classify?: ToolClassification;
     /**
      * Common connector options the deployment set, and only those, ready to
      * spread into `remoteMcp()` or `api()` options.
@@ -150,26 +195,23 @@ export interface ProviderDefinition<O extends ProviderOptions> {
     name: string;
     /** Vendor display name, and the default guide heading. */
     title: string;
-    kind: ProviderKind;
+    kind: "api";
     skill: ProviderSkill;
     /** Maintained display name in the generated README inventory. */
     readme?: string;
-    /** Reviewed build facts; generation never raises an observed cap. */
+    /** Reviewed build facts: the bundle report's baseline, never a cap. */
     bundle?: {
         baselineGzip: number;
-        maxGzip: number;
+        /** @deprecated Ignored: provider entries are reported, not capped. */
+        maxGzip?: number;
         note?: string;
     };
     /** Closed factory options, declared with `optionsOf<O>()` for key parity. */
     options: Field<unknown, unknown>;
-    /**
-     * Reviewed classification of the vendor's hosted MCP catalog. Hosted,
-     * composed, and dual providers pass it to `remoteMcp({ classify })` through
-     * `ProviderContext.classify`, so the verdicts that classify live tools and
-     * the record a drift check reads cannot disagree. `api()` providers annotate
-     * each tool they author and must omit it.
-     */
-    classify?: ToolClassification;
+    /** Required when the guide holds `<!-- when: <key> -->` blocks. */
+    blocks?: ProviderGuideBlocks<O>;
+    /** Set by the provider kit; see `ProviderKitFacts`. */
+    kit?: ProviderKitFacts;
     /**
      * Build the connector. Runs synchronously at construction after its closed
      * options and common values are validated. Throw here for provider-specific
@@ -190,12 +232,4 @@ export interface ProviderFactory<O extends ProviderOptions> {
  * so a deployment never boots in the wrong shape (INV-11).
  */
 export declare function defineProvider<O extends ProviderOptions>(definition: ProviderDefinition<O>): ProviderFactory<O>;
-/**
- * Attach the same validated definition to an existing provider constructor.
- * Its option policy stays in its builder during the mechanical folder move;
- * adopting defineProvider's common-value policy is a separate conversion.
- */
-export declare function asProviderFactory<O extends ProviderOptions>(definition: Omit<ProviderDefinition<O>, "create"> & {
-    create(id: string, options: Readonly<O>): Connector;
-}): ProviderFactory<O>;
 export {};