apps 0.0.1-beta.0

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

@@ -0,0 +1,93 @@
+/** MCP protocol data uses Effect Schema; executable tool methods use Effect. */
+import { type Effect, type Redacted, Schema } from "effect";
+import type { Elicit, ElicitationFailed } from "./elicitation.js";
+import { type JsonValue } from "./schema.js";
+/** Upstream MCP resource bounds, independent of the outer codemode execution budget. */
+export declare const McpClientLimits: Schema.Struct<{
+    readonly timeoutMs: Schema.Int;
+    readonly maxTimeoutMs: Schema.Int;
+    readonly maxTools: Schema.Int;
+    readonly maxPaginationCursors: Schema.Int;
+    readonly cleanupTimeoutMs: Schema.Int;
+}>;
+export type McpClientLimits = typeof McpClientLimits.Type;
+/** HTTP and stdio share discovery ceilings and the default provider timeout. */
+export declare const defaultMcpClientLimits: {
+    readonly timeoutMs: number;
+    readonly maxTimeoutMs: number;
+    readonly maxTools: number;
+    readonly maxPaginationCursors: number;
+    readonly cleanupTimeoutMs: number;
+};
+/** Platform timer ceiling, not an execution allowance; our active-time clock owns the call deadline. */
+export declare const mcpSdkTimerCeilingMs = 2147483647;
+/** Server and headers for this selected account. Headers are a credential snapshot. */
+export declare const McpToolsOptions: Schema.Struct<{
+    readonly url: Schema.String;
+    readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    readonly signal: Schema.optional<Schema.instanceOf<AbortSignal, AbortSignal>>;
+    readonly timeoutMs: Schema.optional<Schema.Number>;
+}>;
+export type McpToolsOptions = typeof McpToolsOptions.Type;
+/** One parsed server and credential snapshot; never shared across account evaluations. */
+export interface McpConnection {
+    readonly url: URL;
+    readonly headers: Redacted.Redacted<Readonly<Record<string, string>>>;
+    readonly timeoutMs: number;
+}
+export { ToolAnnotations as McpToolAnnotations } from "./tools.js";
+/** Native MCP result semantics. Protocol/transport failures use the Effect error channel. */
+export declare const McpToolResult: Schema.Struct<{
+    readonly content: Schema.$Array<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly structuredContent: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly isError: Schema.optional<Schema.Boolean>;
+    readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+}>;
+export type McpToolResult = typeof McpToolResult.Type;
+/** Remote metadata. Input/output schemas remain upstream JSON Schema documents. */
+export declare const McpToolMetadata: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly title: Schema.optional<Schema.String>;
+    readonly description: Schema.optional<Schema.String>;
+    readonly inputSchema: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly outputSchema: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly annotations: Schema.optional<Schema.Struct<{
+        readonly title: Schema.optionalKey<Schema.String>;
+        readonly readOnlyHint: Schema.optionalKey<Schema.Boolean>;
+        readonly destructiveHint: Schema.optionalKey<Schema.Boolean>;
+        readonly idempotentHint: Schema.optionalKey<Schema.Boolean>;
+        readonly openWorldHint: Schema.optionalKey<Schema.Boolean>;
+    }>>;
+    readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+}>;
+export type McpToolMetadata = typeof McpToolMetadata.Type;
+/** Direct callers can omit interaction capabilities. A server that asks for input then fails explicitly. */
+export interface McpToolContext {
+    readonly elicit?: Elicit;
+}
+/** A tool bound to one evaluation's account; do not reuse it with another account. */
+export interface McpTool extends McpToolMetadata {
+    readonly description: string;
+    readonly input: Schema.Decoder<JsonValue>;
+    readonly readOnly?: boolean;
+    readonly run: (context: McpToolContext, input: JsonValue) => Effect.Effect<McpToolResult, McpError | ElicitationFailed>;
+}
+/** The discovered catalog keyed by remote tool name. */
+export type McpTools = Readonly<Record<string, McpTool>>;
+declare const McpError_base: Schema.Class<McpError, Schema.TaggedStruct<"McpError", {
+    readonly phase: Schema.Literals<readonly ["connect", "discover", "call", "schema", "transport"]>;
+    readonly reason: Schema.Literals<readonly ["request", "unauthorized", "invalid_response", "timeout", "invalid_input"]>;
+    readonly status: Schema.optional<Schema.Number>;
+}>, import("effect/Cause").YieldableError>;
+/** Safe protocol/transport failure; no raw upstream payloads or credentials. */
+export declare class McpError extends McpError_base {
+}
+/** Public process configuration. Credentials arrive through the selected account. */
+export declare const ProcessConfig: Schema.Struct<{
+    readonly command: Schema.NonEmptyString;
+    readonly args: Schema.$Array<Schema.String>;
+    readonly cwd: Schema.optional<Schema.String>;
+    readonly env: Schema.$Record<Schema.String, Schema.String>;
+    readonly timeoutMs: Schema.Int;
+}>;
+export type ProcessConfig = typeof ProcessConfig.Type;

