apps 0.0.1-beta.10 → 0.0.1-beta.101

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

@@ -0,0 +1,63 @@
+/**
+ * App-owned SQLite. An app with migrations in `migrations/` reads and writes its own database with
+ * plain SQL. The author API mirrors Cloudflare's `SqlStorage`, so tools built for Durable Object
+ * SQLite fit it.
+ */
+/** A value SQLite stores or returns. */
+export type SqlValue = string | number | null | ArrayBuffer;
+/** One result row, keyed by column name. */
+export type SqlRow = Record<string, SqlValue>;
+/** The rows of one statement, already read, and what the statement read and wrote. */
+export interface SqlCursor<Row extends SqlRow = SqlRow> extends Iterable<Row> {
+    readonly columnNames: readonly string[];
+    readonly rowsRead: number;
+    readonly rowsWritten: number;
+    toArray(): Row[];
+    /** The only row. Throws unless the statement returned exactly one. */
+    one(): Row;
+}
+/**
+ * Read-only SQL. Query tools receive this. A query runs in a transaction that is always rolled
+ * back, so nothing it changes commits; one that changes rows fails.
+ */
+export interface SqlReader {
+    exec<Row extends SqlRow = SqlRow>(query: string, ...bindings: SqlValue[]): SqlCursor<Row>;
+}
+/** SQL inside one transaction. */
+export type SqlTransaction = SqlReader;
+/**
+ * Writable SQL. Outside a transaction every statement commits on its own. `transaction` runs its
+ * callback synchronously in one SQLite transaction, so no transaction can stay open while the app
+ * waits on anything else; throwing rolls it back. Apps call outside services between transactions.
+ */
+export interface Sql extends SqlReader {
+    transaction<T>(work: (tx: SqlTransaction) => Synchronous<T>): T;
+}
+/** A transaction callback's result: a Promise means the callback awaited, which is refused. */
+export type Synchronous<T> = T extends PromiseLike<unknown> ? never : T;
+/** The Durable Object storage a data facet hands its app. App code never receives it. */
+export interface AppSqlStorage {
+    readonly sql: {
+        exec(query: string, ...bindings: SqlValue[]): {
+            readonly columnNames: string[];
+            readonly rowsRead: number;
+            readonly rowsWritten: number;
+            toArray(): Record<string, SqlValue>[];
+        };
+    };
+    transactionSync<T>(work: () => T): T;
+}
+/**
+ * Tables Executor keeps in an app's database: applied migrations, workflow step receipts, and
+ * `_executor_legacy_rows (table_name, id, body)`, the rows of the document API apps used before
+ * SQL, with JSON bodies (empty for apps that never stored any). Apps should only read them; a
+ * changed migration history fails the next deploy.
+ */
+export declare const reservedTablePrefix = "_executor_";
+/** Where an app keeps its migrations: `0001_create_notes.sql`, applied in number order. */
+export declare const migrationsDirectory = "migrations";
+/**
+ * The most values one statement may bind. Durable Object SQLite sets `SQLITE_LIMIT_VARIABLE_NUMBER`
+ * to 100 on every host; `ctx.sql` checks it first so the error names the limit.
+ */
+export declare const sqlBindingsLimit = 100;

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

@@ -1,24 +1,58 @@
 /** 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>;
+import { Schema, type Effect, type Stream } from "effect";
+import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api";
+import { withLegacyKeys } from "../../../utils/src/legacy-keys.js";
+export declare const UiContext: withLegacyKeys<Schema.Struct<{
+    readonly version: Schema.NonEmptyString;
+    readonly accounts: Schema.optional<Schema.$Record<Schema.NonEmptyString, Schema.$Array<Schema.NonEmptyString>>>;
+}>, {
+    readonly version: "deployment";
 }>;
+/** A problem with one of the page's accounts, from stored state. Labels are the owner's own names. */
+export type UiAccountProblem = {
+    readonly provider: string;
+    readonly reason: "missing" | "removed" | "incompatible";
+} | {
+    readonly provider: string;
+    readonly account: string;
+    readonly reason: "credentials_rejected" | "forbidden" | "upstream_unavailable" | "check_failed";
+};
+/** Account problems found when the page opened, with dashboard links that resolve them. */
+export interface UiAccountNotice {
+    readonly app: string;
+    readonly problems: readonly UiAccountProblem[];
+    /** The app's accounts in the dashboard. */
+    readonly fix: string;
+}
 /** Retained browser bytes. Hosts authorize access before reading or rendering them. */
