@fabrika/app 0.3.3 → 0.4.0

package/src/implement/serve.ts

@@ -0,0 +1,142 @@
+// `serve(contract, { database, deps })`: how `src/app.ts` serves a contract of the staged kit. Its handlers sit
+// beside their endpoints, so there is no handler tree to pass: `serve` collects the one `boot` binds by endpoint id.
+
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { isProcedure, type ProcedureTreeDeclaration, SURFACE_SECTIONS } from '../contract/declaration'
+import type { AnyContract, Schema } from '../contract/define'
+import { handlerOf, kitOriginOf, snapshotsOf } from '../contract/handled'
+import { ContractError } from '../contract/problems'
+import {
+	type ApplicationEnvironment,
+	type ContractImplementation,
+	contractImplementation,
+	type DepsRuntime,
+	type ImplementationDatabase,
+} from './implement'
+import { type SiteHandler, siteHandler } from './invocation'
+
+/**
+ * The application's dependencies, built at each `boot` from its own environment. A handler imports the module that
+ * defines them and reads `get()` while it runs: it answers what the boot serving that invocation built. At module load
+ * there is nothing to read yet.
+ */
+export interface AppDeps<D> {
+	get(): D
+}
+
+/** Runs `work` with one boot's dependencies as the ones `get()` answers. */
+type WithDeps = <R>(work: () => R) => R
+
+/** Builds one boot's dependencies; what `serve` runs at `boot`, since `AppDeps` itself exposes only `get`. */
+type DepsBuild = (env: ApplicationEnvironment, runtime: DepsRuntime) => WithDeps
+
+const builds = new WeakMap<AppDeps<unknown>, DepsBuild>()
+
+class Deps<D> implements AppDeps<D> {
+	/** The dependencies of the boot whose handler is running; two runtimes of one process each keep their own. */
+	readonly #current = new AsyncLocalStorage<{ readonly value: D }>()
+
+	constructor(build: (env: ApplicationEnvironment, runtime: DepsRuntime) => D) {
+		builds.set(this, (env, runtime) => {
+			const built = { value: build(env, runtime) }
+			return (work) => this.#current.run(built, work)
+		})
+	}
+
+	get(): D {
+		const built = this.#current.getStore()
+		if (built === undefined) {
+			throw new Error('the dependencies are built at boot: read deps.get() inside a handler, not at module load')
+		}
+		return built.value
+	}
+}
+
+/** Declares how each `boot` builds the dependencies; `serve(contract, { deps })` takes the result. */
+export function defineDeps<D>(build: (env: ApplicationEnvironment, runtime: DepsRuntime) => D): AppDeps<D> {
+	return new Deps(build)
+}
+
+export interface ServeOptions {
+	/** `scoped(tables)` of `@fabrika/db`, which `boot` binds, or `null` for a kit without tables (`defineApp(vocabulary)`). */
+	readonly database: ImplementationDatabase | null
+	readonly deps?: AppDeps<unknown>
+}
+
+/**
+ * The contract with the handlers its endpoints carry, ready for `boot`. The default export of `src/app.ts`. Throws
+ * `ContractError` naming every endpoint, job and webhook that took no `.handle(…)`.
+ */
+export function serve<const C extends AnyContract>(contract: C, options: ServeOptions): ContractImplementation<C> {
+	const origin = kitOriginOf(contract)
+	if (origin === undefined) {
+		throw new ContractError(['serve: takes the contract app.contract(…) returned, itself; a copy or another object loses what the kit keeps beside it'])
+	}
+	handlerTree(contract, (work) => work())
+	if ((origin === 'tableless') !== (options.database === null)) {
+		throw new ContractError([
+			origin === 'tableless'
+				? 'serve: defineApp(vocabulary) declares no tables, so it takes database: null'
+				: 'serve: the kit declares tables, so it takes database: scoped(tables) from @fabrika/db',
+		])
+	}
+	const build = options.deps === undefined ? undefined : builds.get(options.deps)
+	return contractImplementation({
+		contract,
+		database: options.database,
+		connect: snapshotsOf(contract),
+		handlers: (env, runtime) => handlerTree(contract, build?.(env, runtime) ?? ((work) => work())),
+	})
+}
+
+/**
+ * The tree `boot` reads: one handler per procedure of each RPC and link mount, per webhook, job and export procedure,
+ * each run with one boot's dependencies.
+ */
+function handlerTree(contract: AnyContract, withDeps: WithDeps): Record<string, unknown> {
+	const missing: string[] = []
+	const served = (site: { readonly declared?: unknown }, path: string): SiteHandler | undefined => {
+		const handler = handlerOf(site)
+		if (typeof handler !== 'function') {
+			missing.push(path)
+			return undefined
+		}
+		return siteHandler((args) => withDeps(() => Reflect.apply(handler, undefined, [args])), site.declared ?? {})
+	}
+	const procedureHandlers = <Access>(procedures: ProcedureTreeDeclaration<Schema, Access>, path: string): Record<string, unknown> =>
+		Object.fromEntries(
+			Object.entries(procedures).map(([name, node]) => [
+				name,
+				isProcedure(node) ? served(node, `${path}.${name}`) : procedureHandlers(node, `${path}.${name}`),
+			]),
+		)
+	const tree: Record<string, unknown> = {}
+	for (const [name, entry] of Object.entries(contract.surface)) {
+		if (SURFACE_SECTIONS.some((section) => section === name) || typeof entry !== 'object' || !('kind' in entry)) {
+			continue
+		}
+		if (entry.kind === 'rpc') {
+			tree[name] = procedureHandlers(entry.procedures, name)
+		} else if (entry.kind === 'link') {
+			tree[name] = procedureHandlers(entry.procedures, name)
+		} else if (entry.kind === 'webhook') {
+			tree[name] = served(entry, name)
+		}
+	}
+	const jobs = Object.entries(contract.surface.jobs ?? {})
+	if (jobs.length > 0) {
+		tree['jobs'] = Object.fromEntries(jobs.map(([name, job]) => [name, served(job, `jobs.${name}`)]))
+	}
+	const exports = Object.entries(contract.surface.exports ?? {})
+	if (exports.length > 0) {
+		tree['exports'] = Object.fromEntries(
+			exports.map(([name, declaration]) => [name, procedureHandlers(declaration.procedures, `exports.${name}`)]),
+		)
+	}
+	if (missing.length > 0) {
+		throw new ContractError(
+			missing.map((site) => `${site}: add .handle(…) beside its declaration; serve binds every endpoint, job and webhook to its own`),
+		)
+	}
+	return tree
+}

