apps 0.0.1-beta.0 → 0.0.1-beta.1

package/types/apps/src/implementation/cache-session.d.ts

@@ -0,0 +1,7 @@
+import type { HostCache } from "../contracts/cache.js";
+/** Own all refresh promises until drained or cancelled. Only generated trusted bridges create sessions. */
+export declare const isolatedCacheSession: (callback: (input: unknown) => Promise<unknown>) => {
+    cache: HostCache;
+    drain: () => Promise<void>;
+    cancel: () => Promise<void>;
+};

package/types/apps/src/implementation/cache.d.ts

@@ -0,0 +1,6 @@
+import type { AppCache, HostCache } from "../contracts/cache.js";
+import type { ResolvedAccounts } from "../contracts/host.js";
+/** Missing host support is explicit on use; ordinary apps do not need cache support. */
+export declare const unavailableCache: HostCache;
+/** Account scopes are derived from trusted current bindings. Loaders get a fresh owned HTTP signal. */
+export declare const authorCache: (host: HostCache, accounts: ResolvedAccounts, signal: AbortSignal) => AppCache;

package/types/apps/src/implementation/catalog-cache.d.ts

@@ -0,0 +1,29 @@
+import { Duration, Effect, Schema } from "effect";
+import type { AppCache, CacheLoadContext } from "../contracts/cache.js";
+import { type JsonValue } from "../contracts/schema.js";
+export interface CatalogCacheOptions {
+    /** App/build scope, optionally narrowed to the current account. */
+    readonly cache?: AppCache;
+    /** Reuse metadata for this duration. Defaults to five minutes. */
+    readonly freshFor?: Duration.Input;
+    /** Serve retained metadata while refreshing. Defaults to one day. */
+    readonly staleFor?: Duration.Input;
+    /** Await a fresh revision at an explicit logical connection or refresh boundary. */
+    readonly revalidate?: boolean;
+}
+export declare const catalogCache: <A extends {
+    readonly name: string;
+}, S>(options: CatalogCacheOptions & {
+    readonly prefix: readonly JsonValue[];
+    readonly schema: Schema.Decoder<A>;
+    /** Schema-free projection stored beside the full pages, so browsing never reads schemas. */
+    readonly summary: {
+        readonly schema: Schema.Decoder<S>;
+        readonly of: (tool: A) => S;
+    };
+    readonly load: (context?: CacheLoadContext) => Effect.Effect<readonly A[], unknown>;
+}) => Effect.Effect<{
+    list: () => Effect.Effect<readonly A[], unknown, never>;
+    summaries: () => Effect.Effect<S[], unknown, never>;
+    resolve: (name: string) => Effect.Effect<A | undefined, unknown, never>;
+}, unknown, never>;

package/types/apps/src/implementation/dynamic-skills.d.ts

@@ -0,0 +1,7 @@
+/** Author-facing lazy skill sources adapt once to the framework's Effect execution path. */
+import type { DynamicSkills } from "../contracts/dynamic-skills.js";
+import type { AppSkillSource } from "../contracts/skills.js";
+/** Declare skills that load only when skills are read, such as `list: () => githubSkills({...})`. */
+export declare const dynamicSkills: (source: {
+    readonly list: () => readonly AppSkillSource[] | Promise<readonly AppSkillSource[]>;
+}) => DynamicSkills;

package/types/apps/src/implementation/dynamic-tools.d.ts

@@ -0,0 +1,8 @@
+import { HostedTool } from "../contracts/host.js";
+import type { DynamicTools } from "../contracts/dynamic-tools.js";
+import { type OperationDeclaration } from "./operations.js";
+/** Declare metadata discovery separately from executable resolution. Names are fully qualified. */
+export declare const dynamicTools: (source: {
+    readonly list: () => Promise<readonly HostedTool[]>;
+    readonly resolve: (name: string) => Promise<OperationDeclaration<"query" | "mutation"> | undefined>;
+}) => DynamicTools;

package/types/apps/src/implementation/elicitation.d.ts

