@bjornpagen/bumbledb 0.2.0 → 0.3.0

package/src/closed.ts

@@ -4,20 +4,31 @@
  * tiers, one function. The emission per closed relation mirrors the
  * macro's (host-enum analog): handle CONSTANTS on the value
  * (`Kind.Checking`, ids = declaration order, each a BARE `bigint` — no
- * brand), the `fromId` weld, an `id` field descriptor carrying the handle
- * DOMAIN (`"KindId"`, mirroring Rust's `closed relation Kind as KindId`)
+ * brand), the `fromId` weld, an `id` field descriptor carrying the CLOSED
+ * LINKAGE (the roster — pure structure, no declared domain: the laws type
+ * the columns, and `schema()` names the id's generator class `"Kind.id"`)
  * for other relations' field blocks (`kind: Kind.id`), payload readback
  * (`Kind.axioms`), and the declared payload column descriptors
  * (`Kind.columns` — the runtime twin of the `Cols` type parameter, which
- * the face layer's domain wall reads). Bare tier: `closed("Kind", ["Checking",
- * "Savings"])`. Payload tier: `closed("Sev", { pages: bool })({ Critical:
- * { pages: true }, ... })` — the axioms record IS the handle declaration,
- * every handle carrying every column exactly once (type-enforced). No fact
- * type and no insert surface exist — closed relations are unwritable by
- * construction: the value simply lacks the writable relation shape.
+ * the face layer's structural wall reads). Bare tier: `closed("Kind", ["Checking",
+ * "Savings"])`. Payload tier: `closed("Sev", { pages: bool }, { Critical:
+ * { pages: true }, ... })` — one call, three arguments (the curried tier-2
+ * spelling is DELETED — canonical utterance): the axioms record IS the
+ * handle declaration, every handle carrying every column exactly once
+ * (type-enforced). No fact type and no insert surface exist — closed
+ * relations are unwritable by construction: the value simply lacks the
+ * writable relation shape. Both tiers mint `match()` — exhaustive dispatch
+ * over the handle union (arms typed by the mapped type, so a missing or
+ * extra arm is a compile error; the payload tier's arm receives the typed
+ * axiom row). The payload tier additionally mints `where()` — the
+ * ψ-selection surface (`Kind.where({ mastered: true })` as a face source),
+ * resolved through the ONE selection machine
+ * (`relation.ts::resolveSelection`); the bare tier has no payload columns to
+ * select on, so `.where` is absent there, at the type AND on the value.
  */
 
 import * as errors from "@superbuilders/errors"
+import type { OneOf } from "#face.ts"
 import {
 	type AnyField,
 	assertDeclarationOrderKey,
@@ -26,13 +37,17 @@ import {
 	type Infer,
 	literalOf
 } from "#fields.ts"
+import { resolveSelection, type SelectionBinding } from "#relation.ts"
 import type { LiteralSpec } from "#spec.ts"
 
 /**
  * The value-surface property names a handle may not shadow — the macro's
  * name-collision diagnostic, here over the closed value's own properties
  * (`relation`/`selection` are reserved so a closed value can never be
- * mistaken for a selected relation by `on()`'s discriminant).
+ * mistaken for a selected relation by `on()`'s discriminant; `where` is
+ * reserved because the payload tier mints the ψ-selection method under
+ * exactly that name; `match` because BOTH tiers mint the exhaustive
+ * dispatch under exactly that name).
  */
 const reservedHandleNames: readonly string[] = Object.freeze([
 	"name",
@@ -41,6 +56,8 @@ const reservedHandleNames: readonly string[] = Object.freeze([
 	"axioms",
 	"columns",
 	"fromId",
+	"where",
+	"match",
 	"relation",
 	"selection"
 ])
@@ -51,6 +68,18 @@ const reservedHandleNames: readonly string[] = Object.freeze([
  */
 type PayloadField = Exclude<AnyField, { readonly fresh: true }>
 
+/**
+ * A declared payload column BLOCK: name → descriptor, with `id`
+ * unspellable — the sealed shape mints the synthetic `id` itself (ordinal
+ * 0 of the matchable fields), so a declared column named `id` would be
+ * shadowed by the synthetic slot everywhere the shape resolves by name
+ * (`matchFieldsOf`, the projected face, `spec.rs`'s resolver). The wall is
+ * typed here and judged again at construction in {@link mintClosed} — the
+ * runtime twin for untyped callers, warmer and earlier than the engine's
+ * `DuplicateFieldName` at `Db.create`.
+ */
+type PayloadColumns = Record<string, PayloadField> & { readonly id?: never }
+
 /** One declared payload column: name plus its field descriptor. */
 interface ClosedColumn {
 	readonly name: string
@@ -96,21 +125,22 @@ type Axioms<Handles extends string, Cols extends Record<string, PayloadField>> =
 interface ClosedCore<Name extends string, Handles extends string, Cols extends Record<string, PayloadField>> {
 	readonly name: Name
 	/**
-	 * The handle-domain reference descriptor: `kind: Kind.id` in another
-	 * relation's field block is the reference through which bare handle ids
-	 * become legal in that relation's selections. Its domain is the closed
-	 * relation's handle domain (`"KindId"` — Rust's `as KindId`).
+	 * The closed reference descriptor: `kind: Kind.id` in another relation's
+	 * field block is the reference through which bare handle ids become
+	 * legal in that relation's selections. Pure structure plus the roster —
+	 * the referencing field's domain is law-born: `schema()` computes it
+	 * from the declared containment (`"Kind.id"`, the generator class).
 	 */
-	readonly id: ClosedIdField<`${Name}Id`>
+	readonly id: ClosedIdField
 	readonly data: ClosedData
 	/** Payload readback: handle to its declared column values, bare and structural. */
 	readonly axioms: Axioms<Handles, Cols>
 	/**
-	 * The declared payload columns, name → S1 field descriptor — an HONEST
+	 * The declared payload columns, name → field descriptor — an HONEST
 	 * frozen runtime record (the descriptors themselves, by identity), and
-	 * the typed carrier a projected payload column's domain label is
+	 * the typed carrier a projected payload column's structural shape is
 	 * recovered through off the schema type (the face layer's
-	 * `ProjectedDomain` reads it; `data.columns` carries the same
+	 * `ProjectedShape` reads it; `data.columns` carries the same
 	 * descriptors in declaration order for the lowering).
 	 */
 	readonly columns: Cols
@@ -118,17 +148,86 @@ interface ClosedCore<Name extends string, Handles extends string, Cols extends R
 	fromId(id: bigint): Handles | undefined
 }
 
+/**
+ * The `where()` argument of a closed relation: per PAYLOAD column, a bare
+ * structural literal of that column's value type or an `oneOf(a, b, ...)`
+ * literal set — the ordinary `where()`'s vocabulary exactly. The synthetic
+ * `id` is deliberately absent: an id selection is spelled only as handle
+ * literals on the REFERENCING side (the canonical-utterance law).
+ */
+type ClosedSelectionInput<Cols extends Record<string, PayloadField>> = {
+	readonly [C in keyof Cols]?: Infer<Cols[C]> | OneOf<Infer<Cols[C]>>
+}
+
+/**
+ * A closed relation with a ψ selection applied — what `on()` consumes as a
+ * σ-carrying closed source (`on(Kind.where({ mastered: true }), "id")`).
+ * Deliberately the SAME discriminant shape as the ordinary `Selected`
+ * (`relation`/`selection` — `face.ts::faceParts` splits both by `"relation"
+ * in source`), and structurally UNMISTAKABLE for one: an `AnyClosed` lacks
+ * the relation shape (no `fields` record, no `RelationData`).
+ */
+interface SelectedClosed<Name extends string, Handles extends string, Cols extends Record<string, PayloadField>> {
+	readonly relation: Closed<Name, Handles, Cols>
+	readonly selection: readonly SelectionBinding[]
+}
+
+/** Any ψ-selected closed relation value. */
+interface AnySelectedClosed {
+	readonly relation: AnyClosed
+	readonly selection: readonly SelectionBinding[]
+}
+
+/**
+ * The ψ-selection surface of a payload-tier closed value. The selection is
+ * resolved EAGERLY against the declared columns and lowered as-is — the SDK
+ * never pre-folds ψ into an id set: pass-through lowering is what the macro
+ * does, and the ENGINE folds against the sealed extension at validate
+ * (`compile_member_set`).
+ */
+interface ClosedSelectable<Name extends string, Handles extends string, Cols extends Record<string, PayloadField>> {
+	where(selection: ClosedSelectionInput<Cols>): SelectedClosed<Name, Handles, Cols>
+}
+
+/**
+ * Exhaustive dispatch over a BARE closed vocabulary: one arm per handle,
+ * no literal types and no brands — the handle-name union on the value's
+ * type IS the exhaustiveness proof (a missing arm is a missing-property
+ * compile error; an extra arm an excess-property compile error). The bare
+ * tier declares no payload, so an arm takes nothing. The arms record types
+ * any `bigint` in — the runtime roster refuses an out-of-vocabulary id
+ * with a throw, never a misdispatch.
+ */
+interface ClosedMatchBare<Handles extends string> {
+	match<T>(id: bigint, arms: { readonly [H in Handles]: () => T }): T
+}
+
+/**
+ * Exhaustive dispatch over a PAYLOAD-tier closed vocabulary: the same
+ * mapped-type exhaustiveness as the bare tier, and each arm receives its
+ * handle's typed axiom row (the declared columns, bare and structural —
+ * the frozen readback row from `axioms`).
+ */
+interface ClosedMatchPayload<Handles extends string, Cols extends Record<string, PayloadField>> {
+	match<T>(id: bigint, arms: { readonly [H in Handles]: (row: AxiomRow<Cols>) => T }): T
+}
+
 /**
  * A closed relation value: the core surface plus one BARE constant per
  * handle (`Kind.Checking: bigint`, ids = declaration order — the value is
  * structural; the roster judges out-of-vocabulary ids at construction and
- * the engine at commit).
+ * the engine at commit), plus `match()` on BOTH tiers (bare arms take
+ * nothing; payload arms receive the typed axiom row), plus — exactly when
+ * payload columns exist — `where()` (the bare tier has nothing to select
+ * on, so the method is ABSENT there, not merely uncallable).
  */
 type Closed<Name extends string, Handles extends string, Cols extends Record<string, PayloadField>> = ClosedCore<
 	Name,
 	Handles,
 	Cols
-> & { readonly [H in Handles]: bigint }
+> & { readonly [H in Handles]: bigint } & ([keyof Cols] extends [never]
+		? ClosedMatchBare<Handles>
+		: ClosedSelectable<Name, Handles, Cols> & ClosedMatchPayload<Handles, Cols>)
 
 /** Any closed relation value, whatever its roster and columns. */
 interface AnyClosed {
@@ -262,29 +361,40 @@ function closed<const Name extends string, const Handles extends readonly [strin
 ): Closed<Name, Handles[number], Record<never, never>>
 
 /**
- * Payload tier: declared columns, then ground axioms — `closed("Grade",
- * { mastered: bool })({ DirectPass: { mastered: true }, Failed: { mastered:
- * false } })`. The axioms record's keys ARE the handles (declaration order
- * = key order, integer-index names rejected); every row carries every
- * column exactly once (type-enforced by {@link Axioms}).
+ * Payload tier: declared columns AND ground axioms, one call — `closed(
+ * "Grade", { mastered: bool }, { DirectPass: { mastered: true }, Failed:
+ * { mastered: false } })`. The curried tier-2 spelling is DELETED
+ * (canonical utterance): `Cols` infers from the column block, the handle
+ * set from the axioms record's keys (reverse mapped-type inference), and
+ * every row is contextually checked against the declared columns — a
+ * wrong-typed value errors ON its property. The axioms record's keys ARE
+ * the handles (declaration order = key order, integer-index names
+ * rejected); every row carries every column exactly once (type-enforced by
+ * {@link Axioms}).
  */
-function closed<const Name extends string, const Cols extends Record<string, PayloadField>>(
+function closed<const Name extends string, const Cols extends PayloadColumns, Handles extends string>(
 	name: Name,
-	columns: Cols
-): <Handles extends string>(axioms: Axioms<Handles, Cols>) => Closed<Name, Handles, Cols>
+	columns: Cols,
+	axioms: Axioms<Handles, Cols>
+): Closed<Name, Handles, Cols>
 
-function closed<const Name extends string>(
+function closed<const Name extends string, const Cols extends PayloadColumns, Handles extends string>(
 	name: Name,
-	shape: readonly [string, ...string[]] | Record<string, PayloadField>
-):
-	| Closed<Name, string, Record<never, never>>
-	| (<Handles extends string>(
-			axioms: Axioms<Handles, Record<string, PayloadField>>
-	  ) => Closed<Name, Handles, Record<string, PayloadField>>) {
+	shape: readonly [string, ...string[]] | Cols,
+	axioms?: Axioms<Handles, Cols>
+): Closed<Name, string, Record<never, never>> | Closed<Name, Handles, Cols> {
 	if (isHandleTuple(shape)) {
+		if (axioms !== undefined) {
+			throw errors.new(`closed relation ${name}: the bare tier declares no columns, so ground axioms are inadmissible`)
+		}
 		return closedBare(name, shape)
 	}
-	return closedPayload(name, shape)
+	if (axioms === undefined) {
+		throw errors.new(
+			`closed relation ${name}: payload columns declared without ground axioms — the payload tier is spelled closed(name, columns, axioms) (the curried spelling is deleted)`
+		)
+	}
+	return closedPayload(name, shape, axioms)
 }
 
 /** The bare tier's precisely-typed builder: no columns, no axioms. */
@@ -297,35 +407,51 @@ function closedBare<Name extends string, Handles extends string>(
 
 /**
  * The payload tier's precisely-typed builder: column names are judged
- * EAGERLY (at `closed(name, columns)`, before any axioms arrive — the
- * macro-expansion analog), and the returned `withAxioms` reads its handle
- * set off the axioms record's own keys.
+ * first (the macro-expansion analog), then the handle set is read off the
+ * axioms record's own keys.
  */
-function closedPayload<Name extends string, Cols extends Record<string, PayloadField>>(
+function closedPayload<Name extends string, Handles extends string, Cols extends PayloadColumns>(
 	name: Name,
-	columns: Cols
-): <Handles extends string>(axioms: Axioms<Handles, Cols>) => Closed<Name, Handles, Cols> {
+	columns: Cols,
+	axioms: Axioms<Handles, Cols>
+): Closed<Name, Handles, Cols> {
 	for (const columnName of Object.keys(columns)) {
 		assertDeclarationOrderKey(`closed relation ${name} column`, columnName)
 	}
-	return function withAxioms<Handles extends string>(axioms: Axioms<Handles, Cols>): Closed<Name, Handles, Cols> {
-		const handles = Object.keys(axioms)
-		for (const handle of handles) {
-			assertDeclarationOrderKey(`closed relation ${name} handle`, handle)
-		}
-		if (!handleKeysOwn(axioms, handles)) {
-			throw errors.new(`closed relation ${name}: handle enumeration incomplete`)
-		}
-		return mintClosed<Name, Handles, Cols>(name, handles, columns, axioms)
+	const handles = Object.keys(axioms)
+	for (const handle of handles) {
+		assertDeclarationOrderKey(`closed relation ${name} handle`, handle)
+	}
+	if (!handleKeysOwn(axioms, handles)) {
+		throw errors.new(`closed relation ${name}: handle enumeration incomplete`)
 	}
+	return mintClosed<Name, Handles, Cols>(name, handles, columns, axioms)
+}
+
+/**
+ * The trusted seam of the ergonomic-surface mint: `match` reads back as an
+ * own function on BOTH tiers, and `where` exactly when payload columns
+ * exist — the runtime twin of the {@link Closed} type's conditional arm
+ * (`ClosedMatchBare` vs `ClosedSelectable & ClosedMatchPayload`), verified
+ * before the minted value is admitted at the conditional type.
+ */
+function surfaceMinted<Name extends string, Handles extends string, Cols extends Record<string, PayloadField>>(
+	value: ClosedCore<Name, Handles, Cols> & { readonly [H in Handles]: bigint },
+	cols: readonly ClosedColumn[]
+): value is Closed<Name, Handles, Cols> {
+	const matchable = "match" in value && typeof value.match === "function"
+	const selectable = "where" in value && typeof value.where === "function"
+	return matchable && (cols.length > 0 ? selectable : !selectable)
 }
 
 /**
  * Mints one closed relation value — the shared seam of both tiers, HONESTLY
  * typed end to end (a wrong-shaped mint is a compile error here, not a
  * laundered `unknown`): roster checks, eager axiom lowering, the
- * domain-labeled `id` descriptor, the frozen `columns` carrier (the runtime
- * twin of the `Cols` type parameter), and the handle constants.
+ * roster-carrying `id` descriptor, the frozen `columns` carrier (the runtime
+ * twin of the `Cols` type parameter), the handle constants, the exhaustive
+ * `match()` on both tiers, and — on the payload tier only — the
+ * ψ-selection `where()`.
  */
 function mintClosed<Name extends string, Handles extends string, Cols extends Record<string, PayloadField>>(
 	name: Name,
@@ -353,6 +479,11 @@ function mintClosed<Name extends string, Handles extends string, Cols extends Re
 	const cols: ClosedColumn[] = []
 	for (const [columnName, field] of Object.entries(columns)) {
 		assertDeclarationOrderKey(`closed relation ${name} column`, columnName)
+		if (columnName === "id") {
+			throw errors.new(
+				`closed relation ${name}: the payload column id collides with the sealed shape's synthetic id (the relation mints its own id at ordinal 0; name the column something else)`
+			)
+		}
 		cols.push(Object.freeze({ name: columnName, field }))
 	}
 	Object.freeze(cols)
@@ -369,11 +500,7 @@ function mintClosed<Name extends string, Handles extends string, Cols extends Re
 		columns: cols,
 		rows: Object.freeze(rows)
 	})
-	const id: ClosedIdField<`${Name}Id`> = Object.freeze({
-		kind: "u64",
-		domain: `${name}Id`,
-		closed: roster
-	})
+	const id: ClosedIdField = Object.freeze({ kind: "u64", closed: roster })
 	/**
 	 * Handle names are arbitrary identifiers, so rows and constants are
 	 * minted with OWN-property definition (inside {@link mintAxioms} and
@@ -389,18 +516,66 @@ function mintClosed<Name extends string, Handles extends string, Cols extends Re
 	const constants = mintHandleConstants(name, handleList)
 	const columnsOut: Cols = { ...columns }
 	Object.freeze(columnsOut)
-	return Object.freeze({
-		...constants,
-		name,
-		id,
-		data,
-		axioms: axiomsOut,
-		columns: columnsOut,
-		fromId(idValue: bigint): Handles | undefined {
-			return handleList[Number(idValue)]
+	function fromId(idValue: bigint): Handles | undefined {
+		return handleList[Number(idValue)]
+	}
+	const holder: { value: Closed<Name, Handles, Cols> | undefined } = { value: undefined }
+	/**
+	 * The ψ selection: resolved against the declared payload columns through
+	 * the ONE selection machine (`relation.ts::resolveSelection` — a
+	 * `ClosedColumn` is structurally a `RelationField`), never pre-folded
+	 * into an id set (the engine folds at validate).
+	 */
+	function where(selection: ClosedSelectionInput<Cols>): SelectedClosed<Name, Handles, Cols> {
+		const owner = holder.value
+		if (owner === undefined) {
+			throw errors.new(`closed relation ${name}: self-reference read before construction completed`)
 		}
-	})
+		return Object.freeze({
+			relation: owner,
+			selection: resolveSelection(name, cols, Object.entries(selection))
+		})
+	}
+	/**
+	 * The exhaustive dispatch: the ROSTER judges the id (the structural type
+	 * admits any bigint — a dishonest id is a THROW, never a misdispatch),
+	 * and the chosen arm receives the handle's frozen axiom row (the bare
+	 * tier's arms are typed to take nothing; the empty row rides along
+	 * unread). One implementation serves both tiers — the conditional
+	 * {@link Closed} arm claims the tier-exact arm signature and
+	 * {@link surfaceMinted} is the trusted seam that admits it.
+	 */
+	function match<T>(idValue: bigint, arms: { readonly [H in Handles]: (row: AxiomRow<Cols>) => T }): T {
+		const handle = fromId(idValue)
+		if (handle === undefined) {
+			throw errors.new(`closed relation ${name}: match on id ${idValue} misses the roster (${handleList.join(", ")})`)
+		}
+		return arms[handle](axiomsOut[handle])
+	}
+	const core = { name, id, data, axioms: axiomsOut, columns: columnsOut, fromId }
+	const value: ClosedCore<Name, Handles, Cols> & { readonly [H in Handles]: bigint } =
+		cols.length > 0
+			? Object.freeze({ ...constants, ...core, where, match })
+			: Object.freeze({ ...constants, ...core, match })
+	if (!surfaceMinted<Name, Handles, Cols>(value, cols)) {
+		throw errors.new(`closed relation ${name}: ergonomic-surface minting incomplete`)
+	}
+	holder.value = value
+	return value
 }
 
