apps 0.0.1-beta.89 → 0.0.1-beta.90

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

@@ -33,9 +33,15 @@ export declare const ScheduleTiming: Schema.Union<readonly [Schema.Struct<{
     }>;
 }>]>;
 export type ScheduleTiming = typeof ScheduleTiming.Type;
-/** A named trigger attached to the mutation it invokes, including schema-validated arguments. */
+/**
+ * A named trigger attached to the mutation it invokes, including schema-validated arguments.
+ * `scope: "app"` marks an app schedule: one schedule, run without a caller with the app's accounts.
+ * Without it, each member who enables the schedule has a copy that runs as them; bundles of
+ * protocol 12 and earlier declare only those.
+ */
 export declare const OperationSchedule: Schema.Struct<{
     readonly name: Schema.NonEmptyString;
+    readonly scope: Schema.optionalKey<Schema.Literal<"app">>;
     readonly timing: Schema.Union<readonly [Schema.Struct<{
         readonly kind: Schema.Literal<"interval">;
         readonly milliseconds: Schema.Int;

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

@@ -1,13 +1,15 @@
 /** Browser-to-host operations bind identity and authentication outside authored app code. */
 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. */
+/**
+ * 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 profile's accounts, from stored state. Labels are the owner's own names. */
+/** 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";
@@ -20,10 +22,8 @@ export type UiAccountProblem = {
 export interface UiAccountNotice {
     readonly app: string;
     readonly problems: readonly UiAccountProblem[];
-    /** The profile's accounts in the dashboard. */
+    /** The app's accounts in the dashboard. */
     readonly fix: string;
-    /** The dashboard chooser, returning to this page. */
-    readonly choose: string;
 }
 /** Retained browser bytes. Hosts authorize access before reading or rendering them. */
 export interface AppUiFile {
@@ -51,8 +51,7 @@ 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. */
@@ -88,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

@@ -3,6 +3,7 @@ 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. */
@@ -73,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;
@@ -82,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;
@@ -97,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;
@@ -105,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;
@@ -117,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;
@@ -126,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;
@@ -141,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;
@@ -149,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;
@@ -181,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/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/cache.d.ts

@@ -1,7 +1,7 @@
 /** 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 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

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

@@ -50,8 +50,13 @@ export interface EventEmitter<Events extends Readonly<Record<string, AnyEventDec
 /** One invocation's buffer. The handler reads `emitted` only after the invocation succeeds. */
 export declare const makeEmitter: (input: {
     readonly events: Readonly<Record<string, AppEvent>>;
-    /** Every account ID bound to this invocation. */
+    /** Every account ID bound to this invocation, which an emit may name. */
     readonly accounts: readonly string[];
+    /**
+     * The caller's account IDs. An emit that names no account is attributed to the only one, if
+     * there is exactly one. App accounts never count: they are bound to every call.
+     */
+    readonly attributable: readonly string[];
     /** The webhook's source account, which an emit names by default. */
     readonly sourceAccount?: string;
     readonly emitted: EmittedEvent[];

package/types/apps/src/implementation/failure-detail.d.ts

@@ -11,8 +11,9 @@ export interface FailureDetail {
     readonly fields?: FailureFields;
 }
 /**
- * Every credential field value of a slot-to-account record, longest first. Accepts both resolved
- * host accounts and bound author accounts; each account keeps its credential values in `fields`.
+ * Every credential field value of an invocation's accounts by scope, longest first. The accounts
+ * may not have been checked yet, so each scope is read only when it is a slot-to-account record;
+ * each account keeps its credential values in `fields`.
  */
 export declare const accountFieldSecrets: (accounts: unknown) => string[];
 /** Every credential field value of an invocation's selected accounts. */

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

@@ -1,12 +1,27 @@
 /** Pure operation declarations. Only the author callback crosses the Promise boundary. */
 import { Schema as EffectSchema } from "effect";
 import type { AppOperation } from "../contracts/operations.js";
-import type { AppContext, QueryContext, MutationContext } from "../contracts/context.js";
+import type { AppContext, AppRequirements, AnyScopeMutationContext, MutationContext, QueryContext } from "../contracts/context.js";
+import type { AccountScope } from "../contracts/app.js";
 import type { Approval } from "../approval.js";
 import type { ToolAnnotations } from "../contracts/tools.js";
 import type { JsonObject } from "../contracts/schema.js";
 import { type Schema } from "./schema.js";
 declare const NativeOperation: unique symbol;
+declare const ApprovalDeclared: unique symbol;
+/**
+ * Marks an operation declared with an approval. App-scope work, such as an app schedule, has no
+ * person to approve a call, so it accepts only operations without this mark.
+ */
+export interface Approved {
+    readonly [ApprovalDeclared]: true;
+}
+/** An operation declared without an approval. */
+export interface WithoutApproval {
+    readonly [ApprovalDeclared]?: never;
+}
+/** The context any handler may declare: either scope, so `user` may be absent. */
+export type AnyContext = AppContext<AppRequirements, AccountScope>;
 declare const QueryHandlerContext: unique symbol;
 declare const MutationHandlerContext: unique symbol;
 /**
@@ -90,14 +105,34 @@ export declare const operationOptions: <Input, Output>(options: OperationOptions
  */
 export declare const approvedOperation: <Input, Native extends AppOperation<Input, unknown>>(operation: Native, approval: Approval<Input>) => Native;
 /** Attach the same approval function to a generated or shared operation. */
-export declare const withApproval: <Input, Output, Kind extends "query" | "mutation", Context>(operation: Operation<Input, Output, Kind, Context>, approval: Approval<Input>) => Operation<Input, Output, Kind, Context>;
+export declare const withApproval: <Input, Output, Kind extends "query" | "mutation", Context>(operation: Operation<Input, Output, Kind, Context>, approval: Approval<Input>) => Operation<Input, Output, Kind, Context> & Approved;
 /**
  * The advisory hints an operation carries, such as an MCP server's `destructiveHint`. App code
  * reads them to choose an approval; the framework never infers one from them.
  */
 export declare const toolAnnotations: (operation: OperationDeclaration<"query" | "mutation", never>) => ToolAnnotations | undefined;
 /** Read operation. External reads are allowed; only database writes are mechanically prohibited. */
-export declare const query: <Input, Output, Context extends AppContext = QueryContext>(options: OperationOptions<Input, Output>, run: (context: Context, input: Input) => Promise<Output>) => Operation<Input, Output, "query", Context>;
-/** Explicit write operation. Database writes roll back on failure; external effects cannot be undone. */
-export declare const mutation: <Input, Output, Context extends AppContext = MutationContext>(options: OperationOptions<Input, Output>, run: (context: Context, input: Input) => Promise<Output>) => Operation<Input, Output, "mutation", Context>;
+export declare const query: <Input, Output, Context extends AnyContext = QueryContext>(options: OperationOptions<Input, Output>, run: (context: Context, input: Input) => Promise<Output>) => Operation<Input, Output, "query", Context>;
+/** The parameters a mutation's handler declares: its context and input, its context, or none. */
+type HandlerParameters<Context, Input> = [context: Context, input: Input] | [context: Context] | [];
+/** The context a handler declares; one without parameters may run in either scope. */
+type DeclaredContext<Signature, Context> = Signature extends [] ? AnyScopeMutationContext : Signature extends readonly [infer Declared, ...unknown[]] ? Declared : Context;
+/**
+ * Explicit write operation. Database writes roll back on failure; external effects cannot be undone.
+ * A handler that declares a context gets the caller's, with `user`, unless its type says otherwise.
+ * One that declares no parameters, in a call without explicit type arguments, uses no context, so
+ * it may run as the app, as an app schedule runs it. Explicit type arguments name the context with
+ * the third, which defaults to the caller's. One declared with an approval is marked `Approved`, so
+ * app-scope schedules refuse it.
+ */
+export declare function mutation<Input, Output, Context extends AnyContext = MutationContext>(options: OperationOptions<Input, Output> & {
+    readonly approval: Approval<Input>;
+}, run: (context: Context, input: Input) => Promise<Output>): Operation<Input, Output, "mutation", Context> & Approved;
+export declare function mutation<Input, Output, Context extends AnyContext = MutationContext, Signature extends HandlerParameters<Context, Input> = [context: Context, input: Input]>(options: OperationOptions<Input, Output> & {
+    readonly approval?: undefined;
+}, run: (...parameters: Signature) => Promise<Output>): Operation<Input, Output, "mutation", DeclaredContext<Signature, Context>>;
+/** A handler whose context's type the caller's does not fit, such as one of the `"app"` scope. */
+export declare function mutation<Input, Output, Context extends AnyContext>(options: OperationOptions<Input, Output> & {
+    readonly approval?: undefined;
+}, run: (context: Context, input: Input) => Promise<Output>): Operation<Input, Output, "mutation", Context>;
 export {};

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

@@ -51,6 +51,7 @@ export declare const operationSummary: (name: string, router: string, operation:
             };
         };
         readonly input: Schema.Json;
+        readonly scope?: "app";
     }[];
     readonly readOnly?: boolean;
     readonly tags?: readonly string[];
@@ -90,6 +91,7 @@ export declare const operationDescription: (name: string, router: string, operat
             };
         };
         readonly input: Schema.Json;
+        readonly scope?: "app";
     }[];
     readonly readOnly?: boolean;
     readonly tags?: readonly string[];
@@ -153,6 +155,7 @@ export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined,
                 };
             };
             readonly input: Schema.Json;