@@ -7,76 +7,76 @@ export declare const prepareElicitation: (input: unknown) => Effect.Effect<{
         readonly message: string;
         readonly mode: "form";
         readonly requestedSchema: {
+            readonly type: "object";
             readonly properties: {
                 readonly [x: string]: {
                     readonly type: "string";
                     readonly enum: readonly string[];
                     readonly default?: string;
-                    readonly title?: string;
                     readonly description?: string;
+                    readonly title?: string;
                     readonly enumNames?: readonly string[];
                 } | {
                     readonly type: "string";
                     readonly enum: readonly string[];
                     readonly default?: string;
-                    readonly title?: string;
                     readonly description?: string;
+                    readonly title?: string;
                 } | {
+                    readonly type: "string";
                     readonly oneOf: readonly {
                         readonly const: string;
                         readonly title: string;
                     }[];
-                    readonly type: "string";
                     readonly default?: string;
-                    readonly title?: string;
                     readonly description?: string;
+                    readonly title?: string;
                 } | {
+                    readonly type: "array";
                     readonly items: {
                         readonly type: "string";
                         readonly enum: readonly string[];
                     };
-                    readonly type: "array";
                     readonly default?: readonly string[];
-                    readonly title?: string;
                     readonly description?: string;
+                    readonly title?: string;
                     readonly minItems?: number;
                     readonly maxItems?: number;
                 } | {
+                    readonly type: "array";
                     readonly items: {
                         readonly anyOf: readonly {
                             readonly const: string;
                             readonly title: string;
                         }[];
                     };
-                    readonly type: "array";
                     readonly default?: readonly string[];
-                    readonly title?: string;
                     readonly description?: string;
+                    readonly title?: string;
                     readonly minItems?: number;
                     readonly maxItems?: number;
                 } | {
                     readonly type: "string";
                     readonly default?: string;
                     readonly format?: "email" | "uri" | "date" | "date-time";
-                    readonly title?: string;
                     readonly description?: string;
+                    readonly title?: string;
                     readonly minLength?: number;
                     readonly maxLength?: number;
                 } | {
                     readonly type: "number" | "integer";
                     readonly default?: number;
-                    readonly title?: string;
                     readonly description?: string;
+                    readonly title?: string;
                     readonly minimum?: number;
                     readonly maximum?: number;
                 } | {
                     readonly type: "boolean";
                     readonly default?: boolean;
-                    readonly title?: string;
                     readonly description?: string;
+                    readonly title?: string;
                 };
             };
-            readonly type: "object";
             readonly required?: readonly string[];
             readonly $schema?: string;
         };

package/types/apps/src/implementation/git.d.ts

@@ -0,0 +1,25 @@
+/** A malformed git response; callers report it as an unreadable source document. */
+export declare class GitProtocolError extends Error {
+}
+export declare const gitRequestHeaders: {
+    readonly "Content-Type": "application/x-git-upload-pack-request";
+    readonly "Git-Protocol": "version=2";
+};
+/** Candidate ref names for a branch, tag or HEAD, in lookup order. */
+export declare const refCandidates: (ref: string | undefined) => string[];
+/** Ask only for the named refs, peeling annotated tags to their commits. */
+export declare const lsRefsRequest: (names: readonly string[]) => Uint8Array<ArrayBuffer>;
+/** Map each advertised ref to its commit, using the peeled commit for annotated tags. */
+export declare const parseLsRefs: (bytes: Uint8Array) => Map<string, string>;
+/** Fetch one commit and its trees without file contents or history. */
+export declare const treeFetchRequest: (commit: string) => Uint8Array<ArrayBuffer>;
+export interface GitTreeEntry {
+    /** Repository-relative path. */
+    readonly path: string;
+    /** Git file mode, such as 100644, 100755 or 120000 for a symbolic link. */
+    readonly mode: string;
+}
+/** List the files at a commit, limited to one directory when `path` is set. */
+export declare const parseTreeFetch: (bytes: Uint8Array, commit: string, path: string | undefined, limits: {
+    readonly objectBytes: number;
+}) => Promise<GitTreeEntry[]>;

package/types/apps/src/implementation/graphql-catalog.d.ts

@@ -0,0 +1,10 @@
+import { Effect } from "effect";
+import { GraphqlToolsOptions } from "../contracts/graphql.js";
+import type { DynamicTools } from "../contracts/dynamic-tools.js";
+import { type CatalogCacheOptions } from "./catalog-cache.js";
+import { type OperationKinds } from "./protocol-operations.js";
+export interface GraphqlCatalogOptions extends GraphqlToolsOptions, CatalogCacheOptions {
+}
+export declare const graphqlCatalog: (options: GraphqlCatalogOptions, kinds: OperationKinds) => Effect.Effect<{
+    dynamicTools: DynamicTools;
+}, unknown, never>;

package/types/apps/src/implementation/graphql.d.ts

@@ -1,5 +1,83 @@
+import { ProviderError } from "../contracts/provider-error.js";
 /** Discover GraphQL tools live; transport, decoding and cancellation stay in Effect. */
-import { Effect } from "effect";
-import { GraphqlError, GraphqlToolsOptions, type GraphqlTools } from "../contracts/graphql.js";
+import { Effect, Schema } from "effect";
+import { OperationTypeNode } from "graphql";
+import { GraphqlError, GraphqlIntrospection, GraphqlToolsOptions, type GraphqlToolDefinition, type GraphqlTools, type GraphqlTypeRef } from "../contracts/graphql.js";
+import { JsonObject } from "../effect.js";
 /** Resolve schema and calls per account evaluation; never cache credentials or tools globally. */
-export declare const graphqlToolsEffect: (input: GraphqlToolsOptions) => Effect.Effect<GraphqlTools, GraphqlError>;
+export declare const graphqlClientEffect: (input: GraphqlToolsOptions) => Effect.Effect<{
+    request: (phase: "discover" | "call", query: string, variables?: JsonObject) => Effect.Effect<{
+        readonly [x: string]: Schema.Json;
+    }, ProviderError | GraphqlError, never>;
+    discover: Effect.Effect<{
+        readonly __schema: {
+            readonly queryType: {
+                readonly name: string;
+            } | null;
+            readonly mutationType: {
+                readonly name: string;
+            } | null;
+            readonly types: readonly {
+                readonly kind: "SCALAR" | "OBJECT" | "INTERFACE" | "UNION" | "ENUM" | "INPUT_OBJECT" | "LIST" | "NON_NULL";
+                readonly name: string;
+                readonly fields: readonly {
+                    readonly name: string;
+                    readonly description: string | null;
+                    readonly args: readonly {
+                        readonly name: string;
+                        readonly description: string | null;
+                        readonly type: GraphqlTypeRef;
+                        readonly defaultValue: string | null;
+                    }[];
+                    readonly type: GraphqlTypeRef;
+                }[] | null;
+                readonly inputFields: readonly {
+                    readonly name: string;
+                    readonly description: string | null;
+                    readonly type: GraphqlTypeRef;
+                    readonly defaultValue: string | null;
+                }[] | null;
+                readonly enumValues: readonly {
+                    readonly name: string;
+                }[] | null;
+            }[];
+        };
+    }, ProviderError | GraphqlError, never>;
+}, GraphqlError, never>;
+/** Build serializable definitions once per introspection revision, without compiling validators. */
+export declare const graphqlDefinitions: (catalog: GraphqlIntrospection) => Effect.Effect<{
+    name: string;
+    kind: OperationTypeNode.QUERY | OperationTypeNode.MUTATION;
+    field: string;
+    description: string;
+    arguments: {
+        name: string;
+        type: string;
+    }[];
+    inputSchema: {
+        type: string;
+        additionalProperties: boolean;
+        properties: {
+            select?: {
+                type: string;
+                minLength: number;
+                description: string;
+            };
+            arguments: {
+                readonly [x: string]: Schema.Json;
+            };
+        };
+        required: string[];
+        $defs: {
+            [k: string]: {
+                readonly [x: string]: Schema.Json;
+            };
+        };
+    };
+    composite: boolean;
+    selection: string;
+}[], GraphqlError, never>;
+/** Bind only the selected definition to current credentials and compile its input decoder. */
+export declare const adaptGraphqlTool: (client: Effect.Success<ReturnType<typeof graphqlClientEffect>>, definition: GraphqlToolDefinition) => Effect.Effect<import("../contracts/graphql.js").GraphqlTool, GraphqlError, never>;
+/** Low-level callers can still request a complete invocation-owned tool map. */
+export declare const graphqlToolsEffect: (input: GraphqlToolsOptions) => Effect.Effect<GraphqlTools, GraphqlError | ProviderError>;

package/types/apps/src/implementation/inflate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Minimal zlib (RFC 1950) and DEFLATE (RFC 1951) decoder. Git packfiles concatenate zlib streams
+ * without lengths, so readers must know where each stream ends. Platform decompression streams do
+ * not report that, so this decoder returns the offset after the stream's Adler-32 checksum.
+ */
+/** The stream is malformed. */
+export declare class InflateError extends Error {
+}
+/** The decoded stream would exceed the caller's limit. */
+export declare class InflateLimitExceeded extends Error {
+}
+/** Decode one zlib stream starting at `start`, returning its bytes and the offset after it. */
+export declare const inflateZlib: (input: Uint8Array, start: number, limit: number) => {
+    readonly data: Uint8Array;
+    readonly end: number;
+};

package/types/apps/src/implementation/input-problems.d.ts

@@ -0,0 +1,3 @@
+import { HostInputInvalid } from "../contracts/host.js";
+/** Failing input paths and expected shapes from a schema decode failure, without supplied values. */
+export declare const inputInvalid: (error: unknown) => HostInputInvalid;

package/types/apps/src/implementation/mcp-call.d.ts

@@ -1,3 +1,4 @@
+import type { ProviderError } from "../contracts/provider-error.js";
 /** One upstream call, with form requests forwarded to the invocation's existing elicitation capability. */
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { Effect, Schema } from "effect";
@@ -5,7 +6,7 @@ import { ElicitationFailed } from "../contracts/elicitation.js";
 import { McpError, type McpToolContext } from "../contracts/mcp.js";
 import type { JsonObject } from "../contracts/schema.js";
 /** Register prompts only around tools/call, preserve metadata, and close every callback with the call. Never retries. */
-export declare const mcpCall: (client: Client, name: string, input: JsonObject, context: McpToolContext, timeoutMs: number, failure: (phase: McpError["phase"], error: unknown) => McpError) => Effect.Effect<{
+export declare const mcpCall: (client: Client, name: string, input: JsonObject, context: McpToolContext, timeoutMs: number, failure: (phase: McpError["phase"], error: unknown) => McpError | ProviderError) => Effect.Effect<{
     readonly content: readonly {
         readonly [x: string]: Schema.Json;
     }[];
@@ -16,4 +17,4 @@ export declare const mcpCall: (client: Client, name: string, input: JsonObject,
         readonly [x: string]: Schema.Json;
     } | undefined;
     readonly isError?: boolean | undefined;
-}, ElicitationFailed | McpError, never>;
+}, ProviderError | ElicitationFailed | McpError, never>;

package/types/apps/src/implementation/mcp-catalog.d.ts

@@ -0,0 +1,12 @@
+import { Effect } from "effect";
+import type { DynamicTools } from "../contracts/dynamic-tools.js";
+import { McpToolsOptions } from "../contracts/mcp.js";
+import { type CatalogCacheOptions } from "./catalog-cache.js";
+import { type OperationKinds } from "./protocol-operations.js";
+/** Metadata policy for HTTP/SSE sources. A missing cache keeps discovery invocation-local. */
+export interface McpCatalogOptions extends McpToolsOptions, CatalogCacheOptions {
+}
+/** Construction opens no transport unless explicit revalidation is requested. */
+export declare const mcpCatalog: (options: McpCatalogOptions, kinds: OperationKinds) => Effect.Effect<{
+    dynamicTools: DynamicTools;
+}, unknown, never>;

package/types/apps/src/implementation/mcp-client.d.ts

@@ -1,3 +1,4 @@
+import type { ProviderError } from "../contracts/provider-error.js";
 /** Shared MCP pagination, wire parsing and calls. Transport owns connection lifetime. */
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { jsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/types.js";
@@ -8,20 +9,23 @@ import type { JsonObject } from "../effect.js";
 export declare const mcpJsonSchemaValidator: jsonSchemaValidator;
 /** An operation owns its connection; it must close even when interrupted. */
 export interface WithMcpClient {
-    <A, E>(mode: "discover" | "call", use: (client: Client) => Effect.Effect<A, E>): Effect.Effect<A, E | McpError>;
+    <A, E>(mode: "discover" | "call", use: (client: Client) => Effect.Effect<A, E>): Effect.Effect<A, E | McpError | ProviderError>;
 }
 /** Shared client operations never cache catalogs or account credentials. */
-export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number, failure: (phase: McpError["phase"], error: unknown) => McpError): {
+export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number, failure: (phase: McpError["phase"], error: unknown) => McpError | ProviderError): {
     list: Effect.Effect<{
         readonly name: string;
         readonly inputSchema: {
             readonly [x: string]: Schema.Json;
         };
+        readonly description?: string | undefined;
         readonly _meta?: {
             readonly [x: string]: Schema.Json;
         } | undefined;
         readonly title?: string | undefined;
-        readonly description?: string | undefined;
+        readonly outputSchema?: {
+            readonly [x: string]: Schema.Json;
+        } | undefined;
         readonly annotations?: {
             readonly title?: string;
             readonly readOnlyHint?: boolean;
@@ -29,10 +33,7 @@ export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number,
             readonly idempotentHint?: boolean;
             readonly openWorldHint?: boolean;
         } | undefined;
-        readonly outputSchema?: {
-            readonly [x: string]: Schema.Json;
-        } | undefined;
-    }[], McpError, never>;
+    }[], ProviderError | McpError, never>;
     call: (name: string, input: JsonObject, context: McpToolContext) => Effect.Effect<{
         readonly content: readonly {
             readonly [x: string]: Schema.Json;
@@ -44,7 +45,7 @@ export declare function mcpClient(withClient: WithMcpClient, timeoutMs: number,
             readonly [x: string]: Schema.Json;
         } | undefined;
         readonly isError?: boolean | undefined;
-    }, import("../index.js").ElicitationFailed | McpError, never>;
+    }, ProviderError | import("../index.js").ElicitationFailed | McpError, never>;
 };
 /** Transport-independent operations consumed by the app tool adapter. */
 export type McpClient = ReturnType<typeof mcpClient>;

