@bjornpagen/bumbledb 0.3.0 → 0.5.0

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

@@ -4,9 +4,12 @@
  * (`bumbledb/crates/bumbledb/src/ir.rs`, the bijection target;
  * `docs/architecture/20-query-ir.md` normative). A `match` binding record
  * binds fields to vars, params, ∈-set params, or bare structural literals
+ * — a closed-reference field's literal is its handle NAME, and a plain
+ * ARRAY of names there is membership, folded into the program (closed-only
+ * 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
@@ -26,7 +29,7 @@
 
 import * as errors from "@superbuilders/errors"
 import type { AnyClosed } from "#closed.ts"
-import type { AnyField, ClosedIdField, Infer, IntervalValue } from "#fields.ts"
+import type { AnyField, ClosedIdField, ClosedRoster, Infer, IntervalValue } from "#fields.ts"
 import type { ClassLookup, ClassRecordOf, SchemaClasses } from "#law.ts"
 import type {
 	ClassedField,
@@ -55,23 +58,32 @@ type MatchOwner = AnyRelation | AnyClosed
 /**
  * The matchable field block of an atom owner: a relation's declared
  * fields; a closed relation's SEALED shape — the synthetic `id` (the
- * roster-carrying descriptor) 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 `#query/lower.ts`; the id-first ordinal shift the two
- * tiers share is pinned by the lowering golden.
+ * value's OWN roster-carrying descriptor, at its precise type: the handle
+ * 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 `sealedFieldsOf` in
+ * `#query/lower.ts`; the id-first ordinal shift the two tiers share is
+ * pinned by the lowering golden.
  */
 type MatchFields<R extends MatchOwner> = R extends AnyClosed
-	? { readonly id: ClosedIdField } & R["columns"]
+	? { readonly id: R["id"] } & R["columns"]
 	: R extends AnyRelation
 		? RelationFields<R>
 		: never
 
-/** One atom-binding position as runtime data. */
+/**
+ * One atom-binding position as runtime data. `literalSet` is a membership
+ * ARRAY at a closed-reference field, folded into the program: `name` is
+ * the content-addressed registry key its dense `ParamId` is minted under
+ * (the lowering rides the existing param-set term; the SDK itself supplies
+ * the translated member set at every execute — never the host).
+ */
 type BindingTermData =
 	| { readonly kind: "var"; readonly name: string }
 	| { readonly kind: "param"; readonly name: string }
 	| { readonly kind: "setParam"; readonly name: string }
+	| { readonly kind: "literalSet"; readonly name: string; readonly members: readonly string[] }
 	| { readonly kind: "literal"; readonly value: unknown }
 
 /** One resolved binding: the field's name, its descriptor, its law-computed class, and the term. */
@@ -135,10 +147,18 @@ type SelectEntryData =
 	| { readonly kind: "measure"; readonly over: string }
 	| { readonly kind: "aggregate"; readonly agg: AggData }
 
-/** One answer column: its name (the row object key) and its entry. */
+/**
+ * One answer column: its name (the row object key), its entry, and — when
+ * the column's value is a closed reference (a projected var or an
+ * Arg-carried payload bound at a closed-referencing field) — the roster the
+ * decode lifts row ids back to handle NAMES through (the read half of the
+ * marshal bijection; `undefined` on every bare column). The slice is
+ * SDK-side marshaling data only: the wire `ProgramIr` never carries it.
+ */
 interface SelectColumn {
 	readonly name: string
 	readonly entry: SelectEntryData
+	readonly closed: ClosedRoster | undefined
 }
 
 /** One body item of a rule, in written order. */
@@ -151,13 +171,17 @@ type RuleItem =
 /**
  * One use of a parameter inside a rule, in written order: the census the
  * query-level registry folds (first use mints the dense `ParamId`, first
- * FIELD-ANCHORED use types the wire).
+ * FIELD-ANCHORED use types the wire). `members` is present exactly on a
+ * membership-array use (a literal set folded into the program): the handle
+ * names the SDK itself translates and supplies at execute — the entry
+ * never appears in the host's params object.
  */
 interface ParamUse {
 	readonly name: string
 	readonly shape: "value" | "set" | "mask"
 	readonly anchor: AnyField | "measure" | undefined
 	readonly op: "binding" | CmpKind
+	readonly members: readonly string[] | undefined
 }
 
 /** One complete rule as runtime data. */
@@ -184,10 +208,18 @@ interface RecData {
  * of the field's value type, a var/param/∈-set-param term — and, when the
  * field is interval-typed, a bare point literal (the IR's membership
  * typing rule: an element-typed term at an interval field is point
- * membership; an interval-typed term is value equality).
+ * membership; an interval-typed term is value equality). A
+ * CLOSED-reference field additionally takes a plain ARRAY of handle names
+ * read as membership — `kind: ["Practice", "Review"]` (the drizzle law:
+ * set membership is an array, never an operator). Arrays are CLOSED-ONLY
+ * in this packet by owner ruling: ordinary u64/str membership already has
+ * its spelling through `r.inSet` params; widening literal arrays to every
+ * literal-capable kind is a separate future taste call — deliberately not
+ * done here.
  */
 type BindingInput<F extends AnyField> =
 	| Infer<F>
+	| (F extends ClosedIdField ? readonly Infer<F>[] : never)
 	| (F extends { readonly kind: "interval" } ? bigint : never)
 	| Var<string>
 	| Param<string>
@@ -323,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. */
@@ -394,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`:
@@ -516,11 +540,22 @@ function not<R extends MatchOwner, const B extends MatchShape<MatchFields<R>>>(
 	return Object.freeze(value)
 }
 
-/** Whether a var name is bound in the environment at an orderable (u64/i64) field. */
+/**
+ * Whether a var name is bound in the environment at an orderable (u64/i64)
+ * field. A CLOSED reference is excluded even though its kind is `u64`: a
+ * vocabulary's declaration-id order is an accident, not semantics
+ * (`docs/architecture/10-data-model.md` § orderability — order on it is
+ * refused exactly as the enum's ordinal order was), so every
+ * order-comparison and fold position refuses closed-bound terms — this
+ * judgment is the one gate they all read, and the construction-time
+ * validations in `#query/lower.ts` are its runtime twin.
+ */
 type OrderVarOk<Env extends EnvShape, N extends string> = N extends keyof Env
-	? Env[N]["field"]["kind"] extends "u64" | "i64"
-		? true
-		: false
+	? Env[N]["field"] extends { readonly closed: ClosedRoster }
+		? false
+		: Env[N]["field"]["kind"] extends "u64" | "i64"
+			? true
+			: false
 	: false
 
 /** Whether a var name is bound at an interval field. */
@@ -576,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
@@ -704,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 }