apps 0.0.1-beta.9 → 0.0.1-beta.91

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,57 @@
 /** 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. */
+import { Schema, type Effect, type Stream } from "effect";
+import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api";
+/**
+ * Non-secret page context injected by the serving host. `accounts` names the account IDs the page
+ * runs with, by requirement, when the app has requirements.
+ */
 export declare const UiContext: Schema.Struct<{
     readonly deployment: Schema.NonEmptyString;
-    readonly profile: Schema.optional<Schema.NonEmptyString>;
-    readonly expectedProfileRevision: Schema.optional<Schema.Int>;
+    readonly accounts: Schema.optional<Schema.$Record<Schema.NonEmptyString, Schema.$Array<Schema.NonEmptyString>>>;
 }>;
+/** 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;
 }
+/** One byte range of a stored file, already within its size. */
+export interface AppUiRange {
+    readonly offset: number;
+    readonly length: number;
+}
+/**
+ * A public file the deployment'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 deployment, never another app or account. */
 export declare const UiOperation: Schema.Struct<{
     readonly name: Schema.NonEmptyString;
     readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
     readonly deployment: Schema.NonEmptyString;
-    readonly profile: Schema.optional<Schema.NonEmptyString>;
-    readonly expectedProfileRevision: Schema.optional<Schema.Int>;
+    readonly accounts: Schema.optional<Schema.$Record<Schema.NonEmptyString, Schema.$Array<Schema.NonEmptyString>>>;
 }>;
 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. */