-export interface AppUiAsset {
+export interface AppUiFile {
     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<{
+/** One byte range of a stored file, already within its size. */
+export interface AppUiRange {
+    readonly offset: number;
+    readonly length: number;
+}
+/**
+ * A public file the version's source served from `ui/public/`, which the host copied to its
+ * own store. `etag` names its exact bytes. Hosts authorize access before reading it.
+ */
+export interface AppUiStoredFile {
+    readonly contentType: string;
+    readonly size: number;
+    readonly etag: string;
+    readonly read: (range: AppUiRange | undefined) => Effect.Effect<Stream.Stream<Uint8Array, UiFailed>, UiFailed>;
+}
+export type AppUiAsset = AppUiFile | AppUiStoredFile;
+/** Requests name an operation on this app and the page's version, never another app or account. */
+export declare const UiOperation: withLegacyKeys<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>;
+    readonly version: Schema.NonEmptyString;
+    readonly accounts: Schema.optional<Schema.$Record<Schema.NonEmptyString, Schema.$Array<Schema.NonEmptyString>>>;
+}>, {
+    readonly version: "deployment";
 }>;
 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. */
@@ -28,9 +62,12 @@ declare const UiForbidden_base: Schema.Class<UiForbidden, Schema.TaggedStruct<"U
 /** 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 UiVersionChanged_base: Schema.Class<UiVersionChanged, Schema.TaggedStruct<"UiDeploymentChanged", {}>, import("effect/Cause").YieldableError>;
+/**
+ * The page should reload before starting another operation. The tag keeps its former name: pages
+ * built with earlier framework releases reload on it.
+ */
+export declare class UiVersionChanged extends UiVersionChanged_base {
 }
 declare const UiFailed_base: Schema.Class<UiFailed, Schema.TaggedStruct<"UiFailed", {
     readonly reason: Schema.Literals<readonly ["unavailable", "operation_failed", "account_required"]>;
@@ -50,24 +87,27 @@ export declare const UiSnapshot: Schema.Union<readonly [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<{
+export declare const AppUiApi: HttpApi.HttpApi<"app-ui", HttpApiGroup.HttpApiGroup<"ui", HttpApiEndpoint.HttpApiEndpoint<"query", "POST", "/_executor/api/query", never, never, Schema.toCodecJson<withLegacyKeys<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 version: Schema.NonEmptyString;
+    readonly accounts: Schema.optional<Schema.$Record<Schema.NonEmptyString, Schema.$Array<Schema.NonEmptyString>>>;
+}>, {
+    readonly version: "deployment";
+}>>, never, Schema.toCodecJson<Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.toCodecJson<typeof UiUnauthorized | typeof UiForbidden | typeof UiVersionChanged | typeof UiFailed>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"mutate", "POST", "/_executor/api/mutate", never, never, Schema.toCodecJson<withLegacyKeys<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 version: Schema.NonEmptyString;
+    readonly accounts: Schema.optional<Schema.$Record<Schema.NonEmptyString, Schema.$Array<Schema.NonEmptyString>>>;
+}>, {
+    readonly version: "deployment";
+}>>, never, Schema.toCodecJson<Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.toCodecJson<typeof UiUnauthorized | typeof UiForbidden | typeof UiVersionChanged | typeof UiFailed>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"subscribe", "POST", "/_executor/api/subscribe", never, never, Schema.toCodecJson<withLegacyKeys<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>;
+    readonly version: Schema.NonEmptyString;
+    readonly accounts: Schema.optional<Schema.$Record<Schema.NonEmptyString, Schema.$Array<Schema.NonEmptyString>>>;
+}>, {
+    readonly version: "deployment";
 }>>, 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>;
@@ -77,7 +117,7 @@ export declare const AppUiApi: HttpApi.HttpApi<"app-ui", HttpApiGroup.HttpApiGro
     readonly error: typeof UiFailed;
 }>, Schema.Struct<{
     readonly type: Schema.Literal<"heartbeat">;
-}>]>>, Schema.Union<readonly [typeof UiUnauthorized, typeof UiForbidden, typeof UiDeploymentChanged, typeof UiFailed]>, {
+}>]>>, Schema.Union<readonly [typeof UiUnauthorized, typeof UiForbidden, typeof UiVersionChanged, typeof UiFailed]>, {
     readonly value: Schema.Json;
     readonly type: "snapshot";
     readonly trace?: unknown;
@@ -86,5 +126,5 @@ export declare const AppUiApi: HttpApi.HttpApi<"app-ui", HttpApiGroup.HttpApiGro
     readonly error: UiFailed;
 } | {
     readonly type: "heartbeat";
-}>, Schema.toCodecJson<typeof UiUnauthorized | typeof UiForbidden | typeof UiDeploymentChanged | typeof UiFailed>, never, never>, false>>;
+}>, Schema.toCodecJson<typeof UiUnauthorized | typeof UiForbidden | typeof UiVersionChanged | typeof UiFailed>, never, never>, false>>;
 export {};

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

