apps 0.0.1-beta.5 → 0.0.1-beta.55

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

@@ -1,5 +1,5 @@
 /** Pure operation declarations. Only the author callback crosses the Promise boundary. */
-import { Effect, Schema as EffectSchema } from "effect";
+import { Schema as EffectSchema } from "effect";
 import type { AppOperation } from "../contracts/operations.js";
 import type { AppContext, QueryContext, MutationContext } from "../contracts/context.js";
 import type { Approval } from "../approval.js";
@@ -7,16 +7,44 @@ import type { ToolAnnotations } from "../contracts/tools.js";
 import type { JsonObject } from "../contracts/schema.js";
 import { type Schema } from "./schema.js";
 declare const NativeOperation: unique symbol;
-declare const HandlerContext: unique symbol;
-/** A server-only declaration with its category preserved for catalog validation. */
+declare const QueryHandlerContext: unique symbol;
+declare const MutationHandlerContext: unique symbol;
+/**
+ * A server-only declaration with its category preserved for catalog validation. Queries and
+ * mutations carry their handler context under different phantom keys, so a router can type a
+ * query's handler from its query context alone.
+ */
 export interface OperationDeclaration<Kind extends "query" | "mutation", Context = never> {
-    readonly [HandlerContext]?: (context: Context) => void;
+    readonly [QueryHandlerContext]?: "query" extends Kind ? (context: Context) => void : never;
+    readonly [MutationHandlerContext]?: "mutation" extends Kind ? (context: Context) => void : never;
     readonly kind: Kind;
     readonly [NativeOperation]: Omit<AppOperation<never>, "kind" | "input"> & {
         readonly kind: Kind;
         readonly input: EffectSchema.Decoder<unknown>;
     };
 }