package/types/apps/src/implementation/mcp-stdio.d.ts

@@ -1,4 +1,4 @@
 import { Effect } from "effect";
 import { McpError, ProcessConfig } from "../contracts/mcp.js";
 /** Each discovery/call owns and closes its subprocess. Deployment never starts it. */
-export declare const stdioToolsEffect: (input: ProcessConfig) => Effect.Effect<Readonly<Record<string, import("../contracts/mcp.js").McpTool>>, McpError, never>;
+export declare const stdioToolsEffect: (input: ProcessConfig) => Effect.Effect<Readonly<Record<string, import("../contracts/mcp.js").McpTool>>, import("../index.js").ProviderError | McpError, never>;

package/types/apps/src/implementation/mcp-tools.d.ts

@@ -1,6 +1,9 @@
+import type { ProviderError } from "../contracts/provider-error.js";
 /** Adapt any MCP transport into ordinary tools with shared validation behavior. */
 import { Effect } from "effect";
-import { McpError, type McpTools } from "../contracts/mcp.js";
+import { McpError, type McpTools, type McpToolMetadata } from "../contracts/mcp.js";
 import type { McpClient } from "./mcp-client.js";
-/** Evaluate fresh metadata for the account bound to this client. */
-export declare const adaptMcpTools: (client: McpClient) => Effect.Effect<McpTools, McpError>;
+/** Compile only the selected tool and bind its executable to the current invocation. */
+export declare const adaptMcpTool: (client: McpClient, tool: McpToolMetadata) => Effect.Effect<import("../contracts/mcp.js").McpTool, McpError, never>;
+/** Discover a complete catalog for probes and uncached low-level callers. */
+export declare const adaptMcpTools: (client: McpClient) => Effect.Effect<McpTools, McpError | ProviderError>;