package/src/implement/types.ts

@@ -0,0 +1,215 @@
+// The handler types `implement` checks against the contract: one handler per declared procedure, nothing else, each
+// with the context its access form grants and returning only the fields its output declares.
+
+import type { z } from 'zod/v4'
+import type { ConnectSnapshot } from '../contract/connect'
+import type { SurfaceSection } from '../contract/declaration'
+import type { Export, InputOf, InputSchema, LinkMount, MemberAccess, Procedure, RoleOf, RpcMount, Schema, WebhookMount } from '../contract/define'
+import type { JobHandlersOf } from '../jobs/types'
+import type { AppCapability, Ref, Within } from './capability'
+import type { ConnectResult } from './connect'
+import type { LinkIssuing, MemberDirectory, MemberLookup, MemberManagement } from './membership'
+import type { AppPrincipal, LinkHolder, PrincipalOf, ServicePrincipal } from './principal'
+import type { WebhookDelivery, WebhookPrincipal } from './webhook'
+
+/** What every handler gets: who called, this request's id, and the signal that ends it. */
+export interface RequestContext<P> {
+	readonly principal: P
+	readonly requestId: string
+	/**
+	 * Aborts when the client leaves or the request outlives `REQUEST_BUDGET_MS`; its transaction then rolls back. Pass
+	 * it to every outbound call, so the call stops with the request.
+	 */
+	readonly signal: AbortSignal
+}
+
+/** The capability an access form hands. `{ member: true }` hands none. */
+export type AccessContext<Acc> = Acc extends MemberAccess ? unknown
+	: Acc extends { readonly action: infer A extends string; readonly over: infer D extends string } ? { readonly within: Within<D, A> }
+	: Acc extends { readonly action: infer A extends string; readonly in: infer D extends string } ? { readonly target: Ref<D, A> }
+	: Acc extends { readonly action: infer A extends string; readonly on: infer D extends string } ? { readonly target: Ref<D, A> }
+	: Acc extends { readonly action: infer A extends string; readonly creates: infer D extends string } ? { readonly created: Ref<D, A> }
+	: Acc extends { readonly action: infer A extends string; readonly app: true } ? { readonly app: AppCapability<A> }
+	: never
+
+type DimensionsOf<C> = C extends { readonly dimensions: infer Dims } ? Dims : never
+
+/** The dimension and action of an access form that hands a `Ref` of an existing object. */
+type TargetOf<Acc> = Acc extends { readonly action: infer A extends string; readonly in: infer D extends string } ? readonly [D, A]
+	: Acc extends { readonly action: infer A extends string; readonly on: infer D extends string } ? readonly [D, A]
+	: never
+
+/** The nearest dimension, `D` or one containing it, that declares members; `never` when none does. */
+type DirectoryOf<C, D extends string> = D extends keyof DimensionsOf<C> ? DimensionsOf<C>[D] extends { readonly members: object } ? D
+	: DimensionsOf<C>[D] extends { readonly in: infer P extends string } ? DirectoryOf<C, P>
+	: never
+	: never
+
+/**
+ * `ctx.members` (ADR-0012 §6): management where the action is the dimension's `members.manage`; otherwise the directory
+ * of the nearest dimension that declares members, which lists them only for its `members.list`.
+ */
+type MembersContext<C, Acc> = TargetOf<Acc> extends readonly [infer D extends string, infer A extends string]
+	? DimensionsOf<C>[D & keyof DimensionsOf<C>] extends { readonly members: { readonly manage: A } }
+		? { readonly members: MemberManagement<D, A, RoleOf<C>> }
+	: [DirectoryOf<C, D>] extends [never] ? unknown
+	: DimensionsOf<C>[DirectoryOf<C, D>] extends { readonly members: { readonly list: A } } ? { readonly members: MemberDirectory }
+	: { readonly members: MemberLookup }
+	: unknown
+
+/** The link mounts whose dimension and issuing action are `D` and `A`. */
+type IssuingMounts<C, D extends string, A extends string> =
+	& {
+		[M in keyof SurfaceOf<C>]: SurfaceOf<C>[M] extends { readonly kind: 'link'; readonly dimension: D; readonly issuedBy: A } ? M : never
+	}[keyof SurfaceOf<C>]
+	& string
+
+/** `ctx.links`, only where the `Ref` carries a link mount's issuing action for its dimension. */
+type LinksContext<C, Acc> = TargetOf<Acc> extends readonly [infer D extends string, infer A extends string]
+	? [IssuingMounts<C, D, A>] extends [never] ? unknown : { readonly links: LinkIssuing<D, A, IssuingMounts<C, D, A>> }
+	: unknown
+
+/** What a procedure's context carries for its access form in this contract. */
+export type ContractContext<C, Acc> = AccessContext<Acc> & MembersContext<C, Acc> & LinksContext<C, Acc>
+
+/** The input without the `from` field: the only copy of that id a handler has is the checked capability. */
+export type HandlerInput<I, Acc> = Acc extends { readonly from: infer F extends string }
+	? { readonly [K in keyof InputOf<I> as K extends F ? never : K]: InputOf<I>[K] }
+	: InputOf<I>
+
+export type Handler<In, Ctx, O extends Schema> = (args: { readonly input: In; readonly ctx: Ctx }) => z.input<O> | Promise<z.input<O>>
+
+// ── Connectors: `ctx.connect` in the handlers an import's `usedBy` names, typed by the vendored snapshot ────────
+
+type ImportsOf<C> = SurfaceOf<C> extends { readonly imports: infer I } ? I : Record<never, never>
+
+/** What `implement({ connect })` takes: the vendored snapshot of each import, by the import's name. */
+export type ConnectSnapshots<C> = { readonly [K in keyof ImportsOf<C>]: ConnectSnapshot }
+
+type ImportsUsedBy<C, Id extends string> = {
+	[K in keyof ImportsOf<C>]: ImportsOf<C>[K] extends { readonly usedBy: readonly (infer U)[] } ? Id extends U ? K : never : never
+}[keyof ImportsOf<C>]
+
+type ImportedProcedures<C, K> = K extends keyof ImportsOf<C>
+	? ImportsOf<C>[K] extends { readonly procedures: readonly (infer P extends string)[] } ? P : never
+	: never
+
+/** A connector call never throws for the owner's answer: it resolves to a typed outcome. */
+export type ConnectCall<I, O extends Schema> = [I] extends [InputSchema] ? (input: z.input<I>) => Promise<ConnectResult<z.output<O>>>
+	: (input?: Record<never, never>) => Promise<ConnectResult<z.output<O>>>
+
+type ConnectorOf<S, P extends string> = {
+	readonly [Path in P]: S extends
+		{ readonly procedures: { readonly [Q in Path]: { readonly input: infer I; readonly output: infer O extends Schema } } } ? ConnectCall<I, O>
+		: never
+}
+
+/** `ctx.connect` with the imports whose `usedBy` names endpoint `Id`; nothing for any other endpoint. */
+export type ConnectContext<C, Snap, Id extends string> = [ImportsUsedBy<C, Id>] extends [never] ? unknown
+	: { readonly connect: { readonly [K in ImportsUsedBy<C, Id> & keyof Snap]: ConnectorOf<Snap[K], ImportedProcedures<C, K>> } }
+
+type RpcHandlers<C, P, T, Snap, Prefix extends string> = {
+	readonly [K in keyof T]: T[K] extends Procedure<'query' | 'mutation', infer I, infer O, infer Acc> ? Handler<
+			HandlerInput<I, Acc>,
+			RequestContext<P> & ContractContext<C, Acc> & ConnectContext<C, Snap, `${Prefix}${K & string}`>,
+			O
+		>
+		: RpcHandlers<C, P, T[K], Snap, `${Prefix}${K & string}.`>
+}
+
+/** An export handler runs read-only: its context carries its capability and nothing that writes. */
+type ExportHandlers<T> = {
+	readonly [K in keyof T]: T[K] extends Procedure<'query', infer I, infer O, infer Acc>
+		? Handler<HandlerInput<I, Acc>, RequestContext<ServicePrincipal | AppPrincipal> & AccessContext<Acc>, O>
+		: ExportHandlers<T[K]>
+}
+
+type ExportsOf<C> = SurfaceOf<C> extends { readonly exports: infer E } ? E : Record<never, never>
+
+type ExportHandlersOf<C> = [keyof ExportsOf<C>] extends [never] ? unknown
+	: { readonly exports: { readonly [E in keyof ExportsOf<C>]: ExportsOf<C>[E] extends Export<infer T> ? ExportHandlers<T> : never } }
+
+/** A link procedure acts on the object its key is bound to. */
+type LinkHandlers<D extends string, T> = {
+	readonly [K in keyof T]: T[K] extends Procedure<'query' | 'mutation', infer I, infer O, { readonly action: infer A extends string }>
+		? Handler<InputOf<I>, RequestContext<LinkHolder> & { readonly target: Ref<D, A> }, O>
+		: LinkHandlers<D, T[K]>
+}
+
+/**
+ * A delivery's handler: the declared input, a `Ref` of the bound value for each declared action, and the delivery's
+ * stable key. It runs at least once per delivery: a failed run is run again on GitHub's redelivery.
+ */
+export type WebhookHandler<B extends string, Acts extends string, I> = (args: {
+	readonly input: z.output<I>
+	readonly ctx: RequestContext<WebhookPrincipal> & { readonly refs: { readonly [A in Acts]: Ref<B, A> }; readonly delivery: WebhookDelivery }
+}) => void | Promise<void>
+
+type MountHandlers<C, M, Name extends string, Snap> = M extends RpcMount<infer Callers, infer T>
+	? RpcHandlers<C, PrincipalOf<Callers[number]>, T, Snap, `${Name}.`>
+	: M extends LinkMount<infer D, string, string, infer T> ? LinkHandlers<D, T>
+	: M extends WebhookMount<infer B, infer Acts, infer I> ? WebhookHandler<B, Acts, I>
+	: never
+
+type ServedMount<M> = M extends { readonly kind: 'rpc' | 'link' | 'webhook' } ? true : false
+
+type SurfaceOf<C> = C extends { readonly surface: infer S } ? S : never
+
+/**
+ * One handler tree per procedure mount and one handler per webhook, keyed like the contract, one per job under `jobs`,
+ * and the export handlers under `exports`.
+ */
+export type HandlersOf<C, Snap = unknown> =
+	& {
+		readonly [M in keyof SurfaceOf<C> as M extends SurfaceSection ? never : ServedMount<SurfaceOf<C>[M]> extends true ? M : never]: MountHandlers<
+			C,
+			SurfaceOf<C>[M],
+			M & string,
+			Snap
+		>
+	}
+	& JobHandlersOf<C>
+	& ExportHandlersOf<C>
+
+// ── Exactness: no handler outside the contract, no field outside the declared output ────────────
+
+/** An `any` comes from an error elsewhere in the handler; reporting it here too would only add noise. */
+export type IsAny<T> = 0 extends 1 & T ? true : false
+
+/** Fields of `R` that the output `O` does not declare. When `O` is a union, a value that fits one branch has none. */
+export type ExtraKeys<R, O> = IsAny<R> extends true ? never
+	: true extends (O extends unknown ? ([ExtraKeysOf<R, O>] extends [never] ? true : false) : never) ? never
+	: ExtraKeysOf<R, O>
+
+type ExtraKeysOf<R, O> = R extends readonly (infer RE)[] ? (O extends readonly (infer OE)[] ? ExtraKeys<RE, OE> : never)
+	: R extends object ? O extends object ? Exclude<keyof R, keyof O> | { [Q in keyof R & keyof O]: ExtraKeys<R[Q], O[Q]> }[keyof R & keyof O]
+		: never
+	: never
+
+type Returned<F> = F extends (args: never) => infer R ? Awaited<R> : never
+
+type Undeclared<F, Expected> = ExtraKeys<Returned<F>, Returned<Expected>>
+
+/** No undeclared field, or a field whose type is an error reported where it arose. */
+type NoneOrError<U> = [U] extends [never] ? true : IsAny<U>
+
+type ExactTree<H, E, Path extends string> = {
+	readonly [K in keyof H]: K extends keyof E ? E[K] extends (args: never) => unknown ? NoneOrError<Undeclared<H[K], E[K]>> extends true ? H[K]
+			: {
+				readonly [_ in `handler '${Path}${K & string}' returns fields the contract output does not declare. Return only declared fields`]: Undeclared<
+					H[K],
+					E[K]
+				>
+			}
+		: ExactTree<H[K], E[K], `${Path}${K & string}.`>
+		: `'${Path}${K & string}' is not in the contract. Declare the endpoint in fabrika.contract.ts first.`
+}
+
+type KindOf<M> = M extends { readonly kind: infer K extends string } ? K : 'section'
+
+export type ExactHandlers<H, C> = {
+	readonly [M in keyof H]: M extends keyof HandlersOf<C> ? HandlersOf<C>[M] extends (args: never) => unknown ? H[M]
+		: ExactTree<H[M], HandlersOf<C>[M], `${M & string}.`>
+		: M extends keyof SurfaceOf<C> ? `'${M & string}' is a ${KindOf<SurfaceOf<C>[M]>} mount; it takes no handler. Remove it from handlers.`
+		: `'${M & string}' is not in the contract. Declare the mount in fabrika.contract.ts first.`
+}

