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

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

@@ -4,10 +4,8 @@
  */
 import { Effect, Schema } from "effect";
 import { HostDeclarationInvalid, HostEvaluationFailed, type HostRouterError } from "../contracts/host.js";
-import { McpError } from "../contracts/mcp.js";
 import type { AppOperation } from "../contracts/operations.js";
 import type { AppRouter, DynamicRouter, RouterMeta } from "../contracts/router.js";
-import { SkillLoadFailed } from "../contracts/skills.js";
 import type { OperationSchedule } from "../contracts/schedules.js";
 /**
  * Keep only a failure's safe fields. Anything unrecognized becomes an evaluation failure with the
@@ -29,8 +27,9 @@ export declare const routerSkillPrefix = "tools";
 export declare const routerSkillName: (path: string) => string;
 /** A declared operation's catalog entry without schemas. `router` is its owning router's path. */
 export declare const operationSummary: (name: string, router: string, operation: AppOperation, schedules?: readonly OperationSchedule[]) => Effect.Effect<{
-    readonly name: string;
     readonly description: string;
+    readonly name: string;
+    readonly router?: string;
     readonly title?: string;
     readonly annotations?: {
         readonly title?: string;
@@ -52,21 +51,23 @@ export declare const operationSummary: (name: string, router: string, operation:
             };
         };
         readonly input: Schema.Json;
+        readonly scope?: "app";
     }[];
     readonly readOnly?: boolean;
-    readonly router?: string;
     readonly tags?: readonly string[];
+    readonly kindConfirmed?: boolean;
 }, HostDeclarationInvalid, never>;
 /** A declared operation's full description, including rendered schemas. */
 export declare const operationDescription: (name: string, router: string, operation: AppOperation, schedules?: readonly OperationSchedule[]) => Effect.Effect<{
-    readonly name: string;
     readonly description: string;
+    readonly name: string;
     readonly inputSchema: {
         readonly [x: string]: Schema.Json;
     };
     readonly _meta?: {
         readonly [x: string]: Schema.Json;
     };
+    readonly router?: string;
     readonly title?: string;
     readonly annotations?: {
         readonly title?: string;
@@ -91,14 +92,15 @@ export declare const operationDescription: (name: string, router: string, operat
             };
         };
         readonly input: Schema.Json;
+        readonly scope?: "app";
     }[];
     readonly readOnly?: boolean;
-    readonly router?: string;
     readonly tags?: readonly string[];
+    readonly kindConfirmed?: boolean;
 }, HostDeclarationInvalid, never>;
 /**
- * A dynamic router over operations already discovered, such as an eager OpenAPI document or a
- * stdio server. Upstream names can contain dots, which static router keys cannot.
+ * A dynamic router over operations already discovered, such as an eager OpenAPI document.
+ * Upstream names can contain dots, which static router keys cannot.
  */
 export declare const fixedRouter: (operations: Readonly<Record<string, AppOperation>>, meta?: RouterMeta) => DynamicRouter;
 export interface CatalogOptions {
@@ -122,14 +124,15 @@ export interface CatalogOptions {
  */
 export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined, options: CatalogOptions) => Effect.Effect<{
     tools: ({
-        readonly name: string;
         readonly description: string;
+        readonly name: string;
         readonly inputSchema: {
             readonly [x: string]: Schema.Json;
         };
         readonly _meta?: {
             readonly [x: string]: Schema.Json;
         };
+        readonly router?: string;
         readonly title?: string;
         readonly annotations?: {
             readonly title?: string;
@@ -154,13 +157,15 @@ export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined,
                 };
             };
             readonly input: Schema.Json;
+            readonly scope?: "app";
         }[];
         readonly readOnly?: boolean;
-        readonly router?: string;
         readonly tags?: readonly string[];
+        readonly kindConfirmed?: boolean;
     } | {
-        readonly name: string;
         readonly description: string;
+        readonly name: string;
+        readonly router?: string;
         readonly title?: string;
         readonly annotations?: {
             readonly title?: string;
@@ -182,36 +187,37 @@ export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined,
                 };
             };
             readonly input: Schema.Json;
+            readonly scope?: "app";
         }[];
         readonly readOnly?: boolean;