package/types/apps/src/implementation/mcp.d.ts

@@ -1,4 +1,41 @@
-import { Effect } from "effect";
+import { ProviderError } from "../contracts/provider-error.js";
+import { Effect, Schema } from "effect";
 import { McpError, McpToolsOptions } from "../contracts/mcp.js";
 /** Discover and call with a fresh selected-account transport for each operation. */
-export declare const mcpToolsEffect: (input: McpToolsOptions) => Effect.Effect<Readonly<Record<string, import("../contracts/mcp.js").McpTool>>, McpError, never>;
+export declare const mcpClientEffect: (input: McpToolsOptions, changed?: Effect.Effect<void, unknown>) => Effect.Effect<{
+    list: Effect.Effect<{
+        readonly name: string;
+        readonly inputSchema: {
+            readonly [x: string]: Schema.Json;
+        };
+        readonly description?: string | undefined;
+        readonly _meta?: {
+            readonly [x: string]: Schema.Json;
+        } | undefined;
+        readonly title?: string | undefined;
+        readonly outputSchema?: {
+            readonly [x: string]: Schema.Json;
+        } | undefined;
+        readonly annotations?: {
+            readonly title?: string;
+            readonly readOnlyHint?: boolean;
+            readonly destructiveHint?: boolean;
+            readonly idempotentHint?: boolean;
+            readonly openWorldHint?: boolean;
+        } | undefined;
+    }[], ProviderError | McpError, never>;
+    call: (name: string, input: import("../index.js").JsonObject, context: import("../mcp.js").McpToolContext) => Effect.Effect<{
+        readonly content: readonly {
+            readonly [x: string]: Schema.Json;
+        }[];
+        readonly _meta?: {
+            readonly [x: string]: Schema.Json;
+        } | undefined;
+        readonly structuredContent?: {
+            readonly [x: string]: Schema.Json;
+        } | undefined;
+        readonly isError?: boolean | undefined;
+    }, ProviderError | import("../index.js").ElicitationFailed | McpError, never>;
+}, McpError, never>;
+/** Discover and compile all tools for connection probes and low-level consumers. */
+export declare const mcpToolsEffect: (input: McpToolsOptions) => Effect.Effect<Readonly<Record<string, import("../contracts/mcp.js").McpTool>>, ProviderError | McpError, never>;

package/types/apps/src/implementation/openapi-compile.d.ts

@@ -0,0 +1,119 @@
+/** Compile an OpenAPI document into tool declarations inside the app runtime, never a second execution engine. */
+import { Effect, Schema } from "effect";
+import { JsonObject } from "../contracts/schema.js";
+import "../contracts/swagger-client.ts";
+import { OpenapiCompileError as TemplateError } from "../contracts/openapi-compile.js";
+import type { OpenApiImport } from "../contracts/openapi-document.js";
+import { type GeneratedOperation, type GeneratedSecrets } from "../contracts/openapi-document.js";
+/** Compile a revision of a live OpenAPI source into tool declarations for the app runtime. */
+export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocument: unknown, options?: {
+    readonly baseUrl?: string;
+    readonly allowedOrigin?: string;
+    readonly securitySchemes?: Readonly<Record<string, JsonObject>>;
+    readonly fallbackSecurity?: GeneratedOperation["request"]["security"];
+}) => Effect.Effect<{
+    operations: {
+        readonly name: string;
+        readonly path: string;
+        readonly description: string;
+        readonly request: {
+            readonly parameters: readonly {
+                readonly name: string;
+                readonly in: "query" | "path" | "header" | "cookie";
+                readonly required?: boolean;
+                readonly schema?: {
+                    readonly [x: string]: Schema.Json;
+                };
+                readonly content?: {
+                    readonly [x: string]: Schema.Json;
+                };
+                readonly style?: string;
+                readonly explode?: boolean;
+                readonly allowReserved?: boolean;
+                readonly allowEmptyValue?: boolean;
+            }[];
+            readonly security: readonly {
+                readonly [x: string]: readonly string[];
+            }[];
+            readonly responses: {
+                readonly [x: string]: {
+                    readonly [x: string]: Schema.Json;
+                };
+            };
+            readonly requestBody?: {
+                readonly content: {
+                    readonly [x: string]: {
+                        readonly schema?: {
+                            readonly [x: string]: Schema.Json;
+                        };
+                        readonly encoding?: {
+                            readonly [x: string]: Schema.Json;
+                        };
+                    };
+                };
+                readonly required?: boolean;
+            };
+        };
+        readonly input: {
+            readonly [x: string]: Schema.Json;
+        };
+        readonly method: "HEAD" | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
+        readonly securitySchemes: {
+            readonly [x: string]: {
+                readonly [x: string]: Schema.Json;
+            };
+        };
+        readonly baseUrl: string;
+        readonly openapi: string;
+        readonly outputSchema?: {
+            readonly [x: string]: Schema.Json;
+        };
+        readonly streaming?: true;
+        readonly errorResponses?: readonly {
+            readonly code: string;
+            readonly status: number;
+            readonly message: {
+                readonly source: "body";
+            } | {
+                readonly source: "schema";
+                readonly value: string;
+            };
+            readonly schema: {
+                readonly [x: string]: Schema.Json;
+            };
+        }[];
+    }[];
+    definitions: {
+        [k: string]: {
+            readonly [x: string]: Schema.Json;
+        };
+    };
+    methods: {
+        [k: string]: readonly {
+            readonly scheme: string;
+            readonly field: string;
+            readonly part: "value" | "username" | "password";
+            readonly prefix: string;
+        }[];
+    };
+    secrets: GeneratedSecrets[];
+    oauth: {
+        name: string;
+        config: {
+            discover: string;
+        } | {
+            authorizationUrl: string;
+            tokenUrl: string;
+            scopes: readonly string[];
+        };
+    }[];
+    schemes: {
+        [x: string]: {
+            readonly [x: string]: Schema.Json;
+        };
+    };
+    pinnedOrigin: string | undefined;
+    fallback: readonly {
+        readonly [x: string]: readonly string[];
+    }[] | undefined;
+}, TemplateError, never>;

