@bjornpagen/bumbledb 0.4.0 → 0.5.0

package/src/db.ts

@@ -32,8 +32,10 @@
 
 import * as path from "node:path"
 import * as errors from "@superbuilders/errors"
+import { isClosedMember, sealedFieldsOf } from "#closed.ts"
 import type { Exhumed } from "#exhume.ts"
 import { exhumeStore } from "#exhume.ts"
+import { rosterOf } from "#fields.ts"
 import { lower } from "#lower.ts"
 import {
 	factOf,
@@ -59,13 +61,13 @@ import type {
 	Violation as WireViolation,
 	ViolationFact as WireViolationFact
 } from "#native.ts"
-import { native } from "#native.ts"
+import { bridged, native } from "#native.ts"
 import type { SelectColumn } from "#query/atom.ts"
 import type { Query } from "#query/lower.ts"
 import { lowerQuery } from "#query/lower.ts"
 import { decodeAnswers, wireParams } from "#query/run.ts"
 import type { ParamEntry, ParamsRecord } from "#query/scope.ts"
-import type { AnyRelation, Fact, InsertFact, RelationField } from "#relation.ts"
+import type { AnyRelation, Fact, InsertFact } from "#relation.ts"
 import type { AnySchema, Schema, SchemaRelation, SchemaRelations } from "#schema.ts"
 import type { KeyStatement, Statement } from "#statements.ts"
 
@@ -348,11 +350,16 @@ interface Db<Rels extends SchemaRelations> {
 	 * The ONE witnessed-write form: snapshot → `fn` (premise reads via
 	 * `snap`, delta via `tx`) → witnessed commit, which lands only if no
 	 * state-changing commit intervened since the snapshot. On a moved
-	 * generation the WHOLE `fn` reruns on a fresh snapshot, unbounded: this
-	 * process holds the store's only write handle, so every generation move
-	 * is self-inflicted by the host's own interleaved writes — contention
-	 * is bounded by the host's own progress, and any retry cap would be an
-	 * invented limit (the house no-limits law). `fn` may decline to commit
+	 * generation the WHOLE `fn` reruns on a fresh snapshot: this process
+	 * holds the store's only write handle, so every generation move is
+	 * self-inflicted by the host's own interleaved writes, and each rerun
+	 * witnesses a strictly newer generation — the benign race converges.
+	 * The loop's honesty bound is {@link WITNESSED_ATTEMPT_CAP}: a callback
+	 * that moves the generation on EVERY attempt (a plain `db.write` before
+	 * its first tx verb) would spin forever, so past the cap the typed
+	 * {@link ErrWitnessedLivelock} is thrown instead of a silent loop (the
+	 * engine's ruling: the error, never a loop — retry is host policy, and
+	 * the cap is that policy's own diagnostic). `fn` may decline to commit
 	 * by returning {@link abandon}`(payload)` — the outcome is then
 	 * `{ ok: false, abandoned: payload }` and NO commit (not even an empty
 	 * one) is issued.
@@ -368,19 +375,6 @@ interface Db<Rels extends SchemaRelations> {
 	prepare<Row, Params extends ParamsRecord>(q: Query<Rels, Row, Params>): Prepared<Rels, Row, Params>
 }
 
-/**
- * The bridge guard: runs one native call and wraps anything it throws —
- * marshal-shape refusals and handle-lifecycle refusals cross as genuine
- * typed failures, never bare foreign errors.
- */
-function bridged<T>(context: string, run: () => T): T {
-	const result = errors.trySync(run)
-	if (result.error) {
-		throw errors.wrap(result.error, context)
-	}
-	return result.data
-}
-
 /** One relation's runtime tables: engine id, the identical schema member, field ids, primary key. */
 interface RelationEntry {
 	readonly id: number
@@ -443,7 +437,7 @@ function materializedEntries(theory: AnySchema): StatementEntry[] {
 function impliedKeyEntries(theory: AnySchema): StatementEntry[] {
 	const entries: StatementEntry[] = []
 	for (const member of Object.values(theory.relations)) {
-		if ("handles" in member.data) {
+		if (isClosedMember(member)) {
 			continue
 		}
 		for (const declared of member.data.fields) {
@@ -457,7 +451,7 @@ function impliedKeyEntries(theory: AnySchema): StatementEntry[] {
 		}
 	}
 	for (const member of Object.values(theory.relations)) {
-		if ("handles" in member.data) {
+		if (isClosedMember(member)) {
 			entries.push({
 				kind: "functionality",
 				statement: undefined,
@@ -527,6 +521,33 @@ function isStatementValue<R extends AnyRelation, P extends readonly string[]>(
 	return typeof data === "object" && data !== null && "kind" in data
 }
 
+/**
+ * THE one selector dispatch of the `get` overload pair (primary-key vs
+ * key-statement, `docs/architecture/70-api.md` § the freeze): judges the
+ * middle argument once and hands the narrowed pieces to the chosen
+ * continuation. `Db.get` and the read scope's `get` both dispatch through
+ * here, so the two mismatch refusals speak with one voice and the symmetry
+ * rule (`db.get(...) === db.read(snap => snap.get(...))`) holds by
+ * construction.
+ */
+function selectKeyRead<R extends AnyRelation, P extends readonly string[], T>(
+	keyOrStatement: KeyFact<R> | KeyStatement<R, P>,
+	declaredKey: DeclaredKeyFact<R, P> | undefined,
+	byStatement: (statement: KeyStatement<R, P>, key: DeclaredKeyFact<R, P>) => T,
+	byPrimary: (key: KeyFact<R>) => T
+): T {
+	if (declaredKey !== undefined) {
+		if (!isStatementValue(keyOrStatement)) {
+			throw errors.new("keyed get takes a key() statement value as its second argument")
+		}
+		return byStatement(keyOrStatement, declaredKey)
+	}
+	if (isStatementValue(keyOrStatement)) {
+		throw errors.new("keyed get with a statement selector also takes the key object — get(relation, keyStatement, key)")
+	}
+	return byPrimary(keyOrStatement)
+}
+
 /** Maps a slot's reversal flag to the violation's `orientation` payload. */
 function orientationOf(reversed: boolean | undefined): "written" | "mirrored" | undefined {
 	if (reversed === undefined) {
@@ -538,22 +559,6 @@ function orientationOf(reversed: boolean | undefined): "written" | "mirrored" |
 	return "written"
 }
 
-/**
- * The declared field descriptors a violation's offending cells decode
- * through: an ordinary relation's declared fields; a closed relation's
- * SEALED shape — the roster-carrying synthetic `id` (the member's own
- * reference descriptor) plus its payload columns (a `ClosedColumn` is
- * structurally a `RelationField`). This is how {@link openDb}'s
- * `offendingFactOf` reaches the open-time descriptors: the cited relation
- * name resolves to the schema member, and the member carries them.
- */
-function declaredFieldsOf(member: SchemaRelation): readonly RelationField[] {
-	if ("axioms" in member) {
-		return [{ name: "id", field: member.id }, ...member.data.columns]
-	}
-	return member.data.fields
-}
-
 /** The id-resolution tables one open builds: relation entries by name, statement slots by id. */
 interface Tables {
 	readonly relations: ReadonlyMap<string, RelationEntry>
@@ -667,6 +672,32 @@ const planReclaimer = new FinalizationRegistry<PreparedHandle>(function reclaimP
  */
 const generationMovedSignal = errors.new("bumbledb witnessed generation moved")
 
+/**
+ * The witnessed loop's attempt cap — a generous power of two. Benign
+ * self-inflicted contention (the host's own commits landing between an
+ * attempt's snapshot and its witnessed begin) converges in a handful of
+ * retries because each rerun reads a FRESHER snapshot; a workload that moves
+ * the generation on EVERY one of this many consecutive attempts is not
+ * converging and never will (see {@link ErrWitnessedLivelock}).
+ */
+const WITNESSED_ATTEMPT_CAP = 64
+
+/**
+ * The typed livelock refusal `writeWitnessed` throws past
+ * {@link WITNESSED_ATTEMPT_CAP} attempts: every attempt found the generation
+ * moved, which is only sustainable when the callback ITSELF (even
+ * indirectly) issues an interleaved plain `db.write` before its first tx
+ * verb on every attempt — each rerun then re-moves the generation it is
+ * about to witness, forever. That is host-policy pathology, not engine
+ * judgment (the engine ships the error, never a loop), so it THROWS rather
+ * than returning a result arm. Match with `errors.is`; the remedy is to
+ * move the interleaved write out of the callback (or make it first-attempt
+ * only — the delta belongs on `tx`, premise reads on `snap`).
+ */
+const ErrWitnessedLivelock = errors.new(
+	"bumbledb writeWitnessed livelock: the generation moved on every attempt — the callback itself commits an interleaved write each try, so no snapshot can ever stay current"
+)
+
 /**
  * Fills one insert's omitted fresh cells through the engine's
  * alloc-then-insert dyn lane (there is no insert-with-omitted-fields wire
@@ -725,7 +756,7 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		if (entry === undefined || entry.member !== relation) {
 			throw errors.new(`relation ${relation.name} is not a member of schema ${theory.name}`)
 		}
-		if ("handles" in relation.data) {
+		if (isClosedMember(relation)) {
 			throw errors.new(
 				`relation ${relation.name} is closed — its extension is schema data (axioms), never scanned or written`
 			)
@@ -738,15 +769,16 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		if (entry === undefined || !isMemberName(fact.relation)) {
 			throw errors.new(`bumbledb violation cites unknown relation ${fact.relation}`)
 		}
-		const declared = declaredFieldsOf(entry.member)
+		const declared = sealedFieldsOf(entry.member)
 		const decoded: Record<string, FactValue> = {}
 		for (const cell of fact.fields) {
 			const cited = declared.find(function byName(candidate) {
 				return candidate.name === cell.name
 			})
+			const roster = rosterOf(cited?.field)
 			decoded[cell.name] =
-				cited !== undefined && "closed" in cited.field
-					? handleOf(`violation fact ${fact.relation} field ${cell.name}`, cited.field.closed, cell.value)
+				roster !== undefined
+					? handleOf(`violation fact ${fact.relation} field ${cell.name}`, roster, cell.value)
 					: cell.value
 		}
 		return Object.freeze({ relation: fact.relation, fact: Object.freeze(decoded) })
@@ -828,25 +860,22 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		): Fact<R> | undefined {
 			assertLive()
 			const entry = resolveOrdinary(relation)
-			if (declaredKey !== undefined) {
-				if (!isStatementValue(keyOrStatement)) {
-					throw errors.new("keyed get takes a key() statement value as its second argument")
+			return selectKeyRead(
+				keyOrStatement,
+				declaredKey,
+				function byStatement(statement, key) {
+					return readThroughKey(relation, entry, declaredKeyOf(relation, statement), recordOf(key))
+				},
+				function byPrimary(key) {
+					const primaryKey = entry.primaryKey
+					if (primaryKey === undefined) {
+						throw errors.new(
+							`relation ${relation.name} has no candidate key — keyed get requires a fresh field or a declared key statement`
+						)
+					}
+					return readThroughKey(relation, entry, primaryKey, recordOf(key))
 				}
-				const selected = declaredKeyOf(relation, keyOrStatement)
-				return readThroughKey(relation, entry, selected, recordOf(declaredKey))
-			}
-			if (isStatementValue(keyOrStatement)) {
-				throw errors.new(
-					"keyed get with a statement selector also takes the key object — get(relation, keyStatement, key)"
-				)
-			}
-			const primaryKey = entry.primaryKey
-			if (primaryKey === undefined) {
-				throw errors.new(
-					`relation ${relation.name} has no candidate key — keyed get requires a fresh field or a declared key statement`
-				)
-			}
-			return readThroughKey(relation, entry, primaryKey, recordOf(keyOrStatement))
+			)
 		}
 		return { contains, get }
 	}
@@ -1003,18 +1032,16 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		declaredKey?: DeclaredKeyFact<R, P>
 	): Fact<R> | undefined {
 		return read(function getInScope(snap) {
-			if (declaredKey !== undefined) {
-				if (!isStatementValue(keyOrStatement)) {
-					throw errors.new("keyed get takes a key() statement value as its second argument")
+			return selectKeyRead(
+				keyOrStatement,
+				declaredKey,
+				function byStatement(statement, key) {
+					return snap.get(relation, statement, key)
+				},
+				function byPrimary(key) {
+					return snap.get(relation, key)
 				}
-				return snap.get(relation, keyOrStatement, declaredKey)
-			}
-			if (isStatementValue(keyOrStatement)) {
-				throw errors.new(
-					"keyed get with a statement selector also takes the key object — get(relation, keyStatement, key)"
-				)
-			}
-			return snap.get(relation, keyOrStatement)
+			)
 		})
 	}
 
@@ -1298,13 +1325,32 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		return commitWitnessed(state, txHandle)
 	}
 
+	/**
+	 * The witnessed retry loop. What it retries: the benign race — the
+	 * host's OWN interleaved commit landing between an attempt's snapshot
+	 * and its witnessed begin (every writer shares this handle, so a move
+	 * is always self-inflicted) — by rerunning the WHOLE callback on a
+	 * fresh snapshot, which converges because each rerun witnesses a
+	 * strictly newer generation. What it refuses: the pathology where the
+	 * callback itself (even indirectly) issues a plain `db.write` before
+	 * its first tx verb, moving the generation on EVERY attempt — an
+	 * unbounded loop would spin forever with no diagnostic, so past
+	 * {@link WITNESSED_ATTEMPT_CAP} attempts the loop throws the typed
+	 * {@link ErrWitnessedLivelock} instead (the engine's ruling: the
+	 * error, never a loop — retry is host policy, and this is the host
+	 * policy's own honesty bound).
+	 */
 	function writeWitnessed<R>(fn: (snap: ReadScope<Rels>, tx: Tx<Rels>) => R): WitnessedWriteResult<Rels, R> {
-		for (;;) {
+		for (let attempts = 0; attempts < WITNESSED_ATTEMPT_CAP; attempts += 1) {
 			const attempt = witnessedAttempt(fn)
 			if (attempt !== undefined) {
 				return attempt
 			}
 		}
+		throw errors.wrap(
+			ErrWitnessedLivelock,
+			`writeWitnessed livelock: the generation moved on all ${WITNESSED_ATTEMPT_CAP} attempts against schema ${theory.name}`
+		)
 	}
 
 	/**
@@ -1326,17 +1372,9 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 			if (member === undefined) {
 				throw errors.new(`bumbledb manifest drift: schema ${theory.name} lost relation ${name}`)
 			}
-			const sealed =
-				"handles" in member.data
-					? [
-							"id",
-							...member.data.columns.map(function columnName(column) {
-								return column.name
-							})
-						]
-					: member.data.fields.map(function fieldName(declared) {
-							return declared.name
-						})
+			const sealed = sealedFieldsOf(member).map(function fieldName(declared) {
+				return declared.name
+			})
 			sealed.forEach(function verifyField(fieldName, fieldOrdinal) {
 				if (entry.fieldIds.get(fieldName) !== fieldOrdinal) {
 					throw errors.new(
@@ -1581,4 +1619,4 @@ export type {
 	WitnessedWriteResult,
 	WriteResult
 }
-export { abandon, Db, ErrNewtypeMismatch }
+export { abandon, Db, ErrNewtypeMismatch, ErrWitnessedLivelock, WITNESSED_ATTEMPT_CAP }

package/src/exhume.ts

@@ -26,7 +26,7 @@
 
 import * as errors from "@superbuilders/errors"
 import type { FactValue, Manifest } from "#native.ts"
-import { native } from "#native.ts"
+import { bridged, native } from "#native.ts"
 import type { ValueTypeSpec } from "#spec.ts"
 
 /**
@@ -132,20 +132,6 @@ interface Exhumed {
 	scan(relation: string): readonly ExhumedFact[]
 }
 
-/**
- * The bridge guard (db.ts's twin over this module's calls): runs one
- * native call and wraps anything it throws, so marshal-shape and
- * handle-lifecycle refusals cross as genuine typed failures, never bare
- * foreign errors.
- */
-function bridged<T>(context: string, run: () => T): T {
-	const result = errors.trySync(run)
-	if (result.error) {
-		throw errors.wrap(result.error, context)
-	}
-	return result.data
-}
-
 /**
  * Shapes the bridge's manifest rendering of the stored descriptor into the
  * SDK's {@link ExhumedDescriptor}: same relations in the same engine-id

package/src/face.ts

@@ -101,11 +101,11 @@ type FaceSource = AnyRelation | AnyClosed | AnySelected | AnySelectedClosed
  * names address the sealed shape).
  */
 type FaceFields<S extends FaceSource> = S extends AnySelected
-	? keyof S["relation"]["fields"] & string
+	? keyof RelationFields<S["relation"]> & string
 	: S extends AnySelectedClosed
 		? "id" | (keyof S["relation"]["columns"] & string)
 		: S extends AnyRelation
-			? keyof S["fields"] & string
+			? keyof RelationFields<S> & string
 			: S extends { readonly axioms: Readonly<Record<string, infer Row>> }
 				? "id" | (keyof Row & string)
 				: never
@@ -263,7 +263,8 @@ function on<S extends FaceSource>(source: S, fields: string | readonly string[])
 }
 
 /**
- * The trusted seam of the face mint (the `refsComplete` pattern): the
+ * The trusted admission seam of the face mint (the pattern's home is
+ * `isTypedScope` in query/lower.ts): the
  * checkable facts — the value carries exactly the source and projection it
  * was built from, and `data.owner` is exactly the owner {@link faceParts}
  * resolves for that source — are verified before the wide construction is

package/src/fields.ts

@@ -172,15 +172,31 @@ type Infer<F extends AnyField> = F extends { readonly kind: "bool" }
 							: never
 
 /**
- * The typed shape refusal of the selection-literal machine — reached only
+ * The typed shape refusal shared by every literal machine — the selection
+ * lowering here, the row marshaler (`marshal.ts`), and the query-literal
+ * tagger (`query/lower.ts`) all throw through this ONE voice; reached only
  * through ill-typed input (the well-typed surfaces make it unrepresentable).
  */
-function literalShapeError(expected: string, value: unknown): Error {
-	return errors.new(`selection literal shape mismatch: expected ${expected}, got ${typeof value}`)
+function literalShapeError(context: string, expected: string, value: unknown): Error {
+	return errors.new(`${context}: expected ${expected}, got ${typeof value}`)
 }
 
-/** Narrows an interval literal: a plain object with bigint start/end. */
-function isIntervalLiteral(value: unknown): value is IntervalValue {
+/**
+ * The roster a field descriptor carries — THE one reader: present exactly
+ * on a closed-reference descriptor (the structural `closed` property of
+ * {@link ClosedIdField}), absent on every other field kind. Tolerates
+ * `undefined` so name-lookup misses flow through without a re-spelled
+ * probe at every call site.
+ */
+function rosterOf(field: AnyField | undefined): ClosedRoster | undefined {
+	if (field !== undefined && "closed" in field) {
+		return field.closed
+	}
+	return undefined
+}
+
+/** Narrows an interval-shaped value: a plain object with bigint start/end — THE one interval predicate. */
+function isIntervalValue(value: unknown): value is IntervalValue {
 	return (
 		typeof value === "object" &&
 		value !== null &&
@@ -202,7 +218,7 @@ function isIntervalLiteral(value: unknown): value is IntervalValue {
  */
 function handleLiteral(closed: ClosedRoster, value: unknown): LiteralSpec {
 	if (typeof value !== "string") {
-		throw literalShapeError(`a ${closed.name} handle name (string)`, value)
+		throw literalShapeError("selection literal", `a ${closed.name} handle name (string)`, value)
 	}
 	if (!closed.handles.includes(value)) {
 		throw errors.new(`"${value}" is not a handle of ${closed.name} — the roster is ${closed.handles.join(", ")}`)
@@ -212,8 +228,8 @@ function handleLiteral(closed: ClosedRoster, value: unknown): LiteralSpec {
 
 /** Lowers one interval literal at its element type. */
 function intervalLiteral(element: "u64" | "i64", value: unknown): LiteralSpec {
-	if (!isIntervalLiteral(value)) {
-		throw literalShapeError("interval ({ start, end } bigints)", value)
+	if (!isIntervalValue(value)) {
+		throw literalShapeError("selection literal", "interval ({ start, end } bigints)", value)
 	}
 	if (element === "u64") {
 		return { kind: "value", value: { kind: "intervalU64", start: value.start, end: value.end } }
@@ -306,37 +322,50 @@ function interval(element: U64Field | I64Field, width?: bigint): IntervalField<"
  * else lowers to a plain value tagged by the field's structural kind.
  */
 function literalOf(field: AnyField, value: unknown): LiteralSpec {
-	if ("closed" in field) {
-		return handleLiteral(field.closed, value)
+	const roster = rosterOf(field)
+	if (roster !== undefined) {
+		return handleLiteral(roster, value)
 	}
 	switch (field.kind) {
 		case "bool": {
 			if (typeof value !== "boolean") {
-				throw literalShapeError("boolean", value)
+				throw literalShapeError("selection literal", "boolean", value)
 			}
 			return { kind: "value", value: { kind: "bool", value } }
 		}
 		case "u64": {
 			if (typeof value !== "bigint") {
-				throw literalShapeError("bigint", value)
+				throw literalShapeError("selection literal", "bigint", value)
 			}
 			return { kind: "value", value: { kind: "u64", value } }
 		}
 		case "i64": {
 			if (typeof value !== "bigint") {
-				throw literalShapeError("bigint", value)
+				throw literalShapeError("selection literal", "bigint", value)
 			}
 			return { kind: "value", value: { kind: "i64", value } }
 		}
 		case "str": {
 			if (typeof value !== "string") {
-				throw literalShapeError("string", value)
+				throw literalShapeError("selection literal", "string", value)
+			}
+			/**
+			 * The marshal's bijection law at the schema-literal seam
+			 * (`marshal.ts` cellOf): a lone surrogate would cross dbCreate
+			 * lossily (stored as U+FFFD engine-side), collapsing two
+			 * distinct TS schema values into one stored theory/fingerprint
+			 * and splitting the canonical statement rendering from the
+			 * SDK's. All three string-admission seams — fact row, query
+			 * literal/param, schema literal — enforce the one law.
+			 */
+			if (!value.isWellFormed()) {
+				throw literalShapeError("selection literal", "well-formed string", value)
 			}
 			return { kind: "value", value: { kind: "string", value } }
 		}
 		case "bytes": {
 			if (!(value instanceof Uint8Array)) {
-				throw literalShapeError("Uint8Array", value)
+				throw literalShapeError("selection literal", "Uint8Array", value)
 			}
 			return { kind: "value", value: { kind: "fixedBytes", value } }
 		}
@@ -359,4 +388,17 @@ export type {
 	StrField,
 	U64Field
 }
-export { assertDeclarationOrderKey, bool, bytes, i64, interval, literalOf, span, str, u64 }
+export {
+	assertDeclarationOrderKey,
+	bool,
+	bytes,
+	i64,
+	interval,
+	isIntervalValue,
+	literalOf,
+	literalShapeError,
+	rosterOf,
+	span,
+	str,
+	u64
+}

package/src/index.ts

@@ -14,10 +14,13 @@
  * `db.prepare` as a plain value; the comparison/connective builders are
  * also free exports, and the free names `eq`/`not`/`and`/`or` collide with
  * common host identifiers — import aliasing is the answer; the SDK does
- * not rename for collision-avoidance), and the exhume surface
+ * not rename for collision-avoidance), the exhume surface
  * (`Db.exhume` — the one schema-independent read path: the store's
  * self-described shapes and raw facts by name, typed at bare structural
- * values, deliberately schema-free). The raw native bridge is not exported.
+ * values, deliberately schema-free), and the answer-ordering helpers
+ * (`by`/`desc` — sort keys as data for the language's own `.sort`; answers
+ * are sets, the engine never orders, and limit is the language's own
+ * `.slice`). The raw native bridge is not exported.
  */
 
 export type {
@@ -50,7 +53,7 @@ export type {
 	WitnessedWriteResult,
 	WriteResult
 } from "#db.ts"
-export { abandon, Db, ErrNewtypeMismatch } from "#db.ts"
+export { abandon, Db, ErrNewtypeMismatch, ErrWitnessedLivelock, WITNESSED_ATTEMPT_CAP } from "#db.ts"
 export type {
 	Exhumed,
 	ExhumedAxiom,
@@ -105,6 +108,8 @@ export type {
 	Staleness,
 	StatementKindTag
 } from "#native.ts"
+export type { Desc, SortKey } from "#order.ts"
+export { by, desc } from "#order.ts"
 
 export type {
 	AnyCond,
@@ -119,7 +124,7 @@ export type {
 	SelectColumn,
 	Tree
 } from "#query/atom.ts"
-export { ALLEN, allen, and, covers, eq, ge, gt, le, lt, ne, not, or, pointIn } from "#query/atom.ts"
+export { ALLEN, allen, and, eq, ge, gt, le, lt, ne, not, or, pointIn } from "#query/atom.ts"
 export type {
 	AnyQuery,
 	AnyRuleValue,
@@ -150,16 +155,13 @@ export type {
 	ParamEntry,
 	ParamsRecord,
 	SetParam,
-	Var,
-	VarsRecord
+	Var
 } from "#query/scope.ts"
 export type { Agg, SelectEntry } from "#query/select.ts"
 export type {
 	AnyRelation,
 	AnySelected,
 	Fact,
-	FieldRef,
-	FieldRefs,
 	FieldsShape,
 	FreshKeys,
 	InsertFact,

package/src/law.ts

@@ -52,6 +52,7 @@
 
 import * as errors from "@superbuilders/errors"
 import type { AnyClosed } from "#closed.ts"
+import { isClosedMember, sealedFieldsOf } from "#closed.ts"
 import type { FaceData } from "#face.ts"
 import type { AnyRelation, RelationFields } from "#relation.ts"
 import type { SchemaRelation, SchemaRelations } from "#schema.ts"
@@ -328,22 +329,21 @@ interface MemberCoords {
 	readonly fields: ReadonlyArray<{ readonly name: string; readonly generator: boolean }>
 }
 
-/** Reads every member's coordinates off the relation record, declaration order throughout. */
+/**
+ * Reads every member's coordinates off the relation record, declaration
+ * order throughout — the sealed shape through THE one reader
+ * (`sealedFieldsOf`): a closed member's generator is its synthetic `id`
+ * (ordinal 0), an ordinary member's generators are its fresh-marked fields.
+ */
 function memberCoords(relations: SchemaRelations): MemberCoords[] {
 	const out: MemberCoords[] = []
 	for (const [relationName, member] of Object.entries(relations)) {
-		if ("handles" in member.data) {
-			const fields = [
-				{ name: "id", generator: true },
-				...member.data.columns.map(function columnCoord(column) {
-					return { name: column.name, generator: false }
-				})
-			]
-			out.push({ relation: relationName, fields })
-			continue
-		}
-		const fields = member.data.fields.map(function fieldCoord(declared) {
-			return { name: declared.name, generator: "fresh" in declared.field && declared.field.fresh === true }
+		const closed = isClosedMember(member)
+		const fields = sealedFieldsOf(member).map(function fieldCoord(declared) {
+			return {
+				name: declared.name,
+				generator: closed ? declared.name === "id" : "fresh" in declared.field && declared.field.fresh === true
+			}
 		})
 		out.push({ relation: relationName, fields })
 	}
@@ -490,7 +490,8 @@ function computeClasses(name: string, relations: SchemaRelations, statements: re
 }
 
 /**
- * The trusted seam of the class-map mint (the `refsComplete` pattern): the
+ * The trusted admission seam of the class-map mint (the pattern's home is
+ * `isTypedScope` in query/lower.ts): the
  * checkable facts — one own record per declared relation, one own entry
  * per declared field (the closed sealed shape's `id` included), everything
  * frozen — are verified before the runtime map is admitted at the computed

package/src/lower.ts

@@ -9,11 +9,12 @@
  */
 
 import type { AnyClosed } from "#closed.ts"
+import { isClosedMember } from "#closed.ts"
 import type { FaceData } from "#face.ts"
 import type { AnyField } from "#fields.ts"
 import type { RelationClasses } from "#law.ts"
 import type { AnyRelation } from "#relation.ts"
-import type { AnySchema, SchemaRelation } from "#schema.ts"
+import type { AnySchema } from "#schema.ts"
 import type {
 	FieldSpec,
 	LiteralSetSpec,
@@ -25,14 +26,6 @@ import type {
 } from "#spec.ts"
 import type { Statement } from "#statements.ts"
 
-/**
- * The relation-kind discriminant: a closed relation's runtime description
- * carries its handle roster, an ordinary relation's never does.
- */
-function isClosedMember(member: SchemaRelation): member is AnyClosed {
-	return "handles" in member.data
-}
-
 /**
  * Lowers one field descriptor's structural type to the wire
  * {@link ValueTypeSpec}: the S1 kind tags map 1:1 onto the `ValueType`