@rafads/plugin-openapi 1.5.38

package/dist/sdk/spec-blob-migration.d.ts

@@ -0,0 +1,7 @@
+import { Effect } from "effect";
+import { type SqliteDataMigrationClient } from "@rafads/sdk/core";
+/** Registry entry for the boot-time data-migration ledger. */
+export declare const openApiSpecBlobDataMigration: {
+    name: string;
+    run: (client: SqliteDataMigrationClient) => Effect.Effect<void, import("@rafads/sdk/core").DataMigrationError, never>;
+};

package/dist/sdk/spec-blob.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/spec-format.d.ts

@@ -0,0 +1,36 @@
+import type { Layer } from "effect";
+import { Effect } from "effect";
+import type { HttpClient } from "effect/unstable/http";
+import type { Authentication } from "./types";
+import type { OpenApiIntegrationConfig } from "./config";
+import type { KeepPathItem } from "./split";
+import { OpenApiParseError } from "./errors";
+export interface SpecFetchCredentials {
+    readonly headers?: Record<string, string>;
+    readonly queryParams?: Record<string, string>;
+}
+export interface SpecFetchInput {
+    readonly urls: readonly string[];
+    readonly credentials?: SpecFetchCredentials;
+    readonly httpClientLayer: Layer.Layer<HttpClient.HttpClient, never, never>;
+}
+export interface DerivedIdentity {
+    readonly slug: string;
+    readonly name: string;
+    readonly description?: string;
+}
+export interface ConvertedSpec {
+    readonly specText: string;
+    readonly specUrl?: string;
+    readonly baseUrl?: string;
+    readonly authenticationTemplate?: readonly Authentication[];
+    readonly config?: Partial<OpenApiIntegrationConfig> & Readonly<Record<string, unknown>>;
+    readonly keepPathItem?: KeepPathItem;
+    readonly document?: unknown;
+}
+export interface SpecFormatAdapter {
+    readonly id: string;
+    readonly fetch: (input: SpecFetchInput) => Effect.Effect<ConvertedSpec, OpenApiParseError>;
+    readonly deriveIdentity?: (doc: unknown) => DerivedIdentity | null;
+}
+export declare const resolveSpecFormatAdapter: (adapters: readonly SpecFormatAdapter[], id: string | undefined) => Effect.Effect<SpecFormatAdapter | null, OpenApiParseError>;