package/types/apps/src/contracts/openapi.d.ts

@@ -0,0 +1,105 @@
+/** Normalized OpenAPI metadata retained with app source; no compiler or protocol client is required. */
+import { Schema, type Effect } from "effect";
+import { JsonObject } from "./schema.js";
+/** One parameter's HTTP placement and serialization. */
+export declare const RequestParameter: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly in: Schema.Literals<readonly ["path", "query", "header"]>;
+    readonly style: Schema.String;
+    readonly explode: Schema.Boolean;
+}>;
+export type RequestParameter = typeof RequestParameter.Type;
+/** Credential-free operation data emitted by the OpenAPI importer. */
+export declare const OpenapiOperation: Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly description: Schema.String;
+    readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]>;
+    readonly path: Schema.String;
+    readonly baseUrl: Schema.String;
+    readonly parameters: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly in: Schema.Literals<readonly ["path", "query", "header"]>;
+        readonly style: Schema.String;
+        readonly explode: Schema.Boolean;
+    }>>;
+    readonly body: Schema.Literals<readonly ["json", "base64", "none"]>;
+    /** Streams remain in the metadata but cannot run through a single-result tool call. */
+    readonly streaming: Schema.optionalKey<Schema.Literal<true>>;
+    readonly security: Schema.$Array<Schema.$Array<Schema.String>>;
+    readonly input: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly outputSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+}>;
+export type OpenapiOperation = typeof OpenapiOperation.Type;
+/** One field's placement, potentially combined with other fields in an authentication method. */
+export declare const CredentialBinding: Schema.Struct<{
+    readonly scheme: Schema.String;
+    readonly field: Schema.String;
+    readonly in: Schema.Literals<readonly ["header", "query"]>;
+    readonly name: Schema.String;
+    readonly prefix: Schema.String;
+}>;
+export type CredentialBinding = typeof CredentialBinding.Type;
+/** Selected credentials stay in the server runtime, separate from operation metadata. */
+export declare const OpenapiAccount: Schema.Struct<{
+    readonly method: Schema.String;
+    readonly fields: Schema.$Record<Schema.String, Schema.Unknown>;
+}>;
+export type OpenapiAccount = typeof OpenapiAccount.Type;
+/** Parsed options for one account's evaluation. */
+export declare const OpenapiToolsOptions: Schema.Struct<{
+    readonly operations: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.NonEmptyString;
+        readonly description: Schema.String;
+        readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]>;
+        readonly path: Schema.String;
+        readonly baseUrl: Schema.String;
+        readonly parameters: Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly in: Schema.Literals<readonly ["path", "query", "header"]>;
+            readonly style: Schema.String;
+            readonly explode: Schema.Boolean;
+        }>>;
+        readonly body: Schema.Literals<readonly ["json", "base64", "none"]>;
+        /** Streams remain in the metadata but cannot run through a single-result tool call. */
+        readonly streaming: Schema.optionalKey<Schema.Literal<true>>;
+        readonly security: Schema.$Array<Schema.$Array<Schema.String>>;
+        readonly input: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly outputSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    }>>;
+    readonly methods: Schema.$Record<Schema.String, Schema.$Array<Schema.Struct<{
+        readonly scheme: Schema.String;
+        readonly field: Schema.String;
+        readonly in: Schema.Literals<readonly ["header", "query"]>;
+        readonly name: Schema.String;
+        readonly prefix: Schema.String;
+    }>>>;
+    readonly oauth: Schema.$Array<Schema.String>;
+    readonly account: Schema.optional<Schema.Struct<{
+        readonly method: Schema.String;
+        readonly fields: Schema.$Record<Schema.String, Schema.Unknown>;
+    }>>;
+    readonly signal: Schema.optional<Schema.instanceOf<AbortSignal, AbortSignal>>;
+    readonly fetch: Schema.optional<Schema.declare<typeof fetch, typeof fetch>>;
+}>;
+/** JSON imports are decoded at the helper boundary, without assertions in app source. */
+export type OpenapiToolsOptions = Omit<typeof OpenapiToolsOptions.Type, "operations"> & {
+    readonly operations: unknown;
+};
+declare const OpenapiError_base: Schema.Class<OpenapiError, Schema.TaggedStruct<"OpenapiError", {
+    readonly reason: Schema.Literals<readonly ["invalid_definition", "invalid_input", "request"]>;
+    readonly status: Schema.optional<Schema.Number>;
+}>, import("effect/Cause").YieldableError>;
+/** Safe failures omit request headers, credentials and upstream bodies. */
+export declare class OpenapiError extends OpenapiError_base {
+}
+/** An ordinary native tool bound to one selected account. */
+export interface OpenapiTool {
+    readonly description: string;
+    readonly readOnly: boolean;
+    readonly outputSchema?: JsonObject;
+    readonly input: Schema.Decoder<Schema.Json>;
+    readonly run: (context: unknown, input: Schema.Json) => Effect.Effect<unknown, OpenapiError>;
+}
+/** Executable operations keyed by their generated names. */
+export type OpenapiTools = Readonly<Record<string, OpenapiTool>>;
+export {};

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

@@ -0,0 +1,30 @@
+/** Native operation declarations. Database access is an optional invocation capability. */
+import type { Effect, Schema } from "effect";
+import type { Approval } from "./approval.js";
+import type { BoundContext, AccountSlots } from "./app.js";
+import type { Database, DatabaseReader, Tables } from "./storage.js";
+import type { ToolAnnotations } from "./tools.js";
+import type { JsonObject } from "./schema.js";
+/** Host-bound operation capabilities; the author declaration refines accounts and storage. */
+export type OperationContext = BoundContext<AccountSlots> & {
+    readonly db?: DatabaseReader<Tables> | Database<Tables>;
+};
+/** The host validates input, checks approval, then owns the transaction and output validation. */
+export interface AppOperation<Input = unknown, Output = unknown> {
+    readonly kind: "query" | "mutation";
+    readonly description?: string;
+    readonly title?: string;
+    readonly annotations?: ToolAnnotations;
+    readonly _meta?: JsonObject;
+    readonly input: Schema.Decoder<Input>;
+    readonly output?: Schema.Decoder<Output>;
+    /** Upstream protocol result metadata; the protocol adapter validates its own result envelope. */
+    readonly outputSchema?: JsonObject;
+    readonly approval?: Approval<Input>;
+    readonly run: (context: OperationContext, input: Input) => Effect.Effect<Output, unknown>;
+}
+/** Agent tool names carry the operation kind; catalogs may reuse the same local name. */
+export declare const OperationToolPrefixes: {
+    readonly query: "queries.";
+    readonly mutate: "mutations.";
+};

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