@@ -54,20 +87,17 @@ export declare const AppUiApi: HttpApi.HttpApi<"app-ui", HttpApiGroup.HttpApiGro
     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 accounts: Schema.optional<Schema.$Record<Schema.NonEmptyString, Schema.$Array<Schema.NonEmptyString>>>;
 }>>, never, Schema.toCodecJson<Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.toCodecJson<typeof UiUnauthorized | typeof UiForbidden | typeof UiDeploymentChanged | typeof UiFailed>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"mutate", "POST", "/_executor/api/mutate", never, never, Schema.toCodecJson<Schema.Struct<{
     readonly name: Schema.NonEmptyString;
     readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
     readonly deployment: Schema.NonEmptyString;
-    readonly profile: Schema.optional<Schema.NonEmptyString>;
-    readonly expectedProfileRevision: Schema.optional<Schema.Int>;
+    readonly accounts: Schema.optional<Schema.$Record<Schema.NonEmptyString, Schema.$Array<Schema.NonEmptyString>>>;
 }>>, never, Schema.toCodecJson<Schema.Codec<Schema.Json, Schema.Json, never, never>>, Schema.toCodecJson<typeof UiUnauthorized | typeof UiForbidden | typeof UiDeploymentChanged | typeof UiFailed>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"subscribe", "POST", "/_executor/api/subscribe", never, never, Schema.toCodecJson<Schema.Struct<{
     readonly name: Schema.NonEmptyString;
     readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
     readonly deployment: Schema.NonEmptyString;
-    readonly profile: Schema.optional<Schema.NonEmptyString>;
-    readonly expectedProfileRevision: Schema.optional<Schema.Int>;
+    readonly accounts: Schema.optional<Schema.$Record<Schema.NonEmptyString, Schema.$Array<Schema.NonEmptyString>>>;
 }>>, 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>;

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,9 @@
 /** Portable workflow declarations, run views and durable execution capabilities. */
 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 +51,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 {
@@ -67,7 +74,6 @@ 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<{
     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;
@@ -76,7 +82,6 @@ export declare const WorkflowRun: Schema.Union<readonly [Schema.Struct<{
 }>, 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;
@@ -91,7 +96,6 @@ 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;
@@ -99,7 +103,6 @@ export declare const WorkflowRun: Schema.Union<readonly [Schema.Struct<{
     readonly createdAt: Schema.String;
 }>, 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;
@@ -111,7 +114,6 @@ export type WorkflowRun = typeof WorkflowRun.Type;
 export declare const WorkflowRunPage: Schema.Struct<{
     readonly items: Schema.$Array<Schema.Union<readonly [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;
@@ -120,7 +122,6 @@ export declare const WorkflowRunPage: Schema.Struct<{
     }>, 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;
@@ -135,7 +136,6 @@ 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;
@@ -143,7 +143,6 @@ export declare const WorkflowRunPage: Schema.Struct<{
         readonly createdAt: Schema.String;
     }>, 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;
@@ -175,25 +174,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>);

package/types/apps/src/implementation/browser-scripts.gen.d.ts

@@ -0,0 +1,6 @@
+/** Compiled from src/browser/app-watch.ts. */
+export declare const appWatchSource = "\"use strict\";(()=>{var s=()=>{let i=document.getElementById(\"executor-context\")?.textContent;if(!i)return;let n=JSON.parse(i);if(typeof n!=\"object\"||n===null||!(\"deployment\"in n))return;let r=n.deployment;if(typeof r!=\"string\"||r.length===0)return;let t=new EventSource(\"/_executor/version\"),l=!1,o=()=>{l||(l=!0,t.close(),location.reload())};t.addEventListener(\"version\",d=>{let e=JSON.parse(d.data);typeof e==\"object\"&&e!==null&&\"deployment\"in e&&(e.deployment===null||typeof e.deployment==\"string\")&&e.deployment!==r&&o()}),t.addEventListener(\"revoked\",o),window.addEventListener(\"executor:deployment-changed\",o),window.addEventListener(\"pagehide\",()=>t.close(),{once:!0}),window.addEventListener(\"pageshow\",d=>{d.persisted&&o()})};s();})();";
+/** Compiled from src/browser/app-failure.ts. */
+export declare const appFailureSource = "\"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();})();";
+/** Compiled from src/browser/account-notice.ts. */
+export declare const accountNoticeSource = "\"use strict\";(()=>{var g=()=>{let r=document.getElementById(\"executor-account-notice\")?.textContent;if(!r)return;let t=JSON.parse(r);if(typeof t!=\"object\"||t===null||!(\"items\"in t)||!(\"fix\"in t))return;let c=t.items,s=t.fix;if(!Array.isArray(c)||typeof s!=\"string\")return;let a=()=>{let i=document.createElement(\"div\"),x=i.attachShadow({mode:\"open\"}),d=document.createElement(\"style\");d.textContent=\"aside{position:fixed;right:16px;bottom:16px;z-index:2147483647;max-width:360px;box-sizing:border-box;padding:14px 16px;border-radius:10px;border:1px solid #fcd34d;background:#fffbeb;color:#451a03;font:14px/1.45 ui-sans-serif,system-ui,sans-serif;box-shadow:0 8px 24px rgb(0 0 0/.12)}strong{display:block;margin-bottom:4px}ul{margin:0 0 10px;padding-left:18px}div{display:flex;gap:12px;align-items:center}a{color:inherit;font-weight:600}button{margin-left:auto;font:inherit;background:none;border:0;padding:0;color:inherit;text-decoration:underline;cursor:pointer}\";let e=document.createElement(\"aside\");e.setAttribute(\"role\",\"status\"),e.setAttribute(\"aria-label\",\"Account warning\");let l=document.createElement(\"strong\");l.textContent=\"Some things might not work\";let m=document.createElement(\"ul\");for(let f of c){let p=document.createElement(\"li\");p.textContent=String(f),m.append(p)}let u=document.createElement(\"div\"),n=document.createElement(\"a\");n.href=s,n.target=\"_top\",n.textContent=\"Review accounts\";let o=document.createElement(\"button\");o.type=\"button\",o.textContent=\"Dismiss\",o.addEventListener(\"click\",()=>i.remove()),u.append(n,o),e.append(l,m,u),x.append(d,e),document.documentElement.append(i)};document.readyState===\"loading\"?document.addEventListener(\"DOMContentLoaded\",a,{once:!0}):a()};g();})();";

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

@@ -1,8 +1,35 @@
-import type { AppCache, HostCache } from "../contracts/cache.js";
-import type { ResolvedAccounts } from "../contracts/host.js";
+/** Bind the portable Effect cache to an app invocation's author API. */
+import { type Context } from "effect";
+import type { AppCache, CacheGetOptions, HostCache } from "../contracts/cache.js";
+import { type ResolvedAccounts } from "../contracts/host.js";
+import type { JsonValue } from "../contracts/schema.js";
+/**
+ * Framework-only: `get` that also reads other keys of the same scope in its round trip to the
+ * store. Authored code never sees it; framework helpers use it when a cache provides it.
+ */
+export declare const getWithReads: unique symbol;
+/**
+ * A `get` value, the store key it was read under, and the stored values of the other keys when
+ * the value was read from the store. The values are not decoded: the caller decodes only those it
+ * uses. A key with no value reads `undefined`.
+ */
+export interface GetWithReads<A> {
+    readonly value: A;
+    /** The entry's store key, unique to the cache's scope and the key. */
+    readonly key: string;
+    /** Undefined when the value was loaded or the store did not read them: read them separately. */
+    readonly reads: readonly unknown[] | undefined;
+}
+/** The framework-only `get` an app's cache provides beside the author API. */
+export type CacheWithReads = AppCache & {
+    /** `keys` gets the entry's store key and names the other keys to read with it. */
+    readonly [getWithReads]?: <A>(options: CacheGetOptions<A>, keys: (key: string) => readonly JsonValue[]) => Promise<GetWithReads<A>>;
+};
 /** Missing host support is explicit on use; ordinary apps do not need cache support. */
 export declare const unavailableCache: HostCache;
 /** Account scopes are derived from trusted current bindings. Loaders get a fresh owned HTTP signal. */
 export declare const authorCache: (host: HostCache, accounts: ResolvedAccounts, signal: AbortSignal, 
+/** The invocation's telemetry, which Promise calls from authored code run in. */
+telemetry: Context.Context<never>, 
 /** The invocation's trusted deadline. Waiting on another caller's load never runs past it. */
 deadline?: number) => AppCache;