package/types/apps/src/implementation/openapi-document.d.ts

@@ -0,0 +1,53 @@
+/** OpenAPI reference and dialect rules, shared by every part of the app importer. */
+import "../contracts/swagger-client.ts";
+import { Schema } from "effect";
+import { JsonObject } from "../contracts/schema.js";
+/** Resolve OpenAPI objects once with Swagger; schemas retain their original recursive references.
+ * Scalar first upgrades Swagger 2.0 and OpenAPI 3.0 to 3.1, so the importer has one dialect and
+ * 3.1 keywords that appear in 3.0 documents keep their meaning.
+ * Unsupported versions, references and conversions throw TemplateError at the import boundary.
+ */
+export declare function openApiDocument(input: unknown): Promise<{
+    spec: {
+        readonly openapi: string;
+        readonly paths: {
+            readonly [x: string]: {
+                readonly [x: string]: Schema.Json;
+            };
+        };
+        readonly security?: readonly {
+            readonly [x: string]: readonly string[];
+        }[];
+        readonly servers?: readonly {
+            readonly url: string;
+            readonly variables?: {
+                readonly [x: string]: Schema.Json;
+            };
+        }[];
+        readonly components?: {
+            readonly securitySchemes?: {
+                readonly [x: string]: {
+                    readonly [x: string]: Schema.Json;
+                };
+            };
+            readonly schemas?: {
+                readonly [x: string]: {
+                    readonly [x: string]: Schema.Json;
+                };
+            };
+        };
+    };
+    definitions: Map<string, {
+        readonly [x: string]: Schema.Json;
+    }>;
+    /** Inspect a component schema without expanding its children. OpenAPI object refs must already be resolved by Swagger. */
+    resolve(value: JsonObject): JsonObject;
+    /** Compose a Draft 2020-12 schema around API Schema Objects. Only values passed to
+     * `api` use the document's OpenAPI dialect; Executor-authored wrappers are already
+     * Draft 2020-12 and must not be reinterpreted. Reached components are converted once into
+     * the shared `definitions` and stay references here; nothing is inlined or copied per operation.
+     */
+    schema(build: (api: (input: Schema.Json) => JsonObject) => JsonObject): JsonObject;
+}>;
+/** A parsed document with one reference scope and one schema dialect. */
+export type OpenApiDocument = Awaited<ReturnType<typeof openApiDocument>>;