@fabrika/db 0.8.2 → 0.9.0-cloudflare.2

package/src/store.ts

@@ -1,3 +1,4 @@
+import { uuidv7 } from '@fabrika/platform'
 import { BinaryOperationNode, type OperationNode, OperatorNode, type ReturningNode, ValueNode } from 'kysely'
 import { admissions } from './admissions'
 import {
@@ -31,8 +32,11 @@ import {
 	type Within,
 	type WithinGrant,
 } from './capability'
-import { type Database, InvocationTransaction, type Session, sessionOf } from './database'
+import { type Database, InvocationTransaction, type Session, sessionOf, type SqlDialect } from './database'
 import {
+	type Compare,
+	type Condition,
+	type Contains,
 	finishSelect,
 	isPrimitive,
 	type JoinShape,
@@ -49,7 +53,7 @@ import { fileReference } from './file-references'
 import { webhookTables } from './framework-tables'
 import type { ForeignKeyPair, GuardContext, RootKind } from './guard'
 import { fencedTransaction, jobLeases } from './job-leases'
-import { linksPredicate, linkValues } from './links'
+import { linksPredicate, type LinkValue, linkValues } from './links'
 import {
 	acknowledgement,
 	acknowledgementNode,
@@ -99,11 +103,11 @@ import {
 	type VersionArguments,
 	visibleFor,
 } from './policy'
-import { frameworkSideOf, type Locator, register } from './registry'
+import { frameworkSideOf, type ProvisionalBinding, register } from './registry'
 import type { ScopeTerms, ScopeTest, ScopeUse } from './sql'
 import { storedFiles, storedFilesMetadata } from './stored-files'
 import { type TablePolicies, tablePolicies } from './tables'
-import { answerDays, dayInput, timestampInput } from './temporal'
+import { answerRows, dayInput, type RowColumns, storedTimestamp, timestampInput } from './temporal'
 
 export interface DataLayerRuntime {
 	readonly database: Database
@@ -124,9 +128,86 @@ export interface TableContext {
 	readonly destination: TableModel | undefined
 	readonly shape: TableShape
 	readonly joins: Readonly<Record<string, readonly ForeignKeyPair[]>>
+	/** The model of each child a select may join, by its table name. */
+	readonly children: Readonly<Record<string, TableModel>>
 	readonly connection: Connection
 }
 
+/** The dialect of the database the layer is bound to: what a read answers and a write binds depends on it. */
+export function dialectOf(context: TableContext): SqlDialect {
+	return runtimeOf(context.connection).database.dialect
+}
+
+/** The columns of `model`'s own rows that a read answers in a form of its own (`answerRows`). */
+export function rowColumnsOf(model: TableModel): RowColumns {
+	return { days: model.dates, timestamps: model.timestamps, booleans: model.booleans }
+}
+
+/** A timestamp's bound value on SQLite: its stored UTC text. Postgres takes a `Date` or ISO text as it is. */
+function boundTimestamp(model: TableModel, column: string, value: Primitive): Primitive {
+	if (typeof value !== 'string' && !(value instanceof Date)) {
+		throw new QueryRefusedError('invalid_value', `${model.name}.${column} takes a Date or ISO 8601 text with Z or an offset`)
+	}
+	return storedTimestamp(value, `${model.name}.${column}`)
+}
+
+/** The values a write binds: on SQLite each timestamp as its stored UTC text, so text order is time order. */
+export function boundValues(context: TableContext, values: ReadonlyMap<string, Primitive | null>): ReadonlyMap<string, Primitive | null> {
+	const model = context.model
+	if (dialectOf(context) === 'postgres' || ownKeys(model.timestamps).length === 0) {
+		return values
+	}
+	const bound = new Map<string, Primitive | null>()
+	for (const [name, value] of values) {
+		bound.set(name, value === null || !inSet(model.timestamps, name) ? value : boundTimestamp(model, name, value))
+	}
+	return bound
+}
+
+/** A term's values as they are bound: on SQLite, one over a timestamp of `model` compares stored UTC text. */
+function boundTerm(model: TableModel, term: Compare | Contains): Compare | Contains {
+	const value = term.kind === 'compare' ? term.value : null
+	if (term.kind !== 'compare' || value === null || !inSet(model.timestamps, term.column)) {
+		return term
+	}
+	const bind = (item: Primitive): Primitive => boundTimestamp(model, term.column, item)
+	return { ...term, value: isList(value) ? value.map(bind) : bind(value) }
+}
+
+function isList(value: Primitive | readonly Primitive[]): value is readonly Primitive[] {
+	return isArray(value)
+}
+
+/** A list's terms over `model`'s columns, as `boundTerm` binds each. */
+export function boundTerms(context: TableContext, model: TableModel, terms: readonly (Compare | Contains)[]): readonly (Compare | Contains)[] {
+	if (dialectOf(context) === 'postgres' || ownKeys(model.timestamps).length === 0) {
+		return terms
+	}
+	return terms.map((term) => boundTerm(model, term))
+}
+
+/** A description's conditions over `model`'s columns, an OR group's terms included, as `boundTerm` binds each. */
+function boundConditions(context: TableContext, model: TableModel, conditions: readonly Condition[]): readonly Condition[] {
+	if (dialectOf(context) === 'postgres' || ownKeys(model.timestamps).length === 0) {
+		return conditions
+	}
+	return conditions.map((condition) =>
+		condition.kind === 'any' ? { ...condition, conditions: condition.conditions.map((term) => boundTerm(model, term)) } : boundTerm(model, condition)
+	)
+}
+
+/** A select's conditions, its joined children's included, as they are bound. */
+function boundState(context: TableContext, state: SelectState): SelectState {
+	if (dialectOf(context) === 'postgres') {
+		return state
+	}
+	const joins = state.joins.map((join) => {
+		const child = ownEntry(context.children, join.join.shape.table)
+		return child === undefined ? join : { ...join, select: { ...join.select, conditions: boundConditions(context, child, join.select.conditions) } }
+	})
+	return { ...state, conditions: boundConditions(context, context.model, state.conditions), joins }
+}
+
 export function runtimeOf(connection: Connection): DataLayerRuntime {
 	const runtime = connection.runtime
 	if (runtime === undefined) {
@@ -227,6 +308,76 @@ function linksAbove(model: TableModel, dimension: string): readonly Container[]
 	return []
 }
 
+/**
+ * The links of a row that lie inside the `Within`'s own dimension: the object itself for a dimension table, and the
+ * chain links nearer than `dimension`. A grant on one of them admits the row as a single-object read admits it.
+ */
+function linksBelow(model: TableModel, dimension: string): readonly Container[] {
+	const links = model.scope.mode === 'dimension' ? selfLinks(model) : model.chain
+	const below: Container[] = []
+	for (let index = 0; index < links.length; index++) {
+		const link = links[index]
+		if (link === undefined || link.dimension === dimension) {
+			return below
+		}
+		below[below.length] = link
+	}
+	return []
+}
+
+/**
+ * One `<column> in (values)` per contained grant on a link of the row inside the `Within`'s dimension. A grant on a
+ * dimension the table carries no link of admits none of its rows; one on the `Within`'s dimension or above it is refused.
+ */
+function containedTests(model: TableModel, grant: WithinGrant): { readonly column: string; readonly values: readonly string[] }[] {
+	const below = linksBelow(model, grant.dimension)
+	const above = linksAbove(model, grant.dimension)
+	const tests: { readonly column: string; readonly values: readonly string[] }[] = []
+	for (let index = 0; index < grant.contained.length; index++) {
+		const contained = grant.contained[index]
+		if (contained === undefined) {
+			continue
+		}
+		if (contained.dimension === grant.dimension || linkOf(above, contained.dimension) !== undefined) {
+			throw new CapabilityError(
+				'unenforceable',
+				`the Within of ${grant.dimension} carries a grant on ${contained.dimension}, which does not lie inside ${grant.dimension} in ${model.name}`,
+			)
+		}
+		const link = linkOf(below, contained.dimension)
+		if (link !== undefined && contained.values.length > 0) {
+			tests[tests.length] = { column: link.column, values: contained.values }
+		}
+	}
+	return tests
+}
+
+/** The link of `dimension` among `links`, by an index loop: no array method an application could replace. */
+function linkOf(links: readonly Container[], dimension: string): Container | undefined {
+	for (let index = 0; index < links.length; index++) {
+		const link = links[index]
+		if (link !== undefined && link.dimension === dimension) {
+			return link
+		}
+	}
+	return undefined
+}
+
+/** Every scope value a `Within` carries: its own, its containers' and its contained dimensions'. */
+function withinCount(grant: WithinGrant): number {
+	if (grant.values === 'all') {
+		return 0
+	}
+	let count = grant.values.length
+	for (let index = 0; index < grant.containers.length; index++) {
+		count += grant.containers[index]?.values.length ?? 0
+	}
+	for (let index = 0; index < grant.contained.length; index++) {
+		count += grant.contained[index]?.values.length ?? 0
+	}
+	return count
+}
+
 /**
  * `column in (values) or <container column> in (container values) …`, one disjunct per container dimension, so
  * the statement itself judges each row by the chain it carries now. Undefined for an empty `Within`: the caller
@@ -238,7 +389,7 @@ function withinPredicate(model: TableModel, column: string, grant: WithinGrant):
 	}
 	const above = linksAbove(model, grant.dimension)
 	const predicates: OperationNode[] = []
-	let count = grant.values.length
+	const count = withinCount(grant)
 	if (grant.values.length > 0) {
 		predicates[predicates.length] = inList(model.name, column, grant.values)
 	}
@@ -247,23 +398,24 @@ function withinPredicate(model: TableModel, column: string, grant: WithinGrant):
 		if (container === undefined) {
 			continue
 		}
-		let link: Container | undefined
-		for (let position = 0; position < above.length; position++) {
-			if (above[position]?.dimension === container.dimension) {
-				link = above[position]
-			}
-		}
+		const link = linkOf(above, container.dimension)
 		if (link === undefined) {
 			throw new CapabilityError(
 				'unenforceable',
 				`the Within of ${grant.dimension} reaches through ${container.dimension}, which ${model.name} carries no column for above ${grant.dimension}; the layer cannot enforce it`,
 			)
 		}
-		count += container.values.length
 		if (container.values.length > 0) {
 			predicates[predicates.length] = inList(model.name, link.column, container.values)
 		}
 	}
+	const contained = containedTests(model, grant)
+	for (let index = 0; index < contained.length; index++) {
+		const test = contained[index]
+		if (test !== undefined) {
+			predicates[predicates.length] = inList(model.name, test.column, test.values)
+		}
+	}
 	if (count > MAX_WITHIN_VALUES) {
 		throw new CapabilityError('within_size', `a Within carries at most ${MAX_WITHIN_VALUES} scope values; this one carries ${count}`)
 	}
@@ -273,7 +425,14 @@ function withinPredicate(model: TableModel, column: string, grant: WithinGrant):
 /** The object a Ref of the model's own dimension names, with every link of its chain. */
 export function selfLinks(model: TableModel): readonly Container[] {
 	const scope = dimensionScope(model)
-	return [{ dimension: scope.dimension, column: scope.key }, ...model.chain]
+	const links: Container[] = [{ dimension: scope.dimension, column: scope.key }]
+	for (let index = 0; index < model.chain.length; index++) {
+		const link = model.chain[index]
+		if (link !== undefined) {
+			links[links.length] = link
+		}
+	}
+	return links
 }
 
 /** This object, over the whole chain the Ref carries. */
@@ -443,7 +602,22 @@ export function scopeTerms(context: TableContext, capability: unknown, use: Scop
 		if (use === 'read' && !namesAction(model, grant.action)) {
 			throw new CapabilityError('wrong_action', `${model.name} does not name the action ${grant.action}: a Ref reads it with an action it names`)
 		}
-		return [linkValues(model.name, links.slice(start), grant).map(({ link, value }) => ({ column: link.column, value }))]
+		const reached: Container[] = []
+		for (let index = start; index < links.length; index++) {
+			const link = links[index]
+			if (link !== undefined) {
+				reached[reached.length] = link
+			}
+		}
+		const values = linkValues(model.name, reached, grant)
+		const tests: ScopeTest[] = []
+		for (let index = 0; index < values.length; index++) {
+			const entry = values[index]
+			if (entry !== undefined) {
+				tests[tests.length] = { column: entry.link.column, value: entry.value }
+			}
+		}
+		return [tests]
 	}
 	const column = reachColumn(model, grant.dimension)
 	if (column === undefined) {
@@ -463,21 +637,31 @@ export function scopeTerms(context: TableContext, capability: unknown, use: Scop
 	}
 	const above = linksAbove(model, grant.dimension)
 	const groups: ScopeTest[][] = []
-	let count = grant.values.length
+	const count = withinCount(grant)
 	if (grant.values.length > 0) {
-		groups.push([{ column, value: grant.values }])
+		groups[groups.length] = [{ column, value: grant.values }]
 	}
-	for (const container of grant.containers) {
-		const link = above.find((candidate) => candidate.dimension === container.dimension)
+	for (let index = 0; index < grant.containers.length; index++) {
+		const container = grant.containers[index]
+		if (container === undefined) {
+			continue
+		}
+		const link = linkOf(above, container.dimension)
 		if (link === undefined) {
 			throw new CapabilityError(
 				'unenforceable',
 				`the Within of ${grant.dimension} reaches through ${container.dimension}, which ${model.name} carries no column for above ${grant.dimension}; the layer cannot enforce it`,
 			)
 		}
-		count += container.values.length
 		if (container.values.length > 0) {
-			groups.push([{ column: link.column, value: container.values }])
+			groups[groups.length] = [{ column: link.column, value: container.values }]
+		}
+	}
+	const contained = containedTests(model, grant)
+	for (let index = 0; index < contained.length; index++) {
+		const test = contained[index]
+		if (test !== undefined) {
+			groups[groups.length] = [{ column: test.column, value: test.values }]
 		}
 	}
 	if (count > MAX_WITHIN_VALUES) {
@@ -895,29 +1079,39 @@ async function selectRows<S>(
 	if (scope === undefined) {
 		return []
 	}
-	const node = selectNode(state, visible, scope, undefined, context.model.dates)
+	const dialect = dialectOf(context)
+	const node = selectNode(boundState(context, state), visible, scope, undefined, context.model.dates, dialect)
 	const rows = await (await run.read()).run<S>(node, guard(context, 'SelectQueryNode', scope))
-	return answerDays(context.model.name, joinedDays(context.model.dates, state), rows)
+	return answerRows(dialect, context.model.name, joinedColumns(context, state), rows)
 }
 
-/** The `date` columns of a select's rows: the table's own, and each joined child's under its `<child>.<column>` alias. */
-function joinedDays(own: NameSet, state: SelectState): NameSet {
+/** The column sets of a select's rows: the table's own, and each joined child's under its `<child>.<column>` alias. */
+function joinedColumns(context: TableContext, state: SelectState): RowColumns {
+	const own = rowColumnsOf(context.model)
 	if (state.joins.length === 0) {
 		return own
 	}
-	const names: string[] = []
-	const ownDates = namesOf(own)
-	for (let index = 0; index < ownDates.length; index++) {
-		names[names.length] = ownDates[index] ?? ''
-	}
-	for (let index = 0; index < state.joins.length; index++) {
-		const shape = state.joins[index]?.join.shape
-		const dates = shape === undefined ? [] : namesOf(shape.dates)
-		for (let position = 0; position < dates.length; position++) {
-			names[names.length] = `${shape?.table}.${dates[position]}`
+	const joined = (pick: (columns: RowColumns) => NameSet): NameSet => {
+		const names: string[] = []
+		const owned = namesOf(pick(own))
+		for (let index = 0; index < owned.length; index++) {
+			names[names.length] = owned[index] ?? ''
+		}
+		for (let index = 0; index < state.joins.length; index++) {
+			const table = state.joins[index]?.join.shape.table ?? ''
+			const child = ownEntry(context.children, table)
+			const columns = child === undefined ? [] : namesOf(pick(rowColumnsOf(child)))
+			for (let position = 0; position < columns.length; position++) {
+				names[names.length] = `${table}.${columns[position]}`
+			}
 		}
+		return nameSet(names)
+	}
+	return {
+		days: joined((columns) => columns.days),
+		timestamps: joined((columns) => columns.timestamps),
+		booleans: joined((columns) => columns.booleans),
 	}
-	return nameSet(names)
 }
 
 /**
@@ -933,10 +1127,11 @@ export async function selectOne<O>(
 ): Promise<O> {
 	const start = startSelect(context.shape)
 	const state = finishSelect(start, start)
-	const node = selectNode(state, visible, scope, undefined, context.model.dates)
+	const dialect = dialectOf(context)
+	const node = selectNode(state, visible, scope, undefined, context.model.dates, dialect)
 	const session = await run.read()
 	const rows = await session.run<O>(node, guard(context, 'SelectQueryNode', scope))
-	const [row] = answerDays(context.model.name, context.model.dates, rows)
+	const [row] = answerRows(dialect, context.model.name, rowColumnsOf(context.model), rows)
 	if (row === undefined) {
 		throw new NotFoundError(`${context.model.name} not found`)
 	}
@@ -1027,9 +1222,10 @@ async function lockDestination(transaction: Session, context: TableContext, gran
 export async function insertRow<O>(
 	context: TableContext,
 	run: Runner,
-	values: ReadonlyMap<string, Primitive | null>,
+	given: ReadonlyMap<string, Primitive | null>,
 	destination: RefGrant | undefined,
 ): Promise<O> {
+	const values = boundValues(context, given)
 	return run.write(async (transaction) => {
 		if (destination !== undefined) {
 			await lockDestination(transaction, context, destination)
@@ -1172,10 +1368,12 @@ async function insertOnConflict(
 	context: TableContext,
 	run: Runner,
 	transaction: Session,
-	values: ReadonlyMap<string, Primitive | null>,
+	given: ReadonlyMap<string, Primitive | null>,
 	conflict: OnConflict,
 ): Promise<Readonly<Record<string, unknown>>> {
 	const model = context.model
+	const values = boundValues(context, given)
+	const updates = boundValues(context, conflict.updates)
 	const matches: OperationNode[] = []
 	for (let index = 0; index < conflict.columns.length; index++) {
 		const name = conflict.columns[index] ?? ''
@@ -1201,17 +1399,17 @@ async function insertOnConflict(
 			return { inserted: false }
 		}
 		const where = scopedWhere(allOf(matches), scope)
-		const unchanged = conflict.updates.size === 0
+		const unchanged = updates.size === 0
 		const update = unchanged
 			? acknowledgementNode(model.name, keyOf(model), model.version, where)
-			: updateNode(model.name, conflict.updates, model.version, where, answer(context))
+			: updateNode(model.name, updates, model.version, where, answer(context))
 		const [updated] = await transaction.run<Readonly<Record<string, unknown>>>(
 			update,
 			guard(context, unchanged ? 'SelectQueryNode' : 'UpdateQueryNode', scope),
 		)
 		if (updated !== undefined) {
 			checkVersion(context, updated)
-			await referenceUpdated(context, run, transaction, conflict.updates, updated)
+			await referenceUpdated(context, run, transaction, updates, updated)
 			return { ...updated, inserted: false }
 		}
 	}
@@ -1264,11 +1462,12 @@ export async function updateRow<O>(
 	context: TableContext,
 	run: Runner,
 	target: Addressed,
-	changes: ReadonlyMap<string, Primitive | null>,
+	given: ReadonlyMap<string, Primitive | null>,
 	expectedVersion: OperationNode | undefined,
 	destination?: RefGrant,
 ): Promise<O> {
 	const { name: table, version } = context.model
+	const changes = boundValues(context, given)
 	const where = scopedWhere(conditionsWith(target, expectedVersion), target.scope)
 	const unchanged = changes.size === 0
 	const node = unchanged
@@ -1389,18 +1588,26 @@ export async function aggregateRows<Row, O>(
 	if (scope === undefined) {
 		return []
 	}
-	const node = aggregateNode(context.model.name, columns, filter?.conditions ?? [], scope, context.model.dates)
+	const dialect = dialectOf(context)
+	const conditions = boundConditions(context, context.model, filter?.conditions ?? [])
+	const node = aggregateNode(context.model.name, columns, conditions, scope, context.model.dates)
 	const rows = await (await run.read()).run<O>(node, guard(context, 'SelectQueryNode', scope))
-	return answerDays(context.model.name, aggregateDays(context.model.dates, columns), rows)
+	const own = rowColumnsOf(context.model)
+	const answered = answerRows(dialect, context.model.name, {
+		days: aggregated(own.days, columns),
+		timestamps: aggregated(own.timestamps, columns),
+		booleans: aggregated(own.booleans, columns),
+	}, rows)
+	return dialect === 'postgres' ? answered : sqliteAggregates(context.model.name, columns, answered)
 }
 
-/** The `date` columns of an aggregate's rows: a grouped one by its name, and its `min_` and `max_`. */
-function aggregateDays(dates: NameSet, columns: AggregateColumns): NameSet {
+/** The columns of `set` among an aggregate's: a grouped one by its name, and its `min_` and `max_`. */
+function aggregated(set: NameSet, columns: AggregateColumns): NameSet {
 	const names: string[] = []
 	const add = (prefix: string, list: readonly string[]) => {
 		for (let index = 0; index < list.length; index++) {
 			const name = list[index] ?? ''
-			if (inSet(dates, name)) {
+			if (inSet(set, name)) {
 				names[names.length] = `${prefix}${name}`
 			}
 		}
@@ -1411,6 +1618,37 @@ function aggregateDays(dates: NameSet, columns: AggregateColumns): NameSet {
 	return nameSet(names)
 }
 
+/**
+ * An aggregate's numbers as Postgres's driver answers them: `count` as bigint text, and an integral `sum` as text too
+ * (Postgres sums an integer as bigint or numeric). SQLite answers both as numbers, and a whole sum of a REAL column is
+ * text here where Postgres's float8 sum is a number; `AggregateRow` types a sum as either.
+ */
+function sqliteAggregates<O>(table: string, columns: AggregateColumns, rows: O[]): O[] {
+	const integral = (where: string, value: unknown): unknown => {
+		if (typeof value !== 'number' || !Number.isInteger(value)) {
+			return value
+		}
+		if (!isSafeInteger(value)) {
+			throw new QueryRefusedError('unexpected_row', `${where} came back as an integer past the safe range, which a number cannot hold exactly`)
+		}
+		return String(value)
+	}
+	for (let index = 0; index < rows.length; index++) {
+		const row = rows[index]
+		if (typeof row !== 'object' || row === null) {
+			continue
+		}
+		if (columns.count) {
+			defineValue(row, 'count', integral(`${table}.count`, ownDescriptor(row, 'count')?.value))
+		}
+		for (let position = 0; position < columns.sum.length; position++) {
+			const name = `sum_${columns.sum[position] ?? ''}`
+			defineValue(row, name, integral(`${table}.${name}`, ownDescriptor(row, name)?.value))
+		}
+	}
+	return rows
+}
+
 /** An insert's row, stamped from its capability, the destination it locks, and what it does on a conflict. */
 export interface PreparedInsert {
 	readonly row: Map<string, Primitive | null>
@@ -1433,10 +1671,8 @@ export function prepareDimensionInsert(context: TableContext, target: unknown, v
 		stampInsert(context, grant, row, scope.key, grant.id)
 		return { row, destination: undefined, conflict }
 	}
-	stampInsert(context, grant, row, scope.key, Bun.randomUUIDv7())
-	for (const { link, value } of linkValues(context.model.name, context.model.chain, grant)) {
-		row.set(link.column, value)
-	}
+	stampInsert(context, grant, row, scope.key, uuidv7())
+	stampChain(row, linkValues(context.model.name, context.model.chain, grant))
 	return { row, destination: grant, conflict }
 }
 
@@ -1445,7 +1681,7 @@ export function prepareApplicationInsert(context: TableContext, capability: unkn
 	const grant = appGrant(context, capability, 'insert')
 	const row = readValues(values, context.model.insert, 'insert', context.model)
 	const conflict = onConflictOf(context, options, grant.action, row)
-	stampInsert(context, grant, row, keyOf(context.model), Bun.randomUUIDv7())
+	stampInsert(context, grant, row, keyOf(context.model), uuidv7())
 	return { row, destination: undefined, conflict }
 }
 
@@ -1455,13 +1691,21 @@ export function prepareChildInsert(context: TableContext, parent: unknown, value
 	const grant = refGrant(context, parent, scope.parent.dimension, 'insert')
 	const row = readValues(values, context.model.insert, 'insert', context.model)
 	const conflict = onConflictOf(context, options, grant.action, row)
-	stampInsert(context, grant, row, scope.key, Bun.randomUUIDv7())
-	for (const { link, value } of linkValues(context.model.name, context.model.chain, grant)) {
-		row.set(link.column, value)
-	}
+	stampInsert(context, grant, row, scope.key, uuidv7())
+	stampChain(row, linkValues(context.model.name, context.model.chain, grant))
 	return { row, destination: grant, conflict }
 }
 
+/** Writes each chain column the destination `Ref` settles into an insert's row. */
+function stampChain(row: Map<string, Primitive | null>, values: readonly LinkValue[]): void {
+	for (let index = 0; index < values.length; index++) {
+		const entry = values[index]
+		if (entry !== undefined) {
+			row.set(entry.link.column, entry.value)
+		}
+	}
+}
+
 /** A prepared insert, with its conflict handling when the caller named one. */
 export function insertPrepared(context: TableContext, run: Runner, prepared: PreparedInsert): Promise<Readonly<Record<string, unknown>>> {
 	const conflict = prepared.conflict
@@ -1565,9 +1809,17 @@ export class DimensionTable<DB, P, T extends string> {
 		const scope = objectPredicate(context, ref, 'delete')
 		const target = refGrant(context, to, container.dimension, 'insert')
 		const values = linkValues(context.model.name, context.model.chain, target)
-		const changes = new Map<string, Primitive | null>(values.map(({ link, value }) => [link.column, value]))
+		const changes = new Map<string, Primitive | null>()
+		stampChain(changes, values)
+		const chain: Record<string, string> = {}
+		for (let index = 0; index < values.length; index++) {
+			const entry = values[index]
+			if (entry !== undefined) {
+				setOwn(chain, entry.link.dimension, entry.value)
+			}
+		}
 		const acknowledged = await updateRow<Acknowledgement<P, T>>(context, storeRunner(context), addressed(scope), changes, undefined, target)
-		return { ...acknowledged, chain: Object.fromEntries(values.map(({ link, value }) => [link.dimension, value])) }
+		return { ...acknowledged, chain }
 	}
 
 	async aggregate<const S extends AggregateSpec<Row<DB, P, T>>>(
@@ -1900,8 +2152,23 @@ export function scoped<DB, P>(tables: Tables<DB, P>): ScopedDatabase<DB, P> {
 				setOwn(joins, child, join.on)
 			}
 		}
+		const childModels: Record<string, TableModel> = {}
+		for (let index = 0; index < children.length; index++) {
+			const child = modelOf(models, children[index] ?? '')
+			if (child !== undefined) {
+				setOwn(childModels, child.name, child)
+			}
+		}
 		const shape = shapeOf(model, joinable)
-		return freeze({ model, parent, destination: destinationOf(models, model, parent), shape, joins: freeze(joins), connection })
+		return freeze({
+			model,
+			parent,
+			destination: destinationOf(models, model, parent),
+			shape,
+			joins: freeze(joins),
+			children: freeze(childModels),
+			connection,
+		})
 	}
 
 	const database: ScopedDatabase<DB, P> = Object.freeze({ tables: tablePolicies(tables) })
@@ -1917,13 +2184,20 @@ export function scoped<DB, P>(tables: Tables<DB, P>): ScopedDatabase<DB, P> {
 			}
 			return probeOf(contextFor(table, mode))
 		},
-		bind(runtime: DataLayerRuntime): Locator {
+		bind(runtime: DataLayerRuntime): ProvisionalBinding {
 			if (connection.runtime !== undefined) {
 				throw new CapabilityError('layer_unbound', 'the data layer is already connected; only the framework connects it, once, at boot')
 			}
 			const bound: DataLayerRuntime = freeze({ database: runtime.database, capabilities: runtime.capabilities, readOnly: runtime.readOnly })
 			connection.runtime = bound
-			return async (dimension, id, using) => locateObject(models, bound, dimension, id, using)
+			return freeze({
+				locate: async (dimension: string, id: string, using?: Session) => locateObject(models, bound, dimension, id, using),
+				release() {
+					if (connection.runtime === bound) {
+						connection.runtime = undefined
+					}
+				},
+			})
 		},
 		framework: freeze({
 			webhooks: webhookTables(() => runtimeOf(connection)),