@fabrika/app 0.8.2 → 0.9.0-cloudflare.1

package/src/implement/dispatch.ts

@@ -16,6 +16,7 @@ import {
 	type EndpointRow,
 	type ExportDescription,
 	FORM_URLENCODED_TYPE,
+	type IamTerminalRpc,
 	isAttachmentShape,
 	isFileShape,
 	isRedirectShape,
@@ -67,9 +68,9 @@ import {
 import type { RequestExecutionContext } from '../fetch'
 import { FileWork, type StoredFileKinds, storedFilesHandle } from '../files/kinds'
 import { FileDownload, fileResponse, withFileTreatment } from '../files/treatment'
-import { abortedBody, bodyDeadlineMs, bootstrapPath, bootstrapResponse, readBoundedBody, withBootstrap } from './anonymous'
+import { abortedBody, bodyDeadlineMs, bootstrapPath, bootstrapResponse, readBodyInTime, withBootstrap } from './anonymous'
 import { attachmentResponse } from './attachment'
-import { boundedStream, handlerSignal, readBoundedBytes } from './bounded'
+import { boundedStream, type Deadline, deadline, handlerSignal, readBoundedBytes } from './bounded'
 import type { BrowserConfig } from './browser-config'
 import {
 	type AppCapability,
@@ -104,6 +105,7 @@ import { paramsObject, urlParams } from './params'
 import { pageCallerOf, presentedBy, type Principal } from './principal'
 import { project, ProjectionRefusedError } from './project'
 import { bucketsOf, DEFAULT_ADMISSION, type InFlightShare, type ProcedureAdmission, requestClient } from './public'
+import { type TerminalIdentification, terminalIdentification } from './terminals'
 import type { SignedTokens } from './tokens'
 import type { AppUrl } from './urls'
 import { githubAccounts, verifyDelivery } from './verifiers'
@@ -241,6 +243,8 @@ export interface RuntimeParts {
 	readonly assets: SpaAssets | null
 	/** IAM's membership operations; `boot` refuses a contract that needs them when the adapter supplies none. */
 	readonly membership: IamMembership | null
+	/** IAM's identification operations, where the contract declares a terminal; `boot` refuses one without them. */
+	readonly terminals: IamTerminalRpc | null
 	/** The framework's own writes (admission buckets, webhook tables); `boot` refuses a webhook or a bucket without them. */
 	readonly framework: FrameworkTables | null
 	/** This runtime's capability mint, which `boot` alone holds, and the authority its stores are bound to. */
@@ -518,6 +522,22 @@ export class ContractRuntime {
 		const admission = served.admission ?? DEFAULT_ADMISSION
 		await this.#admit(served.row, admission, request, caller.subject)
 		const body = await procedureBody(served, request, this.#parts.fileKinds)
+		try {
+			return await this.#procedureInvocation(served, request, exec, caller, admission, body)
+		} finally {
+			// Whatever refuses the request once the body is open, a multipart body's stream and deadline end here.
+			await body.multipart?.close()
+		}
+	}
+
+	async #procedureInvocation(
+		served: Extract<ServedEndpoint, { kind: 'procedure' }>,
+		request: Request,
+		exec: RequestExecutionContext | undefined,
+		caller: Caller,
+		admission: ProcedureAdmission,
+		body: Awaited<ReturnType<typeof procedureBody>>,
+	): Promise<Response | FileDownload> {
 		// Signed tokens are verified as the input is parsed; the texts they carry are what the request may redirect to.
 		const carried = new Set<string>()
 		const fields = this.#parts.tokens.verifyFields(served.row.input, body.multipart === null ? body.input : body.multipart.json, carried)
@@ -528,58 +548,64 @@ export class ContractRuntime {
 		const invocation = site === undefined ? null : new Invocation(frame, this.#data(), site.kind === 'query' || served.readOnly === true)
 		const kicks = kickRecorder(`'${served.row.id}'`, site?.declaration.kicks ?? [])
 		let outcome: 'open' | 'committing' = 'open'
+		let budget: Deadline | null = null
 		try {
 			const input = body.multipart === null
 				? fields
 				: this.#parts.tokens.verifyFields(served.row.input, await this.#fileInput(served, body.multipart, work), carried)
 			// The handler's time starts after the last body byte, so a slow upload does not eat it.
-			const signal = handlerSignal(request, admission.timeoutMs)
-			let result: unknown
-			try {
-				result = await runInRequest(frame, async () => {
-					const membership = this.#membershipRequest(served.row, caller, request, frame)
-					const access = await this.#access(served.row, caller, input, frame, membership)
-					const binding = this.#parts.fileKinds?.binding(work)
-					const ctx = Object.freeze({
-						principal: caller.principal,
-						requestId: frame.id,
-						signal,
-						client: requestClient(request, this.#parts.clientVouched),
-						url: this.#parts.url,
-						...access.context,
-						...this.#facilities(served.facilities, served.row, membership, access.context['target'], {
-							credential: caller.token,
-							requestId: request.headers.get(REQUEST_ID_HEADER) ?? frame.id,
-						}),
-						...(served.connect === undefined ? {} : { connect: connectContext(served.connect, frame) }),
-						...(site === undefined || invocation === null ? {} : siteContext(served.row, site, invocation, caller.subject, access.context, binding)),
-						// An export's consumer reaches its rows only, never the files of their owners.
-						...(site === undefined || invocation === null || served.readOnly === true
-							? {}
-							: { files: this.#files(served.row.id, invocation, site.kind, work) }),
-						...(served.binds === undefined || invocation === null
-							? {}
-							: { webhooks: this.#webhookBindings(served.row.id, served.binds, invocation, caller.subject) }),
-						...this.#signing(`'${served.row.id}'`, site?.declaration.signs ?? []),
-						kick: kicks.kick,
+			budget = handlerSignal(request, admission.timeoutMs)
+			const { signal } = budget
+			const answer = await enclosedAnswer(invocation, this.#hold(served.row.id, exec), async () => {
+				let result: unknown
+				try {
+					result = await runInRequest(frame, async () => {
+						const membership = this.#membershipRequest(served.row, caller, request, frame)
+						const access = await this.#access(served.row, caller, input, frame, membership)
+						const binding = this.#parts.fileKinds?.binding(work)
+						const ctx = Object.freeze({
+							principal: caller.principal,
+							requestId: frame.id,
+							signal,
+							client: requestClient(request, this.#parts.clientVouched),
+							url: this.#parts.url,
+							...access.context,
+							...this.#facilities(served.facilities, served.row, membership, access.context['target'], {
+								credential: caller.token,
+								requestId: request.headers.get(REQUEST_ID_HEADER) ?? frame.id,
+							}),
+							...this.#terminals(caller.token, request.headers.get(REQUEST_ID_HEADER) ?? frame.id),
+							...(served.connect === undefined ? {} : { connect: connectContext(served.connect, frame) }),
+							...(site === undefined || invocation === null ? {} : siteContext(served.row, site, invocation, caller.subject, access.context, binding)),
+							// An export's consumer reaches its rows only, never the files of their owners.
+							...(site === undefined || invocation === null || served.readOnly === true
+								? {}
+								: { files: this.#files(served.row.id, invocation, site.kind, work) }),
+							...(served.binds === undefined || invocation === null
+								? {}
+								: { webhooks: this.#webhookBindings(served.row.id, served.binds, invocation, caller.subject) }),
+							...this.#signing(`'${served.row.id}'`, site?.declaration.signs ?? []),
+							kick: kicks.kick,
+						})
+						const args = { input: access.input, ctx, ...(query === undefined ? {} : { query }) }
+						const egress = served.egress
+						return egress === undefined
+							? await served.handler(args)
+							: await runAsSite(`'${served.row.id}'`, egress, async () => await served.handler(args))
 					})
-					const args = { input: access.input, ctx, ...(query === undefined ? {} : { query }) }
-					const egress = served.egress
-					return egress === undefined
-						? await served.handler(args)
-						: await runAsSite(`'${served.row.id}'`, egress, async () => await served.handler(args))
-				})
-			} finally {
-				frame.end()
-			}
-			const answer = await this.#answerOf(served, result, request, work, carried)
-			outcome = 'committing'
-			await commitAnswer(invocation, signal, answer)
+				} finally {
+					frame.end()
+				}
+				const answer = await this.#answerOf(served, result, request, work, carried)
+				outcome = 'committing'
+				await commitAnswer(invocation, signal, answer)
+				return answer
+			})
 			this.#kickAll(kicks.kicked(), exec)
 			return answer
 		} finally {
+			budget?.clear()
 			await invocation?.rollback()
-			await body.multipart?.close()
 			// Only a known rollback deletes what the request staged; after a commit that may have happened, the sweep decides.
 			if (outcome === 'open') {
 				await this.#parts.fileKinds?.release(work)
@@ -671,6 +697,22 @@ export class ContractRuntime {
 		return data
 	}
 
+	/** Where an invocation of `site` reports a long hold of its transaction: `FailureReports`, its delivery kept alive like a failure's. */
+	#hold(site: string, exec: RequestExecutionContext | undefined): Hold {
+		return {
+			site,
+			held: (heldMs) => {
+				// The transaction already settled: a report that cannot be made, kept or sent never changes the answer.
+				try {
+					const delivery = this.#parts.failures.held(site, heldMs).catch(() => undefined)
+					exec?.waitUntil(delivery)
+				} catch {
+					// Dropped, like a delivery that fails.
+				}
+			},
+		}
+	}
+
 	/** The caller's authority at IAM for this request, when the endpoint's access form names a dimension and an action. */
 	#membershipRequest(row: CredentialedEndpoint, caller: Caller, request: Request, frame: RequestFrame): MembershipRequest | null {
 		const iam = this.#parts.membership
@@ -687,6 +729,12 @@ export class ContractRuntime {
 		}
 	}
 
+	/** `ctx.terminals`, with the credential IAM takes the request's application from: the caller's, or the workload's. */
+	#terminals(credential: string, requestId: string): { readonly terminals?: TerminalIdentification } {
+		const rpc = this.#parts.terminals
+		return rpc === null ? {} : { terminals: terminalIdentification(rpc, { app: this.#parts.audience, credential, requestId }) }
+	}
+
 	/** `ctx.members` and `ctx.links`, for exactly the endpoints the artifact gives them. */
 	#facilities(
 		facilities: Facilities,
@@ -755,17 +803,21 @@ export class ContractRuntime {
 		}
 	}
 
-	/** The values of `dimension` in which the caller holds `action`, directly or through a container; all for a global grant. */
+	/**
+	 * The values of `dimension` in which the caller holds `action`, directly or through a container, and its grants on the
+	 * dimensions inside it, so a list returns every row a single-object read admits (S4); all for a global grant.
+	 */
 	#within(caller: Caller, action: string, dimension: string, frame: RequestFrame): Within<string, string> {
 		const direct = scopedValues(caller.perms, action, dimension)
 		if (direct === null) {
 			return this.#parts.mint.within(frame, dimension, action, caller.subject, 'all')
 		}
 		const held = this.#heldContainers(caller.perms, action, dimension)
-		if (direct.length === 0 && held.length === 0) {
+		const inside = this.#heldContained(caller.perms, action, dimension)
+		if (direct.length === 0 && held.length === 0 && inside.length === 0) {
 			throw new ForbiddenError(`The caller holds '${action}' in no ${dimension}`)
 		}
-		return this.#parts.mint.within(frame, dimension, action, caller.subject, direct, held)
+		return this.#parts.mint.within(frame, dimension, action, caller.subject, direct, held, inside)
 	}
 
 	/** A scope value the caller acts in: without a grant on it or on a container of it, 403 whether it exists or not. */
@@ -908,7 +960,7 @@ export class ContractRuntime {
 					admission.repeatableToken,
 				)
 			}
-			return await this.#publicInvocation(served, request, body, fields, query, carried, authority.perms, exec)
+			return await this.#publicInvocation(served, request, body, fields, query, carried, authority, exec)
 		} finally {
 			await multipart?.close()
 			release()
@@ -974,9 +1026,10 @@ export class ContractRuntime {
 		fields: Readonly<Record<string, unknown>>,
 		query: Readonly<Record<string, unknown>> | undefined,
 		carried: Set<string>,
-		perms: readonly PermissionEntry[],
+		authority: { readonly perms: readonly PermissionEntry[]; readonly token: string },
 		exec: RequestExecutionContext | undefined,
 	): Promise<Response | FileDownload> {
+		const { perms } = authority
 		const kicks = kickRecorder(`'${served.row.id}'`, served.site.declaration.kicks)
 		const frame = new RequestFrame(crypto.randomUUID(), { readOnly: served.site.kind === 'query', endpoint: served.row.id })
 		const work = new FileWork(frame, frame.id)
@@ -995,55 +1048,62 @@ export class ContractRuntime {
 			return this.#parts.mint.app(frame, action, subject)
 		}
 		let outcome: 'open' | 'committing' = 'open'
+		let budget: Deadline | null = null
 		try {
 			// The file parts come after the challenge, so a refused visitor stores nothing.
 			const input = body.multipart === null
 				? fields
 				: this.#parts.tokens.verifyFields(served.row.input, await this.#fileInput(served, body.multipart, work), carried)
 			// The handler's time starts after the last body byte, so a slow upload does not eat it.
-			const signal = handlerSignal(request, served.admission.timeoutMs)
-			let result: unknown
-			try {
-				result = await runInRequest(frame, async () => {
-					const handles = invocation.handles(
-						served.site.kind,
-						served.site.declaration,
-						subject,
-						{ carried },
-						this.#parts.fileKinds?.binding(work),
-					)
-					const where = `'${served.row.id}'`
-					const ctx = Object.freeze({
-						principal: Object.freeze({ kind: 'public', endpoint: served.row.id }),
-						requestId: frame.id,
-						signal,
-						client: requestClient(request, this.#parts.clientVouched),
-						url: this.#parts.url,
-						app,
-						db: Object.freeze({ app: (action: string) => handles.app(app(action)) }),
-						...this.#signing(`'${served.row.id}'`, served.site.declaration.signs),
-						files: storedFilesHandle(this.#parts.fileKinds, work, {
-							where,
-							check: boundTo(frame, () => false, 'ctx.files'),
-							writes: served.site.kind !== 'query',
-						}),
-						kick: kicks.kick,
+			budget = handlerSignal(request, served.admission.timeoutMs)
+			const { signal } = budget
+			const answer = await enclosedAnswer(invocation, this.#hold(served.row.id, exec), async () => {
+				let result: unknown
+				try {
+					result = await runInRequest(frame, async () => {
+						const handles = invocation.handles(
+							served.site.kind,
+							served.site.declaration,
+							subject,
+							{ carried },
+							this.#parts.fileKinds?.binding(work),
+						)
+						const where = `'${served.row.id}'`
+						const ctx = Object.freeze({
+							principal: Object.freeze({ kind: 'public', endpoint: served.row.id }),
+							requestId: frame.id,
+							signal,
+							client: requestClient(request, this.#parts.clientVouched),
+							url: this.#parts.url,
+							app,
+							db: Object.freeze({ app: (action: string) => handles.app(app(action)) }),
+							...this.#signing(`'${served.row.id}'`, served.site.declaration.signs),
+							files: storedFilesHandle(this.#parts.fileKinds, work, {
+								where,
+								check: boundTo(frame, () => false, 'ctx.files'),
+								writes: served.site.kind !== 'query',
+							}),
+							...this.#terminals(authority.token, request.headers.get(REQUEST_ID_HEADER) ?? frame.id),
+							kick: kicks.kick,
+						})
+						const args = { input, ctx, ...(query === undefined ? {} : { query }) }
+						return await runAsSite(`'${served.row.id}'`, served.site.declaration.egress, async () => await served.handler(args))
 					})
-					const args = { input, ctx, ...(query === undefined ? {} : { query }) }
-					return await runAsSite(`'${served.row.id}'`, served.site.declaration.egress, async () => await served.handler(args))
-				})
-			} finally {
-				frame.end()
-			}
-			const output = served.row.output
-			const answer = output !== null && isFileShape(output)
-				? await this.#fileKinds(served.row.id).download(work, served.row.id, output.kind, result)
-				: outputResponse(served.row, served.output, result, request, carried)
-			outcome = 'committing'
-			await commitAnswer(invocation, signal, answer)
+				} finally {
+					frame.end()
+				}
+				const output = served.row.output
+				const answer = output !== null && isFileShape(output)
+					? await this.#fileKinds(served.row.id).download(work, served.row.id, output.kind, result)
+					: outputResponse(served.row, served.output, result, request, carried)
+				outcome = 'committing'
+				await commitAnswer(invocation, signal, answer)
+				return answer
+			})
 			this.#kickAll(kicks.kicked(), exec)
 			return answer
 		} finally {
+			budget?.clear()
 			await invocation.rollback()
 			if (outcome === 'open') {
 				await this.#parts.fileKinds?.release(work)
@@ -1066,7 +1126,7 @@ export class ContractRuntime {
 	): Promise<Response> {
 		admitContentType(served.row, request)
 		const limit = maxBytesOf(served.row)
-		const body = await readBoundedBody(request, limit, AbortSignal.timeout(bodyDeadlineMs(limit)))
+		const body = await readBodyInTime(request, limit)
 		const tables = this.#framework().webhooks
 		const bindingId = params[WEBHOOK_BINDING_PARAMETER] ?? ''
 		const binding = BINDING_ID.test(bindingId) ? await tables.binding(served.webhook, bindingId) : null
@@ -1130,60 +1190,63 @@ export class ContractRuntime {
 		// The claim stays outside the delivery's transaction, and its completion commits inside it, with the work.
 		const invocation = site === undefined ? null : new Invocation(frame, this.#data(), false)
 		const kicks = kickRecorder(`webhook '${served.webhook}'`, site?.kicks ?? [])
-		const signal = handlerSignal(request, budgetMs)
+		const budget = handlerSignal(request, budgetMs)
+		const { signal } = budget
 		let committing = false
 		try {
-			try {
-				await runInRequest(frame, async () => {
-					const subject = webhookSubject(binding.id)
-					const reach = this.#webhookReach(served, frame, subject, binding.scope.value, chain)
-					const principal: WebhookPrincipal = Object.freeze({ kind: 'webhook', bindingId: binding.id })
-					const delivery = Object.freeze({ key })
-					const handles = site === undefined || invocation === null
-						? null
-						: invocation.handles('mutation', site, subject, 'declared', this.#parts.fileKinds?.binding(work))
-					const data = site === undefined || invocation === null || handles === null
-						? {}
-						: {
-							db: siteData(handles, (action) => handles.app(reach.app(action))),
-							sql: site.sql === null ? undeclaredSql(served.row.id, 'mutation') : invocation.sql(site.sql),
-						}
-					const client = requestClient(request, this.#parts.clientVouched)
-					const args = {
-						input,
-						ctx: Object.freeze({
-							principal,
-							requestId: frame.id,
-							signal,
-							client,
-							url: this.#parts.url,
-							...reach.context,
-							delivery,
-							files: storedFilesHandle(this.#parts.fileKinds, work, {
-								where: `webhook '${served.webhook}'`,
-								check: boundTo(frame, () => false, 'ctx.files'),
-								writes: true,
+			await enclosed(invocation, this.#hold(served.row.id, exec), async () => {
+				try {
+					await runInRequest(frame, async () => {
+						const subject = webhookSubject(binding.id)
+						const reach = this.#webhookReach(served, frame, subject, binding.scope.value, chain)
+						const principal: WebhookPrincipal = Object.freeze({ kind: 'webhook', bindingId: binding.id })
+						const delivery = Object.freeze({ key })
+						const handles = site === undefined || invocation === null
+							? null
+							: invocation.handles('mutation', site, subject, 'declared', this.#parts.fileKinds?.binding(work))
+						const data = site === undefined || invocation === null || handles === null
+							? {}
+							: {
+								db: siteData(handles, (action) => handles.app(reach.app(action))),
+								sql: site.sql === null ? undeclaredSql(served.row.id, 'mutation') : invocation.sql(site.sql),
+							}
+						const client = requestClient(request, this.#parts.clientVouched)
+						const args = {
+							input,
+							ctx: Object.freeze({
+								principal,
+								requestId: frame.id,
+								signal,
+								client,
+								url: this.#parts.url,
+								...reach.context,
+								delivery,
+								files: storedFilesHandle(this.#parts.fileKinds, work, {
+									where: `webhook '${served.webhook}'`,
+									check: boundTo(frame, () => false, 'ctx.files'),
+									writes: true,
+								}),
+								...this.#signing(`webhook '${served.webhook}'`, site?.signs ?? []),
+								kick: kicks.kick,
+								...data,
 							}),
-							...this.#signing(`webhook '${served.webhook}'`, site?.signs ?? []),
-							kick: kicks.kick,
-							...data,
-						}),
-					}
-					if (site === undefined) {
-						await served.handler(args)
-					} else {
-						await runAsSite(`webhook '${served.webhook}'`, site.egress, async () => await served.handler(args))
-					}
-				})
-			} finally {
-				frame.end()
-			}
-			const using = invocation === null ? undefined : await invocation.frameworkSite('the delivery claim').session()
-			if (!(await tables.completeDelivery(claim, using))) {
-				throw new ServerFault('webhook_claim_lost', `the claim of a delivery to '${served.webhook}' expired and another copy took it over`)
-			}
-			committing = true
-			await invocation?.commit(signal)
+						}
+						if (site === undefined) {
+							await served.handler(args)
+						} else {
+							await runAsSite(`webhook '${served.webhook}'`, site.egress, async () => await served.handler(args))
+						}
+					})
+				} finally {
+					frame.end()
+				}
+				const using = invocation === null ? undefined : await invocation.frameworkSite('the delivery claim').session()
+				if (!(await tables.completeDelivery(claim, using))) {
+					throw new ServerFault('webhook_claim_lost', `the claim of a delivery to '${served.webhook}' expired and another copy took it over`)
+				}
+				committing = true
+				await invocation?.commit(signal)
+			})
 			this.#kickAll(kicks.kicked(), exec)
 		} catch (error) {
 			await invocation?.rollback()
@@ -1196,6 +1259,8 @@ export class ContractRuntime {
 			console.error(`fabrika: ${served.row.id}: delivery_failed; the provider's redelivery runs it again`)
 			await tables.releaseDelivery(claim)
 			throw error
+		} finally {
+			budget.clear()
 		}
 		return jsonResponse({ result: { received: true } }, 200)
 	}
@@ -1257,6 +1322,14 @@ export class ContractRuntime {
 			return values.length === 0 ? [] : [{ dimension: container, values }]
 		})
 	}
+
+	/** The caller's grants of `action` on every dimension that lies inside `dimension`. */
+	#heldContained(perms: PermissionEntry[], action: string, dimension: string): ContainerGrant[] {
+		return [...this.#parts.containers].flatMap(([inner, containers]) => {
+			const values = containers.includes(dimension) ? scopedValues(perms, action, inner) ?? [] : []
+			return values.length === 0 ? [] : [{ dimension: inner, values }]
+		})
+	}
 }
 
 /** `ctx.db` (by the access form) and `ctx.sql` of a staged-kit endpoint: the declared tag, or one that refuses. */
@@ -1475,7 +1548,7 @@ async function readInput(
 		const limit = served.row.admission?.maxBytes ?? null
 		const text = limit === null
 			? await request.text()
-			: new TextDecoder().decode(await readBoundedBody(request, limit, AbortSignal.timeout(bodyDeadlineMs(limit))))
+			: new TextDecoder().decode(await readBodyInTime(request, limit))
 		if (mediaType(request.headers.get('Content-Type')) === FORM_URLENCODED_TYPE) {
 			body = paramsObject(new URLSearchParams(text), served.row.input)
 		} else if (text.trim() !== '') {
@@ -1547,16 +1620,17 @@ async function openMultipart(
 	if (Number.isFinite(declared) && declared > bodyBytes) {
 		throw tooLarge()
 	}
-	const deadline = AbortSignal.any([request.signal, AbortSignal.timeout(bodyDeadlineMs(maxBytes))])
+	const timer = deadline(bodyDeadlineMs(maxBytes), request.signal)
 	const body = boundedStream(request.body ?? new Blob([]).stream(), bodyBytes)
 	const parts = multipartParts(body.stream, boundary, { maxHeaderBytes: PROCEDURE_LIMITS.maxPartHeaderBytes })
-	const failure = (error: unknown) => (body.exceeded() ? tooLarge() : multipartFailure(error, parts, deadline, request))
+	const failure = (error: unknown) => (body.exceeded() ? tooLarge() : multipartFailure(error, parts, timer.signal, request))
 	const stop = () => {
 		parts.cancel().catch(() => {})
 	}
-	deadline.addEventListener('abort', stop, { once: true })
+	timer.signal.addEventListener('abort', stop, { once: true })
 	const close = async () => {
-		deadline.removeEventListener('abort', stop)
+		timer.signal.removeEventListener('abort', stop)
+		timer.clear()
 		await parts.cancel()
 	}
 	let json: Readonly<Record<string, unknown>>
@@ -1617,6 +1691,36 @@ async function openMultipart(
 	}
 }
 
+/** The site an invocation's long hold is logged under, and where it is reported. */
+interface Hold {
+	readonly site: string
+	readonly held: (heldMs: number) => void
+}
+
+/** Runs `work` in the invocation's transaction (`Invocation.enclose`), or as is without one. */
+function enclosed<T>(invocation: Invocation | null, hold: Hold, work: () => Promise<T>): Promise<T> {
+	return invocation === null ? work() : invocation.enclose(work, hold.site, hold.held)
+}
+
+/**
+ * An answer's work, from the handler to its commit, in the invocation's transaction. Where the transaction encloses
+ * the work (SQLite) its COMMIT runs after `commitAnswer`, so a failed one cancels a file's object stream here.
+ */
+async function enclosedAnswer<A extends Response | FileDownload>(invocation: Invocation | null, hold: Hold, work: () => Promise<A>): Promise<A> {
+	let answer: A | undefined
+	try {
+		return await enclosed(invocation, hold, async () => {
+			answer = await work()
+			return answer
+		})
+	} catch (error) {
+		if (answer instanceof FileDownload) {
+			await answer.body.cancel()
+		}
+		throw error
+	}
+}
+
 /**
  * Commits the invocation of an answer that is ready: a file's object stream was opened before the commit, so a failed
  * commit cancels it and nothing of it is sent.

package/src/implement/failures.ts

@@ -2,7 +2,7 @@
 // fixed codes and bounded identifiers only, never an error's name or message: application code, drivers and even the
 // framework's own refusals can put request data there. The event adds what was thrown as its cause chain, scrubbed of
 // the environment's secrets and of credential patterns, a framework failure's message replaced by its catalog text
-// (ADR-0059).
+// (ADR-0059). A writing invocation that held its Durable Object's transaction too long is an event on the same budget.
 
 import { CAPABILITY_ERRORS, CapabilityError, QUERY_REFUSALS, QueryRefusedError } from '@fabrika/db/framework'
 import { isStructuralError } from '../errors'
@@ -127,4 +127,20 @@ export class FailureReports {
 			error: failure.error,
 		})
 	}
+
+	/**
+	 * A writing invocation that held its object's transaction past `@fabrika/db`'s report threshold, which already
+	 * logged it. Never rejects; the delivery may outlive the response like a failure's.
+	 */
+	held(endpoint: string, heldMs: number): Promise<void> {
+		if (this.#reporter === null || !this.#budget.admit()) {
+			return Promise.resolve()
+		}
+		return this.#reporter.report({
+			fingerprint: ['fabrika-transaction-held', endpoint],
+			type: 'TransactionHeld',
+			message: `endpoint '${endpoint}' held its object's transaction for ${heldMs} ms`,
+			tags: { endpoint, code: 'transaction_held', held_ms: String(heldMs) },
+		})
+	}
 }

package/src/implement/faults.ts

@@ -19,6 +19,7 @@ export const SERVER_FAULTS = {
 	webhook_unverifiable: 'a webhook verifies a signature over its public URL (Twilio), and the environment has no FABRIKA_APP_ORIGIN',
 	webhook_claim_lost: "a delivery's claim expired and another copy of the delivery took it over before this one committed; nothing it wrote is kept",
 	workload_unauthorized: "the workload's key or token does not carry the authority its declaration needs",
+	terminal_refused: "IAM refused the application's own credential for an identification at a terminal",
 	request_cancelled: 'the request was cancelled or outlived its budget before its transaction committed; nothing it wrote is kept',
 	file_object_missing: "a file's object is missing from storage",
 	file_object_mismatch: "a file's object has another size than its row records",

package/src/implement/index.ts

@@ -53,6 +53,7 @@ export type {
 } from './membership'
 export type { AppPrincipal, LinkHolder, Principal, PrincipalOf, PublicPrincipal, ServicePrincipal, UserPrincipal } from './principal'
 export { type AppDeps, defineDeps, serve, type ServeOptions } from './serve'
+export type { AssertedIdentity, OpenIdentification, TerminalIdentification } from './terminals'
 export type {
 	AccessContext,
 	ConnectCall,

package/src/implement/invocation.ts

@@ -321,6 +321,14 @@ export class Invocation {
 		return { check: boundTo(this.#frame, () => transaction.ended, handle), session: () => transaction.session() }
 	}
 
+	/**
+	 * Runs `work`, from the handler to `commit`, in this invocation's transaction. On SQLite it encloses `work`, and a
+	 * hold past `@fabrika/db`'s report threshold reaches `held`, logged under `site`.
+	 */
+	enclose<T>(work: () => Promise<T>, site: string, held: (heldMs: number) => void): Promise<T> {
+		return this.#transaction.enclose(work, { site, held })
+	}
+
 	/** Commits; a request the caller abandoned meanwhile rolls back instead. */
 	async commit(signal: AbortSignal | null): Promise<void> {
 		if (signal?.aborted === true) {