@bjornpagen/bumbledb 0.4.0 → 0.5.0

package/src/marshal.ts

@@ -29,6 +29,7 @@
 
 import * as errors from "@superbuilders/errors"
 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"
 
@@ -66,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
@@ -121,7 +105,7 @@ function closedCellOf(context: string, closed: ClosedRoster, name: string): Fact
  */
 function handleOf(context: string, closed: ClosedRoster, cell: FactValue): string {
 	if (typeof cell !== "bigint") {
-		throw cellShapeError(context, `a ${closed.name} handle id (bigint)`, cell)
+		throw literalShapeError(context, `a ${closed.name} handle id (bigint)`, cell)
 	}
 	const handle = closed.handles[Number(cell)]
 	if (handle === undefined) {
@@ -144,29 +128,30 @@ function handleOf(context: string, closed: ClosedRoster, cell: FactValue): strin
  * boundary.
  */
 function cellOf(context: string, field: AnyField, value: unknown): FactValue {
-	if ("closed" in field) {
+	const roster = rosterOf(field)
+	if (roster !== undefined) {
 		if (typeof value !== "string") {
-			throw cellShapeError(context, `a ${field.closed.name} handle name (string)`, value)
+			throw literalShapeError(context, `a ${roster.name} handle name (string)`, value)
 		}
-		return closedCellOf(context, field.closed, 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
@@ -176,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 }
 		}
@@ -289,10 +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`)
 		}
+		const roster = rosterOf(declared.field)
 		decoded[declared.name] =
-			"closed" in declared.field
-				? handleOf(`relation ${data.name} field ${declared.name}`, declared.field.closed, cell)
-				: cell
+			roster !== undefined ? handleOf(`relation ${data.name} field ${declared.name}`, roster, cell) : cell
 	})
 	Object.freeze(decoded)
 	if (!isCompleteFact(relation, decoded)) {

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 }

package/src/order.ts

@@ -0,0 +1,156 @@
+/**
+ * Host-side answer ordering — the census-fired convenience
+ * (`docs/architecture/70-api.md` § the freeze ledger). Answers are SETS and
+ * the ENGINE NEVER ORDERS; the language owns the sort (`rows.sort(...)`)
+ * and the limit (`.slice(0, n)`) — the drizzle law. What JS lacks is a
+ * number-returning comparator over the SDK's bigint-bearing cells, so the
+ * SDK ships exactly that: sort keys are DATA — a bare column name is
+ * ascending (the punning spelling; no `asc` wrapper exists — one spelling
+ * per meaning) and `desc(name)` is the one descending spelling — folded by
+ * `by(...)` into one row-typed comparator. Cross-type cells cannot arise
+ * within one column (one column, one domain), and the cell order is TOTAL
+ * anyway (the type-rank wall), so the comparator never throws.
+ */
+
+import type { FactValue } from "#native.ts"
+
+/** One DESCENDING sort key, plain data — built by {@link desc}. */
+interface Desc<K extends string> {
+	readonly key: K
+	readonly desc: true
+}
+
+/** One sort key: a bare column name (ascending — the punning spelling) or `desc(name)`. */
+type SortKey<K extends string> = K | Desc<K>
+
+/**
+ * The type-rank wall: boolean 0, bigint 1, string 2, bytes 3, interval 4.
+ * One column carries one domain, so a mixed pair never arises from decoded
+ * answer rows — the wall exists to keep the cell order TOTAL (never a
+ * throw), not to be reached.
+ */
+function cellRank(value: FactValue): number {
+	if (typeof value === "boolean") {
+		return 0
+	}
+	if (typeof value === "bigint") {
+		return 1
+	}
+	if (typeof value === "string") {
+		return 2
+	}
+	if (value instanceof Uint8Array) {
+		return 3
+	}
+	return 4
+}
+
+/**
+ * One cell against one cell. Same-type arms: boolean orders false < true;
+ * bigint by `<`/`>`; string by the host language's own `<`/`>` (flavor,
+ * recorded); bytes bytewise over the shared prefix, then by length;
+ * intervals by start, then end. A mixed pair falls through to the
+ * type-rank wall.
+ */
+function cellCmp(left: FactValue, right: FactValue): number {
+	if (typeof left === "boolean" && typeof right === "boolean") {
+		if (left === right) {
+			return 0
+		}
+		if (left) {
+			return 1
+		}
+		return -1
+	}
+	if (typeof left === "bigint" && typeof right === "bigint") {
+		if (left < right) {
+			return -1
+		}
+		if (left > right) {
+			return 1
+		}
+		return 0
+	}
+	if (typeof left === "string" && typeof right === "string") {
+		if (left < right) {
+			return -1
+		}
+		if (left > right) {
+			return 1
+		}
+		return 0
+	}
+	if (left instanceof Uint8Array && right instanceof Uint8Array) {
+		const shared = Math.min(left.length, right.length)
+		for (let index = 0; index < shared; index += 1) {
+			const leftByte = left[index]
+			const rightByte = right[index]
+			// `index < shared` keeps both reads in bounds; the `undefined`
+			// arms are the checker's indexed-access tax, never taken.
+			if (leftByte !== undefined && rightByte !== undefined && leftByte !== rightByte) {
+				return leftByte - rightByte
+			}
+		}
+		return left.length - right.length
+	}
+	if (
+		typeof left === "object" &&
+		!(left instanceof Uint8Array) &&
+		typeof right === "object" &&
+		!(right instanceof Uint8Array)
+	) {
+		if (left.start < right.start) {
+			return -1
+		}
+		if (left.start > right.start) {
+			return 1
+		}
+		if (left.end < right.end) {
+			return -1
+		}
+		if (left.end > right.end) {
+			return 1
+		}
+		return 0
+	}
+	return cellRank(left) - cellRank(right)
+}
+
+/** Marks one sort key DESCENDING — the single descending spelling (a bare name is already ascending). */
+function desc<const K extends string>(key: K): Desc<K> {
+	const marker: Desc<K> = { key, desc: true }
+	return Object.freeze(marker)
+}
+
+/**
+ * Folds sort keys into ONE comparator typed against the row —
+ * `Row extends Readonly<Record<K, FactValue>>` — so a key the row lacks, or
+ * a column typed `number` (outside the cell domain), is a COMPILE error at
+ * the `.sort` call site: the laws typed the columns, and the row type
+ * carries that proof here (parse-don't-validate). The generic RETURN is the
+ * load-bearing trick: `rows.sort(by("rank"))` instantiates `Row` from the
+ * array's own element type and checks the key set right there.
+ */
+function by<const K extends string>(
+	first: SortKey<K>,
+	...rest: ReadonlyArray<SortKey<K>>
+): <Row extends Readonly<Record<K, FactValue>>>(left: Row, right: Row) => number {
+	const entries = [first, ...rest].map(function normalizeKey(sortKey): { readonly key: K; readonly factor: 1 | -1 } {
+		if (typeof sortKey === "string") {
+			return { key: sortKey, factor: 1 }
+		}
+		return { key: sortKey.key, factor: -1 }
+	})
+	return function compare<Row extends Readonly<Record<K, FactValue>>>(left: Row, right: Row): number {
+		for (const entry of entries) {
+			const order = cellCmp(left[entry.key], right[entry.key]) * entry.factor
+			if (order !== 0) {
+				return order
+			}
+		}
+		return 0
+	}
+}
+
+export type { Desc, SortKey }
+export { by, desc }

package/src/query/atom.ts

@@ -9,7 +9,7 @@
  * by owner ruling; see {@link BindingInput})
  * (unmentioned fields ARE the wildcard — no wildcard value exists);
  * `not(Rel, {...})` is negation-as-position (anti-join); `eq`/`ne` and the
- * order roster, `pointIn`/`covers` (both spellings of `ir::CmpOp::PointIn`,
+ * order roster, `pointIn` (the one spelling of `ir::CmpOp::PointIn`,
  * always lowered interval-left), `allen` (the 13-bit mask pair
  * comparison), and `and`/`or` (the input condition-tree grammar) complete
  * the roster. Nothing beyond the IR exists here — and the walls the engine
@@ -62,7 +62,7 @@ type MatchOwner = AnyRelation | AnyClosed
  * union rides into ψ id bindings and joins exactly as it does on a
  * referencing column) first, then the declared payload columns read
  * through the typed `columns` carrier (the one source of payload typing —
- * no parallel column table exists). The runtime twin is `matchFieldsOf` in
+ * no parallel column table exists). The runtime twin is `sealedFieldsOf` in
  * `#query/lower.ts`; the id-first ordinal shift the two tiers share is
  * pinned by the lowering golden.
  */
@@ -355,10 +355,10 @@ type NeRight = Var<string> | Param<string> | bigint | string | boolean | Uint8Ar
 /** One side of an order comparison: orderable terms only (the IR's comparison rules). */
 type OrderSide = Var<string> | Param<string> | Duration<string> | bigint
 
-/** The point side of `pointIn`/`covers`. */
+/** The point side of `pointIn`. */
 type PointSide = Var<string> | Param<string> | bigint
 
-/** The interval side of `pointIn`/`covers`/`allen`. */
+/** The interval side of `pointIn`/`allen`. */
 type IntervalSide = Var<string> | Param<string> | IntervalValue
 
 /** Builds one comparison value. */
@@ -426,29 +426,21 @@ function ge<const L extends OrderSide, const R extends OrderSide>(left: L, right
 }
 
 /**
- * Point membership as a predicate (`ir::CmpOp::PointIn`), membership
+ * Point membership as a predicate (`ir::CmpOp::PointIn`) — THE one
  * spelling: `pointIn(t, w)` holds iff `w.start ≤ t < w.end`. The IR
  * orders the operands interval-left, point-right; the value stores them
- * that way whatever the surface spelling.
+ * that way whatever the surface argument order (a literal `span(...)`
+ * interval operand is legal and tags by the point sibling's element
+ * domain — the bug-hunt fix, now also a type-level guarantee).
+ * Interval ⊇ interval is NOT this operator; that predicate is
+ * `allen(a, ALLEN.covers, b)` — the name `covers` belongs to the Allen
+ * roster alone (the canonical-utterance law: one meaning, one spelling).
  */
 function pointIn<const P extends PointSide, const I extends IntervalSide>(point: P, interval: I): Cmp<"pointIn", I, P> {
 	assertTermSide("pointIn", point, interval)
 	return comparison("pointIn", interval, point, undefined)
 }
 
-/**
- * Point membership, coverage spelling — `covers(w, t)` is `pointIn(t, w)`
- * with the interval written first (the IR's own operand order; a literal
- * `span(...)` left operand is legal and tags by the point sibling's
- * element domain — the bug-hunt fix, now also a type-level guarantee).
- * Interval ⊇ interval is NOT this operator; that predicate is
- * `allen(a, ALLEN.covers, b)`.
- */
-function covers<const I extends IntervalSide, const P extends PointSide>(interval: I, point: P): Cmp<"pointIn", I, P> {
-	assertTermSide("covers", interval, point)
-	return comparison("pointIn", interval, point, undefined)
-}
-
 /**
  * The 13-bit mask range: bits above the low 13 are unrepresentable in the
  * engine's `AllenMask` (`bumbledb/crates/bumbledb/src/allen.rs`:
@@ -619,7 +611,7 @@ type NotOk<Env extends EnvShape, F extends FieldsShape, CR, B> = false extends {
  * twin of the engine's comparison roster: class-equal joins (off the
  * schema type's class map), orderable order sides (an interval var under a
  * non-`pointIn` op is exactly here refused), kind-correct
- * `pointIn`/`covers`/`allen` sides, and negated-atom safety (the negated
+ * `pointIn`/`allen` sides, and negated-atom safety (the negated
  * relation's class record is resolved through `Classes` by its name). The
  * leading `[AnyTreeChild] extends [C]` arm is the recursion's base case:
  * at an UNRESOLVED constraint (the whole condition union — or a tree's
@@ -747,4 +739,4 @@ export type {
 	Tree,
 	TreeData
 }
-export { ALLEN, allen, and, comparison, covers, eq, ge, gt, le, lt, ne, not, or, pointIn }
+export { ALLEN, ALLEN_ALL_BITS, allen, and, comparison, eq, ge, gt, le, lt, ne, not, or, pointIn }