-export type { AnyClosed, AxiomRow, Axioms, Closed, ClosedColumn, ClosedCore, ClosedData, ClosedRow, PayloadField }
+export type {
+	AnyClosed,
+	AnySelectedClosed,
+	AxiomRow,
+	Axioms,
+	Closed,
+	ClosedColumn,
+	ClosedCore,
+	ClosedData,
+	ClosedRow,
+	ClosedSelectionInput,
+	PayloadField,
+	SelectedClosed
+}
 export { closed }

package/src/db.ts

@@ -1419,16 +1419,31 @@ process.once("exit", function closeCachedStores() {
 	}
 })
 
+/**
+ * The engine twin of the schema-level class wall, as a matchable value
+ * (`errors.is`): the shared lowering rejected a spec whose statement pairs
+ * faces with disagreeing newtype labels — the faces of a dependency agree
+ * on their newtype, or neither carries one. UNREACHABLE through the typed
+ * builder (the SDK computes every label from the laws, so its lowered
+ * specs cohere by construction); a raw spec handed to the bridge is the
+ * one road here, and the runtime referee that proves the engine judges
+ * what the types claim.
+ */
+const ErrNewtypeMismatch = errors.new(
+	"bumbledb newtypeMismatch: a statement pairs faces whose newtypes disagree — the faces of a dependency agree on their newtype, or neither carries one"
+)
+
 /**
  * The one admission path both verbs share: canonical-path cache lookup
  * first (a hit returns the SAME `Db` value for the identical theory, a
  * typed fingerprint error for a different one, and a typed refusal for
  * `create` — the store a cache entry proves initialized is exactly what
  * create refuses). On a miss: lower the theory, run one bridge call, and
- * wrap the two domain refusals — `schemaError` (spec resolution + schema
- * validation, every issue in one message) and `fingerprintMismatch` (a
- * different theory cannot open the store) — into typed errors carrying the
- * engine's message intact.
+ * wrap the domain refusals — `schemaError` (spec resolution + schema
+ * validation, every issue in one message), `newtypeMismatch` (the
+ * coherence wall, {@link ErrNewtypeMismatch}), and `fingerprintMismatch`
+ * (a different theory cannot open the store) — into typed errors carrying
+ * the engine's message intact.
  */
 function admit<Rels extends SchemaRelations>(
 	verb: "create" | "open",
@@ -1458,6 +1473,9 @@ function admit<Rels extends SchemaRelations>(
 		return native.dbOpen(canonical, spec)
 	})
 	if (!opened.ok) {
+		if (opened.kind === "newtypeMismatch") {
+			throw errors.wrap(ErrNewtypeMismatch, `${verb} ${canonical}: ${opened.message}`)
+		}
 		throw errors.new(`bumbledb ${opened.kind} (${verb} ${canonical}): ${opened.message}`)
 	}
 	const manifest = bridged("fetch bumbledb manifest", function fetchManifest() {
@@ -1526,4 +1544,4 @@ export type {
 	WitnessedWriteResult,
 	WriteResult
 }
-export { abandon, Db }
+export { abandon, Db, ErrNewtypeMismatch }