@@ -0,0 +1,22 @@
+/** Convex-style temporary query projections; server operations remain authoritative. */
+import type { OperationReference } from "./live.js";
+/** Read or replace mounted queries during a synchronous optimistic update. Never mutate returned values. */
+export interface OptimisticLocalStore {
+    /** Read the projected result, or undefined if this query is not loaded in this client. */
+    getQuery<Input, Output>(reference: OperationReference<Input, Output, "query">, input: NoInfer<Input>): Output | undefined;
+    /** Read all mounted argument variants of an operation, including loading queries. */
+    getAllQueries<Input, Output>(reference: OperationReference<Input, Output, "query">): readonly {
+        readonly input: Input;
+        readonly value: Output | undefined;
+    }[];
+    /** Replace a mounted query's projected result. The query's output schema validates the new value. */
+    setQuery<Input, Output>(reference: OperationReference<Input, Output, "query">, input: NoInfer<Input>, value: NoInfer<Output>): void;
+}
+/** Pure synchronous projection. Replayed over current data; create temporary IDs before invoking the mutation. */
+export type OptimisticUpdate<Input> = (store: OptimisticLocalStore, input: Input) => undefined;
+/** A callable mutation. Success means the write was acknowledged; its overlay stays until fresh reads finish. */
+export interface AppMutation<Input, Output> {
+    (input: Input): Promise<Output>;
+    /** Return a new mutation handle with this projection. Failures remove only this invocation's changes. */
+    withOptimisticUpdate(update: OptimisticUpdate<Input>): AppMutation<Input, Output>;
+}

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

@@ -0,0 +1,96 @@
+/** Provider declarations use native Effect schemas. The trusted host interprets them. */
+import { Data, Schema } from "effect";
+import { type AccountId } from "./schema.js";
+declare const SecretsMethod_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Readonly<A> & {
+    readonly _tag: "secrets";
+} & import("effect/Pipeable").Pipeable;
+/** A named secrets method; its schema retains the provider's own field names. */
+export declare class SecretsMethod<Fields extends Schema.Decoder<unknown>> extends SecretsMethod_base<{
+    readonly label: string;
+    readonly fields: Fields;
+}> {
+}
+/** How an OAuth client authenticates at the token endpoint; raw Basic is an explicit provider compatibility option. */
+export declare const OAuthClientAuth: Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+export type OAuthClientAuth = typeof OAuthClientAuth.Type;
+/** Machine clients always authenticate; public clients cannot use the client-credentials grant. */
+export declare const OAuthSecretClientAuth: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+/** OAuth endpoints and protocol choices. Omitted grant means authorization code; clients remain host-owned. */
+export declare const OAuth2Config: Schema.Union<readonly [Schema.Struct<{
+    readonly discover: Schema.String;
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+    readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+    readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+}>, Schema.Struct<{
+    readonly authorizationUrl: Schema.String;
+    readonly tokenUrl: Schema.String;
+    readonly scopes: Schema.$Array<Schema.String>;
+    readonly discover: Schema.optionalKey<Schema.Never>;
+    readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+    readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+}>, Schema.Struct<{
+    readonly grant: Schema.Literal<"client_credentials">;
+    readonly discover: Schema.String;
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+    readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+}>, Schema.Struct<{
+    readonly grant: Schema.Literal<"client_credentials">;
+    readonly tokenUrl: Schema.String;
+    readonly scopes: Schema.$Array<Schema.String>;
+    readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly discover: Schema.optionalKey<Schema.Never>;
+}>]>;
+export type OAuth2Config = typeof OAuth2Config.Type;
+/** Default app-visible OAuth projection. Refresh tokens and client secrets remain with the host. */
+export declare const OAuth2AccessToken: Schema.Struct<{
+    readonly access_token: Schema.String;
+}>;
+declare const OAuth2Method_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Readonly<A> & {
+    readonly _tag: "oauth2";
+} & import("effect/Pipeable").Pipeable;
+/** OAuth declaration with an explicit schema for app-visible account fields. */
+export declare class OAuth2Method<Response extends Schema.Decoder<unknown>> extends OAuth2Method_base<{
+    readonly config: OAuth2Config;
+    readonly response: Response;
+}> {
+}
+/** Supported declarations; these acquire credentials rather than normalize them. */
+export type AuthMethod = SecretsMethod<Schema.Decoder<unknown>> | OAuth2Method<Schema.Decoder<unknown>>;
+/** Auth method names are chosen by the provider author. */
+export type AuthMethods = Readonly<Record<string, AuthMethod>>;
+/** A provider declaration. The future host derives its identity from normalized content. */
+export declare class Provider<Auth extends AuthMethods> extends Data.Class<{
+    readonly name: string;
+    readonly auth: Auth;
+}> {
+    /** Declare zero or more accounts from this provider without performing I/O. */
+    many(): ManyAccounts<Auth>;
+}
+declare const ManyAccounts_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Readonly<A> & {
+    readonly _tag: "many";
+} & import("effect/Pipeable").Pipeable;
+/** A collection requirement; selecting accounts does not copy or transfer them. */
+export declare class ManyAccounts<Auth extends AuthMethods> extends ManyAccounts_base<{
+    readonly provider: Provider<Auth>;
+}> {
+}
+/** Infer the data for one method from its native Effect decoder. */
+export type AuthMethodData<Method> = Method extends SecretsMethod<infer Fields> ? Fields["Type"] : Method extends OAuth2Method<infer Response> ? Response["Type"] : never;
+/** One selected account, discriminated by its author-chosen method name. */
+export type AccountOf<P> = P extends Provider<infer Auth> ? {
+    readonly [Method in keyof Auth & string]: {
+        readonly id: AccountId;
+        readonly method: Method;
+        readonly fields: AuthMethodData<Auth[Method]>;
+    };
+}[keyof Auth & string] : never;
+export {};