+/**
+ * A router declaration. The phantom contexts let `defineApp` type inline handlers; protocol
+ * routers accept any context because their operations only use the framework's own capabilities.
+ * The native router is held under a private key in implementation/router.ts.
+ */
+export interface RouterDeclaration<Query = unknown, Mutation = unknown> {
+    readonly [QueryHandlerContext]?: (context: Query) => void;
+    readonly [MutationHandlerContext]?: (context: Mutation) => void;
+    readonly [NativeRouterKey]: unknown;
+}
+/** An operation or nested router under one key. Each child is typed only by its own kind's context. */
+export interface RouterChild<Query, Mutation> {
+    readonly [QueryHandlerContext]?: (context: Query) => void;
+    readonly [MutationHandlerContext]?: (context: Mutation) => void;
+}
+/**
+ * A query or mutation whose handler context is checked by its kind, as a dynamic router resolves
+ * one. `query()` and `mutation()` results fit with their inferred contexts.
+ */
+export type OperationChild<Query, Mutation> = RouterChild<Query, Mutation> & Pick<OperationDeclaration<"query" | "mutation">, "kind" | typeof NativeOperation>;
+/** Private key for a router's native definition. */
+export declare const NativeRouterKey: unique symbol;
 /** Typed operation handles drive browser reference inference without bundling handlers. */
 export interface Operation<Input, Output, Kind extends "query" | "mutation", Context = AppContext> extends OperationDeclaration<Kind, Context> {
     readonly [NativeOperation]: AppOperation<Input, Output> & {
@@ -41,7 +69,7 @@ export interface OperationOptions<Input, Output> {
 }
 /** Adapt metadata and approval without running user code. */
 export declare const operationOptions: <Input, Output>(options: OperationOptions<Input, Output>) => {
-    approval?: (context: Parameters<Approval<Input>>[0]) => Effect.Effect<"approved" | "denied" | "user-approval", unknown, never>;
+    approval?: (context: Parameters<Approval<Input>>[0]) => import("effect/Effect").Effect<"approved" | "denied" | "user-approval", unknown, never>;
     input: EffectSchema.Decoder<Input, never>;
     _meta?: {
         readonly [x: string]: EffectSchema.Json;
@@ -56,8 +84,18 @@ export declare const operationOptions: <Input, Output>(options: OperationOptions
     title?: string;
     description?: string;
 };
+/**
+ * Replace a native operation's approval. Property descriptors are copied so an output schema that
+ * a protocol adapter builds only when read stays lazy.
+ */
+export declare const approvedOperation: <Input, Native extends AppOperation<Input, unknown>>(operation: Native, approval: Approval<Input>) => Native;
 /** Attach the same approval function to a generated or shared operation. */
 export declare const withApproval: <Input, Output, Kind extends "query" | "mutation", Context>(operation: Operation<Input, Output, Kind, Context>, approval: Approval<Input>) => Operation<Input, Output, Kind, Context>;
+/**
+ * The advisory hints an operation carries, such as an MCP server's `destructiveHint`. App code
+ * reads them to choose an approval; the framework never infers one from them.
+ */
+export declare const toolAnnotations: (operation: OperationDeclaration<"query" | "mutation", never>) => ToolAnnotations | undefined;
 /** Read operation. External reads are allowed; only database writes are mechanically prohibited. */
 export declare const query: <Input, Output, Context extends AppContext = QueryContext>(options: OperationOptions<Input, Output>, run: (context: Context, input: Input) => Promise<Output>) => Operation<Input, Output, "query", Context>;
 /** Explicit write operation. Database writes roll back on failure; external effects cannot be undone. */

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

@@ -1,6 +1,6 @@
 /** One client's mounted queries and ordered optimistic write/read handoffs. */
 import { Effect } from "effect";
-import { Atom, AsyncResult } from "effect/unstable/reactivity";
+import { Atom, AsyncResult } from "effect/reactivity";
 import type { AppMutation } from "../contracts/optimistic.js";
 import type { OperationReference } from "../contracts/live.js";
 import { JsonValue } from "../contracts/schema.js";

package/types/apps/src/implementation/protocol-operations.d.ts

@@ -13,12 +13,14 @@ interface ProtocolOperation {
     readonly annotations?: ToolAnnotations | undefined;
     readonly _meta?: JsonObject | undefined;
     readonly input: Schema.Decoder<JsonValue>;
+    /** Checks and describes every returned value. */
+    readonly output?: Schema.Decoder<JsonValue> | undefined;
+    /** Describes the returned value without checking it; ignored when `output` is declared. */
     readonly outputSchema?: JsonObject | undefined;
     readonly run: (context: OperationContext, input: JsonValue) => Effect.Effect<unknown, unknown>;
 }
 /** Unknown behavior defaults to mutation. Classification never enforces an external service's behavior. */
-export declare const protocolOperations: (operations: Readonly<Record<string, ProtocolOperation>>, kinds?: OperationKinds) => {
-    queries: Record<string, Operation<Schema.Json, unknown, "query", OperationContext>>;
-    mutations: Record<string, Operation<Schema.Json, unknown, "mutation", OperationContext>>;
-};
+export declare const protocolOperations: (operations: Readonly<Record<string, ProtocolOperation>>, kinds?: OperationKinds) => Record<string, Operation<Schema.Json, unknown, "query" | "mutation", OperationContext>>;
+/** Operations already discovered, as a router keyed by upstream name. */
+export declare const protocolRouter: (operations: Readonly<Record<string, ProtocolOperation>>, kinds?: OperationKinds) => import("./operations.js").RouterDeclaration<unknown, unknown>;
 export {};

package/types/apps/src/implementation/provider-error.d.ts

@@ -1,10 +1,37 @@
 import { Option } from "effect";
+import type { FailurePhase, UpstreamError } from "../contracts/failure.js";
 import { ProviderError } from "../contracts/provider-error.js";
+import { AccountId } from "../contracts/schema.js";
+/** A provider failure's fields, each optional one possibly absent. */
+interface ProviderErrorFields {
+    readonly reason: ProviderError["reason"];
+    readonly status?: number | undefined;
+    readonly accountId?: AccountId | undefined;
+    readonly phase?: FailurePhase | undefined;
+    readonly upstream?: UpstreamError | undefined;
+}
+/**
+ * Construct a provider failure without keys for absent fields. Failures inside a catalog cross the
+ * boundary as JSON values, which have no `undefined`.
+ */
+export declare const providerError: ({ reason, status, accountId, phase, upstream, }: ProviderErrorFields) => ProviderError;
 /** Parse and rebuild the allowlisted fields, including when the input is already an Error instance. */
 export declare function parseProviderError(error: unknown): Option.Option<ProviderError>;
-/** Classify only explicit HTTP evidence. Raw provider content never enters the error. */
+/**
+ * The same failure with detail its raiser could not know: the phase it happened in, and the
+ * error the service stated. Detail the failure already carries is kept.
+ */
+export declare function providerErrorDetail(error: ProviderError, detail: {
+    readonly phase?: FailurePhase;
+    readonly upstream?: UpstreamError | undefined;
+}): ProviderError;
+/**
+ * Classify only explicit HTTP evidence. Raw provider content never enters the error; a Bearer
+ * challenge's documented error code and description do.
+ */
 export declare function httpProviderError(status: number, headers?: Readonly<Record<string, string>>): ProviderError | undefined;
 /** Attach the account used by the enclosing operation, without preserving arbitrary thrown fields. */
 export declare function accountProviderError<E>(error: E, accountId: string): E | ProviderError;
 /** GraphQL has no standard auth code; recognize these documented codes without guessing from prose. */
 export declare function graphqlProviderError(errors: readonly unknown[], status: number): ProviderError | undefined;
+export {};

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

@@ -1,16 +1,30 @@
 /** Pure constructors over the native provider contracts. */
 import { Effect, Schema } from "effect";
-import { type AuthMethods, OAuth2Config, OAuth2Method, Provider, SecretsMethod } from "../contracts/provider.js";
+import { type PromiseMethod } from "./authoring.js";
+import { type AccountCheck, type AuthMethods, type FieldExposure, OAuth2Config, OAuth2Method, Provider, SecretsMethod } from "../contracts/provider.js";
 import type { ValidationError } from "../contracts/schema.js";
 /** Declare a secrets method with an Effect decoder. */
 export declare const secrets: <Fields extends Schema.Decoder<unknown>>(options: {
     readonly label: string;
     readonly fields: Fields;
+    readonly exposure?: Readonly<Record<string, FieldExposure>>;
 }) => SecretsMethod<Fields>;
 /** Validate OAuth endpoints while declaring their app-visible response projection. */
-export declare const oauth2: <Response extends Schema.Decoder<unknown>>(config: OAuth2Config, response: Response) => Effect.Effect<OAuth2Method<Response>, ValidationError>;
-/** Retain the provider and literal method names without registering or authenticating it. */
-export declare const defineProvider: <const Auth extends AuthMethods>(options: {
+export declare const oauth2: <Response extends Schema.Decoder<unknown>>(config: OAuth2Config, response: Response, exposure?: Readonly<Record<string, FieldExposure>>) => Effect.Effect<OAuth2Method<Response>, ValidationError>;
+/** Author options: the account check is an ordinary async function. */
+export interface ProviderOptions<Auth extends AuthMethods> {
     readonly name: string;
     readonly auth: Auth;
-}) => Provider<Auth>;
+    /**
+     * Hosts the credentials may be sent to: `api.example.com`, `api.example.com:8443`, or
+     * `*.example.com` for one level of subdomain. Secret fields then reach app code as handles
+     * that the outbound network replaces only on requests to these hosts. An account records the
+     * hosts it was connected for; changing them does not change the provider, but an existing
+     * account sends only to hosts it was connected for until it is connected again.
+     */
+    readonly hosts?: readonly string[];
+    /** Verify a connected account with a safe read, optionally reporting its upstream identity. */
+    readonly health?: PromiseMethod<AccountCheck<Auth>["run"]>;
+}
+/** Retain the provider and literal method names without registering or authenticating it. */
+export declare const defineProvider: <const Auth extends AuthMethods>({ health, ...options }: ProviderOptions<Auth>) => Provider<Auth>;

package/types/apps/src/implementation/query-commit.d.ts

@@ -1,4 +1,4 @@
-import { AsyncResult } from "effect/unstable/reactivity";
+import { AsyncResult } from "effect/reactivity";
 /** Per-result metadata follows the exact Atom registry snapshot, including concurrent mounts. */
 export interface ObservedQueryValue<A> {
     readonly value: A;

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

@@ -0,0 +1,223 @@
+/**
+ * Read a live router tree into tools, routers and router skills. A nested dynamic router that fails
+ * is reported on its own entry; the root failing fails the read, as a single-source app would.
+ */
+import { Effect, Schema } from "effect";
+import { HostDeclarationInvalid, HostEvaluationFailed, type HostRouterError } from "../contracts/host.js";
+import type { AppOperation } from "../contracts/operations.js";
+import type { AppRouter, DynamicRouter, RouterMeta } from "../contracts/router.js";
+import type { OperationSchedule } from "../contracts/schedules.js";
+/**
+ * Keep only a failure's safe fields. Anything unrecognized becomes an evaluation failure with the
+ * error's name and bounded message, with the given account secrets replaced.
+ */
+export declare const safeFailure: (error: unknown, secrets: readonly string[]) => HostRouterError;
+/**
+ * Router skills are named `tools` for the root and `tools-<path>` below it, so a router's
+ * instructions never take an authored skill's name by accident.
+ */
+export declare const routerSkillPrefix = "tools";
+/**
+ * The skill name for a router path. A path of lowercase letters and digits is spelled out:
+ * `issues.open` is `tools-issues-open`. Any other path, or one too long, is a readable slug
+ * followed by a hash of the exact path, such as `tools-issues-list-0123456789`. Plain segments
+ * start with a letter and a hash is all digits, so the two forms never meet, and paths that slug
+ * alike, such as `issues_list` and `issues.list`, get different names.
+ */
+export declare const routerSkillName: (path: string) => string;
+/** A declared operation's catalog entry without schemas. `router` is its owning router's path. */
+export declare const operationSummary: (name: string, router: string, operation: AppOperation, schedules?: readonly OperationSchedule[]) => Effect.Effect<{
+    readonly description: string;
+    readonly name: string;
+    readonly router?: string;
+    readonly title?: string;
+    readonly annotations?: {
+        readonly title?: string;
+        readonly readOnlyHint?: boolean;
+        readonly destructiveHint?: boolean;
+        readonly idempotentHint?: boolean;
+        readonly openWorldHint?: boolean;
+    };
+    readonly schedules?: readonly {
+        readonly name: string;
+        readonly timing: {
+            readonly kind: "interval";
+            readonly milliseconds: number;
+        } | {
+            readonly kind: "cron";
+            readonly calendar: {
+                readonly expression: string;
+                readonly timezone: string;
+            };
+        };
+        readonly input: Schema.Json;
+    }[];
+    readonly readOnly?: boolean;
+    readonly tags?: readonly string[];
+}, HostDeclarationInvalid, never>;
+/** A declared operation's full description, including rendered schemas. */
+export declare const operationDescription: (name: string, router: string, operation: AppOperation, schedules?: readonly OperationSchedule[]) => Effect.Effect<{
+    readonly description: string;
+    readonly name: string;
+    readonly inputSchema: {
+        readonly [x: string]: Schema.Json;
+    };
+    readonly _meta?: {
+        readonly [x: string]: Schema.Json;
+    };
+    readonly router?: string;
+    readonly title?: string;
+    readonly annotations?: {
+        readonly title?: string;
+        readonly readOnlyHint?: boolean;
+        readonly destructiveHint?: boolean;
+        readonly idempotentHint?: boolean;
+        readonly openWorldHint?: boolean;
+    };
+    readonly outputSchema?: {
+        readonly [x: string]: Schema.Json;
+    };
+    readonly schedules?: readonly {
+        readonly name: string;
+        readonly timing: {
+            readonly kind: "interval";
+            readonly milliseconds: number;
+        } | {
+            readonly kind: "cron";
+            readonly calendar: {
+                readonly expression: string;
+                readonly timezone: string;
+            };
+        };
+        readonly input: Schema.Json;
+    }[];
+    readonly readOnly?: boolean;
+    readonly tags?: readonly string[];
+}, HostDeclarationInvalid, never>;
+/**
+ * A dynamic router over operations already discovered, such as an eager OpenAPI document or a
+ * stdio server. Upstream names can contain dots, which static router keys cannot.
+ */
+export declare const fixedRouter: (operations: Readonly<Record<string, AppOperation>>, meta?: RouterMeta) => DynamicRouter;
+export interface CatalogOptions {
+    /** Omit schemas. */
+    readonly summary: boolean;
+    /** Account secrets that a failure's message must not reveal. */
+    readonly secrets: readonly string[];
+    /** Only these full tool names. Routers with none of them are not read. */
+    readonly wanted?: ReadonlySet<string>;
+    /** Schedules that target a declared operation, by full name. */
+    readonly schedules: (name: string) => readonly OperationSchedule[];
+    /**
+     * Only declared operations that have schedules. Schedules never target dynamic routers, and
+     * their catalogs can be expensive to discover, so none is read.
+     */
+    readonly scheduled?: true;
+}
+/**
+ * Read a router tree. Every nested router is listed, for grouping; the root only when it has
+ * metadata. A nested dynamic source that fails is reported on its router's entry.
+ */
+export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined, options: CatalogOptions) => Effect.Effect<{
+    tools: ({
+        readonly description: string;
+        readonly name: string;
+        readonly inputSchema: {
+            readonly [x: string]: Schema.Json;
+        };
+        readonly _meta?: {
+            readonly [x: string]: Schema.Json;
+        };
+        readonly router?: string;
+        readonly title?: string;
+        readonly annotations?: {
+            readonly title?: string;
+            readonly readOnlyHint?: boolean;
+            readonly destructiveHint?: boolean;
+            readonly idempotentHint?: boolean;
+            readonly openWorldHint?: boolean;
+        };
+        readonly outputSchema?: {
+            readonly [x: string]: Schema.Json;
+        };
+        readonly schedules?: readonly {
+            readonly name: string;
+            readonly timing: {
+                readonly kind: "interval";
+                readonly milliseconds: number;
+            } | {
+                readonly kind: "cron";
+                readonly calendar: {
+                    readonly expression: string;
+                    readonly timezone: string;
+                };
+            };
+            readonly input: Schema.Json;
+        }[];
+        readonly readOnly?: boolean;
+        readonly tags?: readonly string[];
+    } | {
+        readonly description: string;
+        readonly name: string;
+        readonly router?: string;
+        readonly title?: string;
+        readonly annotations?: {
+            readonly title?: string;
+            readonly readOnlyHint?: boolean;
+            readonly destructiveHint?: boolean;
+            readonly idempotentHint?: boolean;
+            readonly openWorldHint?: boolean;
+        };
+        readonly schedules?: readonly {
+            readonly name: string;
+            readonly timing: {
+                readonly kind: "interval";
+                readonly milliseconds: number;
+            } | {
+                readonly kind: "cron";
+                readonly calendar: {
+                    readonly expression: string;
+                    readonly timezone: string;
+                };
+            };
+            readonly input: Schema.Json;
+        }[];
+        readonly readOnly?: boolean;
+        readonly tags?: readonly string[];
+    })[];
+    routers: {
+        readonly path: string;
+        readonly description?: string;
+        readonly error?: import("../index.js").ProviderError | import("../contracts/host.js").McpError | import("../contracts/host.js").SkillLoadFailed | HostDeclarationInvalid | HostEvaluationFailed;
+        readonly title?: string;
+        readonly tags?: {
+            readonly [x: string]: string;
+        };
+        readonly icons?: readonly {
+            readonly src: string;
+            readonly mimeType?: string;
+            readonly sizes?: readonly string[];
+            readonly theme?: "light" | "dark";
+        }[];
+        readonly skill?: string;
+    }[];
+}, import("../index.js").ProviderError | import("../contracts/host.js").McpError | import("../contracts/host.js").SkillLoadFailed | HostDeclarationInvalid | HostEvaluationFailed, never>;
+/**
+ * One skill for each router with instructions. Skills and tools fail independently: a dynamic
+ * router whose metadata cannot be read, including the root, contributes no skill and does not
+ * fail the others. Metadata comes through each source's catalog cache, like a tool listing.
+ */
+export declare const routerSkills: (root: AppRouter | DynamicRouter | undefined) => Effect.Effect<{
+    readonly description: string;
+    readonly name: string;
+    readonly files: readonly {
+        readonly path: string;
+        readonly content: string;
+    }[];
+    readonly license?: string;
+    readonly compatibility?: string;
+    readonly metadata?: {
+        readonly [x: string]: string;
+    };
+    readonly "allowed-tools"?: string;
+}[], never, never>;

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

@@ -0,0 +1,70 @@
+import { HostedTool } from "../contracts/host.js";
+import type { AppOperation } from "../contracts/operations.js";
+import { RouterMeta, type AppRouter, type DynamicRouter, type RouterIcon } from "../contracts/router.js";
+import type { Approval } from "../approval.js";
+import { type OperationChild, type OperationDeclaration, type RouterChild, type RouterDeclaration } from "./operations.js";
+export type { OperationChild, OperationDeclaration, RouterChild, RouterDeclaration, } from "./operations.js";
+/** Author metadata for a router. Instructions become a skill named after the router's path. */
+export interface RouterOptions {
+    readonly title?: string;
+    readonly description?: string;
+    readonly instructions?: string;
+    readonly icons?: readonly RouterIcon[];
+    readonly tags?: Readonly<Record<string, string>>;
+}
+/** Wrap a native router. Protocol helpers use this for the routers they build. */
+export declare const routerDeclaration: (node: AppRouter | DynamicRouter) => RouterDeclaration;
+/** Accept only framework-created routers. */
+export declare const nativeRouter: (value: unknown) => AppRouter | DynamicRouter | undefined;
+/** Author fields win; a field the author omits keeps the source's value. */
+export declare const mergeMeta: (base: RouterMeta | undefined, override: RouterMeta | undefined) => RouterMeta | undefined;
+/**
+ * Group operations and routers under path keys, like tRPC's nested routers, with metadata an
+ * agent can read. Passing an existing router instead of children overrides its metadata:
+ * `router(mcpRouter(options), { description: "..." })`.
+ */
+export declare function router<Query = unknown, Mutation = unknown>(children: Readonly<Record<string, RouterChild<Query, Mutation>>>, options?: RouterOptions): RouterDeclaration<Query, Mutation>;
+export declare function router<Query, Mutation>(source: RouterDeclaration<Query, Mutation>, options: RouterOptions): RouterDeclaration<Query, Mutation>;
+/**
+ * Declare a router whose tools are discovered when read. `list` returns tools with names relative
+ * to this router; mark queries with `readOnly: true`. `resolve` receives one of those names.
+ * The router carries the handler contexts of the operations `resolve` returns, so `defineApp`
+ * checks them like a static router's.
+ */
+export declare const dynamicRouter: <Query = unknown, Mutation = unknown>(source: {
+    readonly meta?: () => RouterOptions | Promise<RouterOptions>;
+    readonly list: () => readonly HostedTool[] | Promise<readonly HostedTool[]>;
+    readonly resolve: (name: string) => OperationChild<Query, Mutation> | undefined | Promise<OperationChild<Query, Mutation> | undefined>;
+}) => RouterDeclaration<Query, Mutation>;
+/** Join a router path and a relative name. The root router's path is "". */
+export declare const joinPath: (path: string, name: string) => string;
+/** Where a full tool name points: a declared operation, or a name inside a dynamic router. */
+export type Location = {
+    readonly kind: "operation";
+    readonly operation: AppOperation;
+    readonly router: string;
+} | {
+    readonly kind: "dynamic";
+    readonly source: DynamicRouter;
+    readonly router: string;
+    readonly name: string;
+};
+/**
+ * Walk static keys until the name ends at an operation or enters a dynamic router, which receives
+ * the rest of the name. Static keys contain no dots, so every name has at most one location.
+ */
+export declare const locate: (root: AppRouter | DynamicRouter | undefined, name: string) => Location | undefined;
+/** Every declared operation with its full name and owning router. Dynamic routers are not listed. */
+export declare const declaredOperations: (root: AppRouter | undefined, path?: string) => Array<{
+    readonly name: string;
+    readonly router: string;
+    readonly operation: AppOperation;
+}>;
+/**
+ * Choose an approval for each operation a router contains, including tools a dynamic router
+ * resolves later. `policy` receives the operation and its name relative to this router; returning
+ * undefined keeps the operation's own approval. Read hints with `toolAnnotations(operation)`.
+ * Apply it to each account's router before `accountRouter` combines them, so every account keeps
+ * its own tools' hints.
+ */
+export declare const withApprovals: <Query, Mutation>(source: RouterDeclaration<Query, Mutation>, policy: (operation: OperationDeclaration<"query" | "mutation", never>, name: string) => Approval | undefined) => RouterDeclaration<Query, Mutation>;

package/types/apps/src/implementation/runtime-yield.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Let the runtime run its own tasks between long synchronous steps. In a Worker, a large OpenAPI
+ * compilation that never yields leaves the garbage collector only long, full pauses; yielding
+ * between steps measurably shortens it. A timer is used because a resolved promise would continue
+ * without leaving the current task.
+ */
+export declare const yieldToRuntime: () => Promise<void>;

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

@@ -1,12 +1,10 @@
 /** Author schema facade. Internals use the native decoder retained by each value. */
 import { Effect, Schema as EffectSchema } from "effect";
-import { ValidationError, type JsonObject } from "../contracts/schema.js";
-import type { Field } from "../../../app-data/src/contracts/database.js";
-declare const StorageField: unique symbol;
+import { JsonObject, ValidationError } from "../contracts/schema.js";
+import type { FieldExposure } from "../contracts/provider.js";
 declare const Decoder: unique symbol;
 /** An author-facing value schema. Effect is never required in author code. */
 export interface Schema<T, Optional extends boolean = false> {
-    readonly [StorageField]?: Field;
     readonly [Decoder]: EffectSchema.Decoder<T>;
     readonly optionalValue: Optional;
     /** Parse an unknown value; invalid input throws a safe ValidationError. */
@@ -37,10 +35,15 @@ export interface ObjectSchema<F extends Fields> extends Schema<ObjectValue<F>> {
 export declare const decoderOf: <T>(schema: Schema<T, boolean>) => EffectSchema.Decoder<T>;
 /** Recognize schemas made by this author facade when adapting a definition. */
 export declare const isSchema: (value: unknown) => value is Schema<unknown, boolean>;
+/**
+ * Source that skipped type checking can pass any value where a schema belongs, such as `string`
+ * for `string()`. Name the argument and the mistake before a native constructor reads it.
+ */
+export declare const schemaArgument: <S extends Schema<unknown, boolean>>(value: S, role: string) => S;
 /** Decode within an Effect program. Invalid input is omitted from the failure. */
 export declare const parse: <T>(decoder: EffectSchema.Decoder<T>, input: unknown) => Effect.Effect<T, ValidationError>;
 /** Present a native decoder through the synchronous author API. */
-export declare function wrap<T, Optional extends boolean>(decoder: EffectSchema.Decoder<T>, optionalValue: Optional, field?: Field): Schema<T, Optional>;
+export declare function wrap<T, Optional extends boolean>(decoder: EffectSchema.Decoder<T>, optionalValue: Optional): Schema<T, Optional>;
 /** A string, optionally with a minimum length. No coercion. */
 export declare function string(options?: {
     readonly minLength?: number;
@@ -59,6 +62,44 @@ export declare function literal<const T extends string | number | boolean | null
 export declare const array: <T>(item: Schema<T, boolean>) => Schema<readonly T[]>;
 /** Parse declared fields and omit undeclared fields. */
 export declare function object<const F extends Fields>(fields: F): ObjectSchema<F>;
+declare const Exposure: unique symbol;
+/** A schema marked with how app code sees the field in a provider that declares hosts. */
+export type Exposed<S, E extends FieldExposure = FieldExposure> = S & {
+    readonly [Exposure]: E;
+};
+/** The marking of one account field, if any. */
+export declare const exposureOf: (schema: Schema<unknown, boolean>) => FieldExposure | undefined;
+/**
+ * A field that is not secret, such as a subdomain or region. App code reads its real value and
+ * the connect form shows it.
+ */
+export declare const plain: <S extends Schema<unknown, boolean>>(schema: S) => Exposed<S, "plain">;
+/**
+ * A secret field that app code reads as its real value, for request signing and similar uses.
+ * The connect form warns that the app can read it. Prefer an unmarked field, which app code
+ * receives as a handle that only reaches the provider's declared hosts.
+ */
+export declare const raw: <S extends Schema<unknown, boolean>>(schema: S) => Exposed<S, "raw">;
+/** Marked fields of an account object, by name. */
+export declare const fieldExposure: (fields: Fields) => Readonly<Record<string, FieldExposure>>;
+declare const Secret: unique symbol;
+/**
+ * A secret account value. In a provider that declares hosts it is a handle, which the host's
+ * outbound network replaces with the real value only on requests to those hosts. Pass it to
+ * clients and headers as an ordinary string; do not decode or transform it.
+ */
+export type SecretString = string & {
+    readonly [Secret]: true;
+};
+type Sealed<T> = T extends string ? SecretString : T;
+/** Account fields as app code receives them: unmarked string fields are secret. */
+export type SecretFields<F extends Fields> = {
+    readonly [Key in keyof ObjectValue<F>]: Key extends keyof F ? F[Key] extends Exposed<unknown> ? ObjectValue<F>[Key] : Sealed<ObjectValue<F>[Key]> : ObjectValue<F>[Key];
+};
+/** An account object without declared fields, such as a default OAuth projection. */
+export type SecretObject<T> = {
+    readonly [Key in keyof T]: Sealed<T[Key]>;
+};
 declare const ImportedJsonSchema: unique symbol;
 /** Read the original document for an imported decoder without a lossy schema round trip. */
 export declare const importedJsonSchema: (decoder: EffectSchema.Decoder<unknown>) => unknown | undefined;
@@ -72,8 +113,45 @@ export declare const withLazyJsonSchemaDocument: <S extends EffectSchema.Decoder
  * Relocate a self-contained JSON Schema under a document pointer. Resolve references
  * before nesting so account schemas can reuse definition names, IDs and anchors.
  * Only schema nodes are rewritten; examples and ordinary property values stay intact.
+ * A `$recursiveRef` becomes the pointer to its static target, such as the relocated root. The
+ * patched validator applies it like `"#"` was: the recursive anchor in scope, else that target.
  */
 export declare const nestJsonSchema: (input: JsonObject, pointer: string) => JsonObject;
+/**
+ * Whether an input key may be named in a validation problem. Other keys can carry supplied data,
+ * so problems locate them without echoing them.
+ */
+export declare const echoableKey: (key: string) => boolean;
+/**
+ * The keys an object accepts, as `object {name, optional?}`. `...` marks an object that also
+ * accepts other keys. Names come from the schema, never from supplied input.
+ */
+export declare const objectShape: (keys: readonly {
+    readonly name: string;
+    readonly optional: boolean;
+}[], open: boolean, limit?: number) => string;
+/**
+ * The values a schema fixes, as `"v1"` or `one of "a", "b" and 3 more`. Agents already read
+ * these values in the tool's signature, so problems list them, up to {@link maxListedValues}
+ * values and {@link maxValuesText} characters. They come from the schema, never from input.
+ */
+export declare const allowedValues: (values: readonly unknown[]) => string;
+/** Keys listed for each union alternative, so several alternatives fit in one problem. */
+export declare const maxAlternativeKeys = 8;
+/**
+ * The alternatives a union accepts, as `string or object {id}`, and the key whose value tells
+ * them apart. Shapes, values and the key come from the schema, never from supplied input.
+ */
+export declare const unionShape: (alternatives: readonly string[], selector: string | undefined) => string;
+/** The problem for a required key the input omits, with what its schema expects when stated. */
+export declare const missingKey: (expected: string | undefined) => string;
+/** The text every missing-key problem starts with, so the caller can add where the input has it. */
+export declare const missingKeyText = "Missing key";
+/**
+ * Whether the imported schema whose check failed may accept a key as an object's own key, for a
+ * failure's check; undefined when the check is not an imported schema's.
+ */
+export declare const importedSchemaKeys: (check: object) => ((key: string) => boolean) | undefined;
 /** Prepare an interpreted validator. No eval or generated JavaScript runs in any host. */
 export declare const compileJsonSchemaDecoder: (document: JsonObject) => Effect.Effect<EffectSchema.Codec<EffectSchema.Json, EffectSchema.Json, never, never> & {
     [ImportedJsonSchema]: {
@@ -81,14 +159,20 @@ export declare const compileJsonSchemaDecoder: (document: JsonObject) => Effect.
     };
 }, ValidationError, never>;
 export declare const lazyJsonSchemaDecoder: (document: () => JsonObject) => Effect.Effect<EffectSchema.declareConstructor<EffectSchema.Json, EffectSchema.Json, readonly [], EffectSchema.Json>, never, never>;
+/**
+ * A lazy decoder and the compilation it decodes with. Running `compile` first lets a caller
+ * reject an unsupported schema before a side effect whose result the decoder will check.
+ */
+export declare const preparedJsonSchemaDecoder: (document: JsonObject) => {
+    decoder: EffectSchema.declareConstructor<EffectSchema.Json, EffectSchema.Json, readonly [], EffectSchema.Json>;
+    compile: Effect.Effect<EffectSchema.Decoder<EffectSchema.Json, never>, ValidationError, never>;
+};
 /** Preserve the JSON document; compile its validator only when a value is first decoded. */
 export declare const jsonSchemaDecoder: (input: unknown) => Effect.Effect<EffectSchema.declareConstructor<EffectSchema.Json, EffectSchema.Json, readonly [], EffectSchema.Json>, ValidationError, never>;
 /** Import JSON metadata now; unsupported schemas and invalid values fail when parsed. */
 export declare const jsonSchema: (input: unknown) => Schema<EffectSchema.Json>;
-/** Database declaration retained by primitive constructors; nested payload schemas are not database fields. */
-export declare const storageFieldOf: (schema: Schema<unknown, boolean>) => Field | undefined;
-/** A row reference records the target table; existence is not a foreign-key constraint. */
-export declare const id: (table: string) => Schema<string>;
-/** A host user identifier, stored as a string without imposing a product auth model. */
-export declare const userId: () => Schema<string>;
+/** Render a decoder as a JSON Schema document, keeping an imported upstream document as-is. */
+export declare const jsonSchemaDocument: (decoder: EffectSchema.Decoder<unknown>) => Effect.Effect<{
+    readonly [x: string]: EffectSchema.Json;
+}, EffectSchema.SchemaError, never>;
 export {};