-        readonly router?: string;
         readonly tags?: readonly string[];
+        readonly kindConfirmed?: boolean;
     })[];
     routers: {
         readonly path: string;
-        readonly error?: import("../index.js").ProviderError | SkillLoadFailed | McpError | HostDeclarationInvalid | HostEvaluationFailed;
         readonly description?: string;
+        readonly error?: import("../index.js").ProviderError | import("../contracts/host.js").McpError | import("../contracts/host.js").SkillLoadFailed | HostDeclarationInvalid | HostEvaluationFailed;
         readonly title?: string;
-        readonly tags?: {
-            readonly [x: string]: string;
-        };
         readonly icons?: readonly {
             readonly src: string;
             readonly mimeType?: string;
             readonly sizes?: readonly string[];
             readonly theme?: "light" | "dark";
         }[];
+        readonly tags?: {
+            readonly [x: string]: string;
+        };
         readonly skill?: string;
     }[];
-}, import("../index.js").ProviderError | SkillLoadFailed | McpError | HostDeclarationInvalid | HostEvaluationFailed, never>;
+}, import("../index.js").ProviderError | import("../contracts/host.js").McpError | import("../contracts/host.js").SkillLoadFailed | HostDeclarationInvalid | HostEvaluationFailed, never>;
 /**
  * One skill for each router with instructions. Skills and tools fail independently: a dynamic
  * router whose metadata cannot be read, including the root, contributes no skill and does not
  * fail the others. Metadata comes through each source's catalog cache, like a tool listing.
  */
 export declare const routerSkills: (root: AppRouter | DynamicRouter | undefined) => Effect.Effect<{
-    readonly name: string;
     readonly description: string;
+    readonly name: string;
     readonly files: readonly {
         readonly path: string;
         readonly content: string;

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

@@ -1,8 +1,9 @@
 import { HostedTool } from "../contracts/host.js";
 import type { AppOperation } from "../contracts/operations.js";
 import { RouterMeta, type AppRouter, type DynamicRouter, type RouterIcon } from "../contracts/router.js";
-import { type OperationDeclaration, type RouterChild, type RouterDeclaration } from "./operations.js";
-export type { RouterChild, RouterDeclaration } from "./operations.js";
+import type { Approval } from "../approval.js";
+import { type OperationChild, type OperationDeclaration, type RouterChild, type RouterDeclaration } from "./operations.js";
+export type { OperationChild, OperationDeclaration, RouterChild, RouterDeclaration, } from "./operations.js";
 /** Author metadata for a router. Instructions become a skill named after the router's path. */
 export interface RouterOptions {
     readonly title?: string;
@@ -26,13 +27,16 @@ export declare function router<Query = unknown, Mutation = unknown>(children: Re
 export declare function router<Query, Mutation>(source: RouterDeclaration<Query, Mutation>, options: RouterOptions): RouterDeclaration<Query, Mutation>;
 /**
  * Declare a router whose tools are discovered when read. `list` returns tools with names relative
- * to this router; mark queries with `readOnly: true`. `resolve` receives one of those names.
+ * to this router; mark queries with `readOnly: true`, and add `kindConfirmed: true` when your code,
+ * not an upstream service's claim, decides the kind. `resolve` receives one of those names.
+ * The router carries the handler contexts of the operations `resolve` returns, so `defineApp`
+ * checks them like a static router's.
  */
-export declare const dynamicRouter: (source: {
+export declare const dynamicRouter: <Query = unknown, Mutation = unknown>(source: {
     readonly meta?: () => RouterOptions | Promise<RouterOptions>;
     readonly list: () => readonly HostedTool[] | Promise<readonly HostedTool[]>;
-    readonly resolve: (name: string) => OperationDeclaration<"query" | "mutation", unknown> | undefined | Promise<OperationDeclaration<"query" | "mutation", unknown> | undefined>;
-}) => RouterDeclaration;
+    readonly resolve: (name: string) => OperationChild<Query, Mutation> | undefined | Promise<OperationChild<Query, Mutation> | undefined>;
+}) => RouterDeclaration<Query, Mutation>;
 /** Join a router path and a relative name. The root router's path is "". */
 export declare const joinPath: (path: string, name: string) => string;
 /** Where a full tool name points: a declared operation, or a name inside a dynamic router. */
@@ -57,3 +61,19 @@ export declare const declaredOperations: (root: AppRouter | undefined, path?: st
     readonly router: string;
     readonly operation: AppOperation;
 }>;
+/**
+ * Choose an approval for each operation a router contains, including tools a dynamic router
+ * resolves later. `policy` receives the operation and its name relative to this router; returning
+ * undefined keeps the operation's own approval. Read hints with `toolAnnotations(operation)`.
+ * Apply it to each account's router before `accountRouter` combines them, so every account keeps
+ * its own tools' hints.
+ */
+export declare const withApprovals: <Query, Mutation>(source: RouterDeclaration<Query, Mutation>, policy: (operation: OperationDeclaration<"query" | "mutation", never>, name: string) => Approval | undefined) => RouterDeclaration<Query, Mutation>;
+/**
+ * Expose a protocol router's tools under other names, such as the names an earlier client used.
+ * `rename` receives each tool's name relative to this router and returns the name to expose, or
+ * undefined to leave the tool out. When two tools would share a name, the first listed keeps it.
+ * Calls and descriptions find a tool by its exposed name. Works on routers that discover their
+ * tools, such as `mcpRouter`, `graphqlRouter` and `liveOpenapiRouter`.
+ */
+export declare const renameTools: <Query, Mutation>(source: RouterDeclaration<Query, Mutation>, rename: (name: string) => string | undefined) => RouterDeclaration<Query, Mutation>;

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

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

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

@@ -1,16 +1,47 @@
 import { Interval, ScheduleTiming } from "../contracts/schedules.js";
 import { JsonValue } from "../contracts/schema.js";
-import { type Operation, type OperationDeclaration } from "./operations.js";
-/** The app adapter resolves this operation handle to its declared mutation name. */
-export interface ScheduleDeclaration<Context = never> {
+import type { AccountScope } from "../contracts/app.js";
+import { type Operation, type OperationDeclaration, type WithoutApproval } from "./operations.js";
+/**
+ * The app adapter resolves this operation handle to its declared mutation name. A `"user"`
+ * schedule has one copy per member who enables it, run as them with their linked accounts. An
+ * `"app"` schedule is one schedule, enabled by an app manager, run without a caller with the app's
+ * accounts only.
+ */
+export interface ScheduleDeclaration<Context = never, Scope extends AccountScope = AccountScope> {
+    readonly scope: Scope;
     readonly operation: OperationDeclaration<"mutation", Context>;
     readonly timing: ScheduleTiming;
     readonly input: JsonValue;
 }
-/** Run an existing mutation at a fixed interval. Installation enablement belongs to the host. */
-export declare const interval: <Input, Output, Context>(duration: Interval, operation: Operation<Input, Output, "mutation", Context>, input: NoInfer<Input>) => ScheduleDeclaration<Context>;
-/** Calendar alternative for wall-clock schedules. UTC is the explicit default when timezone is omitted. */
-export declare const cron: <Input, Output, Context>(calendar: {
+/**
+ * Refuses, with a message the type error shows, a mutation whose handler context has the caller's
+ * `user`, such as one that declares a context without a type.
+ */
+type RunsAsApp<Context> = [Context] extends [{
+    readonly user: unknown;
+}] ? {
+    readonly 'An app schedule runs without a caller: type the handler\'s context as MutationContext<typeof requirements, "app">, pass it as the third type argument, or declare no parameters and pass no type arguments': never;
+} : unknown;
+/** Run an existing mutation at a fixed interval, once per member who enables it, as them. */
+export declare const userInterval: <Input, Output, Context>(duration: Interval, operation: Operation<Input, Output, "mutation", Context>, input: NoInfer<Input>) => ScheduleDeclaration<Context, "user">;
+/**
+ * Calendar alternative for wall-clock schedules, once per member who enables it, as them. UTC is the
+ * explicit default when timezone is omitted.
+ */
+export declare const userCron: <Input, Output, Context>(calendar: {
     readonly expression: string;
     readonly timezone?: string;
-}, operation: Operation<Input, Output, "mutation", Context>, input: NoInfer<Input>) => ScheduleDeclaration<Context>;
+}, operation: Operation<Input, Output, "mutation", Context>, input: NoInfer<Input>) => ScheduleDeclaration<Context, "user">;
+/**
+ * Run an existing mutation at a fixed interval as the app: one schedule an app manager enables, run
+ * without a caller with the app's accounts. The mutation takes a context of the `"app"` scope and
+ * declares no approval.
+ */
+export declare const appInterval: <Input, Output, Context>(duration: Interval, operation: Operation<Input, Output, "mutation", Context> & WithoutApproval & RunsAsApp<Context>, input: NoInfer<Input>) => ScheduleDeclaration<Context, "app">;
+/** Calendar alternative to `appInterval`. UTC is the explicit default when timezone is omitted. */
+export declare const appCron: <Input, Output, Context>(calendar: {
+    readonly expression: string;
+    readonly timezone?: string;
+}, operation: Operation<Input, Output, "mutation", Context> & WithoutApproval & RunsAsApp<Context>, input: NoInfer<Input>) => ScheduleDeclaration<Context, "app">;
+export {};

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

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

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

@@ -1,35 +1,28 @@
 /** Remote skill readers return complete portable bundles, never installed host files. */
 import { Effect } from "effect";
-import { SkillLoadFailed, type GitHubSkillsOptions, type WellKnownSkillsOptions, type SkillTransport } from "../contracts/skills.js";
+import { NetworkRefused } from "../contracts/network.js";
+import { ProviderError } from "../contracts/provider-error.js";
+import { AppSkills, SkillLoadFailed, type GitHubSkillsOptions, type WellKnownSkillsOptions, type SkillTransport } from "../contracts/skills.js";
 /** Give every failure without a message one that names the service. */
-export declare const withService: (service: string | undefined) => <A, R>(effect: Effect.Effect<A, SkillLoadFailed, R>) => Effect.Effect<A, SkillLoadFailed, R>;
+export declare const withService: (service: string | undefined) => <A, R>(effect: Effect.Effect<A, SkillLoadFailed | NetworkRefused, R>) => Effect.Effect<A, NetworkRefused | SkillLoadFailed, R>;
+interface ReadRequest {
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Describe a refusal by Executor's app network; defaults to the refusal itself. */
+    readonly refused?: (refused: NetworkRefused) => SkillLoadFailed | NetworkRefused;
+}
 /** One loader invocation owns its byte budget and all of its network requests. */
 export declare const reader: (transport: SkillTransport) => Effect.Effect<{
-    fetchBytes: (url: string, post?: {
-        readonly body: Uint8Array;
-        readonly headers: Record<string, string>;
-    }) => Effect.Effect<Uint8Array<ArrayBuffer>, SkillLoadFailed, never>;
-    read: (url: string) => Effect.Effect<string, SkillLoadFailed, never>;
-    json: (url: string) => Effect.Effect<unknown, SkillLoadFailed, never>;
+    fetchBytes: (url: string, request?: ReadRequest & {
+        readonly body?: Uint8Array;
+    }) => Effect.Effect<Uint8Array<ArrayBuffer>, NetworkRefused | SkillLoadFailed, never>;
+    read: (url: string, request?: ReadRequest) => Effect.Effect<string, NetworkRefused | SkillLoadFailed, never>;
+    json: (url: string) => Effect.Effect<unknown, NetworkRefused | SkillLoadFailed, never>;
 }, never, never>;
-export declare const githubSkillsEffect: (options: GitHubSkillsOptions) => Effect.Effect<readonly {
-    readonly name: string;
-    readonly description: string;
-    readonly files: readonly {
-        readonly path: string;
-        readonly content: string;
-    }[];
-    readonly license?: string;
-    readonly compatibility?: string;
-    readonly metadata?: {
-        readonly [x: string]: string;
-    };
-    readonly "allowed-tools"?: string;
-}[], SkillLoadFailed, never>;
+export declare const githubSkillsEffect: (options: GitHubSkillsOptions) => Effect.Effect<typeof AppSkills.Type, SkillLoadFailed | NetworkRefused | ProviderError>;
 /** Fetch all indexed files and reject a publication whose index changes during the read. */
 export declare const wellKnownSkillsEffect: (options: WellKnownSkillsOptions) => Effect.Effect<readonly {
-    readonly name: string;
     readonly description: string;
+    readonly name: string;
     readonly files: readonly {
         readonly path: string;
         readonly content: string;
@@ -40,4 +33,5 @@ export declare const wellKnownSkillsEffect: (options: WellKnownSkillsOptions) =>
         readonly [x: string]: string;
     };
     readonly "allowed-tools"?: string;
-}[], SkillLoadFailed, never>;
+}[], NetworkRefused | SkillLoadFailed, never>;
+export {};

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

@@ -0,0 +1,71 @@
+/**
+ * `ctx.sql` over a data facet's SQLite storage, and the deploy-time migrator.
+ *
+ * Every statement runs inside a synchronous SQLite transaction: alone, or inside the author's
+ * `transaction`. Nothing here can wait on another call, so no lock or transaction outlives the
+ * statement that needs it. What a statement may do is decided by SQLite, not by reading the SQL:
+ * a query runs in a transaction that is always rolled back.
+ */
+import { Effect, Schema } from "effect";
+import { type AppSqlStorage, type Sql, type SqlReader } from "../contracts/sql.js";
+import type { SkillFile } from "../contracts/skills.js";
+export declare const noDatabase: Sql;
+/** A workflow step mutation's identity, from the host's replay record. */
+export interface StepReplay {
+    readonly key: string;
+    readonly fingerprint: string;
+}
+/**
+ * One invocation's SQL. Once the invocation ends or `signal` aborts, every statement is refused, so
+ * code still running after a timeout or cancellation cannot write late.
+ */
+export declare const authorSql: (storage: AppSqlStorage, options: {
+    readonly signal: AbortSignal;
+    readonly step?: StepReplay;
+    /**
+     * The invocation's emitted events. A transaction that rolls back also discards the events its
+     * callback emitted, so subscribers never hear of writes that did not commit.
+     */
+    readonly emitted?: unknown[];
+}) => {
+    reader: SqlReader;
+    writer: Sql;
+    close: () => void;
+};
+declare const MigrationFileInvalid_base: Schema.Class<MigrationFileInvalid, Schema.TaggedStruct<"MigrationFileInvalid", {
+    readonly path: Schema.String;
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** A file in `migrations/` that is not a migration the host can order. */
+export declare class MigrationFileInvalid extends MigrationFileInvalid_base {
+    get message(): string;
+}
+declare const MigrationHistoryChanged_base: Schema.Class<MigrationHistoryChanged, Schema.TaggedStruct<"MigrationHistoryChanged", {
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The build's migrations no longer start with the ones already applied to the database. */
+export declare class MigrationHistoryChanged extends MigrationHistoryChanged_base {
+    get message(): string;
+}
+declare const MigrationFailed_base: Schema.Class<MigrationFailed, Schema.TaggedStruct<"MigrationFailed", {
+    readonly path: Schema.String;
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** SQLite rejected a migration. Every migration of the deploy rolled back. */
+export declare class MigrationFailed extends MigrationFailed_base {
+    get message(): string;
+}
+/** Whether a build's files give the app a database: any `.sql` file in `migrations/`. */
+export declare const hasMigrations: (files: readonly {
+    readonly path: string;
+}[]) => boolean;
+/**
+ * Apply the build's pending migrations and report which ran. Every pending migration runs in one
+ * transaction, so a failing one leaves the database exactly as the active version knows it. The
+ * migrations already applied must still be the build's first ones, byte for byte.
+ */
+export declare const migrate: (storage: AppSqlStorage, files: readonly SkillFile[]) => Effect.Effect<{
+    readonly id: number;
+    readonly name: string;
+}[], MigrationFileInvalid | MigrationHistoryChanged | MigrationFailed, never>;
+export {};

package/types/apps/src/implementation/ui-account-notice.d.ts

@@ -0,0 +1,9 @@
+/** Host-rendered account notices; no authored app code or provider responses enter them. */
+import type { UiAccountNotice, UiAccountProblem } from "../contracts/ui.js";
+/** Missing, removed, incompatible, or rejected accounts stop the app; other failed checks are advisory. */
+export declare const accountProblemBlocks: (problem: UiAccountProblem) => boolean;
+export declare const accountProblemText: (problem: UiAccountProblem) => string;
+/** Full page shown instead of the app while an account problem stops it from working. */
+export declare const accountBlockedPage: (notice: UiAccountNotice) => string;
+/** Inline card for advisory problems; the app still loads underneath. */
+export declare const accountNoticeBootstrap: (notice: UiAccountNotice) => string;

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

@@ -1,5 +1,5 @@
 /** Host responses around app sign-in. They carry no script and never contain product credentials. */
-import { HttpServerResponse } from "effect/unstable/http";
+import { HttpServerResponse } from "effect/http";
 import { type AppSignInId } from "../contracts/ui-auth.js";
 /** Private app responses must not leak authentication URLs through caches or referrers. */
 export declare const appPrivateHeaders: {

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

@@ -1,7 +1,7 @@
-import { Atom } from "effect/unstable/reactivity";
+import { AsyncResult, Atom } from "effect/reactivity";
 import { type OperationReference } from "../contracts/live.js";
 import { type Schema } from "./schema.js";
-/** A scoped page client. Host-injected context carries only the deployment, never credentials. */
+/** A scoped page client. Host-injected context carries only the version, never credentials. */
 export declare const createAppClient: () => {
     /** Close this client when its page or embedding owner is removed. */
     dispose: () => Promise<void>;
@@ -12,5 +12,5 @@ export declare const createAppClient: () => {
     /** Create a callable mutation with optional withOptimisticUpdate projections over mounted queries. */
     mutation: <Input, Output>(reference: OperationReference<Input, Output, "mutation">, output: Schema<NoInfer<Output>, boolean>) => import("../client.js").AppMutation<Input, Output>;
     /** Share a live query across mounts and reconcile optimistic changes against fresh server reads. */
-    queryAtom: <Input, Output>(reference: OperationReference<Input, Output, "query">, input: NoInfer<Input>, output: Schema<NoInfer<Output>, boolean>) => Atom.Atom<import("effect/unstable/reactivity/AsyncResult").AsyncResult<Output, unknown>>;
+    queryAtom: <Input, Output>(reference: OperationReference<Input, Output, "query">, input: NoInfer<Input>, output: Schema<NoInfer<Output>, boolean>) => Atom.Atom<AsyncResult.AsyncResult<Output, unknown>>;
 };

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

@@ -0,0 +1,5 @@
+/**
+ * Retained files sit at the version's asset root. Resolving path-relative resource URLs there,
+ * instead of with `<base>`, leaves the document base as the page URL for links, history and forms.
+ */
+export declare const versionDocument: (html: string, version: string) => string;

package/types/apps/src/implementation/ui-errors.d.ts

@@ -1,2 +1,2 @@
 /** Inline host script: no app dependencies, credentials, or authored HTML enter its source. */
-export declare const appFailureBootstrap: string;
+export declare const appFailureBootstrap = "<script>\"use strict\";(()=>{var M=()=>{let d,w=Date.now(),m=0,g=0,f=new Map,v=/^(?:chrome|moz|safari-web)-extension:/,A=new Set([\"ResizeObserver loop completed with undelivered notifications.\",\"ResizeObserver loop limit exceeded\"]),V=new Set([\"Error\",\"TypeError\",\"ReferenceError\",\"SyntaxError\",\"RangeError\",\"URIError\",\"EvalError\",\"AggregateError\"]),b=(e,t=0,i=0)=>{let r=[];if(!URL.canParse(e))return r;let a=new URL(e);return a.origin!==location.origin||!a.pathname.startsWith(\"/_executor/assets/\")||!a.pathname.endsWith(\".js\")||(r.push({key:\"code.file.path\",value:{stringValue:a.pathname}}),Number.isSafeInteger(t)&&t>0&&r.push({key:\"code.line.number\",value:{intValue:String(t)}}),Number.isSafeInteger(i)&&i>0&&r.push({key:\"code.column.number\",value:{intValue:String(i)}})),r},h=(e,t,i=[])=>{let r=Date.now();r-w>=6e4&&(w=r,m=0,f.clear());let a=`${e}:${t.slice(0,2e3)}`,x=f.get(a);if(x!==void 0&&r-x<1e3||m>=20){g++;return}f.set(a,r),m++,i.push({key:\"executor.ui.failure.suppressed\",value:{intValue:String(g)}}),g=0;let E=Array.from(crypto.getRandomValues(new Uint8Array(16)),s=>s.toString(16).padStart(2,\"0\")).join(\"\"),S=`${Date.now()}000000`,n,l=\"Sending error report\\u2026\",k=()=>{if(d?.open)return;let s=document.createElement(\"div\"),D=s.attachShadow({mode:\"open\"}),o=document.createElement(\"dialog\");d=o,o.setAttribute(\"aria-labelledby\",\"executor-failure-title\");let y=document.createElement(\"h2\");y.id=\"executor-failure-title\",y.textContent=e===\"script\"?\"This app could not load\":\"This app stopped working\";let C=document.createElement(\"p\");C.textContent=e===\"script\"?\"A file needed by this page did not load. Reload the page to try again.\":\"The app encountered an unexpected error. Reload the page to try again.\";let L=document.createElement(\"p\");L.textContent=\"Copy any unsaved work before reloading.\";let R=document.createElement(\"details\"),T=document.createElement(\"summary\");T.textContent=\"Error details\";let c=document.createElement(\"textarea\");c.readOnly=!0,c.rows=10,c.cols=36,c.setAttribute(\"aria-label\",\"Error details\"),c.value=`${t.slice(0,12e3)}\n\nDiagnostic ID: ${E}`,R.append(T,c),n=document.createElement(\"p\"),n.setAttribute(\"role\",\"status\"),n.textContent=l;let u=document.createElement(\"button\");u.type=\"button\",u.textContent=\"Reload page\",u.addEventListener(\"click\",()=>location.reload());let p=document.createElement(\"button\");p.type=\"button\",p.textContent=\"Close\",p.addEventListener(\"click\",()=>o.close()),o.addEventListener(\"close\",()=>{d===o&&(d=void 0),s.remove()}),o.append(y,C,L,R,n,u,p),D.append(o),document.documentElement.append(s),o.showModal()};document.readyState===\"loading\"?document.addEventListener(\"DOMContentLoaded\",k,{once:!0}):k(),fetch(\"/_executor/api/telemetry/traces\",{method:\"POST\",headers:{\"content-type\":\"application/json\"},credentials:\"same-origin\",keepalive:!0,body:JSON.stringify({resourceSpans:[{scopeSpans:[{spans:[{traceId:E,spanId:E.slice(0,16),name:\"ui.app.failure\",kind:1,startTimeUnixNano:S,endTimeUnixNano:S,status:{code:2},attributes:[{key:\"executor.ui.failure.kind\",value:{stringValue:e}},...i]}]}]}]})}).then(s=>{l=s.ok?\"Error report sent.\":\"Could not send the error report. You can copy the error details.\",n&&(n.textContent=l)},()=>{l=\"Could not send the error report. You can copy the error details.\",n&&(n.textContent=l)})};window.addEventListener(\"error\",e=>{if(e instanceof ErrorEvent){if(v.test(e.filename)||e.error===null&&e.lineno===0&&A.has(e.message))return;let t=b(e.filename,e.lineno,e.colno);e.error instanceof Error&&V.has(e.error.name)&&t.push({key:\"exception.type\",value:{stringValue:e.error.name}}),h(\"runtime\",e.error instanceof Error?e.error.stack??e.message:e.message,t)}else e.target instanceof HTMLScriptElement&&h(\"script\",`Could not load script: ${e.target.src}`,b(e.target.src))},!0),window.addEventListener(\"unhandledrejection\",e=>{let t=e.reason;h(\"rejection\",t instanceof Error?t.stack??t.message:\"An app operation failed without handling its error.\")})};M();})();</script>";