package/types/apps/src/contracts/schedules.d.ts

@@ -0,0 +1,51 @@
+/** Serializable schedules trigger existing mutations; they never introduce another execution path. */
+import { Schema } from "effect";
+/** Dispatch coalesces overdue ticks, so sub-minute intervals promise a cadence the runner cannot keep. */
+export declare const minimumIntervalMilliseconds = 60000;
+export declare const Interval: Schema.Union<readonly [Schema.Struct<{
+    readonly seconds: Schema.Int;
+    readonly minutes: Schema.optionalKey<Schema.Never>;
+    readonly hours: Schema.optionalKey<Schema.Never>;
+}>, Schema.Struct<{
+    readonly seconds: Schema.optionalKey<Schema.Never>;
+    readonly minutes: Schema.Int;
+    readonly hours: Schema.optionalKey<Schema.Never>;
+}>, Schema.Struct<{
+    readonly seconds: Schema.optionalKey<Schema.Never>;
+    readonly minutes: Schema.optionalKey<Schema.Never>;
+    readonly hours: Schema.Int;
+}>]>;
+export type Interval = typeof Interval.Type;
+/** Calendar schedules use five cron fields and an explicit IANA time zone. */
+export declare const CalendarSchedule: Schema.Struct<{
+    readonly expression: Schema.NonEmptyString;
+    readonly timezone: Schema.NonEmptyString;
+}>;
+/** Validated timing crosses all runtime and persistence boundaries as data. */
+export declare const ScheduleTiming: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"interval">;
+    readonly milliseconds: Schema.Int;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"cron">;
+    readonly calendar: Schema.Struct<{
+        readonly expression: Schema.NonEmptyString;
+        readonly timezone: Schema.NonEmptyString;
+    }>;
+}>]>;
+export type ScheduleTiming = typeof ScheduleTiming.Type;
+/** A named trigger attached to the mutation it invokes, including schema-validated arguments. */
+export declare const OperationSchedule: Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly timing: Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"interval">;
+        readonly milliseconds: Schema.Int;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"cron">;
+        readonly calendar: Schema.Struct<{
+            readonly expression: Schema.NonEmptyString;
+            readonly timezone: Schema.NonEmptyString;
+        }>;
+    }>]>;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>;
+export type OperationSchedule = typeof OperationSchedule.Type;

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

@@ -0,0 +1,20 @@
+/** Runtime data schemas shared by the app framework. Author helpers live at the boundary. */
+import { Schema } from "effect";
+/** JSON values carried by remote protocols such as MCP. */
+export declare const JsonValue: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+export type JsonValue = Schema.Json;
+/** A JSON object, distinct from an authored value schema. */
+export declare const JsonObject: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+export type JsonObject = typeof JsonObject.Type;
+/** Stable saved account identity supplied by a host, unchanged across refreshes. */
+export declare const AccountId: Schema.brand<Schema.String, "acc">;
+/** Parsed saved account identity. */
+export type AccountId = typeof AccountId.Type;
+/** Absolute HTTP(S) URL; local HTTP hosts are supported. */
+export declare const HttpUrl: Schema.String;
+declare const ValidationError_base: Schema.Class<ValidationError, Schema.TaggedStruct<"ValidationError", {}>, import("effect/Cause").YieldableError>;
+/** Invalid input. Never includes supplied values, credentials or response bodies. */
+export declare class ValidationError extends ValidationError_base {
+    get message(): string;
+}
+export {};