package/dist/sdk/spec-format.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/split.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Structural splitter for large OpenAPI documents written in clean block YAML.
+ *
+ * The whole-document parse of a 37MB spec (Microsoft Graph: 16.5k operations,
+ * 8.2k schemas) builds a ~300MB JS tree that OOMs the 128MB Cloudflare Workers
+ * isolate. This splitter avoids ever holding that tree: it scans the text once,
+ * recording the byte range of each top-level key, each path-item (the indent-2
+ * entries under `paths:`), and each schema (the indent-4 entries under
+ * `components.schemas:`). The streaming compile then slices one item at a time,
+ * de-indents it back to column 0, hands the isolated fragment to a real YAML
+ * parser, and discards the result before moving on. Peak memory stays near the
+ * size of the largest single item plus the raw text, not the parsed whole.
+ *
+ * This is not a YAML reimplementation: it extracts safe byte ranges from a
+ * constrained document shape, then defers every actual parse to `js-yaml`. It
+ * is only valid for the block-YAML profile `isStreamableSpec` accepts (2-space
+ * block maps, top-level keys at column 0, no anchors/aliases/merge keys). Block
+ * scalars (`|` / `>`) in descriptions are tracked so their indented content is
+ * never mistaken for structure.
+ */
+export interface ByteRange {
+    readonly start: number;
+    readonly end: number;
+}
+export interface SpecStructure {
+    /** Raw spec text. Every range below indexes into this string. */
+    readonly text: string;
+    /** Byte ranges of the top-level keys that are not `paths` / `components`
+     *  (openapi, info, servers, tags, security, ...). Concatenated and parsed as
+     *  one small document for the head (servers, info). */
+    readonly headRanges: readonly ByteRange[];
+    /** One range per path-item: the indent-2 entries under `paths:`. */
+    readonly pathItems: readonly ByteRange[];
+    /** One range per schema entry: the indent-4 entries under
+     *  `components.schemas:`. */
+    readonly schemas: readonly ByteRange[];
+    /** Ranges of the indent-2 `components` subkeys we keep whole because they are
+     *  small and may be `$ref`'d by a kept operation (parameters / requestBodies /
+     *  responses / headers / links / securitySchemes). Excludes the huge `schemas`
+     *  (streamed and pruned separately) and `examples` (never referenced by a
+     *  binding). */
+    readonly smallComponentRanges: readonly ByteRange[];
+}
+/**
+ * Scan a document into its structural ranges. Pure and synchronous; never
+ * parses. Returns null when the document does not present the expected shape
+ * (no `paths:` block), so the caller can fall back to a whole-document parse.
+ */
+export declare const structuralSplit: (text: string) => SpecStructure | null;
+/**
+ * Parse a single indent-N entry range (a path-item or a schema) in isolation.
+ * Returns `[name, value]` where `name` is the entry's key and `value` its
+ * parsed body, or null when the fragment does not parse to a single-key map.
+ */
+export declare const parseEntry: (text: string, range: ByteRange, indent: number) => readonly [string, unknown] | null;
+/** Parse the concatenation of the head ranges into the document head (openapi,
+ *  info, servers, tags). Small; safe to materialize whole. */
+export declare const parseHead: (structure: SpecStructure) => Record<string, unknown>;
+/** Parse the small component subkeys (parameters / requestBodies / responses)
+ *  into a `components`-shaped object for `$ref` resolution. */
+export declare const parseSmallComponents: (structure: SpecStructure) => Record<string, unknown>;
+/**
+ * Accept only the block-YAML profile the splitter can safely slice: no tabs, no
+ * anchors/aliases, no merge keys, and a `paths:` block present. Block scalars
+ * are allowed (tracked during the scan). Conservative by design: a false
+ * negative just routes a spec through the whole-document parse.
+ */
+export declare const isStreamableSpec: (text: string) => boolean;
+/** Map each `components.schemas` entry name to its byte range, reading only the
+ *  key line (never parsing the schema body). The schema name is the raw YAML
+ *  key, which matches the trailing segment of a `#/components/schemas/<name>`
+ *  reference. */
+export declare const indexSchemas: (structure: SpecStructure) => ReadonlyMap<string, ByteRange>;
+/**
+ * Resolve the transitive closure of schemas referenced by `roots`, parsing each
+ * referenced schema once from its byte range (BFS over `$ref`s). Schemas not
+ * reachable from `roots` are never parsed, so peak memory tracks the kept
+ * subset rather than the full `components.schemas` map.
+ */
+export declare const collectReferencedSchemas: (structure: SpecStructure, index: ReadonlyMap<string, ByteRange>, roots: readonly unknown[]) => Record<string, unknown>;
+/** A path-item filter for the streaming compile: given a parsed path-item,
+ *  return the (possibly trimmed) value to keep, or null to drop the path
+ *  entirely. Applied per path-item by `streamOperationBindingsFromStructure`. */
+export type KeepPathItem = (path: string, pathItem: Record<string, unknown>) => Record<string, unknown> | null;

package/dist/sdk/store.d.ts

