@fabrika/app 0.5.5 → 0.7.0

package/src/contract/compile.ts

@@ -2,7 +2,8 @@
 // `buildArtifact`. A reader of source produces the same declaration and calls `buildArtifact` itself.
 
 import type { ContractArtifact, SchemaShape, TablePolicyArtifact } from '@fabrika/auth-core'
-import { inboxColumns, isTables, tablePolicies, type Tables } from '@fabrika/db/tables'
+import { isTables, tablePolicies, type Tables } from '@fabrika/db/tables'
+import { z } from 'zod/v4'
 import { attachmentOf } from './attachment'
 import { buildArtifact } from './build'
 import {
@@ -13,24 +14,25 @@ import {
 	type MountDeclaration,
 	type ProcedureDeclaration,
 	type ProcedureTreeDeclaration,
+	type RedirectDeclaration,
 	SURFACE_SECTIONS,
 	type SurfaceSection,
 } from './declaration'
 import type { AnyContract, AnyMount, Schema, Surface } from './define'
 import { Problems } from './problems'
+import { redirectOf } from './redirect'
 import { describeSchema } from './schema-shape'
 
 /**
  * The normalized artifact of a contract and its table policies: what `defineTables` returned (`src/db/tables.ts`),
- * or the artifact form of each policy. Only the first knows each inbox's columns, so only it checks a form's fields
- * against them; `boot` checks them against the data layer either way.
+ * or the artifact form of each policy.
  */
 export function compileContract<DB, P>(
 	contract: AnyContract,
 	tables: Tables<DB, P> | Readonly<Record<string, TablePolicyArtifact>>,
 ): ContractArtifact {
 	const described = describeContract(contract)
-	return isTables(tables) ? buildArtifact(described, tablePolicies(tables), inboxColumns(tables)) : buildArtifact(described, tables)
+	return buildArtifact(described, isTables(tables) ? tablePolicies(tables) : tables)
 }
 
 /** The contract with its schemas read as shapes; throws `ContractError` for a schema outside the subset. */
@@ -46,13 +48,21 @@ export function describeContract(contract: AnyContract): ContractDeclaration<Sch
 		if (isMount(entry)) {
 			mounts[name] = reader.mount(name, entry)
 		} else {
-			problems.add(`mount '${name}'`, 'is not a mount (allowed: c.rpc, c.link, c.spa, c.health, c.form or c.webhook)')
+			problems.add(`mount '${name}'`, 'is not a mount (allowed: c.rpc, c.link, c.spa, c.health or app.webhook)')
 		}
 	}
 	const exports: Record<string, ExportDeclaration<SchemaShape>> = {}
 	for (const [name, declaration] of Object.entries(surface.exports ?? {})) {
 		exports[name] = { ...declaration, procedures: reader.tree(`export '${name}'`, declaration.procedures) }
 	}