package/types/apps/src/contracts/storage.d.ts

@@ -0,0 +1,68 @@
+/** Native app data boundary. Hosts bind a configured app before exposing this capability. */
+import { Schema, type Effect } from "effect";
+import type { RowMetadata, ReadTable, WriteTable } from "../../../app-data/src/index.js";
+import type { Fields, ObjectValue } from "../implementation/schema.js";
+import type { DatabaseSchema, DatabaseSession, AppDatabaseError } from "../../../app-data/src/contracts/database.js";
+/** Names for authored operations and tables. */
+export declare const StorageName: Schema.NonEmptyString;
+declare const AppStorageUnavailable_base: Schema.Class<AppStorageUnavailable, Schema.TaggedStruct<"AppStorageUnavailable", {}>, import("effect/Cause").YieldableError>;
+/** Storage is not configured on this host. */
+export declare class AppStorageUnavailable extends AppStorageUnavailable_base {
+}
+declare const AppStorageError_base: Schema.Class<AppStorageError, Schema.TaggedStruct<"AppStorageError", {}>, import("effect/Cause").YieldableError>;
+/** App storage operations never expose SQL, documents or credentials in failures. */
+export declare class AppStorageError extends AppStorageError_base {
+}
+/** The adapter owns the database connection and transaction for the whole authored invocation. */
+export interface AppStorage {
+    readonly read: <A, E>(schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | AppDatabaseError | AppStorageUnavailable | AppStorageError>;
+    readonly mutate: <A, E>(schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | AppDatabaseError | AppStorageUnavailable | AppStorageError>;
+}
+type InputValue<F extends Fields> = {
+    readonly [K in keyof F as F[K]["optionalValue"] extends true ? never : F[K] extends {
+        readonly hasDefault: true;
+    } ? never : K]: Exclude<import("../implementation/schema.js").Infer<F[K]>, undefined>;
+} & {
+    readonly [K in keyof F as F[K]["optionalValue"] extends true ? K : F[K] extends {
+        readonly hasDefault: true;
+    } ? K : never]?: Exclude<import("../implementation/schema.js").Infer<F[K]>, undefined> | (F[K]["optionalValue"] extends true ? null : F[K] extends {
+        readonly inputOptional: true;
+    } ? null : never) | undefined;
+};
+/** Typed table declaration; indexes refer only to authored or host metadata fields. */
+export interface Table<F extends Fields, Index extends string = never> {
+    readonly fields: F;
+    readonly indexes: ReadonlyArray<{
+        readonly name: string;
+        readonly fields: readonly string[];
+    }>;
+    readonly index: <Name extends string>(name: Name, fields: readonly [
+        (keyof F & string) | keyof typeof RowMetadata.Type,
+        ...((keyof F & string) | keyof typeof RowMetadata.Type)[]
+    ]) => Table<F, Index | Name>;
+}
+/** Structural table catalog accepted at the author boundary. */
+export type Tables = Readonly<Record<string, {
+    readonly fields: Fields;
+    readonly indexes: ReadonlyArray<{
+        readonly name: string;
+        readonly fields: readonly string[];
+    }>;
+}>>;
+/** Generated row metadata is read-only and unavailable on inserts. */
+export type RowOf<T extends Tables[string]> = ObjectValue<T["fields"]> & typeof RowMetadata.Type;
+type IndexOf<T> = T extends Table<Fields, infer I> ? I : string;
+/** Queries receive only read methods. */
+export type DatabaseReader<T extends Tables> = {
+    readonly [K in keyof T]: ReadTable<RowOf<T[K]>, IndexOf<T[K]>>;
+};
+/** Mutation methods stay inside one native SQLite transaction. */
+export type Database<T extends Tables> = {
+    readonly [K in keyof T]: WriteTable<RowOf<T[K]>, InputValue<T[K]["fields"]>, IndexOf<T[K]>>;
+};
+/** Pure database declaration shared by requirements and derived handler contexts. */
+export interface DatabaseDefinition<T extends Tables = Tables> {
+    readonly schema: DatabaseSchema;
+    readonly tables: T;
+}
+export {};

package/types/apps/src/contracts/tools.d.ts

@@ -0,0 +1,11 @@
+/** Agent-facing metadata. Apps author queries and mutations. */
+import { Schema } from "effect";
+/** Advisory tool hints; neither the framework nor these declarations enforce access. */
+export declare const ToolAnnotations: Schema.Struct<{
+    readonly title: Schema.optionalKey<Schema.String>;
+    readonly readOnlyHint: Schema.optionalKey<Schema.Boolean>;
+    readonly destructiveHint: Schema.optionalKey<Schema.Boolean>;
+    readonly idempotentHint: Schema.optionalKey<Schema.Boolean>;
+    readonly openWorldHint: Schema.optionalKey<Schema.Boolean>;
+}>;
+export type ToolAnnotations = typeof ToolAnnotations.Type;

package/types/apps/src/contracts/ui-auth.d.ts

@@ -0,0 +1,28 @@
+/** Browser authentication protocol. Identity and session storage belong to the host. */
+import { Schema } from "effect";
+import { HttpApi, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
+import { UiFailed, UiForbidden, UiUnauthorized } from "./ui.js";
+/** Opaque correlation ID; possession alone does not authorize an app session. */
+export declare const AppSignInId: Schema.brand<Schema.String, "AppSignInId">;
+export type AppSignInId = typeof AppSignInId.Type;
+/** Authentication proofs are redacted at the HTTP boundary. */
+export declare const AppSignInCode: Schema.RedactedFromValue<Schema.String>;
+/** A path on the current app origin, including its query and fragment; never a redirect to another host or host-owned route. */
+export declare const AppReturnPath: Schema.brand<Schema.String, "AppReturnPath">;
+export type AppReturnPath = typeof AppReturnPath.Type;
+/** The trusted callback exchanges an authorization code bound to a browser attempt. */
+export declare const AppSignInCallback: Schema.Struct<{
+    readonly request: Schema.brand<Schema.String, "AppSignInId">;
+    readonly code: Schema.RedactedFromValue<Schema.String>;
+}>;
+/** Host-owned endpoints on every app origin, independent of the product's login mechanism. */
+export declare const AppSignInApi: HttpApi.HttpApi<"app-sign-in", HttpApiGroup.HttpApiGroup<"appSignIn", HttpApiEndpoint.HttpApiEndpoint<"start", "POST", "/_executor/auth/start", never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly returnTo: Schema.brand<Schema.String, "AppReturnPath">;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly url: Schema.String;
+}>>, Schema.toCodecJson<typeof UiForbidden | typeof UiFailed>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"complete", "POST", "/_executor/auth/complete", never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly request: Schema.brand<Schema.String, "AppSignInId">;
+    readonly code: Schema.RedactedFromValue<Schema.String>;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly returnTo: Schema.brand<Schema.String, "AppReturnPath">;
+}>>, Schema.toCodecJson<typeof UiUnauthorized | typeof UiForbidden | typeof UiFailed>, never, never>, false>>;

package/types/apps/src/contracts/ui.d.ts

@@ -0,0 +1,90 @@
+/** Browser-to-host operations bind identity and authentication outside authored app code. */
+import { Schema } from "effect";
+import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/unstable/httpapi";
+/** Non-secret page context injected by the serving host. */
+export declare const UiContext: Schema.Struct<{
+    readonly deployment: Schema.NonEmptyString;
+    readonly profile: Schema.optional<Schema.NonEmptyString>;
+    readonly expectedProfileRevision: Schema.optional<Schema.Int>;
+}>;
+/** Retained browser bytes. Hosts authorize access before reading or rendering them. */
+export interface AppUiAsset {
+    readonly body: Uint8Array;
+    readonly contentType: string;
+}
+/** Requests name an operation on this app and the page's deployment, never another app or account. */
+export declare const UiOperation: Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly deployment: Schema.NonEmptyString;
+    readonly profile: Schema.optional<Schema.NonEmptyString>;
+    readonly expectedProfileRevision: Schema.optional<Schema.Int>;
+}>;
+declare const UiUnauthorized_base: Schema.Class<UiUnauthorized, Schema.TaggedStruct<"UiUnauthorized", {}>, import("effect/Cause").YieldableError>;
+/** The app session is absent or its parent login was revoked. */
+export declare class UiUnauthorized extends UiUnauthorized_base {
+}
+declare const UiForbidden_base: Schema.Class<UiForbidden, Schema.TaggedStruct<"UiForbidden", {}>, import("effect/Cause").YieldableError>;
+/** The request did not originate from the configured app. */
+export declare class UiForbidden extends UiForbidden_base {
+}
+declare const UiDeploymentChanged_base: Schema.Class<UiDeploymentChanged, Schema.TaggedStruct<"UiDeploymentChanged", {}>, import("effect/Cause").YieldableError>;
+/** The page should reload before starting another operation. */
+export declare class UiDeploymentChanged extends UiDeploymentChanged_base {
+}
+declare const UiFailed_base: Schema.Class<UiFailed, Schema.TaggedStruct<"UiFailed", {
+    readonly reason: Schema.Literals<readonly ["unavailable", "operation_failed", "account_required"]>;
+}>, import("effect/Cause").YieldableError>;
+/** Safe app failure without account fields, author exceptions or upstream responses. */
+export declare class UiFailed extends UiFailed_base {
+}
+/** Every live stream carries heartbeats so the browser can detect a lost connection. */
+export declare const UiSnapshot: Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"snapshot">;
+    readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly trace: Schema.optional<Schema.Unknown>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"failure">;
+    readonly error: typeof UiFailed;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"heartbeat">;
+}>]>;
+/** Portable serving contract; the host authenticates and resolves the configured app. */
+export declare const AppUiApi: HttpApi.HttpApi<"app-ui", HttpApiGroup.HttpApiGroup<"ui", HttpApiEndpoint.HttpApiEndpoint<"query", "POST", "/_executor/api/query", never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly deployment: Schema.NonEmptyString;
+    readonly profile: Schema.optional<Schema.NonEmptyString>;
+    readonly expectedProfileRevision: Schema.optional<Schema.Int>;
+}>>, never, Schema.toCodecJson<Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.toCodecJson<typeof UiUnauthorized | typeof UiForbidden | typeof UiDeploymentChanged | typeof UiFailed>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"mutate", "POST", "/_executor/api/mutate", never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly deployment: Schema.NonEmptyString;
+    readonly profile: Schema.optional<Schema.NonEmptyString>;
+    readonly expectedProfileRevision: Schema.optional<Schema.Int>;
+}>>, never, Schema.toCodecJson<Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.toCodecJson<typeof UiUnauthorized | typeof UiForbidden | typeof UiDeploymentChanged | typeof UiFailed>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"subscribe", "POST", "/_executor/api/subscribe", never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly deployment: Schema.NonEmptyString;
+    readonly profile: Schema.optional<Schema.NonEmptyString>;
+    readonly expectedProfileRevision: Schema.optional<Schema.Int>;
+}>>, never, HttpApiSchema.StreamSse<HttpApiSchema.SseEventFromData<Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"snapshot">;
+    readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly trace: Schema.optional<Schema.Unknown>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"failure">;
+    readonly error: typeof UiFailed;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"heartbeat">;
+}>]>>, Schema.Union<readonly [typeof UiUnauthorized, typeof UiForbidden, typeof UiDeploymentChanged, typeof UiFailed]>, {
+    readonly value: Schema.Json;
+    readonly type: "snapshot";
+    readonly trace?: unknown;
+} | {
+    readonly type: "failure";
+    readonly error: UiFailed;
+} | {
+    readonly type: "heartbeat";
+}>, Schema.toCodecJson<typeof UiUnauthorized | typeof UiForbidden | typeof UiDeploymentChanged | typeof UiFailed>, never, never>, false>>;
+export {};