package/src/implement/webhook.ts

@@ -0,0 +1,108 @@
+// `c.webhook` for GitHub (docs/reference/application-runtime.md). A holder of the bound dimension's `members.manage`
+// creates a binding through the generated `webhooks.<name>.bind` endpoint; the framework generates the secret and
+// keeps the binding in `fabrika_webhook_bindings`. A delivery is checked in a fixed order — the binding, the
+// signature over the raw body, the account, the input, the delivery id — before its handler sees a `Ref` of the
+// bound value only.
+
+import type { WebhookTables } from '@fabrika/db/framework'
+import { uuidv7 } from '@fabrika/platform'
+import { z } from 'zod/v4'
+import { joinPath, WEBHOOK_ACCOUNT_PATTERN, WEBHOOK_SCOPE_FIELD } from '../contract/defaults'
+import { NotFoundError } from '../errors'
+import { Ref } from './capability'
+
+/** The input and output of the generated binding endpoints; `build.ts`'s `WEBHOOK_BIND_*` shapes describe them. */
+export const webhookBindInput = z.strictObject({
+	[WEBHOOK_SCOPE_FIELD]: z.string().min(1),
+	account: z.string().regex(new RegExp(WEBHOOK_ACCOUNT_PATTERN)),
+})
+export const webhookBindOutput = z.strictObject({ id: z.uuid(), url: z.string().min(1), secret: z.string().min(1) })
+export const webhookUnbindInput = z.strictObject({ [WEBHOOK_SCOPE_FIELD]: z.string().min(1), id: z.uuid() })
+export const webhookUnbindOutput = z.strictObject({ id: z.uuid() })
+
+/** The workload a delivery runs as: no person, only the binding. It creates no scope and manages no member. */
+export interface WebhookPrincipal {
+	readonly kind: 'webhook'
+	readonly bindingId: string
+}
+
+/** The principal id a delivery's capabilities are granted to. */
+export function webhookSubject(bindingId: string): string {
+	return `webhook:${bindingId}`
+}
+
+/**
+ * A delivery key is kept this long per binding. GitHub signs no timestamp, so a body replayed after the window
+ * runs again; GitHub itself redelivers for three days.
+ */
+export const WEBHOOK_REPLAY_RETENTION_MS = 30 * 24 * 60 * 60 * 1000
+
+/**
+ * `sha256:<hex>` of the binding id and the signed body: what replay protection and an idempotent handler key on.
+ * A redelivery of one event has the same key, whatever its `X-GitHub-Delivery` says.
+ */
+export async function deliveryKey(bindingId: string, body: Uint8Array<ArrayBuffer>): Promise<string> {
+	const id = new TextEncoder().encode(bindingId)
+	const content = new Uint8Array(id.byteLength + body.byteLength)
+	content.set(id, 0)
+	content.set(body, id.byteLength)
+	const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', content))
+	return `sha256:${Array.from(digest, (byte) => byte.toString(16).padStart(2, '0')).join('')}`
+}
+
+/** What a handler knows of its delivery. Handlers run at least once: write idempotently, keyed on `key`. */
+export interface WebhookDelivery {
+	readonly key: string
+}
+
+/** 32 random bytes as hex: the HMAC key GitHub signs with, shown once to the member who binds. */
+function generateSecret(): string {
+	const bytes = crypto.getRandomValues(new Uint8Array(32))
+	return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+export interface BindingHandlers {
+	bind(args: { readonly input: Readonly<Record<string, unknown>>; readonly ctx: object }): Promise<z.output<typeof webhookBindOutput>>
+	unbind(args: { readonly input: Readonly<Record<string, unknown>>; readonly ctx: object }): Promise<z.output<typeof webhookUnbindOutput>>
+}
+
+/** What the `in` access form handed a binding endpoint: the checked `Ref` of the value, and the person. */
+function accessOf(ctx: object): { readonly scope: Ref<string, string>; readonly principal: string } {
+	const target: unknown = Reflect.get(ctx, 'target')
+	const principal: unknown = Reflect.get(ctx, 'principal')
+	const id: unknown = typeof principal === 'object' && principal !== null ? Reflect.get(principal, 'id') : undefined
+	if (!(target instanceof Ref) || typeof id !== 'string') {
+		throw new TypeError('a binding endpoint runs for a person, with the Ref of its in access form')
+	}
+	return { scope: target, principal: id }
+}
+
+/** The framework's handlers of `webhooks.<name>.bind` and `.unbind`. */
+export function bindingHandlers(webhook: string, path: string, tables: () => WebhookTables): BindingHandlers {
+	return {
+		async bind({ input, ctx }) {
+			const { scope, principal } = accessOf(ctx)
+			const account = z.parse(webhookBindInput.shape.account, input['account'])
+			const id = uuidv7()
+			const secret = generateSecret()
+			await tables().createBinding({
+				id,
+				webhook,
+				scope: { type: scope.dimension, value: scope.value },
+				account,
+				secret,
+				createdBy: principal,
+				createdAt: Date.now(),
+			})
+			return { id, url: joinPath(path, id), secret }
+		},
+		async unbind({ input, ctx }) {
+			const { scope } = accessOf(ctx)
+			const id = z.parse(webhookUnbindInput.shape.id, input['id'])
+			if (!(await tables().removeBinding(webhook, id, { type: scope.dimension, value: scope.value }))) {
+				throw new NotFoundError('Not found')
+			}
+			return { id }
+		},
+	}
+}

package/src/implement/workload.ts

@@ -0,0 +1,160 @@
+// A job's and a webhook's authority (ADR-0022 "Principal kinds"): Control reconciles one `px_` key per workload from
+// the approved snapshot and writes it as `FABRIKA_<KIND>_<NAME>_KEY`; IAM signs a token from it carrying the actions
+// the reconciled schema declares. The framework mints a capability only for an action that token carries, so the
+// authority comes from IAM, not from the application's own copy of the contract.
+
+import {
+	API_KEY_PREFIX,
+	type ContractArtifact,
+	type MintFromKeyResult,
+	type PermissionEntry,
+	TOKEN_REFRESH_SKEW_SECONDS,
+	WORKLOAD_TOKEN_PATH,
+	workloadKeyVariable,
+} from '@fabrika/auth-core'
+import type { TokenVerifier } from '@fabrika/jwks'
+import { z } from 'zod/v4'
+
+export type WorkloadKindOf = 'job' | 'webhook'
+
+/** Where a workload exchanges its key for a token: IAM's public `WORKLOAD_TOKEN_PATH`, or a stand-in in a test. */
+export interface WorkloadTokenSource {
+	exchange(input: { readonly app: string; readonly key: string }): Promise<MintFromKeyResult>
+}
+
+/** The token exchange is a cold path, once per token lifetime; it is still bounded. */
+const EXCHANGE_TIMEOUT_MS = 5_000
+
+const mintResultSchema = z.union([
+	z.strictObject({ ok: z.literal(true), token: z.string().min(1), expiresAt: z.number() }),
+	z.strictObject({ ok: z.literal(false), reason: z.enum(['invalid_key', 'unknown_principal', 'disabled', 'token_too_large']) }),
+])
+
+/** IAM's token exchange at its public origin. An answer that is not IAM's decided outcome throws: "IAM could not be asked". */
+export function issuerWorkloadTokens(
+	issuer: string,
+	fetcher: (request: Request) => Promise<Response> = (request) => fetch(request),
+): WorkloadTokenSource {
+	return {
+		async exchange(input) {
+			const response = await fetcher(
+				new Request(new URL(WORKLOAD_TOKEN_PATH, issuer), {
+					method: 'POST',
+					headers: { authorization: `Bearer ${input.key}`, 'content-type': 'application/json' },
+					body: JSON.stringify({ app: input.app }),
+					redirect: 'manual',
+					signal: AbortSignal.timeout(EXCHANGE_TIMEOUT_MS),
+				}),
+			)
+			const parsed = response.status === 200 ? mintResultSchema.safeParse(await response.json()) : null
+			if (parsed === null || !parsed.success) {
+				throw new Error(`IAM answered the workload token exchange with ${response.status}`)
+			}
+			return parsed.data
+		},
+	}
+}
+
+/** What the workload may do now, or why it may do nothing. */
+export type WorkloadAuthority =
+	/** `token` is the bearer IAM signed: what a job that issues links presents to IAM. */
+	| { readonly ok: true; readonly perms: readonly PermissionEntry[]; readonly token: string }
+	/** IAM refused the key, or signed a token that is not this workload's: a decided negative. */
+	| { readonly ok: false; readonly reason: 'refused' }
+	/** IAM or its keys could not be reached. */
+	| { readonly ok: false; readonly reason: 'unavailable' }
+
+export interface WorkloadCredentialOptions {
+	readonly kind: WorkloadKindOf
+	readonly name: string
+	readonly key: string
+	/** This application's IAM id, `<app>@<env>`: the token's audience. */
+	readonly audience: string
+	readonly source: WorkloadTokenSource
+	readonly verifier: TokenVerifier
+}
+
+/** One workload's key, exchanged for a token when none is cached or the cached one is about to expire. */
+export class WorkloadCredential {
+	readonly #options: WorkloadCredentialOptions
+	#cached: { readonly perms: readonly PermissionEntry[]; readonly token: string; readonly exp: number } | null = null
+	#pending: Promise<WorkloadAuthority> | null = null
+
+	constructor(options: WorkloadCredentialOptions) {
+		this.#options = options
+	}
+
+	authority(): Promise<WorkloadAuthority> {
+		const cached = this.#cached
+		if (cached !== null && cached.exp - Math.floor(Date.now() / 1000) > TOKEN_REFRESH_SKEW_SECONDS) {
+			return Promise.resolve({ ok: true, perms: cached.perms, token: cached.token })
+		}
+		this.#pending ??= this.#exchange().finally(() => {
+			this.#pending = null
+		})
+		return this.#pending
+	}
+
+	async #exchange(): Promise<WorkloadAuthority> {
+		const { kind, name, key, audience, source, verifier } = this.#options
+		let minted: MintFromKeyResult
+		try {
+			minted = await source.exchange({ app: audience, key })
+		} catch {
+			// The error may quote IAM's URL or a transport detail; the line names the workload only.
+			console.error(`fabrika: the ${kind} '${name}' could not exchange its key at IAM: iam_unavailable`)
+			return { ok: false, reason: 'unavailable' }
+		}
+		if (!minted.ok) {
+			console.error(`fabrika: IAM refused the key of the ${kind} '${name}': ${minted.reason}`)
+			return { ok: false, reason: 'refused' }
+		}
+		const verified = await verifier.verify(minted.token, audience)
+		if (!verified.ok) {
+			return verified.reason === 'unavailable' ? { ok: false, reason: 'unavailable' } : { ok: false, reason: 'refused' }
+		}
+		const { claims } = verified
+		if (claims.ptype !== kind || claims.workload !== name) {
+			console.error(`fabrika: IAM signed a token for the key of the ${kind} '${name}' that is not this workload's`)
+			return { ok: false, reason: 'refused' }
+		}
+		const perms = Object.freeze(claims.perms.map((entry) => Object.freeze({ ...entry })))
+		this.#cached = { perms, token: minted.token, exp: claims.exp }
+		return { ok: true, perms, token: minted.token }
+	}
+}
+
+export interface WorkloadCredentialsInput {
+	readonly artifact: ContractArtifact
+	readonly framework: Readonly<Record<string, string>>
+	readonly audience: string
+	readonly source: WorkloadTokenSource | undefined
+	readonly verifier: TokenVerifier
+}
+
+/** `job:<name>` and `webhook:<name>` → the workload's credential, or why one cannot start to `problems`. */
+export function workloadCredentials(input: WorkloadCredentialsInput, problems: string[]): ReadonlyMap<string, WorkloadCredential> {
+	const workloads: [WorkloadKindOf, string][] = [
+		...Object.keys(input.artifact.jobs).map((name): [WorkloadKindOf, string] => ['job', name]),
+		...Object.entries(input.artifact.mounts).flatMap((
+			[name, mount],
+		): [WorkloadKindOf, string][] => (mount.kind === 'webhook' ? [['webhook', name]] : [])),
+	]
+	const credentials = new Map<string, WorkloadCredential>()
+	if (workloads.length > 0 && input.source === undefined) {
+		problems.push('the contract declares jobs or webhooks, and the runtime adapter supplies no IAM token exchange for their keys')
+	}
+	for (const [kind, name] of workloads) {
+		const variable = workloadKeyVariable(kind, name)
+		const key = input.framework[variable]?.trim() ?? ''
+		if (!key.startsWith(API_KEY_PREFIX) || key.length <= API_KEY_PREFIX.length) {
+			problems.push(`${variable} is not set to a px_ key; Control writes the credential of the ${kind} '${name}' into every deploy`)
+		} else if (input.source !== undefined) {
+			credentials.set(
+				`${kind}:${name}`,
+				new WorkloadCredential({ kind, name, key, audience: input.audience, source: input.source, verifier: input.verifier }),
+			)
+		}
+	}
+	return credentials
+}