@@ -0,0 +1,49 @@
+import { Effect } from "effect";
+import { type StorageDeps, type StorageFailure } from "@rafads/sdk/core";
+import { OperationBinding } from "./types";
+export interface StoredOperation {
+    /** The integration slug this operation belongs to. */
+    readonly integration: string;
+    /** The tool name (the `<tool>` address segment) this operation backs. */
+    readonly toolName: string;
+    readonly binding: OperationBinding;
+    /** Resolved tool description, persisted alongside the binding so the serve
+     *  path can rebuild the tool def without re-parsing the spec. */
+    readonly description?: string;
+}
+/** Blob key for a spec's content hash. Content-addressed so re-puts are
+ *  idempotent and identical specs share one blob per partition. */
+export declare const specBlobKey: (specHash: string) => string;
+/** Blob key for a spec's compiled `#/$defs/*` schemas, keyed by the same
+ *  content hash as the spec. The serve path reads this instead of re-parsing
+ *  the (potentially multi-MB) spec to rebuild the shared `definitions`. */
+export declare const defsBlobKey: (specHash: string) => string;
+export interface OpenapiStore {
+    /** Replace all stored operations for an integration. */
+    readonly putOperations: (integration: string, operations: readonly StoredOperation[]) => Effect.Effect<void, StorageFailure>;
+    /** Append operations without clearing existing ones. The caller is
+     *  responsible for `removeOperations` first when doing a full rebuild. Used
+     *  by the streaming compile path, which persists operations chunk by chunk so
+     *  a huge spec's bindings are never all materialized at once. */
+    readonly appendOperations: (integration: string, operations: readonly StoredOperation[]) => Effect.Effect<void, StorageFailure>;
+    /** Look up one operation by integration + tool name. */
+    readonly getOperation: (integration: string, toolName: string) => Effect.Effect<StoredOperation | null, StorageFailure>;
+    /** List every stored operation for an integration. */
+    readonly listOperations: (integration: string) => Effect.Effect<readonly StoredOperation[], StorageFailure>;
+    /** Drop all stored operations for an integration. */
+    readonly removeOperations: (integration: string) => Effect.Effect<void, StorageFailure>;
+    /** Persist resolved spec text under its content hash. Org-owned and
+     *  content-addressed; never removed on integration removal because another
+     *  integration in the tenant may share the hash. */
+    readonly putSpec: (specHash: string, specText: string) => Effect.Effect<void, StorageFailure>;
+    /** Load spec text by content hash; null when no blob exists. */
+    readonly getSpec: (specHash: string) => Effect.Effect<string | null, StorageFailure>;
+    /** Persist the compiled `#/$defs/*` JSON for a spec under its content hash.
+     *  Content-addressed like the spec blob; lets the serve path serve the shared
+     *  `definitions` without re-parsing the spec. */
+    readonly putDefs: (specHash: string, defsJson: string) => Effect.Effect<void, StorageFailure>;
+    /** Load the compiled `#/$defs/*` JSON by content hash; null when no blob
+     *  exists (legacy rows added before the defs blob). */
+    readonly getDefs: (specHash: string) => Effect.Effect<string | null, StorageFailure>;
+}
+export declare const makeDefaultOpenapiStore: ({ pluginStorage, blobs }: StorageDeps) => OpenapiStore;

package/dist/sdk/store.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/streaming-response.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/tool-row-projection.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/types.d.ts