+	const tokens = surface.tokens === undefined
+		? undefined
+		: Object.fromEntries(
+			Object.entries(surface.tokens).map(([purpose, declared]) => [purpose, {
+				claims: reader.schema(`token '${purpose}' claims`, declared.claims),
+				maxDays: declared.maxDays,
+			}]),
+		)
 	problems.throwIfAny()
 	return {
 		app: vocabulary.app,
@@ -65,6 +75,7 @@ export function describeContract(contract: AnyContract): ContractDeclaration<Sch
 		exports,
 		imports: surface.imports ?? {},
 		csp: surface.csp ?? {},
+		...(tokens === undefined ? {} : { tokens }),
 		...(vocabulary.locale === undefined ? {} : { locale: vocabulary.locale }),
 		...(vocabulary.displayName === undefined ? {} : { displayName: vocabulary.displayName }),
 		...(vocabulary.mail === undefined ? {} : { mail: vocabulary.mail }),
@@ -79,7 +90,7 @@ function isSection(name: string): name is SurfaceSection {
 	return SECTIONS.has(name)
 }
 
-const MOUNT_KINDS: ReadonlySet<string> = new Set(['rpc', 'link', 'spa', 'health', 'form', 'webhook'])
+const MOUNT_KINDS: ReadonlySet<string> = new Set(['rpc', 'link', 'spa', 'health', 'webhook'])
 
 function isMount(entry: Surface[string]): entry is AnyMount {
 	return typeof entry === 'object' && 'kind' in entry && typeof entry.kind === 'string' && MOUNT_KINDS.has(entry.kind)
@@ -99,8 +110,6 @@ class SchemaReader {
 				return { ...mount, procedures: this.tree(where, mount.procedures) }
 			case 'link':
 				return { ...mount, procedures: this.tree(where, mount.procedures) }
-			case 'form':
-				return { ...mount, input: this.schema(`${where} input`, mount.input) }
 			case 'webhook':
 				return { ...mount, input: this.schema(`${where} input`, mount.input) }
 			default:
@@ -118,6 +127,7 @@ class SchemaReader {
 					...node,
 					input: node.input === null ? null : this.schema(`${at} input`, node.input),
 					...this.output(`${at} output`, node.output),
+					...(node.http === undefined ? {} : { http: this.http(`${at} http.query`, node.http) }),
 				}
 			} else {
 				described[name] = this.tree(where, node, path)
@@ -126,8 +136,27 @@ class SchemaReader {
 		return described
 	}
 
-	/** An `attachment()` output is described as the rows' array, its declaration carried beside it. */
-	output(where: string, schema: Schema): { readonly output: SchemaShape; readonly attachment?: AttachmentDeclaration } {
+	/** `http` as written, its `query` schema described; `buildArtifact` checks the rest. */
+	http(where: string, http: unknown): unknown {
+		if (typeof http !== 'object' || http === null) {
+			return http
+		}
+		const query: unknown = Reflect.get(http, 'query')
+		return isSchema(query) ? { ...http, query: this.schema(where, query) } : http
+	}
+
+	/**
+	 * An `attachment()` output is described as the rows' array, its declaration carried beside it; a `redirect()` as its
+	 * `{ to }` schema, its origins beside it.
+	 */
+	output(
+		where: string,
+		schema: Schema,
+	): { readonly output: SchemaShape; readonly attachment?: AttachmentDeclaration; readonly redirect?: RedirectDeclaration } {
+		const target = redirectOf(schema)
+		if (target !== null) {
+			return { output: this.schema(where, schema), redirect: { origins: [...target.origins] } }
+		}
 		const mark = attachmentOf(schema)
 		if (mark === null) {
 			return { output: this.schema(where, schema) }
@@ -141,3 +170,8 @@ class SchemaReader {
 		return describeSchema(schema, where, this.#problems) ?? { type: 'null' }
 	}
 }
+
+/** Whether `value` is a zod schema: what a contract writes where a schema stands. */
+function isSchema(value: unknown): value is Schema {
+	return value instanceof z.ZodType
+}

package/src/contract/connect.ts

@@ -3,13 +3,16 @@
 // Browser-safe: the snapshot is imported by the contract, which the SPA imports.
 
 import {
+	canonicalAdmission,
 	canonicalJson,
+	canonicalOutput,
 	canonicalShape,
 	type ContractArtifact,
+	type EndpointRow,
 	type ExportDescription,
 	exportDigest,
 	type ExportProcedureDescription,
-	isAttachmentShape,
+	isSchemaOutput,
 	type SchemaShape,
 } from '@fabrika/auth-core'
 import { z } from 'zod/v4'
@@ -49,10 +52,8 @@ export function exportDescription(artifact: ContractArtifact, name: string): Exp
 	const prefix = `${exportBase(name, declaration.version)}.`
 	const procedures: Record<string, ExportProcedureDescription> = {}
 	for (const row of artifact.endpoints) {
-		// The build refuses an attachment on an export, so an export row's output is a schema.
-		if (
-			row.source.kind === 'export' && row.source.name === name && row.id.startsWith(prefix) && row.output !== null && !isAttachmentShape(row.output)
-		) {
+		// The build refuses an attachment and a redirect on an export, so an export row's output is a schema.
+		if (row.source.kind === 'export' && row.source.name === name && row.id.startsWith(prefix) && row.output !== null && isSchemaOutput(row.output)) {
 			procedures[row.id.slice(prefix.length)] = { input: row.input, output: row.output }
 		}
 	}
@@ -147,6 +148,71 @@ export function incompatibleChanges(before: ExportDescription, after: ExportDesc
 	return problems
 }
 
+/**
+ * What `after` breaks for the callers of each mount `before` promises `compatibility: 'backward'`: a procedure it
+ * removes, an input or a query that accepts less, another output, another HTTP shape (method, path, body codec), file
+ * answer or access (its kind, callers, requirement and cross-origin form), or a mount moved. The promise binds the
+ * publication that drops it too, so a breaking change is a new mount beside the old one. Empty when compatible.
+ */
+export function incompatibleMountChanges(before: ContractArtifact, after: ContractArtifact): string[] {
+	const problems: string[] = []
+	for (const [name, mount] of Object.entries(before.mounts)) {
+		if (mount.kind !== 'rpc' || mount.compatibility !== 'backward') {
+			continue
+		}
+		const now = Object.hasOwn(after.mounts, name) ? after.mounts[name] : undefined
+		if (now?.kind !== 'rpc' || now.prefix !== mount.prefix) {
+			problems.push(`mount '${name}' promises backward compatibility, and this deploy removes or moves it`)
+			continue
+		}
+		for (const row of before.endpoints.filter((endpoint) => isMountProcedure(endpoint, name))) {
+			const next = after.endpoints.find((candidate) => candidate.id === row.id)
+			if (next === undefined || !isMountProcedure(next, name)) {
+				problems.push(`removes '${row.id}'`)
+				continue
+			}
+			problems.push(...procedureBreaks(row, next, before.procedures?.[row.id]?.query, after.procedures?.[row.id]?.query))
+		}
+	}
+	return problems
+}
+
+function isMountProcedure(row: EndpointRow, mount: string): boolean {
+	return row.source.kind === 'mount' && row.source.name === mount && (row.kind === 'query' || row.kind === 'mutation' || row.kind === 'public')
+}
+
+function procedureBreaks(
+	before: EndpointRow,
+	after: EndpointRow,
+	queryBefore: SchemaShape | undefined,
+	queryAfter: SchemaShape | undefined,
+): string[] {
+	const id = before.id
+	const breaks: string[] = []
+	if (!acceptsEveryInput(before.input, after.input) || !acceptsEveryInput(queryBefore ?? null, queryAfter ?? null)) {
+		breaks.push(`'${id}' accepts less input than before`)
+	}
+	if (
+		canonicalJson(before.output === null ? null : canonicalOutput(before.output))
+			!== canonicalJson(after.output === null ? null : canonicalOutput(after.output))
+	) {
+		breaks.push(`'${id}' answers another output than before`)
+	}
+	const admission = (row: EndpointRow) => (row.admission === null ? null : canonicalAdmission(row.admission).contentTypes)
+	if (before.method !== after.method || before.path !== after.path || canonicalJson(admission(before)) !== canonicalJson(admission(after))) {
+		breaks.push(`'${id}' changes its HTTP shape`)
+	}
+	if (before.response !== after.response) {
+		breaks.push(`'${id}' changes its file answer`)
+	}
+	const access = (row: EndpointRow) =>
+		canonicalJson({ kind: row.kind, callers: [...row.callers].sort(), requirement: row.requirement, crossOrigin: row.crossOrigin ?? null })
+	if (access(before) !== access(after)) {
+		breaks.push(`'${id}' changes its access`)
+	}
+	return breaks
+}
+
 function acceptsEveryInput(before: SchemaShape | null, after: SchemaShape | null): boolean {
 	if (before === null || after === null) {
 		return before === after

package/src/contract/context.ts

@@ -3,12 +3,15 @@
 // so a group in any module types itself without importing `fabrika.contract.ts`.
 
 import type { JobMailer, RpcCaller } from '@fabrika/auth-core'
+import type { RowRef } from '@fabrika/db/capability'
 import type {
 	AnyDbIndex,
 	ApplicationTables,
+	ClaimedRowHandle,
 	DataKind,
 	FragmentTable,
 	NoUnscoped,
+	PublicApplicationTables,
 	ReferenceTables,
 	ScopedApplicationTables,
 	ScopeTarget,
@@ -18,16 +21,18 @@ import type {
 	WithinTables,
 } from '@fabrika/db/tables'
 import type { z } from 'zod/v4'
-import type { FileCollectionHandle, FileCollectionJobHandle, FileCollectionReadHandle, FileCollections } from '../files/handle'
+import type { StoredFilesHandle, StoredFilesReadHandle } from '../files/handle'
 import type { AppCapability, Ref, Within } from '../implement/capability'
 import type { ApplicationDirectory, LinkIssuing, MemberDirectory, MemberLookup, MemberManagement } from '../implement/membership'
-import type { AppPrincipal, PrincipalOf, ServicePrincipal } from '../implement/principal'
-import type { ConnectCall, RequestContext } from '../implement/types'
+import type { AppPrincipal, PrincipalOf, PublicPrincipal, ServicePrincipal } from '../implement/principal'
+import type { CapabilityOf, ConnectCall, RequestContext } from '../implement/types'
 import type { WebhookDelivery, WebhookPrincipal } from '../implement/webhook'
 import type { AppMail, JobContext } from '../jobs/types'
 import type { ConnectSnapshot } from './connect'
 import type { MemberAccess, Schema } from './define'
 import type { App } from './kit'
+import type { TokenPurposes, TokenSigning } from './token'
+import type { WebhookBindings } from './webhook-binding'
 
 export type { Unavailable } from '@fabrika/db/tables'
 
@@ -55,6 +60,8 @@ export interface KitTypes {
 	/** The table names of `src/db/tables.ts`. */
 	readonly tables: string
 	readonly imports: KitImports
+	/** The token purposes of `defineApp`'s options, by purpose. */
+	readonly tokens: TokenPurposes
 }
 
 /**
@@ -134,17 +141,13 @@ type SqlContext<S, Ix extends AnyDbIndex> = {
 		: SqlTag<Ix, S & SqlMode>
 }
 
-/** `ctx.files(<collection>)`: removal where the site writes (a mutation, a job's transaction), reading everywhere. */
+/** `ctx.files.put` and `.open` of the stored files: a put everywhere but in a query. */
 type FilesContext<Ix, K extends DataKind | 'transaction'> = {
-	readonly files: Ix extends NoTablesIndex ? Unavailable<'this application declares no tables, so it has no file collections'>
-		: FileCollections<
-			K extends 'transaction' ? FileCollectionJobHandle : K extends 'mutation' ? FileCollectionHandle : FileCollectionReadHandle<RemovesIn<K>>
-		>
+	readonly files: Ix extends NoTablesIndex ? Unavailable<'this application declares no tables, so it stores no files'>
+		: K extends 'query' ? StoredFilesReadHandle
+		: StoredFilesHandle
 }
 
-type RemovesIn<K extends DataKind | 'transaction'> = K extends 'job' ? 'a job removes files inside ctx.transaction((tx) => …), as tx.files'
-	: 'a query reads only; remove files in a mutation'
-
 type UnscopedData<Ix extends AnyDbIndex, U, K extends DataKind> = {
 	readonly unscoped: [U] extends [never] ? NoUnscoped : UnscopedTables<Ix, U, K>
 }
@@ -162,6 +165,9 @@ type IsUnion<T, All = T> = T extends unknown ? ([All] extends [T] ? false : true
  */
 export type CheckedAccess<Acc> = true extends IsUnion<Acc> ? InvalidAccess : Acc
 
+/** Every action several capabilities name. */
+type CapabilityActions<C> = { [N in keyof C]: C[N] extends { readonly action: infer A extends string } ? A : never }[keyof C]
+
 /** The capability an access form hands, and what the other forms do not have. */
 export type CapabilityContext<Acc> = Acc extends InvalidAccess ? {
 		readonly target: Unavailable<'the access form of this endpoint is refused where it is declared: fix it there'>
@@ -172,6 +178,11 @@ export type CapabilityContext<Acc> = Acc extends InvalidAccess ? {
 			readonly target: Unavailable<'a member endpoint holds no capability: declare access with on or in for ctx.target'>
 			readonly within: Unavailable<'a member endpoint holds no capability: declare access with over for ctx.within'>
 		}
+	: Acc extends { readonly capabilities: infer C } ? {
+			readonly capabilities: { readonly [N in keyof C]: CapabilityOf<C[N]> }
+			readonly target: Unavailable<'an endpoint of several capabilities holds each in ctx.capabilities.<name>'>
+			readonly within: Unavailable<'an endpoint of several capabilities holds each in ctx.capabilities.<name>'>
+		}
 	: Acc extends { readonly action: infer A extends string; readonly over: infer D extends string } ? {
 			readonly within: Within<D, A>
 			readonly target: Unavailable<'an over endpoint holds ctx.within, the scopes it may list in: declare access with on or in for ctx.target'>
@@ -203,7 +214,6 @@ type Reach<Ix extends AnyDbIndex, T extends string, Form extends 'target' | 'ove
 /** Why the handle `Where` holds no table `T`: one line that names the table, the access form, and the form that reaches it. */
 type Unreached<Ix extends AnyDbIndex, T extends string, Where extends string, Form extends 'target' | 'over'> = T extends Ix['references']
 	? Unavailable<`${T} is a reference table: read it through ctx.db.reference.${T}`>
-	: TableOf<Ix, T>['mode'] extends 'inbox' ? Unavailable<`${T} is a form inbox, which no ctx.db handle reads`>
 	: T extends Ix['applications']
 		? Unavailable<`${T} is an application table: read it through ctx.db.app.${T}, or declare access: { action, app: true }`>
 	: Unavailable<`${T} is not under ${Where} (${Lies<Ix, T>}): ${Reach<Ix, T, Form>}`>
@@ -223,7 +233,12 @@ type Target<Ix extends AnyDbIndex, D extends string, A extends string, K extends
 	'target'
 >
 
-type WithinData<Ix extends AnyDbIndex, D extends string, A extends string> = Reaching<Ix, WithinTables<Ix, D, A>, `over: '${D}'`, 'over'>
+type WithinData<Ix extends AnyDbIndex, D extends string, A extends string, K extends DataKind> = Reaching<
+	Ix,
+	WithinTables<Ix, D, A, K>,
+	`over: '${D}'`,
+	'over'
+>
 
 type AppData<Ix extends AnyDbIndex, A extends string, K extends DataKind> = Reaching<Ix, ApplicationTables<Ix, A, K>, 'app: true', 'over'>
 
@@ -245,8 +260,15 @@ type AccessData<Ix extends AnyDbIndex, K extends DataKind, Acc> = Acc extends In
 	: Acc extends MemberAccess ? {
 			readonly target: Unavailable<'a member endpoint reaches no application data: declare access with on, in or over'>
 		}
+	: Acc extends { readonly capabilities: infer C } ?
+			& CapabilityData<Ix, K, CapabilityActions<C>>
+			& {
+				readonly target: Unavailable<'an endpoint of several capabilities binds each: ctx.db.on(ctx.capabilities.<name>), .in or .over'>
+				readonly within: Unavailable<'an endpoint of several capabilities binds each: ctx.db.on(ctx.capabilities.<name>), .in or .over'>
+				readonly app: Unavailable<'an endpoint of several capabilities binds each: ctx.db.on(ctx.capabilities.<name>), .in or .over'>
+			}
 	: Acc extends { readonly action: infer A extends string; readonly over: infer D extends string } ? {
-			readonly within: WithinData<Ix, D, A>
+			readonly within: WithinData<Ix, D, A, K>
 			readonly app: ScopedAppData<Ix, A>
 			readonly target: Unavailable<'an over endpoint lists through ctx.db.within: declare access with on or in for ctx.db.target'>
 		}
@@ -353,6 +375,63 @@ export type EndpointContext<
 	& { readonly db: DataOf<K['index'], EndpointData<K['index'], Kind, Acc, Of<D, 'unscoped'>>> }
 	& NoMail
 
+type PublicOnly = 'a public procedure acts application-wide, as its own workload: ctx.app(<action>) and ctx.db.app(<action>)'
+
+/**
+ * What the handler of a public procedure receives: anyone called it, and it runs as the endpoint's own workload, holding
+ * its declared actions `Acts` and nothing else. `ctx.app('<action>')` mints, and `ctx.db.app('<action>')` inserts and
+ * reads under it; no other reach.
+ */
+export type PublicContext<K extends KitTypes, Kind extends DataKind, Acts extends string> =
+	& RequestContext<PublicPrincipal>
+	& {
+		/** A capability of one of the procedure's declared actions, application-wide, bound to this request. */
+		app<const A extends Acts>(action: A): AppCapability<A>
+		readonly target: Unavailable<PublicOnly>
+		readonly within: Unavailable<PublicOnly>
+		readonly members: Unavailable<'a public procedure reaches no member directory'>
+		readonly links: Unavailable<'a public procedure issues no share link'>
+		readonly connect: Unavailable<'a public procedure calls no other application'>
+		/** The stored files: a public mutation puts one, and both open one this request holds. */
+		readonly files: Kind extends 'query' ? StoredFilesReadHandle : StoredFilesHandle
+		readonly sql: Unavailable<'a public procedure reaches its actions only: it declares no sql'>
+	}
+	& {
+		readonly db: DataOf<
+			K['index'],
+			{
+				app<const A extends Acts>(action: A): PublicApplicationTables<K['index'], A, Kind>
+				readonly target: Unavailable<PublicOnly>
+				readonly within: Unavailable<PublicOnly>
+				readonly unscoped: Unavailable<'a public procedure reaches its actions only: it declares no unscoped'>
+			}
+		>
+	}
+	& NoMail
+
+/**
+ * `ctx.kick('<job>')` of a site that declares `kicks`: the job runs in the background after the site's transaction
+ * committed, once however often it is kicked, and not at all on a rollback.
+ */
+export type KickContext<Ks> = [Ks] extends [never]
+	? { readonly kick: Unavailable<"declare kicks: ['<cron job>'] on this site to kick a job after its commit"> }
+	: Ks extends readonly (infer N extends string)[] ? { kick(job: N): void }
+	: never
+
+/** `ctx.tokens.sign('<purpose>', claims, { days })` of a site that declares `signs`: a token of one of those purposes. */
+export type TokensContext<K extends KitTypes, Sg> = [Sg] extends [never]
+	? { readonly tokens: Unavailable<"declare signs: ['<token purpose>'] on this site to sign its tokens"> }
+	: Sg extends readonly (infer P extends string)[] ? { readonly tokens: TokenSigning<K['tokens'], P> }
+	: never
+
+/**
+ * `ctx.webhooks('<webhook>')` of a mutation that declares `binds`: the webhook's bindings, on the value a capability of
+ * this request names, written in the mutation's transaction.
+ */
+export type WebhooksContext<Bs> = [Bs] extends [never]
+	? { readonly webhooks: Unavailable<"declare binds: '<webhook>' on this mutation to create and remove its bindings"> }
+	: { webhooks(name: Bs): WebhookBindings }
+
 /** A link procedure acts on the one object its key is bound to. */
 export type LinkContext<
 	K extends KitTypes,
@@ -384,8 +463,10 @@ export type ExportContext<K extends KitTypes, Acc, D extends Declared<'read', un
  */
 export interface CapabilityData<Ix extends AnyDbIndex, Kind extends DataKind, Acts extends string> {
 	on<const D extends string, const A extends Acts>(ref: Ref<D, A>): Target<Ix, D, A, Kind, 'on'>
+	/** A row a claim leased (`row.ref`), finished inside `ctx.transaction`. */
+	on<const T extends TableName<Ix>, const A extends Acts>(ref: RowRef<T, A>): ClaimedRowHandle<T, Ix['tables'][T], A, Kind>
 	in<const D extends string, const A extends Acts>(ref: Ref<D, A>): Target<Ix, D, A, Kind, 'in'>
-	over<const D extends string, const A extends Acts>(within: Within<D, A>): WithinData<Ix, D, A>
+	over<const D extends string, const A extends Acts>(within: Within<D, A>): WithinData<Ix, D, A, Kind>
 }
 
 type SiteData<Ix extends AnyDbIndex, Kind extends DataKind, Acts extends string, U> =
@@ -393,15 +474,23 @@ type SiteData<Ix extends AnyDbIndex, Kind extends DataKind, Acts extends string,
 	& { readonly reference: ReferenceTables<Ix> }
 	& UnscopedData<Ix, U, Kind>
 
+/**
+ * `ctx.db.app('<action>')` of a workload site that acts application-wide (a job): the application tables of one of its
+ * declared actions, over `ctx.app('<action>')`.
+ */
+export interface WorkloadAppData<Ix extends AnyDbIndex, Kind extends DataKind, Acts extends string> {
+	app<const A extends Acts>(action: A): AppData<Ix, A, Kind>
+}
+
 /** The fenced transaction of a job attempt: writes and `tx.sql` commit only while the attempt holds its lease. */
 export type JobTransaction<K extends KitTypes, A extends string, D extends Declared<SqlMode, unknown, never, string, JobMailer>> =
-	& { readonly db: SiteData<K['index'], 'mutation', A, Of<D, 'unscoped'>> }
+	& { readonly db: SiteData<K['index'], 'mutation', A, Of<D, 'unscoped'>> & WorkloadAppData<K['index'], 'mutation', A> }
 	& SqlContext<Of<D, 'sql'>, K['index']>
 	& FilesContext<K['index'], 'transaction'>
 	& {
 		/**
 		 * `ctx.ref`, located in this transaction: an object it wrote is found before the commit, so the same transaction
-		 * attaches a form's file to the record it just created.
+		 * reaches the record it just created.
 		 */
 		ref<const Act extends A, const Dim extends K['dimension']>(action: Act, dimension: Dim, id: string): Promise<Ref<Dim, Act>>
 	}
@@ -420,24 +509,44 @@ type JobMailContext<M extends JobMailer> = [M] extends [never]
 	: { readonly mail: AppMail }
 
 /** A send is external I/O that never rolls back, so only a job sends, from the outbox row an endpoint wrote. */
-type NoMail = { readonly mail: Unavailable<"an endpoint sends no mail: write an outbox row and kick a job that declares mailer (then: '<job>')"> }
+type NoMail = { readonly mail: Unavailable<"an endpoint sends no mail: write an outbox row and kick a job that declares mailer (kicks: ['<job>'])"> }
 
 /** What a cron job's handler receives. Its reads run outside the transaction; every write runs in `ctx.transaction`. */
 export type JobKitContext<K extends KitTypes, A extends string, D extends Declared<SqlMode, unknown, never, string, JobMailer>> =
 	& JobContext<A, K['dimension']>
-	& { readonly db: SiteData<K['index'], 'job', A, Of<D, 'unscoped'>> }
+	& { readonly db: SiteData<K['index'], 'job', A, Of<D, 'unscoped'>> & WorkloadAppData<K['index'], 'job', A> }
 	& { readonly sql: Unavailable<'a job runs ctx.sql inside ctx.transaction((tx) => …), as tx.sql'> }
 	& FilesContext<K['index'], 'job'>
 	& JobLinksContext<K['dimension'], A, Of<D, 'issues'>>
 	& JobMailContext<Of<D, 'mailer'>>
 	& { transaction<R>(work: (tx: JobTransaction<K, A, D>) => Promise<R>): Promise<R> }
 
-/** What a webhook delivery's handler receives: one transaction per delivery, idempotent by `ctx.delivery.key`. */
+type BoundToValue = 'a webhook bound to a dimension acts on its bound value: use ctx.refs and ctx.db.on(ref)'
+
+/**
+ * What a webhook delivery's handler receives: one transaction per delivery, idempotent by `ctx.delivery.key`. A webhook
+ * bound to a dimension acts on its bound value through `ctx.refs`; one bound to `'app'` acts application-wide, as its
+ * own workload: `ctx.app('<action>')` and `ctx.db.app('<action>')`.
+ */
 export type WebhookKitContext<K extends KitTypes, B extends string, Acts extends string, D extends Declared<SqlMode, unknown, never, never>> =
 	& RequestContext<WebhookPrincipal>
-	& { readonly refs: { readonly [A in Acts]: Ref<B, A> }; readonly delivery: WebhookDelivery }
+	& { readonly delivery: WebhookDelivery }
+	& ([B] extends ['app'] ? {
+			/** A capability of one of the webhook's declared actions, application-wide, bound to this delivery. */
+			app<const A extends Acts>(action: A): AppCapability<A>
+			readonly refs: Unavailable<'a webhook bound to the application has no bound value: use ctx.app(<action>) and ctx.db.app(<action>)'>
+		}
+		: { readonly refs: { readonly [A in Acts]: Ref<B, A> }; readonly app: Unavailable<BoundToValue> })
 	& SqlContext<Of<D, 'sql'>, K['index']>
-	& { readonly db: SiteData<K['index'], 'mutation', Acts, Of<D, 'unscoped'>> }
+	& {
+		readonly db:
+			& SiteData<K['index'], 'mutation', Acts, Of<D, 'unscoped'>>
+			& ([B] extends ['app'] ? WorkloadAppData<K['index'], 'mutation', Acts> : { readonly app: Unavailable<BoundToValue> })
+	}
+	& {
+		/** The stored files: a delivery puts one, and opens one it holds. */
+		readonly files: StoredFilesHandle
+	}
 	& NoMail
 
 type IndexOf<A> = A extends App<infer K> ? K['index'] : never
@@ -449,7 +558,7 @@ type IndexOf<A> = A extends App<infer K> ? K['index'] : never
  */
 export type DbHandle<A, F extends TargetForm | 'over', D extends string, Act extends string, K extends DataKind = 'query'> = F extends TargetForm
 	? Target<IndexOf<A>, D, Act, K, F>
-	: WithinData<IndexOf<A>, D, Act>
+	: WithinData<IndexOf<A>, D, Act, K>
 
 /**
  * The type of `ctx.db.app` of an `app` endpoint, for a function of `src/<slice>/queries.ts` that takes it: