apps 0.0.1-beta.11 → 0.0.1-beta.110

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

@@ -0,0 +1,16 @@
+/** Typed refusals and option checks for the fetch app code receives from the framework. */
+import { Effect } from "effect";
+import type { HttpClientResponse } from "effect/http";
+import { type NetworkRefused } from "../contracts/network.js";
+type Fetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** Fail with the refusal a protocol helper's response carries, or continue to its own handling. */
+export declare const failOnNetworkRefusal: (response: HttpClientResponse.HttpClientResponse) => Effect.Effect<void, NetworkRefused>;
+/**
+ * The fetch app code receives as `ctx.fetch`. It rejects a RequestInit value the app runtime
+ * would reject, naming the option, on every host. A request Executor's app network refused
+ * rejects with `NetworkRefused`: the service never answered, so there is no response to return.
+ */
+export declare const appFetch: (fetch: Fetch) => Fetch;
+/** The invocation's correlated, cancellable fetch, as app code receives it. */
+export declare const appInvocationFetch: (signal: AbortSignal) => Effect.Effect<Fetch, never, never>;
+export {};

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

@@ -1,24 +1,48 @@
 /** 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 { OpenapiErrorResponse } from "../contracts/openapi.js";
 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?: {
+import { type OpenApiDocument } from "./openapi-document.js";
+/** Keep tagged errors, including response/component refs and anyOf alternatives.
+ * Public text comes from a declared string message or the schema's static description.
+ * `scripts/check-api-errors.ts` applies this to Executor's own API documents.
+ */
+export declare function errorResponses(document: OpenApiDocument, operation: JsonObject, at: string): OpenapiErrorResponse[];
+/**
+ * The tool name, method and declared path of every operation a definition declares, in definition
+ * order, whether or not the compiler imports it: the names `compileOpenApiDocument` gives them.
+ * The document is consumed, as compilation consumes it.
+ */
+export declare const compiledOperationNames: (document: JsonObject) => Effect.Effect<{
+    name: string;
+    method: string;
+    path: string;
+}[], TemplateError, never>;
+/** Compile a revision of a live OpenAPI source into tool declarations for the app runtime.
+ * The document is consumed: compilation upgrades it in place instead of copying it. It must be a
+ * tree, with no object reached twice, as parsed JSON is.
+ */
+export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocument: JsonObject, options?: {
     readonly baseUrl?: string;
-    readonly allowedOrigin?: string;
+    /** The origins operations may address; every other operation is left out. */
+    readonly allowedOrigin?: string | readonly string[];
+    /** Inserted between every operation's server and path; see `prefixParameters`. */
+    readonly pathPrefix?: string;
     readonly securitySchemes?: Readonly<Record<string, JsonObject>>;
     readonly fallbackSecurity?: GeneratedOperation["request"]["security"];
 }) => Effect.Effect<{
     operations: {
-        readonly name: string;
         readonly path: string;
+        readonly method: "HEAD" | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "QUERY";
         readonly description: string;
+        readonly name: string;
         readonly request: {
             readonly parameters: readonly {
+                readonly in: "path" | "header" | "query" | "querystring" | "cookie";
                 readonly name: string;
-                readonly in: "query" | "path" | "header" | "cookie";
                 readonly required?: boolean;
                 readonly schema?: {
                     readonly [x: string]: Schema.Json;
@@ -56,7 +80,6 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
         readonly input: {
             readonly [x: string]: Schema.Json;
         };
-        readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
         readonly securitySchemes: {
             readonly [x: string]: {
                 readonly [x: string]: Schema.Json;
@@ -84,6 +107,14 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
             };
         }[];
     }[];
+    /** Declared operations left out of `operations`, in definition order. */
+    skipped: {
+        readonly name: string;
+        readonly method: string;
+        readonly path: string;
+        readonly code: "server_protocol" | "server_url" | "external_reference" | "circular_reference" | "schema_keyword" | "schema_reference" | "missing_component" | "openapi_version" | "auth_helper" | "auth_missing" | "operation_path" | "operation_method" | "duplicate_operation" | "server_missing" | "multiple_hosts" | "parameter_encoding" | "parameter_style" | "request_body" | "combined_oauth" | "auth_method" | "event_stream" | "input_schema" | "no_operations" | "no_supported_operations" | "invalid_document" | "source_generation" | "authoring_reference";
+        readonly reason: string;
+    }[];
     definitions: {
         [k: string]: {
             readonly [x: string]: Schema.Json;
@@ -113,7 +144,7 @@ export declare const compileOpenApiDocument: (entry: OpenApiImport, inputDocumen
             readonly [x: string]: Schema.Json;
         };
     };
-    pinnedOrigin: string | undefined;
+    pinnedOrigins: string[];
     fallback: readonly {
         readonly [x: string]: readonly string[];
     }[] | undefined;

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

@@ -1,11 +1,32 @@
 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.
+/**
+ * An object in a document that was validated as JSON when it was read. Compilation only turns JSON
+ * into JSON, so inside it an object's shape is checked, not its every leaf again: re-validating
+ * whole documents was most of a large API's compile time.
  */
-export declare function openApiDocument(input: unknown): Promise<{
+export declare const DocumentObject: Schema.declare<{
+    readonly [x: string]: Schema.Json;
+}, {
+    readonly [x: string]: Schema.Json;
+}>;
+export declare const documentObject: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
+    readonly [x: string]: Schema.Json;
+};
+/** One JSON Pointer reference token. */
+export declare const pointerToken: (key: string) => string;
+/**
+ * Decode one part of the definition, located by the JSON Pointer `at`. A mismatch names the
+ * pointer of the first failing value and what was expected there.
+ */
+export declare const decodeDefinition: <S extends Schema.Decoder<unknown>>(schema: S, value: unknown, at: string, what: string) => S["Type"];
+/** Resolve OpenAPI objects once; schemas retain their original recursive references.
+ * Scalar first upgrades Swagger 2.0 and OpenAPI 3.0 to 3.1, so the importer reads 3.1 and 3.2,
+ * whose Schema Objects share 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: JsonObject): Promise<{
     spec: {
         readonly openapi: string;
         readonly paths: {
@@ -13,39 +34,48 @@ export declare function openApiDocument(input: unknown): Promise<{
                 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 schemas?: {
                 readonly [x: string]: {
                     readonly [x: string]: Schema.Json;
                 };
             };
-            readonly schemas?: {
+            readonly securitySchemes?: {
                 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;
+            };
+        }[];
     };
     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. */
+    /**
+     * The JSON Pointer of the object a local reference resolved to, so a diagnostic can locate
+     * a resolved Response, Parameter, Request Body or Path Item where the definition declares it.
+     */
+    origin(value: unknown): string | undefined;
+    /**
+     * Inspect the schema a reference reaches without expanding its children: a component, or any
+     * other schema in the definition. OpenAPI object references are already resolved.
+     */
     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.
+     * Draft 2020-12 and must not be reinterpreted. `api` takes the schema's JSON Pointer in the
+     * definition, which failures name. 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;
+    schema(build: (api: (input: Schema.Json, at: string) => JsonObject) => JsonObject): JsonObject;
 }>;
 /** A parsed document with one reference scope and one schema dialect. */
 export type OpenApiDocument = Awaited<ReturnType<typeof openApiDocument>>;

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

@@ -11,8 +11,13 @@ export interface OperationNameInput {
     readonly path: string;
 }
 /**
- * Plan one name per input, in input order. Names that collide are refined together: first by
- * the path's version segment, then by the HTTP method, then by a stable hash. Refinement only
- * touches the colliding names, so adding an operation never renames an unrelated one.
+ * Name every input, in input order. Names that collide, whether or not they come from an
+ * operationId, are refined together: first by the path's version segment, then by the path
+ * segments that tell them apart (`GET /items` and `GET /items/{id}` are `items.getItems` and
+ * `items.getItemsById`), then by the whole path, then by the HTTP method, then by a stable hash.
+ * Refinement only touches the colliding names, so adding an operation never renames an unrelated
+ * one.
  */
-export declare const planOperationNames: (inputs: readonly OperationNameInput[]) => string[];
+export declare const planOperationNames: <I extends OperationNameInput>(inputs: readonly I[]) => (I & {
+    readonly name: string;
+})[];

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

@@ -1,3 +1,4 @@
+import { NetworkRefused } from "../contracts/network.js";
 import { ProviderError } from "../contracts/provider-error.js";
 /** Swagger constructs requests; Effect owns HTTP policy and bounded results. */
 import { Effect, Schema } from "effect";
@@ -6,12 +7,19 @@ import { OpenapiError, type CredentialBinding, type OpenapiOperation, type Opena
 type DeclaredError = OpenapiErrorResponse & {
     readonly decoder: Schema.Decoder<Schema.Json>;
 };
+/** What decides whether an account can call an operation: its transport and security. */
+export interface OpenapiOperationAccess {
+    readonly streaming?: true;
+    readonly request: {
+        readonly security: OpenapiOperation["request"]["security"];
+    };
+}
 /** Create request helpers from credential-free generated authentication metadata. */
 export declare function createRequest(config: {
     readonly methods: Readonly<Record<string, readonly CredentialBinding[]>>;
     readonly oauth: readonly string[];
 }): {
-    available: (op: OpenapiOperation, account: OpenapiAccount | undefined) => boolean;
-    call: (op: OpenapiOperation, input: unknown, account: OpenapiAccount | undefined, errors: readonly DeclaredError[]) => Effect.Effect<Schema.Json, ProviderError | OpenapiResponseError | OpenapiError, never>;
+    available: (op: OpenapiOperationAccess, account: OpenapiAccount | undefined) => boolean;
+    call: (op: OpenapiOperation, input: unknown, account: OpenapiAccount | undefined, errors: readonly DeclaredError[]) => Effect.Effect<Schema.Json, ProviderError | NetworkRefused | OpenapiResponseError | OpenapiError, never>;
 };
 export {};

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

@@ -3,6 +3,7 @@ import { Duration } from "effect";
 import type { AppCache } from "../contracts/cache.js";
 import { OpenapiOperation, type OpenapiToolsOptions } from "../contracts/openapi.js";
 import { JsonObject, JsonValue } from "../contracts/schema.js";
+import { type OpenapiToolNames } from "../contracts/openapi-compile.js";
 import { type OperationKinds } from "./protocol-operations.js";
 import { type RouterDeclaration } from "./router.js";
 /** Static credential placement and destination are reviewed when the app is authored/imported. */
@@ -13,9 +14,19 @@ export interface OpenapiSourceOptions extends Omit<OpenapiToolsOptions, "operati
     } | {
         readonly document: JsonObject;
     };
-    readonly allowedOrigin: string;
+    /**
+     * The origin that may receive credentials, or several origins of one service, such as its API
+     * and upload hosts. Operations on any other origin are left out.
+     */
+    readonly allowedOrigin: string | readonly string[];
     readonly securitySchemes: Readonly<Record<string, JsonObject>>;
     readonly baseUrl?: string;
+    /**
+     * A path inserted between the server and every operation's path, for a definition that omits a
+     * leading segment, such as `/projects/{project}`. Each `{name}` becomes a required string path
+     * parameter of every tool, unless the operation already declares it without placing it.
+     */
+    readonly pathPrefix?: string;
     readonly freshFor?: Duration.Input;
     readonly staleFor?: Duration.Input;
     /**
@@ -34,3 +45,14 @@ export interface OpenapiSourceOptions extends Omit<OpenapiToolsOptions, "operati
 export declare function patchOpenapi(root: JsonObject, patches: OpenapiSourceOptions["patches"]): JsonObject;
 /** No I/O during app construction. All accounts share credential-free compilation. */
 export declare const liveOpenapiRouter: (options: OpenapiSourceOptions) => RouterDeclaration;
+/** The settings `openapiToolNames` reads: the router's, without an account or cache. */
+export type OpenapiToolNamesOptions = Omit<OpenapiSourceOptions, "cache" | "account" | "parameterDefaults" | "freshFor" | "staleFor">;
+/**
+ * The tools `liveOpenapiRouter` with the same options exposes, from the definition alone: no
+ * account, cache or deployed version. Each tool says which `methods` and `oauth` entries expose it, so
+ * an author can check the names a `withApprovals` policy matches before any account connects.
+ * `skipped` lists only the operations the compiler left out and why. An operation no configured
+ * `methods` or `oauth` entry can authorize is missing from `tools` and not listed in `skipped`.
+ * `fetch` defaults to the global fetch.
+ */
+export declare const openapiToolNames: (options: OpenapiToolNamesOptions) => Promise<OpenapiToolNames>;

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

@@ -0,0 +1,4 @@
+type Node = Record<string, unknown>;
+/** Upgrade a 3.0 document the caller owns. Any other version is returned unchanged. */
+export declare const upgradeOpenApi30InPlace: (document: Node) => Node;
+export {};

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

@@ -1,12 +1,27 @@
 /** 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 { AppContext, AppRequirements, AnyScopeMutationContext, MutationContext, QueryContext } from "../contracts/context.js";
+import type { AccountScope } from "../contracts/app.js";
 import type { Approval } from "../approval.js";
 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 ApprovalDeclared: unique symbol;
+/**
+ * Marks an operation declared with an approval. App-scope work, such as an app schedule, has no
+ * person to approve a call, so it accepts only operations without this mark.
+ */
+export interface Approved {
+    readonly [ApprovalDeclared]: true;
+}
+/** An operation declared without an approval. */
+export interface WithoutApproval {
+    readonly [ApprovalDeclared]?: never;
+}
+/** The context any handler may declare: either scope, so `user` may be absent. */
+export type AnyContext = AppContext<AppRequirements, AccountScope>;
 declare const QueryHandlerContext: unique symbol;
 declare const MutationHandlerContext: unique symbol;
 /**
@@ -38,6 +53,11 @@ 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. */
@@ -64,7 +84,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;
@@ -79,10 +99,41 @@ 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>;
+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> & Approved;
+/**
+ * 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. An MCP tool's
+ * `readOnlyHint` is its kind, so a `kinds` entry replaces the server's.
+ */
+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. */
-export declare const mutation: <Input, Output, Context extends AppContext = MutationContext>(options: OperationOptions<Input, Output>, run: (context: Context, input: Input) => Promise<Output>) => Operation<Input, Output, "mutation", Context>;
+export declare const query: <Input, Output, Context extends AnyContext = QueryContext>(options: OperationOptions<Input, Output>, run: (context: Context, input: Input) => Promise<Output>) => Operation<Input, Output, "query", Context>;
+/** The parameters a mutation's handler declares: its context and input, its context, or none. */
+type HandlerParameters<Context, Input> = [context: Context, input: Input] | [context: Context] | [];
+/** The context a handler declares; one without parameters may run in either scope. */
+type DeclaredContext<Signature, Context> = Signature extends [] ? AnyScopeMutationContext : Signature extends readonly [infer Declared, ...unknown[]] ? Declared : Context;
+/**
+ * Explicit write operation. Database writes roll back on failure; external effects cannot be undone.
+ * A handler that declares a context gets the caller's, with `user`, unless its type says otherwise.
+ * One that declares no parameters, in a call without explicit type arguments, uses no context, so
+ * it may run as the app, as an app schedule runs it. Explicit type arguments name the context with
+ * the third, which defaults to the caller's. One declared with an approval is marked `Approved`, so
+ * app-scope schedules refuse it.
+ */
+export declare function mutation<Input, Output, Context extends AnyContext = MutationContext>(options: OperationOptions<Input, Output> & {
+    readonly approval: Approval<Input>;
+}, run: (context: Context, input: Input) => Promise<Output>): Operation<Input, Output, "mutation", Context> & Approved;
+export declare function mutation<Input, Output, Context extends AnyContext = MutationContext, Signature extends HandlerParameters<Context, Input> = [context: Context, input: Input]>(options: OperationOptions<Input, Output> & {
+    readonly approval?: undefined;
+}, run: (...parameters: Signature) => Promise<Output>): Operation<Input, Output, "mutation", DeclaredContext<Signature, Context>>;
+/** A handler whose context's type the caller's does not fit, such as one of the `"app"` scope. */
+export declare function mutation<Input, Output, Context extends AnyContext>(options: OperationOptions<Input, Output> & {
+    readonly approval?: undefined;
+}, run: (context: Context, input: Input) => Promise<Output>): Operation<Input, Output, "mutation", Context>;
 export {};

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/placement.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Authoring credential placements. A method's `request` callback runs once, when the provider is
+ * declared, with an opaque reference for each of the method's fields. It returns placements built
+ * from `header` or `query` and a value from `t`, `base64` and references; the result is stored
+ * as data. A reference is not a string: an untagged template literal fails when it is evaluated.
+ */
+import { Placement, type PlacementPart } from "../contracts/placement.js";
+import type { AccountRequest, FieldExposure } from "../contracts/provider.js";
+/** Throw when JavaScript turns a placement into a string, so untagged templates fail. */
+declare class NotAString {
+    #private;
+    constructor(described: string);
+    [Symbol.toPrimitive](): never;
+    toString(): never;
+    toJSON(): never;
+}
+/** A reference to one of the method's account fields, given to its `request` callback. */
+export declare class FieldRef<Name extends string = string> extends NotAString {
+    readonly field: Name;
+    constructor(field: Name);
+}
+/** A value template built with `t` or `base64`. */
+export declare class PlacementValue extends NotAString {
+    readonly parts: readonly PlacementPart[];
+    constructor(parts: readonly PlacementPart[]);
+}
+/** What a template may interpolate: literal text, a field reference or another value. */
+export type PlacementInput = string | FieldRef | PlacementValue;
+/** A value template: literal text with interpolated field references and values. */
+export declare const t: (strings: TemplateStringsArray, ...values: readonly PlacementInput[]) => PlacementValue;
+/** Base64 of a value's UTF-8 bytes, such as the `user:password` of Basic credentials. */
+export declare const base64: (value: PlacementInput) => PlacementValue;
+/** Send a value as the whole value of this header. The name is case-insensitive. */
+export declare const header: (name: string, input: PlacementInput) => Placement;
+/** Send a value as the whole value of this query parameter. */
+export declare const query: (name: string, input: unknown) => Placement;
+/** `Authorization: Bearer <token>`. */
+export declare const bearer: (token: FieldRef) => Placement;
+/** `Authorization: Basic base64(<user>:<password>)`. */
+export declare const basic: (user: PlacementInput, password: PlacementInput) => Placement;
+/** The field references a `request` callback receives, by field name. */
+export type FieldRefs<Name extends string> = {
+    readonly [Key in Name]: FieldRef<Key>;
+};
+/** How a method declares its placements: called once with its field references. */
+export type RequestPlacements<Name extends string> = (fields: FieldRefs<Name>) => Placement | readonly Placement[];
+/**
+ * Run a method's `request` callback once and check its placements. Every reference names one of
+ * the method's fields, no `raw()` field appears, and each placement references a secret field.
+ */
+export declare const declarePlacements: (method: string, names: readonly string[], exposure: Readonly<Record<string, FieldExposure>> | undefined, request: RequestPlacements<string>) => readonly Placement[];
+/**
+ * Give a bound account `headers()` and `url()`, rendering the placements the host granted with the
+ * fields app code holds. They are not enumerable, so the account's JSON is unchanged.
+ */
+export declare const withPlacements: <Account extends {
+    readonly method: string;
+    readonly fields: unknown;
+}>(account: Account, placements: readonly Placement[] | undefined) => Account & AccountRequest;
+export {};

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

@@ -13,6 +13,9 @@ 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>;
 }

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,21 +1,36 @@
 /** Pure constructors over the native provider contracts. */
 import { Effect, Schema } from "effect";
 import { type PromiseMethod } from "./authoring.js";
-import { type AccountCheck, type AuthMethods, OAuth2Config, OAuth2Method, Provider, SecretsMethod } from "../contracts/provider.js";
-import type { ValidationError } from "../contracts/schema.js";
+import { type AccountCheck, type AuthMethods, type FieldExposure, OAuth2Config, OAuth2Method, Provider, SecretsMethod } from "../contracts/provider.js";
+import type { Placement } from "../contracts/placement.js";
+import type { DeclarationInvalid } 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>>;
+    readonly request?: readonly Placement[];
 }) => 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>;
+export declare const oauth2: <Response extends Schema.Decoder<unknown>>(config: OAuth2Config, response: Response, exposure?: Readonly<Record<string, FieldExposure>>, request?: readonly Placement[]) => Effect.Effect<OAuth2Method<Response>, DeclarationInvalid>;
 /** Author options: the account check is an ordinary async function. */
 export interface ProviderOptions<Auth extends AuthMethods> {
     readonly name: string;
     readonly auth: 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. */
+/**
+ * Retain the provider and literal method names without registering or authenticating it. A
+ * method's `request` restricts where its credentials go only among the provider's `hosts`, so a
+ * provider that declares a `request` declares `hosts` too.
+ */
 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;