+            readonly scope?: "app";
         }[];
         readonly readOnly?: boolean;
         readonly tags?: readonly string[];
@@ -181,6 +184,7 @@ export declare const readCatalog: (root: AppRouter | DynamicRouter | undefined,
                 };
             };
             readonly input: Schema.Json;
+            readonly scope?: "app";
         }[];
         readonly readOnly?: boolean;
         readonly tags?: readonly string[];

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/ui-serving.d.ts

@@ -7,8 +7,8 @@ import { UiFailed, UiForbidden, type AppUiAsset, type AppUiRange, type AppUiStor
  */
 export declare const appDocument: <E, R>(options: {
     readonly deployment: string;
-    readonly profile?: string | undefined;
-    readonly expectedProfileRevision?: number | undefined;
+    /** The account IDs the page runs with, by requirement. */
+    readonly accountIds?: Readonly<Record<string, readonly string[]>> | undefined;
     readonly origin: string;
     readonly accounts?: UiAccountNotice | undefined;
     readonly asset: (path: string) => Effect.Effect<AppUiAsset | undefined, E, R>;

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

@@ -1,13 +1,21 @@
 /** Native webhook dispatch. The author verifies signatures before parsing or performing side effects. */
 import { Effect, Schema } from "effect";
-import type { AppDefinition } from "../contracts/app.js";
-import { HostDeclarationInvalid, HostInputInvalid, HostOperationFailed, HostOperationNotFound, HostOutputInvalid, type ResolvedAccounts } from "../contracts/host.js";
+import type { AppDefinition, ScopedSlots } from "../contracts/app.js";
+import { HostDeclarationInvalid, HostInputInvalid, HostOperationFailed, HostOperationNotFound, HostAccountsInvalid, HostOutputInvalid } from "../contracts/host.js";
 import { type WebhookCommand } from "../contracts/webhook-protocol.js";
-/** Run one hook with freshly bound context. No credentials or raw failures enter the response envelope. */
+type ScopeAccounts = {
+    readonly accounts: Readonly<Record<string, unknown>>;
+};
+/**
+ * Run one hook with freshly bound context. No credentials or raw failures enter the response
+ * envelope. An app-account hook runs without a caller: its context has no `user`, whatever the
+ * invocation bound.
+ */
 export declare const dispatchWebhook: <Context extends {
     readonly signal?: AbortSignal;
-    readonly accounts: Readonly<Record<string, unknown>>;
-}>(definition: AppDefinition<Context>, command: WebhookCommand, context: Context, accounts: ResolvedAccounts) => Effect.Effect<Schema.Json | {
+    readonly app: ScopeAccounts;
+    readonly user?: ScopeAccounts;
+}>(definition: AppDefinition<Context>, command: WebhookCommand, context: Context, slots: ScopedSlots) => Effect.Effect<Schema.Json | {
     readonly name: string;
     readonly account: string;
     readonly configSchema: {
@@ -26,4 +34,5 @@ export declare const dispatchWebhook: <Context extends {
         readonly [x: string]: string;
     };
     readonly body: string;
-}, HostDeclarationInvalid | HostOperationNotFound | HostOperationFailed | HostInputInvalid | HostOutputInvalid, never>;
+}, HostDeclarationInvalid | HostAccountsInvalid | HostOperationNotFound | HostOperationFailed | HostInputInvalid | HostOutputInvalid, never>;
+export {};

package/types/apps/src/implementation/workflow-context.d.ts

@@ -1,7 +1,10 @@
 /** Author-facing step methods delegate persistence to the host's durable engine. */
 import { Effect } from "effect";
-import type { AppDefinition } from "../contracts/app.js";
-import { WorkflowFailure, type WorkflowContext, type WorkflowExecution, type WorkflowStepContext } from "../contracts/workflows.js";
+import type { AccountScope, AppDefinition } from "../contracts/app.js";
+import type { AppRequirements } from "../contracts/context.js";
+import { WorkflowFailure, type WorkflowContext, type WorkflowExecution, type WorkflowStepContext as AuthorStepContext } from "../contracts/workflows.js";
+/** A step's context as the host builds it: a run without a caller has no `user`. */
+type WorkflowStepContext = AuthorStepContext<AppRequirements, AccountScope> & Partial<Pick<AuthorStepContext, "user">>;
 /**
  * Preserve typed failures and cancellation. Other errors keep their name and bounded message,
  * with the given account secrets replaced.
@@ -14,3 +17,4 @@ fresh: (stepId: string, signal: AbortSignal) => Effect.Effect<{
     readonly context: WorkflowStepContext;
     readonly secrets: readonly string[];
 }, WorkflowFailure>, signal: AbortSignal) => Effect.Effect<WorkflowContext>;
+export {};