@@ -0,0 +1,352 @@
+import { Schema } from "effect";
+import { type OAuthAuthentication } from "@rafads/sdk/shared";
+import { type ApiKeyAuthMethod, type ApiKeyAuthTemplate } from "@rafads/sdk/http-auth";
+export { TOKEN_VARIABLE } from "@rafads/sdk/http-auth";
+export type APIKeyAuthentication = ApiKeyAuthMethod;
+/** Every method is keyed by `kind` — `kind: "oauth2"` | `kind: "apikey"`. */
+export type Authentication = OAuthAuthentication | APIKeyAuthentication;
+/** What auth inputs accept: oauth templates (wire-typed: plain slug) plus the
+ *  request-shaped apikey dialect (`type: "apiKey"`, headers/queryParams
+ *  records) — the ONE apikey authoring shape. Stored configs and the catalog
+ *  read as canonical placements; `apiKeyAuthTemplateFromMethod` serializes
+ *  them back for read-modify-write flows. */
+export type OAuthAuthenticationInput = Omit<OAuthAuthentication, "slug"> & {
+    readonly slug: string;
+};
+export type AuthenticationInput = OAuthAuthenticationInput | ApiKeyAuthTemplate;
+/** Expand the request-shaped dialect into canonical placements and brand the
+ *  oauth slugs. A dialect entry without a slug gets a blank one —
+ *  `mergeAuthTemplates` backfills `custom_<id>`. */
+export declare const normalizeOpenApiAuthInputs: (inputs: readonly AuthenticationInput[]) => readonly Authentication[];
+export declare const OperationId: Schema.brand<Schema.String, "OperationId">;
+export type OperationId = typeof OperationId.Type;
+export declare const HttpMethod: Schema.Literals<readonly ["get", "put", "post", "delete", "patch", "head", "options", "trace"]>;
+export type HttpMethod = typeof HttpMethod.Type;
+export declare const ParameterLocation: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+export type ParameterLocation = typeof ParameterLocation.Type;
+export declare const OperationParameter: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly location: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+    readonly required: Schema.Boolean;
+    readonly schema: Schema.OptionFromOptional<Schema.Unknown>;
+    readonly style: Schema.OptionFromOptional<Schema.String>;
+    readonly explode: Schema.OptionFromOptional<Schema.Boolean>;
+    readonly allowReserved: Schema.OptionFromOptional<Schema.Boolean>;
+    readonly description: Schema.OptionFromOptional<Schema.String>;
+}>;
+export type OperationParameter = typeof OperationParameter.Type;
+/**
+ * OpenAPI 3.x `Encoding Object` (§4.8.15). Declared per-property inside a
+ * multipart/form-data or application/x-www-form-urlencoded request body.
+ *
+ * - `contentType` — for multipart, overrides the per-part `Content-Type`
+ *   header (e.g. `application/json` for a JSON-encoded metadata part).
+ * - `style` / `explode` / `allowReserved` — for form-urlencoded, control
+ *   array / object serialization the same way parameter-level style does.
+ */
+export declare const EncodingObject: Schema.Struct<{
+    readonly contentType: Schema.OptionFromOptional<Schema.String>;
+    readonly style: Schema.OptionFromOptional<Schema.String>;
+    readonly explode: Schema.OptionFromOptional<Schema.Boolean>;
+    readonly allowReserved: Schema.OptionFromOptional<Schema.Boolean>;
+}>;
+export type EncodingObject = typeof EncodingObject.Type;
+export declare const MediaBinding: Schema.Struct<{
+    readonly contentType: Schema.String;
+    readonly schema: Schema.OptionFromOptional<Schema.Unknown>;
+    readonly encoding: Schema.OptionFromOptional<Schema.$Record<Schema.String, Schema.Struct<{
+        readonly contentType: Schema.OptionFromOptional<Schema.String>;
+        readonly style: Schema.OptionFromOptional<Schema.String>;
+        readonly explode: Schema.OptionFromOptional<Schema.Boolean>;
+        readonly allowReserved: Schema.OptionFromOptional<Schema.Boolean>;
+    }>>>;
+}>;
+export type MediaBinding = typeof MediaBinding.Type;
+export declare const OperationRequestBody: Schema.Struct<{
+    readonly required: Schema.Boolean;
+    /** Default media type — first declared in spec order (not JSON-first).
+     *  Used when the caller does not override via the tool's `contentType` arg. */
+    readonly contentType: Schema.String;
+    /** Schema of the default media type. Kept for backward compat with stored
+     *  bindings from before `contents` was added. */
+    readonly schema: Schema.OptionFromOptional<Schema.Unknown>;
+    /** All declared media types in spec order. Populated by `extract.ts`
+     *  going forward; older persisted bindings may have this unset and will
+     *  fall back to `{contentType, schema}`. */
+    readonly contents: Schema.OptionFromOptional<Schema.$Array<Schema.Struct<{
+        readonly contentType: Schema.String;
+        readonly schema: Schema.OptionFromOptional<Schema.Unknown>;
+        readonly encoding: Schema.OptionFromOptional<Schema.$Record<Schema.String, Schema.Struct<{
+            readonly contentType: Schema.OptionFromOptional<Schema.String>;
+            readonly style: Schema.OptionFromOptional<Schema.String>;
+            readonly explode: Schema.OptionFromOptional<Schema.Boolean>;
+            readonly allowReserved: Schema.OptionFromOptional<Schema.Boolean>;
+        }>>>;
+    }>>>;
+}>;
+export type OperationRequestBody = typeof OperationRequestBody.Type;
+export declare const OperationFileHint: Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["binaryResponse", "byteField"]>;
+    readonly mimeType: Schema.OptionFromOptional<Schema.String>;
+    readonly dataField: Schema.OptionFromOptional<Schema.String>;
+    readonly sizeField: Schema.OptionFromOptional<Schema.String>;
+    readonly encoding: Schema.OptionFromOptional<Schema.Literals<readonly ["base64", "base64url"]>>;
+}>;
+export type OperationFileHint = typeof OperationFileHint.Type;
+export declare const OperationResponseBody: Schema.Struct<{
+    readonly contentType: Schema.String;
+    readonly schema: Schema.OptionFromOptional<Schema.Unknown>;
+    readonly fileHint: Schema.OptionFromOptional<Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["binaryResponse", "byteField"]>;
+        readonly mimeType: Schema.OptionFromOptional<Schema.String>;
+        readonly dataField: Schema.OptionFromOptional<Schema.String>;
+        readonly sizeField: Schema.OptionFromOptional<Schema.String>;
+        readonly encoding: Schema.OptionFromOptional<Schema.Literals<readonly ["base64", "base64url"]>>;
+    }>>;
+}>;
+export type OperationResponseBody = typeof OperationResponseBody.Type;
+export declare const ServerVariable: Schema.Struct<{
+    readonly default: Schema.String;
+    readonly enum: Schema.OptionFromOptional<Schema.$Array<Schema.String>>;
+    readonly description: Schema.OptionFromOptional<Schema.String>;
+}>;
+export type ServerVariable = typeof ServerVariable.Type;
+export declare const ServerInfo: Schema.Struct<{
+    readonly url: Schema.String;
+    readonly description: Schema.OptionFromOptional<Schema.String>;
+    readonly variables: Schema.OptionFromOptional<Schema.$Record<Schema.String, Schema.Struct<{
+        readonly default: Schema.String;
+        readonly enum: Schema.OptionFromOptional<Schema.$Array<Schema.String>>;
+        readonly description: Schema.OptionFromOptional<Schema.String>;
+    }>>>;
+}>;
+export type ServerInfo = typeof ServerInfo.Type;
+export declare const ExtractedOperation: Schema.Struct<{
+    readonly operationId: Schema.brand<Schema.String, "OperationId">;
+    readonly toolPath: Schema.OptionFromOptional<Schema.String>;
+    readonly method: Schema.Literals<readonly ["get", "put", "post", "delete", "patch", "head", "options", "trace"]>;
+    readonly servers: Schema.$Array<Schema.Struct<{
+        readonly url: Schema.String;
+        readonly description: Schema.OptionFromOptional<Schema.String>;
+        readonly variables: Schema.OptionFromOptional<Schema.$Record<Schema.String, Schema.Struct<{
+            readonly default: Schema.String;
+            readonly enum: Schema.OptionFromOptional<Schema.$Array<Schema.String>>;
+            readonly description: Schema.OptionFromOptional<Schema.String>;
+        }>>>;
+    }>>;
+    readonly pathTemplate: Schema.String;
+    readonly summary: Schema.OptionFromOptional<Schema.String>;
+    readonly description: Schema.OptionFromOptional<Schema.String>;
+    readonly tags: Schema.$Array<Schema.String>;
+    readonly parameters: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly location: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+        readonly required: Schema.Boolean;
+        readonly schema: Schema.OptionFromOptional<Schema.Unknown>;
+        readonly style: Schema.OptionFromOptional<Schema.String>;
+        readonly explode: Schema.OptionFromOptional<Schema.Boolean>;
+        readonly allowReserved: Schema.OptionFromOptional<Schema.Boolean>;
+        readonly description: Schema.OptionFromOptional<Schema.String>;
+    }>>;
+    readonly requestBody: Schema.OptionFromOptional<Schema.Struct<{
+        readonly required: Schema.Boolean;
+        /** Default media type — first declared in spec order (not JSON-first).
+         *  Used when the caller does not override via the tool's `contentType` arg. */
+        readonly contentType: Schema.String;
+        /** Schema of the default media type. Kept for backward compat with stored
+         *  bindings from before `contents` was added. */
+        readonly schema: Schema.OptionFromOptional<Schema.Unknown>;
+        /** All declared media types in spec order. Populated by `extract.ts`
+         *  going forward; older persisted bindings may have this unset and will
+         *  fall back to `{contentType, schema}`. */
+        readonly contents: Schema.OptionFromOptional<Schema.$Array<Schema.Struct<{
+            readonly contentType: Schema.String;
+            readonly schema: Schema.OptionFromOptional<Schema.Unknown>;
+            readonly encoding: Schema.OptionFromOptional<Schema.$Record<Schema.String, Schema.Struct<{
+                readonly contentType: Schema.OptionFromOptional<Schema.String>;
+                readonly style: Schema.OptionFromOptional<Schema.String>;
+                readonly explode: Schema.OptionFromOptional<Schema.Boolean>;
+                readonly allowReserved: Schema.OptionFromOptional<Schema.Boolean>;
+            }>>>;
+        }>>>;
+    }>>;
+    readonly responseBody: Schema.OptionFromOptional<Schema.Struct<{
+        readonly contentType: Schema.String;
+        readonly schema: Schema.OptionFromOptional<Schema.Unknown>;
+        readonly fileHint: Schema.OptionFromOptional<Schema.Struct<{
+            readonly kind: Schema.Literals<readonly ["binaryResponse", "byteField"]>;
+            readonly mimeType: Schema.OptionFromOptional<Schema.String>;
+            readonly dataField: Schema.OptionFromOptional<Schema.String>;
+            readonly sizeField: Schema.OptionFromOptional<Schema.String>;
+            readonly encoding: Schema.OptionFromOptional<Schema.Literals<readonly ["base64", "base64url"]>>;
+        }>>;
+    }>>;
+    readonly inputSchema: Schema.OptionFromOptional<Schema.Unknown>;
+    readonly outputSchema: Schema.OptionFromOptional<Schema.Unknown>;
+    readonly deprecated: Schema.Boolean;
+    /** OAuth scope requirements from `security`, alternatives preserved: each
+     *  inner array is one acceptable Security Requirement Object's scope set
+     *  (sorted, deduped); the outer array is an OR across alternatives. An
+     *  absent operation `security` inherits the document default; an explicit
+     *  `security: []` (auth disabled) and a scope-less declaration both omit
+     *  the field. */
+    readonly requiredScopeAlternatives: Schema.optional<Schema.$Array<Schema.$Array<Schema.String>>>;
+}>;
+export type ExtractedOperation = typeof ExtractedOperation.Type;
+export declare const ExtractionResult: Schema.Struct<{
+    readonly title: Schema.OptionFromOptional<Schema.String>;
+    /** The spec's `info.description` — the author's own summary of the API. */
+    readonly description: Schema.OptionFromOptional<Schema.String>;
+    readonly version: Schema.OptionFromOptional<Schema.String>;
+    readonly servers: Schema.$Array<Schema.Struct<{
+        readonly url: Schema.String;
+        readonly description: Schema.OptionFromOptional<Schema.String>;
+        readonly variables: Schema.OptionFromOptional<Schema.$Record<Schema.String, Schema.Struct<{
+            readonly default: Schema.String;
+            readonly enum: Schema.OptionFromOptional<Schema.$Array<Schema.String>>;
+            readonly description: Schema.OptionFromOptional<Schema.String>;
+        }>>>;
+    }>>;
+    readonly operations: Schema.$Array<Schema.Struct<{
+        readonly operationId: Schema.brand<Schema.String, "OperationId">;
+        readonly toolPath: Schema.OptionFromOptional<Schema.String>;
+        readonly method: Schema.Literals<readonly ["get", "put", "post", "delete", "patch", "head", "options", "trace"]>;
+        readonly servers: Schema.$Array<Schema.Struct<{
+            readonly url: Schema.String;
+            readonly description: Schema.OptionFromOptional<Schema.String>;
+            readonly variables: Schema.OptionFromOptional<Schema.$Record<Schema.String, Schema.Struct<{
+                readonly default: Schema.String;
+                readonly enum: Schema.OptionFromOptional<Schema.$Array<Schema.String>>;
+                readonly description: Schema.OptionFromOptional<Schema.String>;
+            }>>>;
+        }>>;
+        readonly pathTemplate: Schema.String;
+        readonly summary: Schema.OptionFromOptional<Schema.String>;
+        readonly description: Schema.OptionFromOptional<Schema.String>;
+        readonly tags: Schema.$Array<Schema.String>;
+        readonly parameters: Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly location: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+            readonly required: Schema.Boolean;
+            readonly schema: Schema.OptionFromOptional<Schema.Unknown>;
+            readonly style: Schema.OptionFromOptional<Schema.String>;
+            readonly explode: Schema.OptionFromOptional<Schema.Boolean>;
+            readonly allowReserved: Schema.OptionFromOptional<Schema.Boolean>;
+            readonly description: Schema.OptionFromOptional<Schema.String>;
+        }>>;
+        readonly requestBody: Schema.OptionFromOptional<Schema.Struct<{
+            readonly required: Schema.Boolean;
+            /** Default media type — first declared in spec order (not JSON-first).
+             *  Used when the caller does not override via the tool's `contentType` arg. */
+            readonly contentType: Schema.String;
+            /** Schema of the default media type. Kept for backward compat with stored
+             *  bindings from before `contents` was added. */
+            readonly schema: Schema.OptionFromOptional<Schema.Unknown>;
+            /** All declared media types in spec order. Populated by `extract.ts`
+             *  going forward; older persisted bindings may have this unset and will
+             *  fall back to `{contentType, schema}`. */
+            readonly contents: Schema.OptionFromOptional<Schema.$Array<Schema.Struct<{
+                readonly contentType: Schema.String;
+                readonly schema: Schema.OptionFromOptional<Schema.Unknown>;
+                readonly encoding: Schema.OptionFromOptional<Schema.$Record<Schema.String, Schema.Struct<{
+                    readonly contentType: Schema.OptionFromOptional<Schema.String>;
+                    readonly style: Schema.OptionFromOptional<Schema.String>;
+                    readonly explode: Schema.OptionFromOptional<Schema.Boolean>;
+                    readonly allowReserved: Schema.OptionFromOptional<Schema.Boolean>;
+                }>>>;
+            }>>>;
+        }>>;
+        readonly responseBody: Schema.OptionFromOptional<Schema.Struct<{
+            readonly contentType: Schema.String;
+            readonly schema: Schema.OptionFromOptional<Schema.Unknown>;
+            readonly fileHint: Schema.OptionFromOptional<Schema.Struct<{
+                readonly kind: Schema.Literals<readonly ["binaryResponse", "byteField"]>;
+                readonly mimeType: Schema.OptionFromOptional<Schema.String>;
+                readonly dataField: Schema.OptionFromOptional<Schema.String>;
+                readonly sizeField: Schema.OptionFromOptional<Schema.String>;
+                readonly encoding: Schema.OptionFromOptional<Schema.Literals<readonly ["base64", "base64url"]>>;
+            }>>;
+        }>>;
+        readonly inputSchema: Schema.OptionFromOptional<Schema.Unknown>;
+        readonly outputSchema: Schema.OptionFromOptional<Schema.Unknown>;
+        readonly deprecated: Schema.Boolean;
+        /** OAuth scope requirements from `security`, alternatives preserved: each
+         *  inner array is one acceptable Security Requirement Object's scope set
+         *  (sorted, deduped); the outer array is an OR across alternatives. An
+         *  absent operation `security` inherits the document default; an explicit
+         *  `security: []` (auth disabled) and a scope-less declaration both omit
+         *  the field. */
+        readonly requiredScopeAlternatives: Schema.optional<Schema.$Array<Schema.$Array<Schema.String>>>;
+    }>>;
+}>;
+export type ExtractionResult = typeof ExtractionResult.Type;
+export declare const OperationBinding: Schema.Struct<{
+    readonly method: Schema.Literals<readonly ["get", "put", "post", "delete", "patch", "head", "options", "trace"]>;
+    readonly servers: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly url: Schema.String;
+        readonly description: Schema.OptionFromOptional<Schema.String>;
+        readonly variables: Schema.OptionFromOptional<Schema.$Record<Schema.String, Schema.Struct<{
+            readonly default: Schema.String;
+            readonly enum: Schema.OptionFromOptional<Schema.$Array<Schema.String>>;
+            readonly description: Schema.OptionFromOptional<Schema.String>;
+        }>>>;
+    }>>>;
+    readonly pathTemplate: Schema.String;
+    readonly parameters: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly location: Schema.Literals<readonly ["path", "query", "header", "cookie"]>;
+        readonly required: Schema.Boolean;
+        readonly schema: Schema.OptionFromOptional<Schema.Unknown>;
+        readonly style: Schema.OptionFromOptional<Schema.String>;
+        readonly explode: Schema.OptionFromOptional<Schema.Boolean>;
+        readonly allowReserved: Schema.OptionFromOptional<Schema.Boolean>;
+        readonly description: Schema.OptionFromOptional<Schema.String>;
+    }>>;
+    readonly requestBody: Schema.OptionFromOptional<Schema.Struct<{
+        readonly required: Schema.Boolean;
+        /** Default media type — first declared in spec order (not JSON-first).
+         *  Used when the caller does not override via the tool's `contentType` arg. */
+        readonly contentType: Schema.String;
+        /** Schema of the default media type. Kept for backward compat with stored
+         *  bindings from before `contents` was added. */
+        readonly schema: Schema.OptionFromOptional<Schema.Unknown>;
+        /** All declared media types in spec order. Populated by `extract.ts`
+         *  going forward; older persisted bindings may have this unset and will
+         *  fall back to `{contentType, schema}`. */
+        readonly contents: Schema.OptionFromOptional<Schema.$Array<Schema.Struct<{
+            readonly contentType: Schema.String;
+            readonly schema: Schema.OptionFromOptional<Schema.Unknown>;
+            readonly encoding: Schema.OptionFromOptional<Schema.$Record<Schema.String, Schema.Struct<{
+                readonly contentType: Schema.OptionFromOptional<Schema.String>;
+                readonly style: Schema.OptionFromOptional<Schema.String>;
+                readonly explode: Schema.OptionFromOptional<Schema.Boolean>;
+                readonly allowReserved: Schema.OptionFromOptional<Schema.Boolean>;
+            }>>>;
+        }>>>;
+    }>>;
+    readonly responseBody: Schema.OptionFromOptional<Schema.Struct<{
+        readonly contentType: Schema.String;
+        readonly schema: Schema.OptionFromOptional<Schema.Unknown>;
+        readonly fileHint: Schema.OptionFromOptional<Schema.Struct<{
+            readonly kind: Schema.Literals<readonly ["binaryResponse", "byteField"]>;
+            readonly mimeType: Schema.OptionFromOptional<Schema.String>;
+            readonly dataField: Schema.OptionFromOptional<Schema.String>;
+            readonly sizeField: Schema.OptionFromOptional<Schema.String>;
+            readonly encoding: Schema.OptionFromOptional<Schema.Literals<readonly ["base64", "base64url"]>>;
+        }>>;
+    }>>;
+    /** Declared OAuth scope alternatives (see
+     *  ExtractedOperation.requiredScopeAlternatives), persisted with the
+     *  binding so the invoke path can annotate a scope-insufficient rejection
+     *  with exactly what the operation needs. Optional so bindings stored
+     *  before this field existed keep decoding. */
+    readonly requiredScopeAlternatives: Schema.optional<Schema.$Array<Schema.$Array<Schema.String>>>;
+}>;
+export type OperationBinding = typeof OperationBinding.Type;
+export declare const InvocationResult: Schema.Struct<{
+    readonly status: Schema.Number;
+    readonly headers: Schema.$Record<Schema.String, Schema.String>;
+    readonly data: Schema.NullOr<Schema.Unknown>;
+    readonly error: Schema.NullOr<Schema.Unknown>;
+}>;
+export type InvocationResult = typeof InvocationResult.Type;

package/dist/sdk/upstream-failures.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/usage-scope-isolation.test.d.ts

@@ -0,0 +1 @@
+export {};