@bjornpagen/bumbledb 0.1.0 → 0.3.0

package/src/count.ts

@@ -1,10 +1,22 @@
 /**
  * Cardinality-window counts — exactly five constructors, and nothing else
- * (`docs/architecture/70-api.md` § the canonical-utterance law). The ban
- * table is enforced REPRESENTATIONALLY, stronger than Rust's expansion
- * errors: `{1..*}`, `{n..n}`, `{0..0}`, `{0..*}`, and inverted windows have
- * NO constructor — the spellings that could produce them are construction
- * errors naming the canonical form, and no other spelling exists at all.
+ * (`docs/architecture/70-api.md` § the canonical-utterance law). The five
+ * constructors PARTITION the legal windows, and the ban table is enforced
+ * REPRESENTATIONALLY, stronger than Rust's expansion errors, in two tiers:
+ *
+ * - **The type tier**: a banned spelling written as a LITERAL does not
+ *   compile — `exactly(0n)`, `between(n, n)`, `between(0n, hi)`,
+ *   `atLeast(0n)`, `atLeast(1n)`, `atMost(0n)`, and every negative bound
+ *   are type errors naming the canonical form (`{n..n}`, `{0..0}`,
+ *   `{0..hi}`-via-between, `{0..*}`, `{1..*}` have NO argument shape that
+ *   produces them), and no sixth constructor exists at all.
+ * - **The construction tier**: a bound the type level cannot judge — a
+ *   COMPUTED `bigint`, whose literal identity is erased, or an inverted
+ *   `between(lo, hi)` order, which type-level bigints cannot compare — is
+ *   judged here at construction with the same canonical-naming errors; and
+ *   past both tiers the engine's own spec validation remains the law for a
+ *   hostile FFI caller (the standing two-tier ban enforcement).
+ *
  * Bounds are `bigint` (u64 crosses as bigint always, PRD-04's law).
  */
 
