@fabrika/db 0.6.0 → 0.7.0

package/src/orm.ts

@@ -10,8 +10,25 @@ import { type CapabilityGrant, describeGrant, type RefGrant } from './capability
 import type { InvocationTransaction, Session } from './database'
 import { columnOf, type Compare, type Contains, parseCondition, type Primitive, type SelectState, type TableShape } from './description'
 import { CapabilityError, NotFoundError, type QueryRefusal, QueryRefusedError } from './errors'
+import { answerFiles, type FileBinding } from './file-columns'
+import { databaseNow } from './job-leases'
 import { linksPredicate, linkValues } from './links'
-import { aggregateNode, allOf, anyOf, column, cursorAlias, equals, everything, lockedSelectNode, selectNode, withCursorColumns } from './nodes'
+import {
+	aggregateNode,
+	allOf,
+	anyOf,
+	claimNode,
+	column,
+	cursorAlias,
+	equals,
+	everything,
+	inList,
+	lockedSelectNode,
+	scopedWhere,
+	selectNode,
+	updateNode,
+	withCursorColumns,
+} from './nodes'
 import type { DataKind, TargetForm, UnscopedMode } from './orm-types'
 import { modelOf, namesAction, type TableModels, updatableBy, visibleFor } from './policy'
 import { type SqlSite, type SqlTag, sqlTag } from './sql'