@@ -1,17 +1,34 @@
 /** Account-bound webhook lifecycle. Register and unregister must be idempotent for subscriptionId. */
 import type { Effect, Schema } from "effect";
 import type { ManualWebhookSetup } from "./webhook-protocol.js";
-import type { AccountSlots, BoundContext } from "./app.js";
-type SourceAccount<Context extends Pick<BoundContext<AccountSlots>, "accounts" | "fetch" | "signal">> = keyof Context["accounts"] & string;
-type SelectedAccount<Context extends Pick<BoundContext<AccountSlots>, "accounts" | "fetch" | "signal">> = {
-    [Slot in keyof Context["accounts"]]: Context["accounts"][Slot] extends readonly (infer Account)[] ? Account : Context["accounts"][Slot];
-}[keyof Context["accounts"]];
+import type { AccountScope, BoundContext, ScopedSlots } from "./app.js";
+/** What every webhook context provides; a context with `user` serves user-account webhooks. */
+type HookContext = Pick<BoundContext<ScopedSlots, AccountScope>, "app" | "fetch" | "signal">;
+/**
+ * The accounts of the webhook's scope. A context with `user` names a user requirement; one of the
+ * `"app"` scope, which has no `user`, an app requirement.
+ */
+type ScopeAccounts<Context extends HookContext> = Context extends {
+    readonly user: {
+        readonly accounts: infer Accounts;
+    };
+} ? Accounts : Context["app"]["accounts"];
+type SourceAccount<Context extends HookContext> = Context extends {
+    readonly user: unknown;
+} ? {
+    readonly user: keyof ScopeAccounts<Context> & string;
+} : {
+    readonly app: keyof ScopeAccounts<Context> & string;
+};
+type SelectedAccount<Context extends HookContext> = {
+    [Slot in keyof ScopeAccounts<Context>]: ScopeAccounts<Context>[Slot] extends readonly (infer Account)[] ? Account : ScopeAccounts<Context>[Slot];
+}[keyof ScopeAccounts<Context>];
 /**
  * Registration, delivery and cleanup share the selected accounts.
  * The host stores account IDs and parsed state, never credentials.
  * Register runs when enabling a subscription, not on every app evaluation.
  */
-interface WebhookLifecycle<Context extends Pick<BoundContext<AccountSlots>, "accounts" | "fetch" | "signal">, Config extends Schema.Decoder<unknown>, State extends Schema.Decoder<unknown>, Error = unknown> {
+interface WebhookLifecycle<Context extends HookContext, Config extends Schema.Decoder<unknown>, State extends Schema.Decoder<unknown>, Error = unknown> {
     readonly account: SourceAccount<Context>;
     readonly config: Config;
     readonly state: State;
@@ -43,7 +60,7 @@ interface WebhookLifecycle<Context extends Pick<BoundContext<AccountSlots>, "acc
     }) => Effect.Effect<void, Error>;
 }
 /** Manual subscriptions collect the state schema in a private browser form instead of invoking provider APIs. */
