@zackbart/connecta 0.34.1 → 0.36.0

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 {};

package/dist/provider.js

@@ -1,10 +1,7 @@
-// The one shape every maintained provider takes. Deliberately transport-free:
-// it imports neither `remoteMcp()` nor `api()`, so an `api()` provider does not
-// acquire the MCP client, OAuth, or Effect graph by using it, and a hosted
-// provider does not acquire `api()`. Its runtime imports validate plain
-// options and reviewed classification, with no I/O.
+// Transport-free maintained API provider definitions and construction validation.
 import { array, assertKnownOptions, ConfigError, fn, keys, object, opaque, required, whole, } from "./config-schema.js";
-import { reviewedClassification } from "./catalog-drift.js";
+import { aliasCallIdentity } from "./provider-call-facts.js";
+import { isConnectorCallErrorCode } from "./errors.js";
 const budget = {
     ...object({
         kind: required(opaque({
@@ -64,10 +61,75 @@ export const PROVIDER_COMMON = {
     callAdmission: CALL_ADMISSION,
 };
 const PROVIDER_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
-const KINDS = new Set(["mcp", "api", "composed", "dual"]);
+const BLOCK_KEY = /^[a-z][a-z0-9:-]*$/;
+/** A when-block marker, alone on its line. */
+const BLOCK_MARKER = /^<!--\s*(?:when:\s*([a-z][a-z0-9:-]*)|end)\s*-->$/;
 function nonEmpty(value) {
     return typeof value === "string" && value.trim() !== "";
 }
+/**
+ * Render a guide's selected when-blocks, or, with no selection, check them
+ * and return their keys. Markers stand alone on their lines and never nest.
+ * Removing an unselected block also removes the blank line it leaves, so
+ * paragraphs and tight lists keep their spacing.
+ */
+function guideBlocks(content, selected) {
+    const keys = new Set();
+    const kept = [];
+    let open;
+    let seam = false;
+    for (const line of content.split("\n")) {
+        const marker = BLOCK_MARKER.exec(line.trim());
+        if (marker) {
+            if (marker[1] !== undefined ? open !== undefined : open === undefined) {
+                throw new Error("when-blocks must open and close in turn, unnested");
+            }
+            if (marker[1] !== undefined)
+                keys.add((open = marker[1]));
+            else {
+                seam = selected !== undefined && !selected.has(open);
+                open = undefined;
+            }
+            continue;
+        }
+        if (/<!--\s*(?:when:|end\s*-->)/.test(line))
+            throw new Error("a when-block marker stands alone on its line");
+        if (open !== undefined && !selected?.has(open))
+            continue;
+        if (seam && !line.trim() && (kept.length === 0 || !kept.at(-1).trim()))
+            continue;
+        seam = false;
+        kept.push(line);
+    }
+    if (open !== undefined)
+        throw new Error(`the when-block "${open}" is never closed`);
+    return { text: kept.join("\n").trim(), keys };
+}
+/** A frozen copy: kit facts are review evidence `providers:generate` reads. */
+function kitFacts(kit) {
+    if (kit.errors && !isConnectorCallErrorCode(kit.errors.unknownId)) {
+        throw new Error("Provider kit errors.unknownId must be a ConnectorCallErrorCode.");
+    }
+    return Object.freeze({
+        operations: Object.freeze([...kit.operations]),
+        ...(kit.pageSize ? { pageSize: Object.freeze({ ...kit.pageSize }) } : {}),
+        ...(kit.hatch
+            ? {
+                hatch: Object.freeze({
+                    name: kit.hatch.name,
+                    verdicts: Object.freeze({ ...kit.hatch.verdicts }),
+                    ...(kit.hatch.paging ? { paging: kit.hatch.paging } : {}),
+                    ...(kit.hatch.fieldsRoot ? { fieldsRoot: kit.hatch.fieldsRoot } : {}),
+                }),
+            }
+            : {}),
+        ...(kit.errors
+            ? { errors: Object.freeze({ ...kit.errors, conflicts: Object.freeze([...kit.errors.conflicts]) }) }
+            : {}),
+        ...(kit.idempotencyKey !== undefined ? { idempotencyKey: kit.idempotencyKey } : {}),
+        ...(kit.refusesWithheld ? { refusesWithheld: true } : {}),
+    });
+}
 /**
  * Define a maintained provider: one validated description and one factory.
  *
@@ -83,23 +145,37 @@ export function defineProvider(definition) {
     if (!nonEmpty(definition.title)) {
         throw new Error(`${label} requires a non-empty title.`);
     }
-    if (!KINDS.has(definition.kind)) {
-        throw new Error(`${label} kind must be "mcp", "api", "composed", or "dual".`);
-    }
+    if (definition.kind !== "api")
+        throw new Error(`${label} kind must be "api".`);
     if (!nonEmpty(definition.skill?.content) || !nonEmpty(definition.skill.instructionsHeading)) {
         throw new Error(`${label} skill requires non-empty content and instructionsHeading.`);
     }
-    if (definition.classify !== undefined && definition.kind === "api") {
-        throw new Error(`${label} is an api() provider; annotate each authored tool instead of classifying a hosted catalog.`);
-    }
+    if (Object.hasOwn(definition, "classify"))
+        throw new Error(`${label} classify was removed; use ConnectaConfig.classification.`);
     if (!definition.options?.shape && !definition.options?.variants) {
         throw new Error(`${label} requires a closed options shape from optionsOf().`);
     }
-    // A validated, deep-frozen copy. The definition is what build and check
-    // tools read and what every later connector classifies with, so nothing
-    // reachable from it may change a verdict after review: neither the
-    // caller's original object nor a write through `factory.definition`.
-    const classify = definition.classify === undefined ? undefined : reviewedClassification(definition.classify, label);
+    const blocks = definition.blocks;
+    if (blocks !== undefined &&
+        (!Array.isArray(blocks.keys) ||
+            blocks.keys.length === 0 ||
+            !blocks.keys.every((key) => typeof key === "string" && BLOCK_KEY.test(key)) ||
+            new Set(blocks.keys).size !== blocks.keys.length ||
+            typeof blocks.select !== "function")) {
+        throw new Error(`${label} blocks require unique lowercase keys and a select function.`);
+    }
+    let used;
+    try {
+        used = guideBlocks(definition.skill.content).keys;
+    }
+    catch (error) {
+        throw new Error(`${label} skill: ${error instanceof Error ? error.message : String(error)}.`, { cause: error });
+    }
+    for (const key of used) {
+        if (!blocks?.keys.includes(key))
+            throw new Error(`${label} skill uses the when-block "${key}" its blocks omit.`);
+    }
+    // Freeze definition facts consumed by construction, generation and checks.
     if (typeof definition.create !== "function") {
         throw new Error(`${label} requires a create function.`);
     }
@@ -110,7 +186,8 @@ export function defineProvider(definition) {
             ...(definition.skill.fragments ? { fragments: Object.freeze(definition.skill.fragments) } : {}),
         }),
         ...(definition.bundle ? { bundle: Object.freeze({ ...definition.bundle }) } : {}),
-        ...(classify !== undefined ? { classify } : {}),
+        ...(blocks ? { blocks: Object.freeze({ keys: Object.freeze([...blocks.keys]), select: blocks.select }) } : {}),
+        ...(definition.kit ? { kit: kitFacts(definition.kit) } : {}),
     });
     const factoryName = `${frozen.name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())}()`;
     const factory = (id, options) => asProvider(frozen.name, frozen.options, id, options, (id, options) => {
@@ -133,7 +210,6 @@ export function defineProvider(definition) {
         const resolved = { ...options, purpose: options.purpose.trim() };
         const instructions = options.instructions?.trim();
         const connector = frozen.create(id, resolved, {
-            ...(frozen.classify !== undefined ? { classify: frozen.classify } : {}),
             connectorOptions: {
                 ...(options.readOnly !== undefined ? { readOnly: options.readOnly } : {}),
                 ...(options.authScope !== undefined ? { authScope: options.authScope } : {}),
@@ -142,7 +218,20 @@ export function defineProvider(definition) {
             },
             usageGuide(input) {
                 const heading = input.heading ?? `${frozen.title} usage`;
-                const body = [...input.context, frozen.skill.content.trim()].join("\n\n");
+                let guide = frozen.skill.content.trim();
+                if (frozen.blocks) {
+                    const { keys, select } = frozen.blocks;
+                    const selected = select(resolved);
+                    if (!Array.isArray(selected))
+                        throw new Error(`${at} requires blocks.select() to return an array of keys.`);
+                    for (const key of selected) {
+                        if (!keys.includes(key)) {
+                            throw new Error(`${at} requires blocks.select() to return declared keys; it returned ${String(key)}.`);
+                        }
+                    }
+                    guide = guideBlocks(frozen.skill.content, new Set(selected)).text;
+                }
+                const body = [...input.context, guide].join("\n\n");
                 return {
                     content: `# ${heading}\n\n${body}\n` +
                         (instructions ? `\n## ${frozen.skill.instructionsHeading}\n\n${instructions}\n` : ""),
@@ -156,28 +245,13 @@ export function defineProvider(definition) {
         }
         return connector;
     });
-    // Frozen whole: build and check tools read `definition` to learn what the
-    // factory classifies, so neither replacing nor deleting it may take effect.
-    return Object.freeze(Object.assign(factory, { definition: frozen }));
-}
-/**
- * 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 function asProviderFactory(definition) {
-    const frozen = defineProvider(definition).definition;
-    const create = definition.create;
-    const factory = (id, options) => asProvider(frozen.name, frozen.options, id, options, create);
-    Object.defineProperty(factory, "name", {
-        value: frozen.name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase()),
-    });
+    // Build and check tools rely on this definition remaining attached.
     return Object.freeze(Object.assign(factory, { definition: frozen }));
 }
 /**
  * Build a maintained provider's connector: refuse unknown options and
  * accessors by path before the builder reads any of them, then stamp the
- * provider onto its description, so the operator surface can say "Linear"
+ * provider onto its description, so the operator surface can say "Stripe"
  * rather than "remote MCP". This is the same construction path defineProvider
  * uses; existing constructors retain their provider-specific option policy.
  */
@@ -202,12 +276,15 @@ function asProvider(provider, shape, id, options, build) {
     const ownReadOnly = Object.getOwnPropertyDescriptor(connector, "readOnly");
     // Keep the receiver of prototype methods (including private fields). When
     // the description cannot be replaced, inherit the whole connector instead
-    // of copying it: decorators may inherit their id, methods, and review.
+    // of copying it: decorators may inherit their id and methods.
     const stamped = Object.isExtensible(connector) &&
         (!ownDescribe || ownDescribe.configurable) &&
         (options.readOnly === undefined || !ownReadOnly || ownReadOnly.configurable)
         ? connector
         : Object.create(connector);
+    // An inheriting stamp serves the connector itself, so it keeps its call identity.
+    if (stamped !== connector)
+        aliasCallIdentity(stamped, connector);
     if (options.readOnly !== undefined) {
         Object.defineProperty(stamped, "readOnly", { value: options.readOnly, enumerable: true, configurable: true });
     }