@@ -19,21 +36,26 @@ import {
 	actionShape,
 	aggregateRows,
 	type AggregateSpec,
+	answer,
 	appKeyPredicate,
 	appListPredicate,
 	appRecordPredicate,
 	appRowPredicate,
 	childObjectPredicate,
 	childScope,
+	claimedRowPredicate,
+	claimScope,
 	type DataLayerRuntime,
-	insertIntoApplication,
-	insertIntoChild,
-	insertIntoDimension,
+	heldAction,
+	insertPrepared,
 	insertRow,
 	keyOf,
 	objectPredicate,
 	ownerOf,
 	parentPredicate,
+	prepareApplicationInsert,
+	prepareChildInsert,
+	prepareDimensionInsert,
 	reachColumn,
 	reachPredicate,
 	readValues,
@@ -50,7 +72,7 @@ import {
 	updatingRef,
 	versionArgument,
 } from './store'
-import { answerDays } from './temporal'
+import { answerDays, timestampInput } from './temporal'
 
 /** A list page holds this many rows unless the caller asks for fewer, and never more than `MAX_LIST_LIMIT`. */
 export const DEFAULT_LIST_LIMIT = 50
@@ -67,6 +89,21 @@ export interface DataSite {
 	readonly unscoped: Readonly<Record<string, UnscopedMode>>
 	/** Who an unscoped insert is stamped with (`createdBy`): no capability carries a principal for it. */
 	readonly principal: string
+	/** A job's schedule period, in ms: a queue claim's first backoff, doubled at each later claim of the row. */
+	readonly tickMs?: number
+	/**
+	 * A public procedure, which anyone calls: its `ctx.db.app` inserts and reads nothing back, reads only under a table's
+	 * read action, and reaches application tables only. It updates or removes only a versioned row whose id a verified
+	 * signed token of its request carries (`carried`); it never locks or claims a row.
+	 */
+	readonly public?: true
+	/**
+	 * Where the site's file references belong: each file column it reads answers one, and a file column it writes takes
+	 * only one it holds. Absent where the framework serves no file; the columns then read as ids and refuse every write.
+	 */
+	readonly files?: FileBinding
+	/** The texts the verified signed tokens of a public procedure's request carry: the row ids it may update or remove. */
+	readonly carried?: ReadonlySet<string>
 	/** Throws unless the work running now is the invocation these handles were made for. */
 	check(): void
 	/** The session every statement of the site runs in. */
@@ -144,6 +181,7 @@ function runnerOf(site: DataSite): Runner {
 	return {
 		read: () => site.session(),
 		write: async (work) => work(await site.session()),
+		...(site.files === undefined ? {} : { files: site.files }),
 	}
 }
 
@@ -234,6 +272,9 @@ function addTable(handle: Record<string, unknown>, table: string, rows: object):
 
 function scopeTarget(parts: DataLayerParts, site: DataSite, run: Runner, capability: unknown, form: TargetForm): object {
 	const grant = resolved(parts, capability)
+	if (grant.kind === 'row' && form === 'on') {
+		return claimedRow(parts.contextOf(grant.table), site, run, capability)
+	}
 	if (grant.kind !== 'ref') {
 		throw new CapabilityError('wrong_capability', 'ctx.db.target is built from a Ref; an over endpoint lists through ctx.db.within')
 	}
@@ -282,7 +323,7 @@ function targetRow(
 	const onOnly = (operation: string) => `${operation} acts on one object: declare access with on`
 	const get = bound(site, async () => {
 		const grant = namedRef(context, capability, dimension)
-		return selectOne(context, run, targetPredicate(context, grant), visibleFor(context.model, grant.action))
+		return selectOne(context, run, targetPredicate(context, grant), visibleFor(context.model, grant.action), grant.action)
 	})
 	const lock = bound(site, async () => {
 		const grant = namedRef(context, capability, dimension)
@@ -294,6 +335,7 @@ function targetRow(
 		if (row === undefined) {
 			throw new NotFoundError(`${context.model.name} not found`)
 		}
+		await answerFiles(context.model, run.files, session, [row], grant.action)
 		return row
 	})
 	const getForUpdate = site.kind === 'job'
@@ -326,7 +368,7 @@ function childRows(context: TableContext, site: DataSite, run: Runner, capabilit
 	return freeze({
 		list: bound(site, async (options?: unknown) => {
 			const grant = namedRef(context, capability, parent)
-			return listRows(context, run, parentPredicate(context, grant), visibleFor(context.model, grant.action), options, [key])
+			return listRows(context, run, parentPredicate(context, grant), visibleFor(context.model, grant.action), options, [key], grant.action)
 		}),
 		get: bound(site, async (id: unknown) => {
 			const grant = namedRef(context, capability, parent)
@@ -334,9 +376,13 @@ function childRows(context: TableContext, site: DataSite, run: Runner, capabilit
 				throw new QueryRefusedError('row_address', `a ${context.model.name} row is addressed by its ${key}, a non-empty string`)
 			}
 			const scope = allOf([equals(context.model.name, key, id), parentPredicate(context, grant)])
-			return selectOne(context, run, scope, visibleFor(context.model, grant.action))
+			return selectOne(context, run, scope, visibleFor(context.model, grant.action), grant.action)
 		}),
-		insert: writing(site, 'insert', async (values: unknown) => insertIntoChild(context, run, capability, values)),
+		insert: writing(
+			site,
+			'insert',
+			async (values: unknown, options?: unknown) => insertPrepared(context, run, prepareChildInsert(context, capability, values, options)),
+		),
 		update: writing(site, 'update', async (id: unknown, values: unknown, ...options: unknown[]) => {
 			if (typeof id !== 'string' || id.length === 0) {
 				throw new QueryRefusedError('row_address', `a ${context.model.name} row is addressed by its parent Ref and its ${key}`)
@@ -358,15 +404,25 @@ function containedRows(context: TableContext, site: DataSite, run: Runner, capab
 		list: bound(site, async (options?: unknown) => {
 			const grant = namedRef(context, capability, dimension)
 			const scope = linksPredicate(context.model.name, linkValues(context.model.name, context.model.chain, grant))
-			return listRows(context, run, scope, visibleFor(context.model, grant.action), options, [keyOf(context.model)])
+			return listRows(context, run, scope, visibleFor(context.model, grant.action), options, [keyOf(context.model)], grant.action)
 		}),
-		insert: writing(site, 'insert', async (values: unknown) => insertIntoDimension(context, run, capability, values)),
+		insert: writing(
+			site,
+			'insert',
+			async (values: unknown, options?: unknown) => insertPrepared(context, run, prepareDimensionInsert(context, capability, values, options)),
+		),
 	})
 }
 
 /** A top-level scope's own row, keyed by the scope's value: what an `in` or `creates` endpoint inserts. */
 function ownerRow(context: TableContext, site: DataSite, run: Runner, capability: unknown): object {
-	return freeze({ insert: writing(site, 'insert', async (values: unknown) => insertIntoDimension(context, run, capability, values)) })
+	return freeze({
+		insert: writing(
+			site,
+			'insert',
+			async (values: unknown, options?: unknown) => insertPrepared(context, run, prepareDimensionInsert(context, capability, values, options)),
+		),
+	})
 }
 
 function withinTables(parts: DataLayerParts, site: DataSite, run: Runner, capability: unknown): object {
@@ -381,20 +437,40 @@ function withinTables(parts: DataLayerParts, site: DataSite, run: Runner, capabi
 		const listable = model?.scope.mode === 'dimension' || model?.scope.mode === 'child'
 		if (model !== undefined && listable && reachColumn(model, grant.dimension) !== undefined) {
 			const context = parts.contextOf(model.name)
-			setOwn(handle, model.name, listedRows(context, site, run, () => reachPredicate(context, capability)))
+			setOwn(handle, model.name, listedRows(parts, context, site, run, capability, () => reachPredicate(context, capability)))
 		}
 	}
 	return freeze(handle)
 }
 
-/** A table read through a `Within` by its read action: `undefined` from `scope` is an empty `Within`, which reads nothing. */
-function listedRows(context: TableContext, site: DataSite, run: Runner, scope: () => OperationNode | undefined): object {
-	const visible = context.model.visible
+/**
+ * A table read through a `Within` by one of its read actions, with the columns that action reads: `undefined` from
+ * `scope` is an empty `Within`, which reads nothing.
+ */
+function listedRows(
+	parts: DataLayerParts,
+	context: TableContext,
+	site: DataSite,
+	run: Runner,
+	capability: unknown,
+	scope: () => OperationNode | undefined,
+): object {
 	const key = [keyOf(context.model)]
+	const visible = () => visibleFor(context.model, heldAction(context, capability))
 	return freeze({
-		list: bound(site, async (options?: unknown) => listRows(context, run, scope(), visible, options, key)),
-		count: bound(site, async (options?: unknown) => countRows(context, run, scope(), visible, options)),
-		aggregate: bound(site, async <Row>(spec: AggregateSpec<Row>) => aggregateRows(context, run, scope(), context.shape, spec)),
+		claim: claiming(parts, context, site, capability),
+		list: bound(site, async (options?: unknown) => {
+			const predicate = scope()
+			return listRows(context, run, predicate, visible(), options, key, heldAction(context, capability))
+		}),
+		count: bound(site, async (options?: unknown) => {
+			const predicate = scope()
+			return countRows(context, run, predicate, visible(), options)
+		}),
+		aggregate: bound(site, async <Row>(spec: AggregateSpec<Row>) => {
+			const predicate = scope()
+			return aggregateRows(context, run, predicate, actionShape(context.model, visible()), spec)
+		}),
 	})
 }
 
@@ -412,8 +488,9 @@ function applicationTables(parts: DataLayerParts, site: DataSite, run: Runner, c
 		}
 		const context = parts.contextOf(model.name)
 		if (model.scope.mode === 'app') {
-			setOwn(handle, model.name, applicationRows(context, site, run, capability))
-		} else if (model.scope.mode === 'dimension' || model.scope.mode === 'child') {
+			const rows = applicationRows(parts, context, site, run, capability)
+			setOwn(handle, model.name, site.public === true ? publicApplicationRows(context, site, run, capability, rows) : freeze(rows))
+		} else if (site.public !== true && (model.scope.mode === 'dimension' || model.scope.mode === 'child')) {
 			setOwn(handle, model.name, appRecordRows(context, site, run, capability, grant.action))
 		}
 	}
@@ -430,7 +507,10 @@ function appRecordRows(context: TableContext, site: DataSite, run: Runner, capab
 	const shape = actionShape(context.model, visible)
 	const key = [keyOf(context.model)]
 	return freeze({
-		list: bound(site, async (options?: unknown) => listRows(context, run, appRecordPredicate(context, capability, 'rows'), visible, options, key)),
+		list: bound(
+			site,
+			async (options?: unknown) => listRows(context, run, appRecordPredicate(context, capability, 'rows'), visible, options, key, action),
+		),
 		count: bound(site, async (options?: unknown) => countRows(context, run, appRecordPredicate(context, capability, 'counts'), visible, options)),
 		aggregate: bound(
 			site,
@@ -459,12 +539,12 @@ function scopedApplicationRows(context: TableContext, site: DataSite, run: Runne
 	const key = [keyOf(model)]
 	const scope = () => scopedApplicationRead(context, capability)
 	return freeze({
-		list: bound(site, async (options?: unknown) => listRows(context, run, scope(), visible, options, key)),
+		list: bound(site, async (options?: unknown) => listRows(context, run, scope(), visible, options, key, heldAction(context, capability))),
 		count: bound(site, async (options?: unknown) => countRows(context, run, scope(), visible, options)),
 		aggregate: bound(site, async <Row>(spec: AggregateSpec<Row>) => aggregateRows(context, run, scope(), context.shape, spec)),
 		get: bound(site, async (id: unknown) => {
 			scope()
-			return selectOne(context, run, appKeyPredicate(model, id), visible)
+			return selectOne(context, run, appKeyPredicate(model, id), visible, heldAction(context, capability))
 		}),
 	})
 }
@@ -489,10 +569,16 @@ function namedApp(context: TableContext, capability: unknown): string {
  * An application table under an `app` capability: listed, counted and aggregated with its read action; one row read
  * (and locked) with any action it names; inserted, updated and removed with that operation's action.
  */
-function applicationRows(context: TableContext, site: DataSite, run: Runner, capability: unknown): object {
+function applicationRows(
+	parts: DataLayerParts,
+	context: TableContext,
+	site: DataSite,
+	run: Runner,
+	capability: unknown,
+): Readonly<Record<string, unknown>> {
 	const model = context.model
 	const table = model.name
-	const visible = model.visible
+	const visible = () => visibleFor(model, heldAction(context, capability))
 	const key = [keyOf(model)]
 	const getForUpdate = site.kind === 'job'
 		? refused(site, 'read_only', 'a job writes inside ctx.transaction((tx) => …): use tx.db there')
@@ -500,27 +586,39 @@ function applicationRows(context: TableContext, site: DataSite, run: Runner, cap
 		? refused(site, 'read_only', 'getForUpdate locks the row, so it runs only in a mutation: declare the endpoint with r.mutation')
 		: bound(site, async (id: unknown) => {
 			const scope = appKeyPredicate(model, id)
-			const node = lockedSelectNode(table, visibleFor(model, namedApp(context, capability)), scope, model.dates)
-			const rows = await (await run.read()).run(node, { root: 'SelectQueryNode', table, joins: {}, scope, lock: 'update' })
+			const action = namedApp(context, capability)
+			const node = lockedSelectNode(table, visibleFor(model, action), scope, model.dates)
+			const session = await run.read()
+			const rows = await session.run(node, { root: 'SelectQueryNode', table, joins: {}, scope, lock: 'update' })
 			const [row] = answerDays(table, model.dates, rows)
 			if (row === undefined) {
 				throw new NotFoundError(`${table} not found`)
 			}
+			await answerFiles(model, run.files, session, [row], action)
 			return row
 		})
-	return freeze({
-		list: bound(site, async (options?: unknown) => listRows(context, run, appListPredicate(context, capability), visible, options, key)),
-		count: bound(site, async (options?: unknown) => countRows(context, run, appListPredicate(context, capability), visible, options)),
+	return {
+		list: bound(
+			site,
+			async (options?: unknown) =>
+				listRows(context, run, appListPredicate(context, capability), visible(), options, key, heldAction(context, capability)),
+		),
+		count: bound(site, async (options?: unknown) => countRows(context, run, appListPredicate(context, capability), visible(), options)),
 		aggregate: bound(
 			site,
-			async <Row>(spec: AggregateSpec<Row>) => aggregateRows(context, run, appListPredicate(context, capability), context.shape, spec),
+			async <Row>(spec: AggregateSpec<Row>) => aggregateRows(context, run, appListPredicate(context, capability), actionShape(model, visible()), spec),
 		),
 		get: bound(site, async (id: unknown) => {
 			const action = namedApp(context, capability)
-			return selectOne(context, run, appKeyPredicate(model, id), visibleFor(model, action))
+			return selectOne(context, run, appKeyPredicate(model, id), visibleFor(model, action), action)
 		}),
 		getForUpdate,
-		insert: writing(site, 'insert', async (values: unknown) => insertIntoApplication(context, run, capability, values)),
+		claim: claiming(parts, context, site, capability),
+		insert: writing(
+			site,
+			'insert',
+			async (values: unknown, options?: unknown) => insertPrepared(context, run, prepareApplicationInsert(context, capability, values, options)),
+		),
 		update: writing(site, 'update', async (id: unknown, values: unknown, ...options: unknown[]) => {
 			const grant = updatingApp(context, capability)
 			const changes = readValues(values, updatableBy(model, grant.action), 'update', model)
@@ -529,9 +627,260 @@ function applicationRows(context: TableContext, site: DataSite, run: Runner, cap
 		remove: writing(site, 'remove', async (id: unknown, ...options: unknown[]) => {
 			await removeRow(context, run, { scope: appRowPredicate(context, capability, id, 'delete') }, versionArgument(context, options))
 		}),
+	}
+}
+
+/**
+ * An application table of a public procedure: listed, counted, aggregated and read by key under its read action only;
+ * inserted with only the new key and version answered; updated or removed only by an id a verified signed token of the
+ * request carries, under `expectVersion`, answering only the new version; never locked or claimed.
+ */
+function publicApplicationRows(
+	context: TableContext,
+	site: DataSite,
+	run: Runner,
+	capability: unknown,
+	rows: Readonly<Record<string, unknown>>,
+): object {
+	const model = context.model
+	const refusal = (operation: string) =>
+		refused(site, 'public_reach', `a public procedure does not ${operation} a ${model.name} row: it inserts, and reads under the read action`)
+	/** A row a public procedure may change: one a verified token names, of a table whose rows carry a version. */
+	const tokenRow = (operation: string, id: unknown): void => {
+		if (model.version === undefined) {
+			throw new QueryRefusedError('public_reach', `a public procedure ${operation}s only a versioned row, and ${model.name} declares no version`)
+		}
+		if (typeof id !== 'string' || site.carried?.has(id) !== true) {
+			throw new QueryRefusedError(
+				'public_reach',
+				`a public procedure ${operation}s a ${model.name} row only by an id a verified signed token of its request carries`,
+			)
+		}
+	}
+	return freeze({
+		list: rows['list'],
+		count: rows['count'],
+		aggregate: rows['aggregate'],
+		get: bound(site, async (id: unknown) => {
+			appListPredicate(context, capability)
+			const action = heldAction(context, capability)
+			return selectOne(context, run, appKeyPredicate(model, id), visibleFor(model, action), action)
+		}),
+		getForUpdate: refusal('lock'),
+		claim: refusal('claim'),
+		update: writing(site, 'update', async (id: unknown, values: unknown, ...options: unknown[]) => {
+			tokenRow('update', id)
+			const grant = updatingApp(context, capability)
+			const changes = readValues(values, updatableBy(model, grant.action), 'update', model)
+			const saved = await updateRow<Readonly<Record<string, unknown>>>(
+				context,
+				run,
+				{ scope: appKeyPredicate(model, id) },
+				changes,
+				versionArgument(context, options),
+			)
+			return freeze({ version: saved['version'] })
+		}),
+		remove: writing(site, 'remove', async (id: unknown, ...options: unknown[]) => {
+			tokenRow('remove', id)
+			await removeRow(context, run, { scope: appRowPredicate(context, capability, id, 'delete') }, versionArgument(context, options))
+		}),
+		insert: bound(site, async (values: unknown, options?: unknown) => {
+			const prepared = prepareApplicationInsert(context, capability, values, options)
+			if (prepared.conflict !== undefined && prepared.conflict.mode !== 'nothing') {
+				throw new QueryRefusedError('public_reach', `a public procedure's insert into ${model.name} takes onConflict do: 'nothing' only`)
+			}
+			return insertPrepared(context, run, prepared)
+		}),
+	})
+}
+
+// ── Queues: a claim's lease, then each row finished through its row.ref ───────────────────────────────────────────────
+
+/** A claim's first backoff where the site names no schedule period: one minute, the shortest cron period. */
+const DEFAULT_TICK_MS = 60_000
+/** The longest backoff: past it the doubling stops, so a row with many attempts is still due within a month. */
+const MAX_BACKOFF_MS = 30 * 24 * 60 * 60_000
+
+/** The backoff after a row's `attempts`-th claim: one tick, doubling with each further claim. */
+function backoffMs(tickMs: number, attempts: number): number {
+	let backoff = tickMs
+	for (let claim = 1; claim < attempts && backoff < MAX_BACKOFF_MS; claim++) {
+		backoff *= 2
+	}
+	return Math.min(backoff, MAX_BACKOFF_MS)
+}
+
+/** `claim`, where the site may lease: a job outside its transaction. Inside one a failure would roll the lease back. */
+function claiming(parts: DataLayerParts, context: TableContext, site: DataSite, capability: unknown): (options?: unknown) => Promise<unknown> {
+	if (site.kind === 'query') {
+		return refused(site, 'claim_site', 'claim leases rows, so it runs only in a job')
+	}
+	if (site.kind === 'mutation') {
+		return refused(
+			site,
+			'claim_site',
+			'claim leases rows in a transaction of its own: a job calls it on ctx.db before ctx.transaction, never inside one or in a request',
+		)
+	}
+	return bound(site, (options?: unknown) => claimRows(parts, context, site, capability, options))
+}
+
+/**
+ * Leases up to `limit` due rows in a transaction of its own, fenced by the job attempt's lease: each claimed row's
+ * attempts grow by one and its `due` moves by the backoff, so a failure or a crash leaves it due again later. Answers
+ * each row with the columns the capability's action reads, its new version and attempts, and its `ref`.
+ */
+async function claimRows(
+	parts: DataLayerParts,
+	context: TableContext,
+	site: DataSite,
+	capability: unknown,
+	input: unknown,
+): Promise<readonly Readonly<Record<string, unknown>>[]> {
+	const model = context.model
+	const table = model.name
+	const { grant, scope } = claimScope(context, capability)
+	const queue = model.queue
+	const version = model.version
+	if (queue === undefined || version === undefined) {
+		throw new CapabilityError('undeclared_operation', `${table} is not a queue table: its policy declares no queue`)
+	}
+	const options = readOptions(input, ['limit', 'where'], 'claim')
+	if (options['limit'] === undefined) {
+		throw new QueryRefusedError('list_page', 'claim takes { limit }: attempts count claims, so claim only what the run will reach')
+	}
+	const limit = limitOf(options['limit'])
+	const visible = visibleFor(model, grant.action)
+	const conditions = conditionsOf(actionShape(model, visible), options['where'])
+	if (scope === undefined) {
+		return []
+	}
+	const key = keyOf(model)
+	const chain = model.chain.map((link) => link.column)
+	const selected = namesOf(nameSet([...visible, key, version, queue.attempts, ...chain]))
+	const tickMs = site.tickMs ?? DEFAULT_TICK_MS
+	const order = [{ column: queue.due, direction: 'asc' as const }, { column: key, direction: 'asc' as const }]
+	const leased = await parts.fenced(parts.runtime(), async (session) => {
+		const now = await databaseNow(session)
+		const node = claimNode(
+			rowState(table, conditions, order, limit),
+			selected,
+			{ due: queue.due, attempts: queue.attempts, now, maxAttempts: queue.maxAttempts },
+			scope,
+			model.dates,
+		)
+		const rows = await session.run<Readonly<Record<string, unknown>>>(node, { root: 'SelectQueryNode', table, joins: {}, scope, lock: 'claim' })
+		const byAttempts = new Map<number, string[]>()
+		for (const row of rows) {
+			const attempts = row[queue.attempts]
+			const id = row[key]
+			if (typeof attempts !== 'number' || !isSafeInteger(attempts) || typeof id !== 'string') {
+				throw new QueryRefusedError('unexpected_row', `${table}.${queue.attempts} must be an integer and ${table}.${key} text`)
+			}
+			byAttempts.set(attempts, [...(byAttempts.get(attempts) ?? []), id])
+		}
+		const claimed = new Map<string, { readonly version: number; readonly attempts: number; readonly due: Date }>()
+		for (const [attempts, ids] of byAttempts) {
+			const due = new Date(now.getTime() + backoffMs(tickMs, attempts + 1))
+			const changes = new Map<string, Primitive>([[queue.attempts, attempts + 1], [queue.due, due]])
+			const updated = await session.run<Readonly<Record<string, unknown>>>(
+				updateNode(table, changes, version, scopedWhere(inList(table, key, ids), scope), answer(context)),
+				{ root: 'UpdateQueryNode', table, joins: {}, scope },
+			)
+			for (const row of updated) {
+				const id = row['id']
+				const next = row['version']
+				if (typeof id !== 'string' || typeof next !== 'number' || !isSafeInteger(next)) {
+					throw new QueryRefusedError('unexpected_row', `${table}.${version} came back as ${typeof next}; a version column is INTEGER`)
+				}
+				claimed.set(id, { version: next, attempts: attempts + 1, due })
+			}
+		}
+		return { rows: await answerFiles(model, site.files, session, answerDays(table, model.dates, rows), grant.action), claimed }
+	})
+	return leased.rows.map((row) => {
+		const id = String(row[key])
+		const lease = leased.claimed.get(id)
+		if (lease === undefined) {
+			throw new QueryRefusedError('unexpected_row', `the claim of ${table} updated no row ${id}`)
+		}
+		const links = new Map<string, string>()
+		for (const name of chain) {
+			links.set(name, String(row[name]))
+		}
+		const ref = runtimeOf(context.connection).capabilities.row({ table, action: grant.action, principal: grant.principal, id, chain: links })
+		const answered: Record<string, unknown> = {}
+		for (const name of visible) {
+			setOwn(answered, name, row[name])
+		}
+		setOwn(answered, version, lease.version)
+		setOwn(answered, 'version', lease.version)
+		if (inSet(nameSet(visible), queue.attempts)) {
+			setOwn(answered, queue.attempts, lease.attempts)
+		}
+		if (inSet(nameSet(visible), queue.due)) {
+			setOwn(answered, queue.due, lease.due)
+		}
+		setOwn(answered, 'ref', ref)
+		return freeze(answered)
+	})
+}
+
+/**
+ * `tx.db.on(row.ref)`: the claimed row, finished in the job's transaction. `update(values, { expectVersion, done })`
+ * writes the columns of the claim's action and, with `done: true`, clears `due` in the same statement; `remove` deletes
+ * it with the table's delete action; `requeue({ at })` makes it due at `at` (now by default) with no attempts.
+ */
+function claimedRow(context: TableContext, site: DataSite, run: Runner, capability: unknown): object {
+	const model = context.model
+	const queue = model.queue
+	if (queue === undefined) {
+		throw new CapabilityError('undeclared_operation', `${model.name} is not a queue table: its policy declares no queue`)
+	}
+	return freeze({
+		update: writing(site, 'update', async (values: unknown, input?: unknown) => {
+			const scope = claimedRowPredicate(context, capability, 'update')
+			const options = readOptions(input, ['expectVersion', 'done'], 'update')
+			const done = options['done']
+			if (done !== undefined && typeof done !== 'boolean') {
+				throw new QueryRefusedError('invalid_argument', 'update takes done: true to finish the row, or no done')
+			}
+			const changes = readValues(values, updatableBy(model, heldAction(context, capability)), 'update', model)
+			if (done === true) {
+				changes.set(queue.due, null)
+			}
+			return updateRow(context, run, { scope }, changes, versionArgument(context, [options]))
+		}),
+		remove: writing(site, 'remove', async (input?: unknown) => {
+			const scope = claimedRowPredicate(context, capability, 'delete')
+			const options = readOptions(input, ['expectVersion'], 'remove')
+			await removeRow(context, run, { scope }, versionArgument(context, [options]))
+		}),
+		requeue: writing(site, 'update', async (input?: unknown) => {
+			const scope = claimedRowPredicate(context, capability, 'update')
+			const options = readOptions(input, ['at'], 'requeue')
+			const at = options['at'] === undefined ? await databaseNow(await run.read()) : dueTime(model.name, queue.due, options['at'])
+			const changes = new Map<string, Primitive>([[queue.due, at], [queue.attempts, 0]])
+			return updateRow(context, run, { scope }, changes, undefined)
+		}),
 	})
 }
 
+/** A requeue's time: a valid `Date`, or ISO 8601 text with an offset. */
+function dueTime(table: string, column: string, value: unknown): Date | string {
+	if (value instanceof Date) {
+		if (Number.isNaN(value.getTime())) {
+			throw new QueryRefusedError('invalid_value', `requeue takes at, a valid Date`)
+		}
+		return value
+	}
+	if (typeof value === 'string') {
+		return timestampInput(value, `${table}.${column}`)
+	}
+	throw new QueryRefusedError('invalid_argument', 'requeue takes { at?: Date | ISO 8601 text }')
+}
+
 function referenceTables(parts: DataLayerParts, site: DataSite, run: Runner): object {
 	const handle: Record<string, unknown> = {}
 	const tables = ownKeys(parts.models)
@@ -581,6 +930,8 @@ function unscopedRows(context: TableContext, site: DataSite, run: Runner, mode:
 	const table = model.name
 	const visible = model.visible
 	const keyed = model.scope.mode === 'dimension' || model.scope.mode === 'child' || model.scope.mode === 'app'
+	// An unscoped read reads through the table's read action.
+	const unscopedRead = model.actions.read[0] ?? ''
 	const byKey = (id: unknown): OperationNode => {
 		if (!keyed) {
 			throw new QueryRefusedError('row_address', `${table} has no key; read it with list`)
@@ -598,17 +949,22 @@ function unscopedRows(context: TableContext, site: DataSite, run: Runner, mode:
 		return writing(site, operation, method)
 	}
 	return freeze({
-		list: bound(site, async (options?: unknown) => listRows(context, run, everything(), visible, options, keyed ? [keyOf(model)] : visible)),
+		list: bound(
+			site,
+			async (options?: unknown) => listRows(context, run, everything(), visible, options, keyed ? [keyOf(model)] : visible, unscopedRead),
+		),
 		count: bound(site, async (options?: unknown) => countRows(context, run, everything(), visible, options)),
 		aggregate: bound(site, async <Row>(spec: AggregateSpec<Row>) => aggregateRows(context, run, everything(), context.shape, spec)),
 		get: bound(site, async (id: unknown) => {
 			const scope = everything()
 			const node = selectNode(rowState(table, [], [], 1), visible, scope, byKey(id), model.dates)
-			const rows = await (await run.read()).run(node, { root: 'SelectQueryNode', table, joins: {}, scope })
+			const session = await run.read()
+			const rows = await session.run(node, { root: 'SelectQueryNode', table, joins: {}, scope })
 			const [row] = answerDays(table, model.dates, rows)
 			if (row === undefined) {
 				throw new NotFoundError(`${table} not found`)
 			}
+			await answerFiles(model, run.files, session, [row], unscopedRead)
 			return row
 		}),
 		insert: write('insert', async (values: unknown) => insertUnscoped(context, run, site.principal, values)),
@@ -841,6 +1197,7 @@ async function listRows(
 	visible: readonly string[],
 	input: unknown,
 	tiebreak: readonly string[],
+	action?: string,
 ): Promise<{ readonly items: Readonly<Record<string, unknown>>[]; readonly next: string | null }> {
 	const table = context.model.name
 	const options = readOptions(input, ['where', 'orderBy', 'limit', 'after'], 'list')
@@ -857,7 +1214,8 @@ async function listRows(
 		table,
 		order.map((term) => term.column),
 	)
-	const rows = await (await run.read()).run<Readonly<Record<string, unknown>>>(node, {
+	const session = await run.read()
+	const rows = await session.run<Readonly<Record<string, unknown>>>(node, {
 		root: 'SelectQueryNode',
 		table,
 		joins: {},
@@ -865,8 +1223,9 @@ async function listRows(
 	})
 	const page = answerDays(table, context.model.dates, rows.slice(0, limit))
 	const last = page[page.length - 1]
+	const items = page.map((row) => withoutCursor(row, order))
 	return {
-		items: page.map((row) => withoutCursor(row, order)),
+		items: action === undefined ? items : await answerFiles(context.model, run.files, session, items, action),
 		next: rows.length > limit && last !== undefined ? encodeCursor(last, order) : null,
 	}
 }