-export type Webhook<Context extends Pick<BoundContext<AccountSlots>, "accounts" | "fetch" | "signal">, Config extends Schema.Decoder<unknown>, State extends Schema.Decoder<unknown>, Error = unknown> = (WebhookLifecycle<Context, Config, State, Error> & {
+export type Webhook<Context extends HookContext, Config extends Schema.Decoder<unknown>, State extends Schema.Decoder<unknown>, Error = unknown> = (WebhookLifecycle<Context, Config, State, Error> & {
     readonly setup?: never;
 }) | (Omit<WebhookLifecycle<Context, Config, State, Error>, "register" | "unregister"> & {
     readonly setup: typeof ManualWebhookSetup.Type;

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

@@ -1,7 +1,10 @@
 /** Portable workflow declarations, run views and durable execution capabilities. */
+import { withLegacyKeys } from "../../../utils/src/legacy-keys.js";
 import { Schema, type Effect } from "effect";
+import { RecordedMessage } from "../../../utils/src/recorded-message.js";
 import { JsonValue } from "./schema.js";
 import type { AppContext, AppRequirements, QueryContext, MutationContext } from "./context.js";
+import type { AccountScope } from "./app.js";
 import type { Operation } from "../implementation/operations.js";
 import type { HostContext } from "./host.js";
 /** Run identity is opaque and shared by author and SDK interfaces. */
@@ -49,6 +52,11 @@ declare const WorkflowFailure_base: Schema.Class<WorkflowFailure, Schema.TaggedS
 }>, import("effect/Cause").YieldableError>;
 /** Failures cross host boundaries as reason codes plus the app's own bounded error detail. */
 export declare class WorkflowFailure extends WorkflowFailure_base {
+    /**
+     * The step name and error detail are the app's. Its run's owner reads them; telemetry records
+     * only the reason, however the failure was built or decoded.
+     */
+    get [RecordedMessage](): string | undefined;
 }
 /** Explicitly stop retrying an authored step. Its message is reported like any step error. */
 export declare class NonRetryableError extends Error {
@@ -64,25 +72,30 @@ export declare const HostedWorkflow: Schema.Struct<{
     readonly outputSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
 }>;
 export type HostedWorkflow = typeof HostedWorkflow.Type;
-/** Results are available only on completed runs; failures carry a reason code and app error detail. */
-export declare const WorkflowRun: Schema.Union<readonly [Schema.Struct<{
+/**
+ * Results are available only on completed runs; failures carry a reason code and app error detail.
+ * Runs name their version under its former name too, for apps and callers written before the rename.
+ */
+export declare const WorkflowRun: Schema.Union<readonly [withLegacyKeys<Schema.Struct<{
     readonly status: Schema.Literals<readonly ["queued", "running", "waiting", "paused", "waitingForPause"]>;
-    readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
     readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
     readonly app: Schema.NonEmptyString;
-    readonly deployment: Schema.NonEmptyString;
+    readonly version: Schema.NonEmptyString;
     readonly workflow: Schema.NonEmptyString;
     readonly createdAt: Schema.String;
-}>, Schema.Struct<{
+}>, {
+    readonly version: "deployment";
+}>, withLegacyKeys<Schema.Struct<{
     readonly status: Schema.Literal<"complete">;
     readonly output: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-    readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
     readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
     readonly app: Schema.NonEmptyString;
-    readonly deployment: Schema.NonEmptyString;
+    readonly version: Schema.NonEmptyString;
     readonly workflow: Schema.NonEmptyString;
     readonly createdAt: Schema.String;
-}>, Schema.Struct<{
+}>, {
+    readonly version: "deployment";
+}>, withLegacyKeys<Schema.Struct<{
     readonly status: Schema.Literal<"errored">;
     readonly error: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
     /** The failing step and the app's own error, when the run recorded them. */
@@ -91,42 +104,46 @@ export declare const WorkflowRun: Schema.Union<readonly [Schema.Struct<{
         errorName: Schema.optionalKey<Schema.String>;
         message: Schema.optionalKey<Schema.String>;
     }>>;
-    readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
     readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
     readonly app: Schema.NonEmptyString;
-    readonly deployment: Schema.NonEmptyString;
+    readonly version: Schema.NonEmptyString;
     readonly workflow: Schema.NonEmptyString;
     readonly createdAt: Schema.String;
-}>, Schema.Struct<{
+}>, {
+    readonly version: "deployment";
+}>, withLegacyKeys<Schema.Struct<{
     readonly status: Schema.Literal<"terminated">;
-    readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
     readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
     readonly app: Schema.NonEmptyString;
-    readonly deployment: Schema.NonEmptyString;
+    readonly version: Schema.NonEmptyString;
     readonly workflow: Schema.NonEmptyString;
     readonly createdAt: Schema.String;
+}>, {
+    readonly version: "deployment";
 }>]>;
 export type WorkflowRun = typeof WorkflowRun.Type;
 /** A bounded run-history page, already scoped to an authorized configured app. */
 export declare const WorkflowRunPage: Schema.Struct<{
-    readonly items: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Union<readonly [withLegacyKeys<Schema.Struct<{
         readonly status: Schema.Literals<readonly ["queued", "running", "waiting", "paused", "waitingForPause"]>;
-        readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
         readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
         readonly app: Schema.NonEmptyString;
-        readonly deployment: Schema.NonEmptyString;
+        readonly version: Schema.NonEmptyString;
         readonly workflow: Schema.NonEmptyString;
         readonly createdAt: Schema.String;
-    }>, Schema.Struct<{
+    }>, {
+        readonly version: "deployment";
+    }>, withLegacyKeys<Schema.Struct<{
         readonly status: Schema.Literal<"complete">;
         readonly output: Schema.Codec<Schema.Json, Schema.Json, never, never>;
-        readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
         readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
         readonly app: Schema.NonEmptyString;
-        readonly deployment: Schema.NonEmptyString;
+        readonly version: Schema.NonEmptyString;
         readonly workflow: Schema.NonEmptyString;
         readonly createdAt: Schema.String;
-    }>, Schema.Struct<{
+    }>, {
+        readonly version: "deployment";
+    }>, withLegacyKeys<Schema.Struct<{
         readonly status: Schema.Literal<"errored">;
         readonly error: Schema.Literals<readonly ["unavailable", "not_found", "input", "output", "operation", "approval", "credentials", "terminated", "execution", "conflict", "engine"]>;
         /** The failing step and the app's own error, when the run recorded them. */
@@ -135,20 +152,22 @@ export declare const WorkflowRunPage: Schema.Struct<{
             errorName: Schema.optionalKey<Schema.String>;
             message: Schema.optionalKey<Schema.String>;
         }>>;
-        readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
         readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
         readonly app: Schema.NonEmptyString;
-        readonly deployment: Schema.NonEmptyString;
+        readonly version: Schema.NonEmptyString;
         readonly workflow: Schema.NonEmptyString;
         readonly createdAt: Schema.String;
-    }>, Schema.Struct<{
+    }>, {
+        readonly version: "deployment";
+    }>, withLegacyKeys<Schema.Struct<{
         readonly status: Schema.Literal<"terminated">;
-        readonly profile: Schema.optionalKey<Schema.NonEmptyString>;
         readonly id: Schema.brand<Schema.NonEmptyString, "wfr">;
         readonly app: Schema.NonEmptyString;
-        readonly deployment: Schema.NonEmptyString;
+        readonly version: Schema.NonEmptyString;
         readonly workflow: Schema.NonEmptyString;
         readonly createdAt: Schema.String;
+    }>, {
+        readonly version: "deployment";
     }>]>>;
     readonly next: Schema.optionalKey<Schema.brand<Schema.NonEmptyString, "wfr">>;
 }>;
@@ -175,25 +194,28 @@ export interface WorkflowControls extends WorkflowReads {
         readonly run: string;
     }) => Promise<WorkflowRun>;
 }
-/** External steps get fresh credentials and cancellation, without storage or live elicitation. */
-export type WorkflowStepContext<Requirements extends AppRequirements = AppRequirements> = Omit<AppContext<Requirements>, "elicit" | "workflows"> & {
+/**
+ * External steps get fresh credentials and cancellation, without storage or live elicitation. A run
+ * started by app-scope work, such as an app schedule, has the `"app"` scope: no `user`.
+ */
+export type WorkflowStepContext<Requirements extends AppRequirements = AppRequirements, Scope extends AccountScope = "user"> = Omit<AppContext<Requirements, Scope>, "elicit" | "workflows"> & {
     readonly runId: WorkflowRunId;
     readonly stepId: string;
     readonly idempotencyKey: string;
 };
 /** Explicit durable boundaries; database access passes through registered app operations. */
-export interface WorkflowStep<Requirements extends AppRequirements = AppRequirements> {
-    do<Output>(name: string, run: (context: WorkflowStepContext<Requirements>) => Promise<Output>): Promise<Output>;
-    do<Output>(name: string, options: WorkflowStepOptions, run: (context: WorkflowStepContext<Requirements>) => Promise<Output>): Promise<Output>;
-    runQuery<Input, Output>(name: string, operation: Operation<Input, Output, "query", QueryContext<Requirements>>, input: NoInfer<Input>, options?: WorkflowStepOptions): Promise<Output>;
-    runMutation<Input, Output>(name: string, operation: Operation<Input, Output, "mutation", MutationContext<Requirements>>, input: NoInfer<Input>, options?: WorkflowStepOptions): Promise<Output>;
+export interface WorkflowStep<Requirements extends AppRequirements = AppRequirements, Scope extends AccountScope = "user"> {
+    do<Output>(name: string, run: (context: WorkflowStepContext<Requirements, Scope>) => Promise<Output>): Promise<Output>;
+    do<Output>(name: string, options: WorkflowStepOptions, run: (context: WorkflowStepContext<Requirements, Scope>) => Promise<Output>): Promise<Output>;
+    runQuery<Input, Output>(name: string, operation: Operation<Input, Output, "query", QueryContext<Requirements, Scope>>, input: NoInfer<Input>, options?: WorkflowStepOptions): Promise<Output>;
+    runMutation<Input, Output>(name: string, operation: Operation<Input, Output, "mutation", MutationContext<Requirements, Scope>>, input: NoInfer<Input>, options?: WorkflowStepOptions): Promise<Output>;
     readonly sleep: (name: string, duration: WorkflowDuration) => Promise<void>;
     readonly sleepUntil: (name: string, timestamp: number | Date) => Promise<void>;
 }
 /** The orchestration body gets no account, database or interactive capabilities. */
-export interface WorkflowContext<Requirements extends AppRequirements = AppRequirements> {
+export interface WorkflowContext<Requirements extends AppRequirements = AppRequirements, Scope extends AccountScope = "user"> {
     readonly runId: WorkflowRunId;
-    readonly step: WorkflowStep<Requirements>;
+    readonly step: WorkflowStep<Requirements, Scope>;
 }
 /** Framework-owned native declaration; only the callback crosses the author Promise boundary. */
 export interface AppWorkflow<Input = unknown, Output = unknown> {

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

@@ -1,5 +1,4 @@
-/** Native workerd SQLite capability; used only by the generated data facet, never browser bundles. */
-import * as Sqlite from "@effect/sql-sqlite-do/SqliteClient";
-import type { AppStorage } from "./contracts/storage.js";
-/** Bind one facet's raw storage at the runtime edge. Each operation owns its native SQL scope. */
-export declare const facetStorage: (storage: NonNullable<Sqlite.SqliteClientConfig["storage"]>) => AppStorage;
+/** The data facet's storage capability; used only by the generated data facet, never browser bundles. */
+import type { AppSqlStorage } from "./contracts/sql.js";
+/** Bind one facet's storage at the runtime edge. App code receives `ctx.sql` over it, never the storage. */
+export declare const facetStorage: (storage: AppSqlStorage) => AppSqlStorage;

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

@@ -6,6 +6,11 @@ export { isolatedCacheSession } from "./implementation/cache-session.js";
 export declare const hostContext: (accounts: ResolvedAccountsInput, approval?: unknown) => HostContext;
 /** Portable Promise handler. Invoke only after the host has authorized and resolved accounts. */
 export declare const createAppHandler: (app: unknown) => ((request: Request, context: HostContext) => Promise<Response>);
+/**
+ * The clock this framework's spans read, in nanoseconds. The runtime's bridge times the isolate's
+ * whole dispatch with it, so that time and the invocation's own timing share one clock.
+ */
+export declare const isolatedClock: () => bigint;
 /** Isolates return bounded, telemetry beside the protocol result; no exporter secret enters app code. */
 export declare const createIsolatedAppHandler: (app: unknown) => (request: Request, context: HostContext) => Promise<Response>;
 /**

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

@@ -3,10 +3,11 @@ import { type RouterDeclaration } from "./router.js";
  * Discover each selected account's router and combine matching names.
  * Calls take { accountId, input }; each branch retains its account's input schema,
  * credentials, approval and output validation. Empty selections expose no operations.
- * Discovery is sequential and cancellation follows the caller's signal.
+ * Discovery is sequential and cancellation follows the caller's signal. `discover` may return the
+ * router or a Promise of it, and the combined router keeps its operations' handler contexts.
  */
 export declare const accountRouter: <Account extends {
     readonly id: string;
-}>(accounts: readonly Account[], discover: (account: Account) => Promise<RouterDeclaration>, options: {
+}, Query = unknown, Mutation = unknown>(accounts: readonly Account[], discover: (account: Account) => RouterDeclaration<Query, Mutation> | Promise<RouterDeclaration<Query, Mutation>>, options: {
     readonly signal: AbortSignal;
-}) => Promise<RouterDeclaration>;
+}) => Promise<RouterDeclaration<Query, Mutation>>;

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

@@ -1,41 +1,68 @@
 import type { ScheduleDeclaration } from "./schedules.js";
-import type { App as NativeApp, AppDefinition as NativeDefinition } from "../contracts/app.js";
-import type { AppRequirements, AppContext, QueryContext, MutationContext, WebhookContext } from "../contracts/context.js";
+import type { App as NativeApp, AccountScope, AppDefinition as NativeDefinition, EvaluationContext } from "../contracts/app.js";
+import type { AppRequirements, QueryContext, MutationContext, RequirementSlots, WebhookContext } from "../contracts/context.js";
 import { type PromiseMethods } from "./authoring.js";
 import { type WorkflowDeclaration } from "./workflows.js";
 import type { WorkflowContext } from "../contracts/workflows.js";
 import { type RouterDeclaration } from "./router.js";
 import { type Schema } from "./schema.js";
-type PromiseCatalog<Catalog> = Catalog extends Readonly<Record<string, object>> ? {
-    readonly [Name in keyof Catalog]: {
-        readonly [Key in keyof Catalog[Name]]: Key extends "config" | "state" ? Schema<unknown, boolean> : PromiseMethods<Catalog[Name]>[Key];
-    };
-} : Catalog;
+/** One native webhook definition with the given handler context. */
+type NativeWebhook<Context> = NonNullable<NativeDefinition<Context>["webhooks"]>[string];
+/** A webhook as authors write it: Promise handlers, author schemas and its source requirement. */
+type AuthorWebhook<Context, Account> = {
+    readonly [Key in keyof NativeWebhook<Context>]: Key extends "config" | "state" ? Schema<unknown, boolean> : Key extends "account" ? Account : PromiseMethods<NativeWebhook<Context>>[Key];
+};
+/**
+ * A user-account webhook gets the caller-shaped context; an app-account webhook runs without a
+ * caller, so its context has no `user`.
+ */
+type AuthorWebhooks<Requirements extends AppRequirements> = Readonly<Record<string, AuthorWebhook<WebhookContext<Requirements>, {
+    readonly user: keyof RequirementSlots<Requirements>["user"] & string;
+}> | AuthorWebhook<WebhookContext<Requirements, "app">, {
+    readonly app: keyof RequirementSlots<Requirements>["app"] & string;
+}>>>;
+/**
+ * User schedules run as each member who enables them; app schedules run without a caller, so their
+ * mutation takes a context of the `"app"` scope.
+ */
+type AuthorSchedules<Requirements extends AppRequirements> = Readonly<Record<string, ScheduleDeclaration<MutationContext<Requirements>, "user"> | ScheduleDeclaration<MutationContext<Requirements, "app">, "app">>>;
+/**
+ * A run started by a caller binds its accounts; one started without a caller, such as by an app
+ * schedule, has no `user`, so its workflow declares a context of the `"app"` scope.
+ */
+type AuthorWorkflows<Requirements extends AppRequirements> = Readonly<Record<string, WorkflowDeclaration<WorkflowContext<Requirements>> | WorkflowDeclaration<WorkflowContext<Requirements, "app">>>>;
 /** Author definition projected from native capabilities. Excluding callable objects keeps
  * factories from being inferred as definitions and preserves contextual handler inference. */
 export type AppDefinition<Requirements extends AppRequirements> = {
-    readonly [Key in keyof NativeDefinition<WebhookContext<Requirements>>]: Key extends "workflows" ? Readonly<Record<string, WorkflowDeclaration<WorkflowContext<Requirements>>>> : Key extends "schedules" ? Readonly<Record<string, ScheduleDeclaration<MutationContext<Requirements>>>> : Key extends "tools" ? RouterDeclaration<QueryContext<Requirements>, MutationContext<Requirements>> : Key extends "webhooks" ? PromiseCatalog<NonNullable<NativeDefinition<WebhookContext<Requirements>>[Key]>> : NativeDefinition<WebhookContext<Requirements>>[Key];
+    readonly [Key in keyof NativeDefinition<WebhookContext<Requirements>>]: Key extends "workflows" ? AuthorWorkflows<Requirements> : Key extends "schedules" ? AuthorSchedules<Requirements> : Key extends "tools" ? RouterDeclaration<QueryContext<Requirements>, MutationContext<Requirements>> : Key extends "webhooks" ? AuthorWebhooks<Requirements> : NativeDefinition<WebhookContext<Requirements>>[Key];
 } & {
     readonly name?: never;
     readonly queries?: never;
     readonly mutations?: never;
     readonly call?: never;
 };
+/** A webhook context as the host builds it: an app-account hook's has no `user`. */
+type HostWebhookContext = WebhookContext<AppRequirements, AccountScope> & Partial<Pick<WebhookContext, "user">>;
 /** Adapt operation and webhook catalogs without evaluating their handlers. */
 export type EffectDefinition<Def> = {
-    readonly [Key in keyof Def]: Key extends "tools" ? NonNullable<NativeDefinition<unknown>["tools"]> : Key extends "workflows" ? Readonly<Record<string, import("../contracts/workflows.js").AppWorkflow>> : Key extends "schedules" ? NonNullable<NativeDefinition<unknown>["schedules"]> : Key extends "webhooks" ? NonNullable<NativeDefinition<WebhookContext>["webhooks"]> : Key extends "skills" ? NonNullable<NativeDefinition<unknown>["skills"]> : Key extends "dynamicSkills" ? NonNullable<NativeDefinition<unknown>["dynamicSkills"]> : Def[Key];
+    readonly [Key in keyof Def]: Key extends "tools" ? NonNullable<NativeDefinition<unknown>["tools"]> : Key extends "workflows" ? Readonly<Record<string, import("../contracts/workflows.js").AppWorkflow>> : Key extends "schedules" ? NonNullable<NativeDefinition<unknown>["schedules"]> : Key extends "webhooks" ? NonNullable<NativeDefinition<HostWebhookContext>["webhooks"]> : Key extends "skills" ? NonNullable<NativeDefinition<unknown>["skills"]> : Key extends "dynamicSkills" ? NonNullable<NativeDefinition<unknown>["dynamicSkills"]> : Def[Key];
 };
 declare const InternalApp: unique symbol;
 /** Recognize a declaration from this framework instance before host adaptation. */
 export declare const isApp: (value: unknown) => value is App<AppRequirements, AppDefinition<AppRequirements>>;
 /** Public app handle; the native app is retained for host use without an async round trip. */
 export interface App<Requirements extends AppRequirements, Def extends AppDefinition<Requirements>> {
-    readonly [InternalApp]: NativeApp<Requirements["accounts"], EffectDefinition<Def>>;
-    readonly accounts: Requirements["accounts"];
-    readonly evaluate: (context: AppContext<Requirements>) => Promise<Def>;
+    readonly [InternalApp]: NativeApp<RequirementSlots<Requirements>, EffectDefinition<Def>>;
+    readonly accounts: RequirementSlots<Requirements>;
+    readonly evaluate: (context: AppFactoryContext<Requirements>) => Promise<Def>;
 }
+/**
+ * What a dynamic definition's factory receives. App-scope work, such as an app schedule, evaluates
+ * the app without a caller, so `user` is absent then.
+ */
+export type AppFactoryContext<Requirements extends AppRequirements> = EvaluationContext<RequirementSlots<Requirements>>;
 /** Retrieve the same declaration for an Effect host. No evaluation or I/O occurs. */
-export declare const toEffectApp: <Requirements extends AppRequirements, Def extends AppDefinition<Requirements>>(app: App<Requirements, Def>) => NativeApp<Requirements["accounts"], EffectDefinition<Def>>;
+export declare const toEffectApp: <Requirements extends AppRequirements, Def extends AppDefinition<Requirements>>(app: App<Requirements, Def>) => NativeApp<RequirementSlots<Requirements>, EffectDefinition<Def>>;
 /** Assemble app behavior. Package names belong in package.json; hosts name installed copies. */
-export declare const defineApp: <const Requirements extends AppRequirements, Def extends AppDefinition<Requirements>>(requirements: Requirements, definition: (Def & AppDefinition<Requirements>) | ((context: AppContext<Requirements>) => Promise<Def & AppDefinition<Requirements>>)) => App<Requirements, Def>;
+export declare const defineApp: <const Requirements extends AppRequirements, Def extends AppDefinition<Requirements>>(requirements: Requirements, definition: (Def & AppDefinition<Requirements>) | ((context: AppFactoryContext<Requirements>) => Promise<Def & AppDefinition<Requirements>>)) => App<Requirements, Def>;
 export {};

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

@@ -1,12 +1,32 @@
 /** Small, explicit adapters between authored callbacks and native Effect operations. */
-import { Effect } from "effect";
+import { Effect, type Context } from "effect";
 /** Project one Effect operation into its author-facing Promise signature. */
 export type PromiseMethod<Method> = Method extends (...args: infer Args) => Effect.Effect<infer A, infer _E> ? (...args: Args) => Promise<A> : Method;
 /** Project only an object's methods; data and schema types are not recursively rewritten. */
 export type PromiseMethods<T> = {
     readonly [Key in keyof T]: PromiseMethod<T[Key]>;
 };
-/** Reuse a framework callback's cancellation-bound Effect, or adapt an ordinary async callback. */
-export declare const fromPromise: <Args extends readonly unknown[], A>(callback: (...args: Args) => Promise<A>) => ((...args: Args) => Effect.Effect<A, unknown>);
-/** Bind cancellation once so Promise callers and native framework callers run the same operation. */
-export declare const toPromise: <Args extends readonly unknown[], A, E>(operation: (...args: Args) => Effect.Effect<A, E>, signal?: AbortSignal) => ((...args: Args) => Promise<A>);
+/** Which of the app's callbacks runs, recorded on the `app.code` span around it. */
+export type AppCode = "factory" | "router" | "approval" | "handler" | "loader" | "cache" | "webhook" | "check" | "skills" | "elicitation" | "workflow" | "step";
+/**
+ * Run `effect` as the app's own code. Its time is the app's, except for work it starts for
+ * Executor, an upstream or a person, which opens its own boundary inside.
+ */
+export declare const appCode: (code: AppCode) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, import("effect/Tracer").ParentSpan>>;
+/**
+ * Reuse a framework callback's cancellation-bound Effect, or run an ordinary async callback as the
+ * app's code. Every callback an app supplies enters the framework here, so its time is the app's.
+ */
+export declare const fromPromise: <Args extends readonly unknown[], A>(callback: (...args: Args) => Promise<A>, code: AppCode) => ((...args: Args) => Effect.Effect<A, unknown>);
+/**
+ * `target[key]`, called on `target`. A method read off its object as a bare value loses its
+ * receiver, so an app's method, such as one of its cache's, enters `fromPromise` through this.
+ */
+export declare const method: <K extends PropertyKey, T extends { readonly [P in K]: (...args: never) => unknown; }>(target: T, key: K) => T[K];
+/**
+ * Bind cancellation once so Promise callers and native framework callers run the same operation.
+ * `signalOf` is the signal, or reads it from each call's arguments, such as a loader's `context.signal`.
+ */
+export declare const toPromise: <Args extends readonly unknown[], A, E>(operation: (...args: Args) => Effect.Effect<A, E>, signalOf?: AbortSignal | ((...args: Args) => AbortSignal), 
+/** Services a Promise call runs with, such as its invocation's telemetry. */
+services?: Context.Context<never>) => ((...args: Args) => Promise<A>);