apps 0.0.1-beta.0

package/types/app-data/src/contracts/database.d.ts

@@ -0,0 +1,193 @@
+/** Portable, serialized app database declarations and operations. No product identity or database secrets cross this boundary. */
+import { Schema, type Effect } from "effect";
+/** Names have Lakebed's identifier shape and are always bound SQL values, never raw SQL. */
+export declare const DataName: Schema.String;
+/** Stored fields and index terms use finite scalar values; absent optional fields are represented by null in transport. */
+export declare const Scalar: Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>;
+export type Scalar = typeof Scalar.Type;
+export declare const Field: Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["string", "number", "boolean", "id", "userId"]>;
+    readonly optional: Schema.optional<Schema.Boolean>;
+    readonly default: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>;
+    readonly references: Schema.optional<Schema.String>;
+}>;
+export type Field = typeof Field.Type;
+export declare const Index: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly fields: Schema.NonEmptyArray<Schema.String>;
+}>;
+export declare const Table: Schema.Struct<{
+    readonly fields: Schema.$Record<Schema.String, Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["string", "number", "boolean", "id", "userId"]>;
+        readonly optional: Schema.optional<Schema.Boolean>;
+        readonly default: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>;
+        readonly references: Schema.optional<Schema.String>;
+    }>>;
+    readonly indexes: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly fields: Schema.NonEmptyArray<Schema.String>;
+    }>>;
+}>;
+export type Table = typeof Table.Type;
+export declare const DatabaseSchema: Schema.$Record<Schema.String, Schema.Struct<{
+    readonly fields: Schema.$Record<Schema.String, Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["string", "number", "boolean", "id", "userId"]>;
+        readonly optional: Schema.optional<Schema.Boolean>;
+        readonly default: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>;
+        readonly references: Schema.optional<Schema.String>;
+    }>>;
+    readonly indexes: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly fields: Schema.NonEmptyArray<Schema.String>;
+    }>>;
+}>>;
+export type DatabaseSchema = typeof DatabaseSchema.Type;
+/** The engine owns stable row identity and timestamps. */
+export declare const Row: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>;
+export type Row = typeof Row.Type;
+export declare const RowMetadata: Schema.Struct<{
+    readonly id: Schema.NonEmptyString;
+    readonly createdAt: Schema.String;
+    readonly updatedAt: Schema.String;
+}>;
+export declare const Patch: Schema.$Record<Schema.String, Schema.NullOr<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>>;
+export declare const RangeClause: Schema.Struct<{
+    readonly field: Schema.String;
+    readonly op: Schema.Literals<readonly ["eq", "gt", "gte", "lt", "lte"]>;
+    readonly value: Schema.NullOr<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>;
+}>;
+export declare const QueryPlan: Schema.Struct<{
+    readonly table: Schema.String;
+    readonly index: Schema.String;
+    readonly order: Schema.Literals<readonly ["asc", "desc"]>;
+    readonly clauses: Schema.$Array<Schema.Struct<{
+        readonly field: Schema.String;
+        readonly op: Schema.Literals<readonly ["eq", "gt", "gte", "lt", "lte"]>;
+        readonly value: Schema.NullOr<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>;
+    }>>;
+}>;
+export type QueryPlan = typeof QueryPlan.Type;
+export declare const QueryTerminal: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"collect">;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"count">;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"first">;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"take">;
+    readonly count: Schema.Int;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"paginate">;
+    readonly cursor: Schema.NullOr<Schema.String>;
+    readonly numItems: Schema.Int;
+}>]>;
+export declare const DatabaseOperation: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"get">;
+    readonly table: Schema.String;
+    readonly id: Schema.NonEmptyString;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"insert">;
+    readonly table: Schema.String;
+    readonly value: Schema.$Record<Schema.String, Schema.NullOr<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"update">;
+    readonly table: Schema.String;
+    readonly id: Schema.NonEmptyString;
+    readonly patch: Schema.$Record<Schema.String, Schema.NullOr<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"delete">;
+    readonly table: Schema.String;
+    readonly id: Schema.NonEmptyString;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"query">;
+    readonly plan: Schema.Struct<{
+        readonly table: Schema.String;
+        readonly index: Schema.String;
+        readonly order: Schema.Literals<readonly ["asc", "desc"]>;
+        readonly clauses: Schema.$Array<Schema.Struct<{
+            readonly field: Schema.String;
+            readonly op: Schema.Literals<readonly ["eq", "gt", "gte", "lt", "lte"]>;
+            readonly value: Schema.NullOr<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>;
+        }>>;
+    }>;
+    readonly terminal: Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"collect">;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"count">;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"first">;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"take">;
+        readonly count: Schema.Int;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"paginate">;
+        readonly cursor: Schema.NullOr<Schema.String>;
+        readonly numItems: Schema.Int;
+    }>]>;
+}>]>;
+export type DatabaseOperation = typeof DatabaseOperation.Type;
+export declare const PaginationResult: Schema.Struct<{
+    readonly page: Schema.$Array<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>>;
+    readonly continueCursor: Schema.NullOr<Schema.String>;
+    readonly isDone: Schema.Boolean;
+}>;
+export declare const OperationResult: Schema.Union<readonly [Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>, Schema.$Array<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>>, Schema.Struct<{
+    readonly page: Schema.$Array<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>>;
+    readonly continueCursor: Schema.NullOr<Schema.String>;
+    readonly isDone: Schema.Boolean;
+}>, Schema.Boolean, Schema.Finite, Schema.Null]>;
+export type OperationResult = typeof OperationResult.Type;
+declare const AppDatabaseError_base: Schema.Class<AppDatabaseError, Schema.TaggedStruct<"AppDatabaseError", {
+    readonly reason: Schema.Literals<readonly ["schema", "schema_changed", "table", "index", "range", "value", "readonly", "cursor", "limit", "closed", "storage", "replay"]>;
+}>, import("effect/Cause").YieldableError>;
+/** Safe expected failures, without supplied documents, SQL text, cursor payloads or credentials. */
+export declare class AppDatabaseError extends AppDatabaseError_base {
+}
+/** Bounded work per authored operation. collect/count do not silently truncate. */
+export declare const DatabaseLimits: Schema.Struct<{
+    readonly rowsRead: Schema.Int;
+    readonly rowsReturned: Schema.Int;
+    readonly bytesRead: Schema.Int;
+    readonly writes: Schema.Int;
+    readonly scanCalls: Schema.Int;
+    readonly directGets: Schema.Int;
+    readonly valueBytes: Schema.Int;
+    readonly indexBytes: Schema.Int;
+}>;
+export type DatabaseLimits = typeof DatabaseLimits.Type;
+/** Current per-invocation budgets, shared by every database adapter. */
+export declare const defaultDatabaseLimits: DatabaseLimits;
+/** Host resource bounds outside an individual database transaction. Durations are milliseconds. */
+export declare const DatabaseRuntimeLimits: Schema.Struct<{
+    readonly maxCursorChars: Schema.Int;
+    readonly connectionCacheCapacity: Schema.Int;
+    readonly connectionCacheTtlMs: Schema.Int;
+}>;
+export type DatabaseRuntimeLimits = typeof DatabaseRuntimeLimits.Type;
+/** Cache eviction closes idle connections; it does not limit installed apps or expire their data. */
+export declare const defaultDatabaseRuntimeLimits: {
+    readonly maxCursorChars: number;
+    readonly connectionCacheCapacity: number;
+    readonly connectionCacheTtlMs: number;
+};
+/** The host binds one database and read/write authority for the entire invocation. */
+export interface DatabaseSession {
+    /** Host-only idempotency receipt, committed atomically with the mutation and validated result. */
+    readonly once: <E, R>(key: string, fingerprint: string, work: () => Effect.Effect<Schema.Json, E, R>) => Effect.Effect<Schema.Json, E | AppDatabaseError, R>;
+    readonly readTables: ReadonlySet<string>;
+    readonly changedTables: ReadonlySet<string>;
+    readonly execute: (operation: DatabaseOperation) => Effect.Effect<OperationResult, AppDatabaseError>;
+}
+/** Native operation scope owns snapshot consistency, write rollback and commit notifications. */
+export interface AppDatabase {
+    readonly schema: DatabaseSchema;
+    readonly schemaHash: string;
+    readonly read: <A, E, R>(work: (session: DatabaseSession) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | AppDatabaseError, R>;
+    readonly mutate: <A, E, R>(work: (session: DatabaseSession) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | AppDatabaseError, R>;
+}
+/** Product-independent app partitions. A host supplies persistent storage; callers never choose filenames. */
+export interface AppDatabases {
+    readonly read: <A, E>(app: string, schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | AppDatabaseError>;
+    readonly mutate: <A, E>(app: string, schema: DatabaseSchema, work: (session: DatabaseSession) => Effect.Effect<A, E>) => Effect.Effect<A, E | AppDatabaseError>;
+}
+export {};

package/types/app-data/src/implementation/cursor.d.ts

@@ -0,0 +1,10 @@
+/** Authenticated, opaque continuation tokens tied to one installation, schema and query plan. */
+import { Effect } from "effect";
+import { AppDatabaseError } from "../contracts/database.js";
+/** Stable SHA-256 fingerprints contain no raw query arguments in logs or metadata keys. */
+export declare const fingerprint: (crypto: Crypto, value: string) => Effect.Effect<string, AppDatabaseError, never>;
+/** Capture a per-database key. Nonces are fresh, and malformed/tampered/cross-query cursors fail closed. */
+export declare const cursorCodec: (crypto: Crypto, bytes: Uint8Array) => Effect.Effect<{
+    encode: (query: string, position: Uint8Array) => Effect.Effect<string, AppDatabaseError, never>;
+    decode: (query: string, token: string) => Effect.Effect<Uint8Array<ArrayBufferLike>, AppDatabaseError, never>;
+}, AppDatabaseError, never>;

package/types/app-data/src/implementation/index-key.d.ts

@@ -0,0 +1,7 @@
+/** Order-preserving scalar tuples. SQLite BLOB ordering supplies bounded prefix/range scans. */
+import { Effect } from "effect";
+import { AppDatabaseError, type Scalar } from "../contracts/database.js";
+/** Compare UTF-8 strings, booleans and finite doubles consistently, with absence before present values. */
+export declare const encodeIndexKey: (values: readonly (Scalar | null)[], maximum?: number) => Effect.Effect<Uint8Array<ArrayBuffer>, AppDatabaseError, never>;
+/** Exclusive upper bound for all tuples beginning with this prefix. */
+export declare const prefixEnd: (prefix: Uint8Array) => Uint8Array | undefined;

package/types/app-data/src/implementation/promise.d.ts

@@ -0,0 +1,68 @@
+import { Row, type DatabaseSession } from "../contracts/database.js";
+/** Index predicates are accumulated immutably, then checked against the declaration by the engine. */
+export interface IndexRange<Fields> {
+    /** Constrain an index prefix field to one value. Null matches a cleared optional field. */
+    readonly eq: <Key extends keyof Fields & string>(field: Key, value: Fields[Key] | null) => IndexRange<Fields>;
+    /** Require a value greater than the bound on the next index field. */
+    readonly gt: <Key extends keyof Fields & string>(field: Key, value: Fields[Key]) => IndexRange<Fields>;
+    /** Require a value greater than or equal to the bound on the next index field. */
+    readonly gte: <Key extends keyof Fields & string>(field: Key, value: Fields[Key]) => IndexRange<Fields>;
+    /** Require a value less than the bound on the next index field. */
+    readonly lt: <Key extends keyof Fields & string>(field: Key, value: Fields[Key]) => IndexRange<Fields>;
+    /** Require a value less than or equal to the bound on the next index field. */
+    readonly lte: <Key extends keyof Fields & string>(field: Key, value: Fields[Key]) => IndexRange<Fields>;
+}
+/** Bounded indexed reads; collect/count reject work beyond the invocation budget. */
+export interface Query<Row> {
+    /** Choose ascending or descending index order without changing this query. */
+    readonly order: (direction: "asc" | "desc") => Query<Row>;
+    /** Read all matching rows within the invocation budget; exceeding it fails. */
+    readonly collect: () => Promise<readonly Row[]>;
+    /** Count matching rows within the scan budget; exceeding it fails. */
+    readonly count: () => Promise<number>;
+    /** Read the first matching row, or null when no row matches. */
+    readonly first: () => Promise<Row | null>;
+    /** Read at most count matching rows within the invocation budget. */
+    readonly take: (count: number) => Promise<readonly Row[]>;
+    /** Read one cursor page. Return its rows, continuation cursor and completion flag. */
+    readonly paginate: (options: {
+        readonly numItems: number;
+        readonly cursor: string | null;
+    }) => Promise<{
+        readonly page: readonly Row[];
+        readonly continueCursor: string | null;
+        readonly isDone: boolean;
+    }>;
+}
+/** Typed table operations exposed to authored queries. */
+export interface ReadTable<Row, Index extends string = string> {
+    /** Read a complete row by ID, or null when it does not exist. */
+    readonly get: (id: string) => Promise<Row | null>;
+    /** Select a declared index or by_creation, with optional prefix and range constraints. */
+    readonly withIndex: (index: Index | "by_creation", range?: (query: IndexRange<Row>) => IndexRange<Row>) => Query<Row>;
+}
+/** Writes are valid only inside their owning mutation. */
+export interface WriteTable<Row, Insert, Index extends string = string> extends ReadTable<Row, Index> {
+    /** Insert authored fields and return the complete row with generated id, createdAt and updatedAt. */
+    readonly insert: (value: Insert) => Promise<Row>;
+    /** Patch authored fields and return the complete row, or null if the ID does not exist. */
+    readonly update: (id: string, patch: Partial<Insert>) => Promise<Row | null>;
+    /** Delete the row and return whether it existed. */
+    readonly delete: (id: string) => Promise<boolean>;
+}
+/** Build an untyped transport facade; the author schema layer installs exact field and row decoders. */
+export declare const promiseTable: (session: DatabaseSession, table: string, signal: AbortSignal) => {
+    get: (id: string) => Promise<{
+        readonly [x: string]: string | number | boolean;
+    } | null>;
+    insert: (value: unknown) => Promise<{
+        readonly [x: string]: string | number | boolean;
+    }>;
+    update: (id: string, patch: unknown) => Promise<{
+        readonly [x: string]: string | number | boolean;
+    } | null>;
+    delete: (id: string) => Promise<boolean>;
+    withIndex: (index: string, range?: (query: IndexRange<Row>) => IndexRange<Row>) => Query<{
+        readonly [x: string]: string | number | boolean;
+    }>;
+};

package/types/app-data/src/implementation/range.d.ts

@@ -0,0 +1,8 @@
+/** Index-prefix equality followed by at most one field's lower and upper bounds. */
+import { Effect } from "effect";
+import { AppDatabaseError, type QueryPlan, type Table } from "../contracts/database.js";
+/** Produce half-open BLOB bounds; absent optional values do not satisfy ordinary range predicates. */
+export declare const queryBounds: (table: Table, plan: QueryPlan, maximum: number) => Effect.Effect<{
+    lower: Uint8Array<ArrayBufferLike>;
+    upper: Uint8Array<ArrayBufferLike> | undefined;
+}, AppDatabaseError, never>;

package/types/app-data/src/implementation/schema.d.ts

@@ -0,0 +1,33 @@
+/** Validate declarations and write values before touching SQLite. */
+import { Effect } from "effect";
+import { AppDatabaseError, DatabaseSchema, RowMetadata, type Field, type Row, type Scalar, type Table } from "../contracts/database.js";
+/** Built-in creation ordering and stable tie-breakers apply to every index. */
+export declare const indexesFor: (table: Table) => {
+    name: string;
+    fields: string[];
+}[];
+/** Metadata fields have stable string semantics and cannot be overwritten. */
+export declare const fieldFor: (table: Table, name: string) => Field | undefined;
+/** Finite numbers and well-formed strings keep JSON and index ordering consistent. */
+export declare const validScalar: (field: Field, value: unknown) => value is Scalar;
+/** Parse the whole schema, including references and composite-index definitions. */
+export declare const parseDatabaseSchema: (input: unknown) => Effect.Effect<{
+    readonly [x: string]: {
+        readonly fields: {
+            readonly [x: string]: {
+                readonly kind: "string" | "number" | "boolean" | "id" | "userId";
+                readonly optional?: boolean | undefined;
+                readonly default?: string | number | boolean | undefined;
+                readonly references?: string | undefined;
+            };
+        };
+        readonly indexes: readonly {
+            readonly name: string;
+            readonly fields: readonly [string, ...string[]];
+        }[];
+    };
+}, AppDatabaseError, never>;
+/** Canonical ordering for schema fingerprints and query-bound cursors. */
+export declare const canonicalSchema: (schema: DatabaseSchema) => string;
+/** Inserts apply declared defaults; updates reject unknown/metadata fields and clear optional values with null. */
+export declare const writeValue: (table: Table, values: Readonly<Record<string, Scalar | null>>, previous: Row | undefined, meta: typeof RowMetadata.Type) => Effect.Effect<Record<string, string | number | boolean>, AppDatabaseError, never>;

package/types/app-data/src/implementation/sqlite.d.ts

@@ -0,0 +1,11 @@
+/** Shared SQLite engine. Drivers, persistent paths and app ownership belong to the host. */
+import { Effect } from "effect";
+import type { SqlClient } from "effect/unstable/sql/SqlClient";
+import { AppDatabaseError, DatabaseLimits, type AppDatabase } from "../contracts/database.js";
+/** Open a database whose storage is owned by exactly one configured app. Schema changes fail closed. */
+export declare const makeSqliteDatabase: (options: {
+    readonly sql: SqlClient;
+    readonly schema: unknown;
+    readonly crypto: Crypto;
+    readonly limits?: DatabaseLimits;
+}) => Effect.Effect<AppDatabase, AppDatabaseError>;

package/types/app-data/src/index.d.ts

@@ -0,0 +1,4 @@
+/** Portable, app-owned database engine and contracts. */
+export * from "./contracts/database.js";
+export { makeSqliteDatabase } from "./implementation/sqlite.js";
+export { promiseTable, type IndexRange, type Query, type ReadTable, type WriteTable, } from "./implementation/promise.js";

package/types/apps/src/approval.d.ts

@@ -0,0 +1,10 @@
+/** Tool approval author API; no state or execution starts during declaration. */
+import type { Effect } from "effect";
+import type { Approval as NativeApproval } from "./contracts/approval.js";
+export type { ApprovalContext, ApprovalDecision } from "./contracts/approval.js";
+/** Synchronous or async policy, projected from the framework's native contract. */
+export type Approval<Input = unknown> = (...args: Parameters<NativeApproval<Input>>) => Effect.Success<ReturnType<NativeApproval<Input>>> | Promise<Effect.Success<ReturnType<NativeApproval<Input>>>>;
+/** Require human approval for every call to the tool. */
+export declare const always: <Input = unknown>() => Approval<Input>;
+/** Never require human approval for this tool. Product access checks still apply. */
+export declare const never: <Input = unknown>() => Approval<Input>;

package/types/apps/src/client.d.ts

@@ -0,0 +1,5 @@
+/** Browser-safe live query API. Server operations are referenced using type-only imports. */
+export { queryReference, mutationReference, liveQueryAtom } from "./implementation/live.js";
+export { AppQueryFailed, type OperationReference, type QueryDescriptor, type QueryTransport, } from "./contracts/live.js";
+export { createAppClient } from "./implementation/ui-client.js";
+export type { AppMutation, OptimisticLocalStore, OptimisticUpdate, } from "./contracts/optimistic.js";

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

@@ -0,0 +1,58 @@
+import type { DatabaseDefinition } from "./storage.js";
+/** Native app contracts; factories and handlers compose in the host's Effect runtime. */
+import { type Effect, Schema } from "effect";
+import type { OperationSchedule } from "./schedules.js";
+import type { AppOperation } from "./operations.js";
+import type { AccountOf, AuthMethods, ManyAccounts, Provider } from "./provider.js";
+import type { AppWorkflow, WorkflowReads } from "./workflows.js";
+import type { Elicit } from "./elicitation.js";
+/** Composition-only view. Specific handler inputs and outputs stay on the inferred definition. */
+type Handler<Context> = (context: Context, input: never) => Effect.Effect<unknown, unknown>;
+/** App capabilities share one account context. Package metadata belongs in package.json. */
+export interface AppDefinition<Context> {
+    readonly workflows?: Readonly<Record<string, AppWorkflow>>;
+    readonly schedules?: Readonly<Record<string, Omit<OperationSchedule, "name"> & {
+        readonly tool: string;
+    }>>;
+    readonly queries?: Readonly<Record<string, AppOperation>>;
+    readonly mutations?: Readonly<Record<string, AppOperation>>;
+    readonly webhooks?: Readonly<Record<string, {
+        readonly account: string;
+        readonly config: Schema.Decoder<unknown>;
+        readonly state: Schema.Decoder<unknown>;
+        readonly setup?: import("./webhook-protocol.js").ManualWebhookSetup;
+        readonly register?: Handler<Context>;
+        readonly handle: Handler<Context>;
+        readonly unregister?: Handler<Context>;
+    }>>;
+}
+/** Named requirements for one account or a collection from a provider. */
+export type AccountSlots = Readonly<Record<string, Provider<AuthMethods> | ManyAccounts<AuthMethods>>>;
+type AccountsFor<Slot> = Slot extends ManyAccounts<infer Auth> ? readonly AccountOf<Provider<Auth>>[] : AccountOf<Slot>;
+/** Current credentials for one invocation. Never retained in source or build output. */
+export interface BoundContext<Slots extends AccountSlots> {
+    /** Read-only run management, bound to this configured app. */
+    readonly workflows: WorkflowReads;
+    /** Ask for user input during this tool call. Unavailable during discovery and after the invocation closes. */
+    readonly elicit: Elicit;
+    /** Invocation-owned HTTP requests with trace propagation and host cancellation. */
+    readonly fetch: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+    /** Host cancellation for this invocation. Pass it to fetch and other interruptible APIs. */
+    readonly signal: AbortSignal;
+    readonly accounts: {
+        readonly [Slot in keyof Slots]: AccountsFor<Slots[Slot]>;
+    };
+}
+/** The host evaluates this factory fresh with the configured app's selected accounts. */
+export interface App<Slots extends AccountSlots, Def extends AppDefinition<never>> {
+    readonly accounts: Slots;
+    readonly database?: DatabaseDefinition;
+    readonly evaluate: (context: BoundContext<Slots>) => Effect.Effect<Def, unknown>;
+}
+declare const NotImplemented_base: Schema.Class<NotImplemented, Schema.TaggedStruct<"NotImplemented", {
+    readonly operation: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** Explicit failure for authored capabilities that are still only sketches. */
+export declare class NotImplemented extends NotImplemented_base {
+}
+export {};

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

@@ -0,0 +1,14 @@
+/** Tool-owned approval policies, evaluated after native input decoding. */
+import { Schema, type Effect } from "effect";
+/** Approve this call, deny it, or stop for a human decision. */
+export declare const ApprovalDecision: Schema.Literals<readonly ["approved", "denied", "user-approval"]>;
+/** Parsed result of one tool approval policy. */
+export type ApprovalDecision = typeof ApprovalDecision.Type;
+/** Context for one tool's policy. toolInput is the same decoded value passed to run. */
+export interface ApprovalContext<Input = unknown> {
+    readonly toolName: string;
+    readonly toolInput: Input;
+    readonly signal: AbortSignal;
+}
+/** Native policy for this tool only. Failures prevent execution and remain private. */
+export type Approval<Input = unknown> = (context: ApprovalContext<Input>) => Effect.Effect<ApprovalDecision, unknown>;

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

@@ -0,0 +1,25 @@
+/** Public handler contexts derive capabilities from one shared requirements declaration. */
+import type { WorkflowControls } from "./workflows.js";
+import type { AccountSlots, BoundContext } from "./app.js";
+import type { Database, DatabaseDefinition, DatabaseReader, Tables } from "./storage.js";
+/** Requirements are pure values; selected accounts and database sessions belong to invocations. */
+export interface AppRequirements {
+    readonly accounts: AccountSlots;
+    readonly database?: DatabaseDefinition;
+}
+type StorageContext<Requirements, Writable extends boolean> = Requirements extends {
+    readonly database: DatabaseDefinition<infer T extends Tables>;
+} ? {
+    readonly db: Writable extends true ? Database<T> : DatabaseReader<T>;
+} : {};
+/** Context available during dynamic app evaluation; storage opens only for handlers. */
+export type AppContext<Requirements extends AppRequirements = AppRequirements> = BoundContext<Requirements["accounts"]>;
+/** Interactive query context; declared storage exposes only read methods. */
+export type QueryContext<Requirements extends AppRequirements = AppRequirements> = AppContext<Requirements> & StorageContext<Requirements, false>;
+/** Interactive mutation context; declared storage belongs to the invocation transaction. */
+export type MutationContext<Requirements extends AppRequirements = AppRequirements> = Omit<AppContext<Requirements>, "workflows"> & {
+    readonly workflows: WorkflowControls;
+} & StorageContext<Requirements, true>;
+/** Background webhook context has account and storage access without interactive input. */
+export type WebhookContext<Requirements extends AppRequirements = AppRequirements> = Omit<MutationContext<Requirements>, "elicit">;
+export {};

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

@@ -0,0 +1,86 @@
+/** Shared MCP elicitation data. Delivery belongs to the host, independently of its transport. */
+import { Schema, type Effect } from "effect";
+import * as McpSchema from "effect/unstable/ai/McpSchema";
+import { type JsonValue } from "./schema.js";
+/** Maximum human-input wait, separate from active provider execution time. */
+export declare const ElicitationLimits: Schema.Struct<{
+    readonly timeoutMs: Schema.Int;
+}>;
+export type ElicitationLimits = typeof ElicitationLimits.Type;
+/** Shared input lifetime for MCP collection and upstream forms. */
+export declare const defaultElicitationLimits: {
+    readonly timeoutMs: number;
+};
+/** Plain-data form request derived from the pinned MCP protocol schema. */
+export declare const FormElicitation: Schema.Struct<{
+    readonly mode: Schema.Literal<"form">;
+    readonly requestedSchema: Schema.toEncoded<Schema.Struct<{
+        readonly $schema: Schema.decodeTo<Schema.optional<Schema.String>, Schema.optionalKey<Schema.String>, never, never>;
+        readonly type: Schema.tag<"object">;
+        readonly properties: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Union<readonly [typeof McpSchema.LegacyTitledEnum, Schema.Union<readonly [typeof McpSchema.UntitledSingleSelectEnum, typeof McpSchema.TitledSingleSelectEnum]>, Schema.Union<readonly [typeof McpSchema.UntitledMultiSelectEnum, typeof McpSchema.TitledMultiSelectEnum]>]>, typeof McpSchema.ElicitationString, typeof McpSchema.ElicitationNumber, typeof McpSchema.ElicitationBoolean]>>;
+        readonly required: Schema.decodeTo<Schema.optional<Schema.$Array<Schema.String>>, Schema.optionalKey<Schema.$Array<Schema.String>>, never, never>;
+    }>>;
+    readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly message: Schema.String;
+}>;
+export type FormElicitation = typeof FormElicitation.Type;
+/** MCP accept/decline/cancel response, without imposing a client or transport on app code. */
+export declare const ElicitationResponse: Schema.Union<readonly [Schema.Struct<{
+    readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly action: Schema.Literal<"accept">;
+    readonly content: Schema.decodeTo<Schema.optional<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>, never, never>;
+}>, Schema.Struct<{
+    readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly action: Schema.Literals<readonly ["cancel", "decline"]>;
+}>]>;
+export type ElicitationResponse = typeof ElicitationResponse.Type;
+declare const ElicitationFailed_base: Schema.Class<ElicitationFailed, Schema.TaggedStruct<"ElicitationFailed", {
+    readonly reason: Schema.Literals<readonly ["unavailable", "transaction", "invalid-request", "invalid-response", "transport", "expired", "forbidden"]>;
+}>, import("effect/Cause").YieldableError>;
+/** A tool interaction could not be delivered or its request/response was invalid. No private payload is retained. */
+export declare class ElicitationFailed extends ElicitationFailed_base {
+}
+/** Trusted, invocation-owned delivery. The signal expires with the tool invocation. */
+export type ElicitationHandler = (request: FormElicitation, signal: AbortSignal) => Effect.Effect<ElicitationResponse, ElicitationFailed>;
+/** App authors await standard MCP form responses without depending on Effect or a particular host. */
+export type Elicit = (request: FormElicitation) => Promise<ElicitationResponse>;
+/** Safe reply for a runtime that crosses an RPC boundary. */
+export declare const ElicitationReply: Schema.Union<readonly [Schema.Struct<{
+    readonly ok: Schema.Literal<true>;
+    readonly response: Schema.Union<readonly [Schema.Struct<{
+        readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        readonly action: Schema.Literal<"accept">;
+        readonly content: Schema.decodeTo<Schema.optional<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>, never, never>;
+    }>, Schema.Struct<{
+        readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        readonly action: Schema.Literals<readonly ["cancel", "decline"]>;
+    }>]>;
+}>, Schema.Struct<{
+    readonly ok: Schema.Literal<false>;
+    readonly error: typeof ElicitationFailed;
+}>]>;
+export type ElicitationReply = typeof ElicitationReply.Type;
+/** Invocation consent requests no additional fields; arguments are reviewed, never edited in the form. */
+export declare const ApprovalElicitation: Schema.Struct<{
+    readonly requestedSchema: Schema.Struct<{
+        readonly type: Schema.Literal<"object">;
+        readonly properties: Schema.$Record<Schema.String, Schema.Never>;
+    }>;
+    readonly mode: Schema.Literal<"form">;
+    readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly message: Schema.String;
+}>;
+export type ApprovalElicitation = typeof ApprovalElicitation.Type;
+/** Only empty form content can answer invocation consent. Extra fields cannot change approved arguments. */
+export declare const ApprovalResponse: Schema.Union<readonly [Schema.Struct<{
+    readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly action: Schema.Literal<"accept">;
+    readonly content: Schema.decodeTo<Schema.optional<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.$Array<Schema.String>]>>>, never, never>;
+}>, Schema.Struct<{
+    readonly _meta: Schema.optional<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly action: Schema.Literals<readonly ["cancel", "decline"]>;
+}>]>;
+export type ApprovalResponse = typeof ApprovalResponse.Type;
+/** Build the framework's own policy prompt after native input decoding. Includes no account credentials. */
+export declare const approvalElicitation: (toolName: string, input: JsonValue) => ApprovalElicitation;
+export {};