@@ -36,14 +48,87 @@ interface Count {
 
 /** Stamps one admitted window as a frozen `Count` value. */
 function admit(window: WindowSpec): Count {
-	return Object.freeze({ window, [admitted]: true as const })
+	const count: Count = { window, [admitted]: true }
+	return Object.freeze(count)
 }
 
+/**
+ * The legible banned-spelling verdict: intersected into a count
+ * constructor's parameter when the LITERAL argument spells a banned window,
+ * naming the canonical form — the compile-time face of the ban table.
+ */
+interface BannedWindow<Canonical extends string> {
+	readonly "banned window spelling — the canonical-utterance law names the one legal form": Canonical
+}
+
+/** `true` exactly when the literal bigint `N` is negative (out of the u64 count domain). */
+type IsNegative<N extends bigint> = `${N}` extends `-${string}` ? true : false
+
+/** The ban verdict on `exactly(n)`: negatives are out of domain; `{0}` is the exclusion, written `none`. */
+type ExactlyBan<N extends bigint> = bigint extends N
+	? unknown
+	: IsNegative<N> extends true
+		? BannedWindow<"window counts are u64 — a negative count is out of domain">
+		: N extends 0n
+			? BannedWindow<"`{0}` is the exclusion — write none">
+			: unknown
+
+/** The ban verdict on `atLeast(lo)`: `{0..*}` is vacuous; `{1..*}` is the bare containment respelled. */
+type AtLeastBan<N extends bigint> = bigint extends N
+	? unknown
+	: IsNegative<N> extends true
+		? BannedWindow<"window counts are u64 — a negative count is out of domain">
+		: N extends 0n
+			? BannedWindow<"`{0..*}` is vacuous — it provably says nothing; delete the statement">
+			: N extends 1n
+				? BannedWindow<"`{1..*}` says only what the bare containment says — write contained(source, target)">
+				: unknown
+
+/** The ban verdict on `atMost(hi)`: `{0..0}` is the exclusion, written `none`. */
+type AtMostBan<N extends bigint> = bigint extends N
+	? unknown
+	: IsNegative<N> extends true
+		? BannedWindow<"window counts are u64 — a negative count is out of domain">
+		: N extends 0n
+			? BannedWindow<"`{0..0}` — the exclusion is written `{0}`: use none">
+			: unknown
+
+/** The ban verdict on a `between` floor of zero: `{0..hi}` is the ceiling respelled (`atMost(hi)`). */
+type BetweenFloorBan<Lo extends bigint> = Lo extends 0n
+	? BannedWindow<"`{0..hi}` — a ceiling is written atMost(hi)">
+	: unknown
+
+/**
+ * The ban verdict on `between(lo, hi)`, judged on the second bound once
+ * both literals are known: `{n..n}` is the exact count respelled
+ * (`exactly(n)`, or `none` at 0), and `{0..hi}` is the ceiling respelled
+ * (`atMost(hi)` — the five constructors PARTITION the legal windows, so
+ * the one ceiling window keeps its one spelling). Bound ORDER (`{hi..lo}`
+ * inverted) is not type-expressible — bigint literals have no type-level
+ * comparison — so inversion stays a construction error below.
+ */
+type BetweenBan<Lo extends bigint, Hi extends bigint> = bigint extends Lo
+	? unknown
+	: bigint extends Hi
+		? unknown
+		: IsNegative<Lo> extends true
+			? BannedWindow<"window counts are u64 — a negative bound is out of domain">
+			: IsNegative<Hi> extends true
+				? BannedWindow<"window counts are u64 — a negative bound is out of domain">
+				: Lo extends Hi
+					? Hi extends Lo
+						? Lo extends 0n
+							? BannedWindow<"`{0..0}` — the exclusion is written `{0}`: use none">
+							: BannedWindow<"`{n..n}` — an exact count is written `{n}`: use exactly(n)">
+						: BetweenFloorBan<Lo>
+					: BetweenFloorBan<Lo>
+
 /**
  * `{n}` — THE exact-count spelling, n ≥ 1. `exactly(0)` is the exclusion
- * respelled and rejected naming `none`.
+ * respelled: unwritable as a literal ({@link ExactlyBan} names `none`),
+ * rejected at construction when computed.
  */
-function exactly(n: bigint): Count {
+function exactly<const N extends bigint>(n: N & ExactlyBan<N>): Count {
 	if (n < 0n) {
 		throw errors.new(`window counts are u64: exactly(${n}) is out of domain`)
 	}
@@ -57,11 +142,15 @@ function exactly(n: bigint): Count {
 const none: Count = admit(exclusion)
 
 /**
- * `{lo..hi}` — both bounds explicit, 0 ≤ lo < hi. `lo === hi` is the exact
- * count respelled (rejected naming `exactly(n)`, or `none` at 0); an
- * inverted window is unsatisfiable and rejected.
+ * `{lo..hi}` — both bounds explicit, 1 ≤ lo < hi. `lo === hi` is the exact
+ * count respelled and `lo === 0` is the ceiling respelled: unwritable as
+ * literals ({@link BetweenBan} names `exactly(n)`, `none` at `{0..0}`, or
+ * `atMost(hi)` at a zero floor — the five constructors PARTITION the legal
+ * windows), rejected at construction when computed; an inverted window is
+ * unsatisfiable and rejected at construction (bigint literals carry no
+ * type-level order).
  */
-function between(lo: bigint, hi: bigint): Count {
+function between<const Lo extends bigint, const Hi extends bigint>(lo: Lo, hi: Hi & BetweenBan<Lo, Hi>): Count {
 	if (lo < 0n || hi < 0n) {
 		throw errors.new(`window counts are u64: between(${lo}, ${hi}) is out of domain`)
 	}
@@ -76,15 +165,19 @@ function between(lo: bigint, hi: bigint): Count {
 		}
 		throw errors.new(`\`{${lo}..${lo}}\` — an exact count is written \`{${lo}}\`: use exactly(${lo})`)
 	}
+	if (lo === 0n) {
+		throw errors.new(`\`{0..${hi}}\` — a ceiling is written atMost: use atMost(${hi})`)
+	}
 	return admit(Object.freeze({ kind: "range", lo, hi }))
 }
 
 /**
  * `{lo..*}` — a floor with no ceiling, lo ≥ 2: `atLeast(1)` says only what
- * the bare containment says (rejected naming `contained`), and
- * `atLeast(0)` is vacuous (rejected naming deletion).
+ * the bare containment says and `atLeast(0)` is vacuous — both unwritable
+ * as literals ({@link AtLeastBan} names the canonical form), rejected at
+ * construction when computed.
  */
-function atLeast(lo: bigint): Count {
+function atLeast<const N extends bigint>(lo: N & AtLeastBan<N>): Count {
 	if (lo < 0n) {
 		throw errors.new(`window counts are u64: atLeast(${lo}) is out of domain`)
 	}
@@ -100,10 +193,11 @@ function atLeast(lo: bigint): Count {
 }
 
 /**
- * `{0..hi}` — a ceiling, hi ≥ 1: `atMost(0)` is the exclusion respelled
- * and rejected naming `none`.
+ * `{0..hi}` — a ceiling, hi ≥ 1: `atMost(0)` is the exclusion respelled —
+ * unwritable as a literal ({@link AtMostBan} names `none`), rejected at
+ * construction when computed.
  */
-function atMost(hi: bigint): Count {
+function atMost<const N extends bigint>(hi: N & AtMostBan<N>): Count {
 	if (hi < 0n) {
 		throw errors.new(`window counts are u64: atMost(${hi}) is out of domain`)
 	}

package/src/db.ts

@@ -32,11 +32,10 @@
 
 import * as path from "node:path"
 import * as errors from "@superbuilders/errors"
-import { phantom } from "#brand.ts"
 import type { Exhumed } from "#exhume.ts"
 import { exhumeStore } from "#exhume.ts"
 import { lower } from "#lower.ts"
-import { factOf, isMintedFresh, type KeyFact, keyRowOf, type Minted, recordOf, rowOf } from "#marshal.ts"
+import { factOf, isFreshField, isMintedFresh, type KeyFact, keyRowOf, type Minted, recordOf, rowOf } from "#marshal.ts"
 
 import type {
 	DbHandle,
@@ -51,7 +50,8 @@ import type {
 	ViolationFact as WireViolationFact
 } from "#native.ts"
 import { native } from "#native.ts"
-import type { Query, SelectColumn } from "#query/lower.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"
@@ -68,8 +68,8 @@ type MemberRelation<Rels extends SchemaRelations> = Extract<Rels[keyof Rels], An
 
 /**
  * The key object of a key-statement-selected `get`: exactly the selected
- * `key()` statement's projection fields, each carrying the relation's own
- * branded value type — the {@link KeyFact} rule generalized from the
+ * `key()` statement's projection fields, each at the relation's own BARE
+ * structural value type — the {@link KeyFact} rule generalized from the
  * primary key to ANY declared key statement.
  */
 type DeclaredKeyFact<R extends AnyRelation, Projection extends readonly string[]> = {
@@ -194,7 +194,7 @@ type WitnessedWriteResult<Rels extends SchemaRelations, R> =
 interface Tx<Rels extends SchemaRelations> {
 	/**
 	 * Records one insert. Omitted fresh fields are MINTED through the
-	 * engine's alloc lane and returned branded; supplying them instead
+	 * engine's alloc lane and returned as bare bigints; supplying them instead
 	 * preserves identity (the resupply idiom). Returns the relation's
 	 * fresh cells, minted or resupplied.
 	 */
@@ -236,7 +236,7 @@ interface ReadScope<Rels extends SchemaRelations> {
 	 * open and the generation read.
 	 */
 	readonly generation: bigint
-	/** Full-relation export in row-id order, decoded to branded facts. */
+	/** Full-relation export in row-id order, decoded to bare structural facts. */
 	scan<R extends MemberRelation<Rels>>(relation: R): Fact<R>[]
 	/**
 	 * Committed-state point lookup through the relation's primary key
@@ -258,12 +258,22 @@ interface ReadScope<Rels extends SchemaRelations> {
 	/**
 	 * Executes a prepared query against this scope's snapshot with the
 	 * typed params object; returns the answer SET as plain rows with
-	 * branded values (no order — the host sorts). This is the ONE
+	 * bare structural values (no order — the host sorts). This is the ONE
 	 * execution spelling ({@link Prepared} carries no `execute`).
 	 */
 	execute<Row, Params extends ParamsRecord>(prepared: Prepared<Rels, Row, Params>, params: Params): Row[]
 }
 
+/**
+ * The module-private inference slot of {@link Prepared}: an optional symbol
+ * property (never set at runtime) that keeps the prepared value's `Row` and
+ * `Params` type arguments load-bearing, so `execute` infers the typed rows
+ * and the typed params object from the value alone — the query module's
+ * `inferred` pattern, local to this module. A type-level carrier only:
+ * values stay bare, nothing is asserted.
+ */
+const preparedTypes: unique symbol = Symbol("bumbledb.prepared.types")
+
 /**
  * One prepared query as a plain VALUE: explicit visible compilation
  * (`db.prepare(q)` lowers, pins the plan, and surfaces every engine roster
@@ -281,7 +291,7 @@ interface Prepared<Rels extends SchemaRelations, Row, Params extends ParamsRecor
 	 * re-prepare.
 	 */
 	staleness(snap: ReadScope<Rels>): Staleness
-	readonly [phantom]?: { readonly row: Row; readonly params: Params }
+	readonly [preparedTypes]?: { readonly row: Row; readonly params: Params }
 }
 
 /**
@@ -424,7 +434,7 @@ function impliedKeyEntries(theory: AnySchema): StatementEntry[] {
 			continue
 		}
 		for (const declared of member.data.fields) {
-			if (declared.field.minted) {
+			if (isFreshField(declared.field)) {
 				entries.push({
 					kind: "functionality",
 					statement: undefined,
@@ -642,7 +652,7 @@ function mintFreshCells(
 ): Record<string, FactValue> {
 	const fresh: Record<string, FactValue> = {}
 	for (const declared of relation.data.fields) {
-		if (!declared.field.minted) {
+		if (!isFreshField(declared.field)) {
 			continue
 		}
 		let cell = values[declared.name]
@@ -1338,7 +1348,7 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 			Object.freeze({
 				handle: preparedHandle,
 				owner,
-				params: q.data.registry.params,
+				params: q.data.params,
 				select: q.data.select
 			})
 		)
@@ -1409,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",
@@ -1448,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() {
@@ -1516,4 +1544,4 @@ export type {
 	WitnessedWriteResult,
 	WriteResult
 }
-export { abandon, Db }
+export { abandon, Db, ErrNewtypeMismatch }

package/src/exhume.ts

@@ -8,13 +8,14 @@
  * is read back for rebirth (exhume the old store, create the successor
  * under the new theory, copy by NAME, re-derive).
  *
- * DELIBERATELY UNTYPED: no branded type appears anywhere on this surface.
- * The caller's schema is the wrong theory for an exhumed store BY
+ * DELIBERATELY SCHEMA-FREE: no schema type appears anywhere on this
+ * surface. The caller's schema is the wrong theory for an exhumed store BY
  * DEFINITION (a store the current theory could open would never need
- * exhuming), so every value crosses as its plain natural JS form and every
- * fact is keyed by field NAME. The SDK never reconstructs a `Schema` value
- * from the descriptor — that inverse mapping is deliberately out of scope;
- * the rebirth tool keys by name.
+ * exhuming), so every value crosses TYPED at its bare structural form
+ * ({@link FactValue} — bigint/string/boolean/bytes/interval, never
+ * `unknown`) and every fact is keyed by field NAME. The SDK never
+ * reconstructs a `Schema` value from the descriptor — that inverse mapping
+ * is deliberately out of scope; the rebirth tool keys by name.
  *
  * ZERO CLOSABLES: no value here carries a close, dispose, or release
  * spelling. The engine-side handle (and the store's exclusive advisory
@@ -57,9 +58,9 @@ const ErrExhumeFormatMismatch = errors.new(
 const ErrExhumeCorruption = errors.new("bumbledb exhume: the persisted schema descriptor fails its integrity gates")
 
 /**
- * One exhumed fact as a plain name-keyed record of natural JS values —
- * deliberately untyped (module doc): `bigint` for u64/i64, `string` for
- * str, `boolean` for bool, `Uint8Array` for bytes<N>, a `{ start, end }`
+ * One exhumed fact as a plain name-keyed record of bare structural values
+ * — deliberately schema-free (module doc): `bigint` for u64/i64, `string`
+ * for str, `boolean` for bool, `Uint8Array` for bytes<N>, a `{ start, end }`
  * bigint pair for intervals. Closed-relation rows open with the synthetic
  * `id` field, exactly as the descriptor's sealed field list declares.
  */
@@ -105,8 +106,8 @@ interface ExhumedRelation {
  * persisted descriptor: relations in engine-id order (declaration order
  * mints every id), each with its ordered field descriptions and closed
  * roster — enough for a caller to key facts by name and re-insert them
- * into a differently-fingerprinted successor store. No branded type
- * appears here (module doc: exhumed data is deliberately untyped).
+ * into a differently-fingerprinted successor store. No schema type appears
+ * here (module doc: the surface is schema-free; rows are typed bare).
  */
 interface ExhumedDescriptor {
 	readonly relations: readonly ExhumedRelation[]