@bjornpagen/bumbledb 0.3.0 → 0.5.0

package/src/fields.ts

@@ -50,11 +50,15 @@ function span(start: bigint, end: bigint): IntervalValue {
  * A closed relation's roster as seen from a referencing field: the handle
  * namespace `where()` selections and ground axioms resolve bare handle ids
  * through (the macro's own rule: a handle is legal exactly on a field that
- * references a closed relation).
+ * references a closed relation). The handle union is PRECISE — `H` carries
+ * the literal handle names in declaration order (the unbound `string`
+ * default exists only as the fallback where no roster is in scope); the
+ * runtime twin is the same frozen declaration-order array that was always
+ * there.
  */
-interface ClosedRoster {
+interface ClosedRoster<H extends string = string> {
 	readonly name: string
-	readonly handles: readonly string[]
+	readonly handles: readonly H[]
 }
 
 /** The `bool` field descriptor: value type `boolean`. No `.fresh` (macro parity). */
@@ -125,14 +129,16 @@ interface IntervalField<
 
 /**
  * A closed relation's reference field descriptor (`Kind.id`) — a u64
- * descriptor carrying the closed linkage: the roster resolves bare handle
- * ids in selections and ground axioms, and `schema()` names the id's
- * generator class `"Kind.id"`. Terminal: no `.fresh` — a vocabulary's rows
- * are ground axioms, never minted.
+ * descriptor carrying the closed linkage: the roster resolves handle
+ * literals in selections and ground axioms, and `schema()` names the id's
+ * generator class `"Kind.id"`. The handle union `H` is the field's VALUE
+ * TYPE (see {@link Infer}); `kind: "u64"` stays load-bearing for the class
+ * map and JoinOk, which compare kind/class/width/element. Terminal: no
+ * `.fresh` — a vocabulary's rows are ground axioms, never minted.
  */
-interface ClosedIdField {
+interface ClosedIdField<H extends string = string> {
 	readonly kind: "u64"
-	readonly closed: ClosedRoster
+	readonly closed: ClosedRoster<H>
 }
 
 /** Any field descriptor, whatever its kind or marks. */
@@ -142,32 +148,55 @@ type AnyField = BoolField | StrField | U64Field | FreshU64Field | I64Field | Byt
  * The bare structural VALUE type of a field descriptor — the one total
  * definition every fact, result row, and query term reads: `bool` →
  * `boolean`, `str` → `string`, `u64`/`i64` → `bigint`, `bytes<N>` →
- * `Uint8Array`, intervals → {@link IntervalValue}.
+ * `Uint8Array`, intervals → {@link IntervalValue}, and a closed reference →
+ * its PRECISE handle union (`"DirectPass" | "Failed"` — the string-literal
+ * union IS the value type at the TS surface; the engine keeps u64 row ids
+ * and the marshal owns the bijection). The closed arm precedes the `u64`
+ * arm because a closed reference is structurally a u64 descriptor plus the
+ * roster.
  */
 type Infer<F extends AnyField> = F extends { readonly kind: "bool" }
 	? boolean
 	: F extends { readonly kind: "str" }
 		? string
-		: F extends { readonly kind: "u64" }
-			? bigint
-			: F extends { readonly kind: "i64" }
+		: F extends { readonly closed: { readonly handles: readonly (infer H extends string)[] } }
+			? H
+			: F extends { readonly kind: "u64" }
 				? bigint
-				: F extends { readonly kind: "bytes" }
-					? Uint8Array
-					: F extends { readonly kind: "interval" }
-						? IntervalValue
-						: never
+				: F extends { readonly kind: "i64" }
+					? bigint
+					: F extends { readonly kind: "bytes" }
+						? Uint8Array
+						: F extends { readonly kind: "interval" }
+							? IntervalValue
+							: 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 &&
@@ -179,28 +208,28 @@ function isIntervalLiteral(value: unknown): value is IntervalValue {
 }
 
 /**
- * Resolves one closed-handle literal: the handle id (a bare bigint) back to
- * its handle NAME through the roster — an out-of-roster id is a
- * construction error, the belt the type level deliberately does not provide
- * (structural values make any bigint spellable here; the roster judges).
+ * Resolves one closed-handle literal: the handle NAME, verified against the
+ * roster — an unknown name is a construction error, the belt the wide
+ * fallback type deliberately does not provide (structural values make any
+ * string spellable here; the roster judges). The name IS the value at the
+ * TS surface (the drizzle law); the wire literal already crossed as
+ * `{ kind: "handle", handle }`, so the output — and every fingerprint
+ * derived from it — is untouched.
  */
 function handleLiteral(closed: ClosedRoster, value: unknown): LiteralSpec {
-	if (typeof value !== "bigint") {
-		throw literalShapeError(`a ${closed.name} handle id (bigint)`, value)
+	if (typeof value !== "string") {
+		throw literalShapeError("selection literal", `a ${closed.name} handle name (string)`, value)
 	}
-	const handle = closed.handles[Number(value)]
-	if (handle === undefined) {
-		throw errors.new(
-			`closed relation ${closed.name} has no handle with id ${value} (roster holds ${closed.handles.length})`
-		)
+	if (!closed.handles.includes(value)) {
+		throw errors.new(`"${value}" is not a handle of ${closed.name} — the roster is ${closed.handles.join(", ")}`)
 	}
-	return { kind: "handle", handle }
+	return { kind: "handle", handle: value }
 }
 
 /** 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 } }
@@ -288,43 +317,55 @@ function interval(element: U64Field | I64Field, width?: bigint): IntervalField<"
  * Lowers one host literal at its field position to the wire
  * {@link LiteralSpec} — the selection-literal machine ground axioms and
  * `where()` bindings both ride (one machine, same errors — the macro's own
- * rule). A value on a closed-reference field resolves to its handle NAME
- * (the id is verified against the roster: an out-of-roster id is a
- * construction error); everything else lowers to a plain value tagged by
- * the field's structural kind.
+ * rule). A value on a closed-reference field IS its handle NAME (verified
+ * against the roster: an unknown name is a construction error); everything
+ * 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 } }
 		}
@@ -347,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,
@@ -75,12 +78,11 @@ export type {
 	FaceShapeMismatch,
 	FaceShapes,
 	FaceSource,
-	OneOf,
 	OwnerOf,
 	SameArity,
 	SameShapes
 } from "#face.ts"
-export { on, oneOf } from "#face.ts"
+export { on } from "#face.ts"
 export type {
 	AnyField,
 	BoolField,
@@ -106,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,
@@ -120,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,
@@ -151,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`

package/src/marshal.ts

@@ -13,10 +13,23 @@
  * the engine admitted IS a legal fact of its relation (the same trust
  * direction as Rust's typed readback). Shape mismatches here are genuine
  * failures and THROW typed; they are never domain data.
+ *
+ * THE CLOSED BIJECTION (0.4.0): a closed-referencing cell crosses this
+ * boundary as its handle NAME — the write side lowers name → u64 row id
+ * (declaration order = row ids, the sealed roster's own law, ≤ 256 rows),
+ * the read side lifts id → name, and both directions are total and static
+ * over the roster. An unknown name is a pointed THROW at the write seam —
+ * a deliberate UPGRADE over 0.3.0, where any bigint sailed through the
+ * marshal to a commit-time containment violation; the wrong spelling now
+ * dies here, before the engine ever sees the row. An out-of-roster id on
+ * the read side (reachable only in a store whose closed-typed column was
+ * never pinned by its containment law) is equally pointed — never a
+ * silent fallback, never `undefined`.
  */
 
 import * as errors from "@superbuilders/errors"
-import type { AnyField } from "#fields.ts"
+import type { AnyField, ClosedRoster } from "#fields.ts"
+import { isIntervalValue, literalShapeError, rosterOf } from "#fields.ts"
 import type { FactValue } from "#native.ts"
 import type { AnyRelation, Fact, FreshKeys, RelationData } from "#relation.ts"
 
@@ -54,23 +67,6 @@ type KeyFact<R extends AnyRelation> = [FreshKeys<R>] extends [never]
 	? Partial<Fact<R>>
 	: { [K in FreshKeys<R>]: Fact<R>[K] }
 
-/** The typed shape refusal of the row marshaler — a genuine failure, never data. */
-function cellShapeError(context: string, expected: string, value: unknown): Error {
-	return errors.new(`${context}: expected ${expected}, got ${typeof value}`)
-}
-
-/** Narrows an interval cell: a plain object with bigint start/end. */
-function isIntervalCell(value: unknown): value is { readonly start: bigint; readonly end: bigint } {
-	return (
-		typeof value === "object" &&
-		value !== null &&
-		"start" in value &&
-		"end" in value &&
-		typeof value.start === "bigint" &&
-		typeof value.end === "bigint"
-	)
-}
-
 /**
  * Reprojects any host object to a string-indexed record — the boundary
  * through which generic fact objects (whose type parameters carry no index
@@ -80,31 +76,82 @@ function recordOf(fact: object): Record<string, unknown> {
 	return Object.fromEntries(Object.entries(fact))
 }
 
+/**
+ * The write half of the closed bijection: one handle NAME to its u64 row
+ * id (declaration order = row ids — the engine's own minting of the
+ * sealed extension). An unknown name is a pointed refusal naming the
+ * vocabulary and its roster — the 0.4.0 upgrade over any-bigint-compiles:
+ * the wrong spelling dies at the marshal, never as a commit-time
+ * violation. `indexOf` is the whole machine (the roster is ≤ 256 rows,
+ * engine law — no map is warranted).
+ */
+function closedCellOf(context: string, closed: ClosedRoster, name: string): FactValue {
+	const id = closed.handles.indexOf(name)
+	if (id === -1) {
+		throw errors.new(
+			`${context}: "${name}" is not a handle of ${closed.name} — the roster is ${closed.handles.join(", ")}`
+		)
+	}
+	return BigInt(id)
+}
+
+/**
+ * The read half of the closed bijection: one u64 row id back to its handle
+ * NAME (`Number(cell)` is safe — the sealed extension holds at most 256
+ * rows, engine law). An id outside the roster THROWS pointed, never a
+ * silent fallback and never `undefined`: the state is reachable only in a
+ * store whose closed-typed column was never pinned by its containment law,
+ * and the error names that missing piece.
+ */
+function handleOf(context: string, closed: ClosedRoster, cell: FactValue): string {
+	if (typeof cell !== "bigint") {
+		throw literalShapeError(context, `a ${closed.name} handle id (bigint)`, cell)
+	}
+	const handle = closed.handles[Number(cell)]
+	if (handle === undefined) {
+		throw errors.new(
+			`${context}: id ${cell} is outside the ${closed.name} roster (${closed.handles.join(", ")}) — the column types ${closed.name} but no law pins it — a containment statement is the missing piece`
+		)
+	}
+	return handle
+}
+
 /**
  * Marshals one host cell at its field position to the natural wire value,
  * schema-directed by the field descriptor's structural kind (never
- * guessed). Values are bare, so the runtime values ARE the wire's natural
- * JS values; widths and domain labels are the engine's own judgment at the
- * write boundary.
+ * guessed). A closed-referencing cell arrives as its handle NAME and
+ * lowers through {@link closedCellOf} — the arm precedes the switch
+ * because a closed reference is structurally a u64 descriptor plus the
+ * roster (the same precedence `Infer` pins at the type level). Everything
+ * else is bare, so the runtime values ARE the wire's natural JS values;
+ * widths and domain labels are the engine's own judgment at the write
+ * boundary.
  */
 function cellOf(context: string, field: AnyField, value: unknown): FactValue {
+	const roster = rosterOf(field)
+	if (roster !== undefined) {
+		if (typeof value !== "string") {
+			throw literalShapeError(context, `a ${roster.name} handle name (string)`, value)
+		}
+		return closedCellOf(context, roster, value)
+	}
 	switch (field.kind) {
 		case "bool": {
 			if (typeof value !== "boolean") {
-				throw cellShapeError(context, "boolean", value)
+				throw literalShapeError(context, "boolean", value)
 			}
 			return value
 		}
 		case "u64":
 		case "i64": {
 			if (typeof value !== "bigint") {
-				throw cellShapeError(context, "bigint", value)
+				throw literalShapeError(context, "bigint", value)
 			}
 			return value
 		}
 		case "str": {
 			if (typeof value !== "string") {
-				throw cellShapeError(context, "string", value)
+				throw literalShapeError(context, "string", value)
 			}
 			/**
 			 * A lone surrogate would be lossily replaced with U+FFFD at the
@@ -114,19 +161,19 @@ function cellOf(context: string, field: AnyField, value: unknown): FactValue {
 			 * lookup lowers through.
 			 */
 			if (!value.isWellFormed()) {
-				throw cellShapeError(context, "well-formed string", value)
+				throw literalShapeError(context, "well-formed string", value)
 			}
 			return value
 		}
 		case "bytes": {
 			if (!(value instanceof Uint8Array)) {
-				throw cellShapeError(context, "Uint8Array", value)
+				throw literalShapeError(context, "Uint8Array", value)
 			}
 			return value
 		}
 		case "interval": {
-			if (!isIntervalCell(value)) {
-				throw cellShapeError(context, "interval ({ start, end } bigints)", value)
+			if (!isIntervalValue(value)) {
+				throw literalShapeError(context, "interval ({ start, end } bigints)", value)
 			}
 			return { start: value.start, end: value.end }
 		}
@@ -210,7 +257,9 @@ function isMintedFresh<R extends AnyRelation>(
 /**
  * Unmarshals one positional row to the relation's named, frozen fact object
  * of bare structural values — the inverse of {@link rowOf},
- * ordinal-directed by the same declaration order.
+ * ordinal-directed by the same declaration order. Closed-referencing cells
+ * lift id → handle NAME through {@link handleOf} (the read half of the
+ * bijection), so every fact a user sees speaks the roster's vocabulary.
  */
 function factOf<R extends AnyRelation>(relation: R, row: readonly FactValue[]): Fact<R> {
 	const data = relation.data
@@ -225,7 +274,9 @@ function factOf<R extends AnyRelation>(relation: R, row: readonly FactValue[]):
 		if (cell === undefined) {
 			throw errors.new(`relation ${data.name}: row cell ${ordinal} (${declared.name}) is absent`)
 		}
-		decoded[declared.name] = cell
+		const roster = rosterOf(declared.field)
+		decoded[declared.name] =
+			roster !== undefined ? handleOf(`relation ${data.name} field ${declared.name}`, roster, cell) : cell
 	})
 	Object.freeze(decoded)
 	if (!isCompleteFact(relation, decoded)) {
@@ -235,4 +286,4 @@ function factOf<R extends AnyRelation>(relation: R, row: readonly FactValue[]):
 }
 
 export type { KeyFact, Minted }
-export { cellOf, factOf, isFreshField, isMintedFresh, keyRowOf, recordOf, rowOf }
+export { cellOf, factOf, handleOf, isFreshField, isMintedFresh, keyRowOf, recordOf, rowOf }

package/src/native.ts

@@ -241,7 +241,7 @@ interface Violation {
 }
 
 /**
- * `dbCreate`/`dbOpen`'s domain outcome. `schemaError` covers both spec
+ * `dbCreate`/`dbOpen`'s domain outcome. `schemaError` spans both spec
  * resolution (unresolvable names, banned spellings — every issue in one
  * message) and schema validation at the declaration boundary;
  * `newtypeMismatch` is the coherence wall's own kind — a spec whose
@@ -471,8 +471,12 @@ interface Native {
  * The sole platform this release ships (PRD-03 ruling 1: prebuilt-only,
  * darwin-arm64). The per-platform-package structure below makes adding
  * `darwin-x64`/`linux-*`/`win32-*` pure addition — one more `os`/`cpu`-gated
- * package plus a CI matrix — never a redesign, so this string is the only
- * place the shipped set is named for the unsupported-platform message.
+ * package plus a CI matrix — never a redesign. This constant names the
+ * shipped set for the unsupported-platform message; the build's
+ * `PUBLISH_PLATFORM` (`scripts/platform.ts` — src cannot import scripts,
+ * the packaging boundary) and the `ts/.gitignore` carve-out spell the same
+ * target, and the single-source pin in `test/build-platform.test.ts` holds
+ * all three in lockstep.
  */
 const SHIPPED_PLATFORMS = "darwin-arm64"
 
@@ -536,6 +540,20 @@ function loadNativeBinding(platform: string, arch: string): Native {
  */
 const native: Native = loadNativeBinding(process.platform, process.arch)
 
+/**
+ * The bridge guard — THE one wrapper every native call crosses (db.ts and
+ * exhume.ts both import it): runs one native call and wraps anything it
+ * throws, so 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
+}
+
 export type {
 	AggOpIr,
 	AtomIr,
@@ -577,4 +595,4 @@ export type {
 	ViolationFact,
 	WriteFromResult
 }
-export { loadNativeBinding, native }
+export { bridged, loadNativeBinding, native, SHIPPED_PLATFORMS }