@bjornpagen/bumbledb 0.7.0 → 0.9.0

package/src/order.ts

@@ -10,6 +10,16 @@
  * `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.
+ *
+ * ZERO keys is the identity key (ruled 2026-07-25): `by()` / `desc()` are
+ * the same two spellings over BARE scalar arrays (`bigint[]` of ids, map
+ * keys) — with no column to name, the value itself is the key, there is
+ * nothing to fold, and the comparator IS the result. One ordering
+ * vocabulary, no sibling names. The identity arms are typed to EXACTLY the
+ * engine-orderable roster ({@link EngineOrderable}) because a bare scalar
+ * carries no decoded-row provenance — the type wall must carry the
+ * orderability law itself, where the row arm's cells arrive under their
+ * columns' law-typed proof.
  */
 
 import type { FactValue } from "#native.ts"
@@ -23,6 +33,23 @@ interface Desc<K extends string> {
 /** One sort key: a bare column name (ascending — the punning spelling) or `desc(name)`. */
 type SortKey<K extends string> = K | Desc<K>
 
+/**
+ * The engine-orderable scalar roster in the SDK's representation — `bigint`
+ * (U64/I64) and `boolean` (false < true — the strict 0/1 encoding IS the
+ * order), EXACTLY as `docs/architecture/10-data-model.md` § "Orderability,
+ * complete" admits it (ruled 2026-07-23, R3/R4), and nothing more:
+ * `string` is deliberately absent (intern ids are meaningless to order — a
+ * typed refusal, not a gap) and `number` is not an engine scalar at all.
+ * The identity comparators `by()`/`desc()` constrain on this alias, so
+ * sorting a `string[]` or `number[]` through them is a COMPILE error naming
+ * this roster. ONE OWNER for scalar ordering semantics: both identity arms
+ * route through the same cell order the row arm uses, whose bigint and
+ * boolean arms mirror the engine's U64/I64/Bool order exactly — a host
+ * sort over these values can never disagree with an engine order judgment
+ * (`Lt`-family, `Min`/`Max`) over the same column.
+ */
+type EngineOrderable = bigint | boolean
+
 /**
  * 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
@@ -116,8 +143,38 @@ function cellCmp(left: FactValue, right: FactValue): number {
 	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> {
+/**
+ * The ascending identity comparator `by()` returns — one value, minted
+ * once (`by() === by()`), {@link cellCmp} narrowed to the engine-orderable
+ * roster (the one owner of the cell order).
+ */
+function identityAscending<T extends EngineOrderable>(left: T, right: T): number {
+	return cellCmp(left, right)
+}
+
+/** The descending identity comparator `desc()` returns — the same owner, sides flipped. */
+function identityDescending<T extends EngineOrderable>(left: T, right: T): number {
+	return cellCmp(right, left)
+}
+
+/**
+ * The descending spelling — ONE name, both arities of one ordering
+ * vocabulary. `desc(name)` marks one sort key DESCENDING: plain data for
+ * {@link by} to fold (a bare name is already ascending). `desc()` — zero
+ * keys, the identity key (ruled 2026-07-25) — is the descending comparator
+ * over engine-orderable scalars themselves: a bare `bigint[]` or
+ * `boolean[]` has no column to name, so the value IS the key, there is
+ * nothing to fold, and the comparator is the result directly. The identity
+ * arm covers EXACTLY the {@link EngineOrderable} roster — `string` and
+ * `number` refuse at compile time, citing the orderability law
+ * (`10-data-model.md` § "Orderability, complete").
+ */
+function desc(): <T extends EngineOrderable>(left: T, right: T) => number
+function desc<const K extends string>(key: K): Desc<K>
+function desc<const K extends string>(key?: K): Desc<K> | (<T extends EngineOrderable>(left: T, right: T) => number) {
+	if (key === undefined) {
+		return identityDescending
+	}
 	const marker: Desc<K> = { key, desc: true }
 	return Object.freeze(marker)
 }
@@ -130,12 +187,33 @@ function desc<const K extends string>(key: K): Desc<K> {
  * 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.
+ *
+ * ZERO keys is the identity key (ruled 2026-07-25): `by()` is the
+ * ascending comparator over engine-orderable scalars themselves —
+ * `ids.sort(by())` — for the bare arrays (`bigint[]`, map keys) the
+ * row-typed arm cannot reach because they have no column to name. One
+ * vocabulary, both arities. The identity arm is typed to EXACTLY the
+ * {@link EngineOrderable} roster: with no law-typed column standing proof
+ * over the values, the type wall carries the orderability law itself —
+ * `string` ordering is deliberately refused and `number` is not an engine
+ * scalar (`10-data-model.md` § "Orderability, complete"), so both refuse
+ * at compile time and a host sort can never disagree with an engine order
+ * judgment.
  */
+function by(): <T extends EngineOrderable>(left: T, right: T) => number
 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 } {
+): <Row extends Readonly<Record<K, FactValue>>>(left: Row, right: Row) => number
+function by<const K extends string>(
+	...keys: ReadonlyArray<SortKey<K>>
+):
+	| (<T extends EngineOrderable>(left: T, right: T) => number)
+	| (<Row extends Readonly<Record<K, FactValue>>>(left: Row, right: Row) => number) {
+	if (keys.length === 0) {
+		return identityAscending
+	}
+	const entries = keys.map(function normalizeKey(sortKey): { readonly key: K; readonly factor: 1 | -1 } {
 		if (typeof sortKey === "string") {
 			return { key: sortKey, factor: 1 }
 		}
@@ -152,5 +230,5 @@ function by<const K extends string>(
 	}
 }
 
-export type { Desc, SortKey }
+export type { Desc, EngineOrderable, SortKey }
 export { by, desc }

package/src/query/atom.ts

@@ -335,8 +335,8 @@ type EqRight = AnyVar | Param<string> | SetParam<string> | bigint | string | boo
 /** What `ne`'s right side accepts. */
 type NeRight = AnyVar | Param<string> | bigint | string | boolean | Uint8Array | IntervalValue
 
-/** One side of an order comparison: orderable terms only (the IR's comparison rules). */
-type OrderSide = AnyVar | Param<string> | Duration | bigint
+/** One side of an order comparison: orderable terms only (the IR's comparison rules — bool orders, `false < true`, R3). */
+type OrderSide = AnyVar | Param<string> | Duration | bigint | boolean
 
 /** The point side of `pointIn`. */
 type PointSide = AnyVar | Param<string> | bigint
@@ -388,7 +388,7 @@ function order<Op extends "lt" | "le" | "gt" | "ge", const L extends OrderSide,
 	return comparison(op, left, right, undefined)
 }
 
-/** Strict less-than (`ir::CmpOp::Lt`) — orderable sides only, never intervals/bytes/strings/bools. */
+/** Strict less-than (`ir::CmpOp::Lt`) — orderable sides only (bool included: `false < true`, R3), never intervals/bytes/strings. */
 function lt<const L extends OrderSide, const R extends OrderSide>(left: L, right: R): Cmp<"lt", L, R> {
 	return order("lt", left, right)
 }
@@ -531,19 +531,32 @@ function isRecTarget(value: MatchOwner | RecTarget): value is RecTarget {
 }
 
 /**
- * Whether a variable's OWN field is orderable (u64/i64). A CLOSED reference
+ * Whether a variable's OWN field is NUMERIC (u64/i64) — the judgment the
+ * point side of `pointIn` and the `sum` input read: a point lives in the
+ * interval's element domain, and a quantifier is not an addition, so bool
+ * (orderable, never numeric) is exactly here refused. 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), 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.
+ * closed-bound terms — the construction-time validations in
+ * `#query/lower.ts` are that ban's runtime twin.
  */
-type OrderVarOk<V extends AnyVar> = V["field"] extends { readonly closed: ClosedRoster }
+type NumericVarOk<V extends AnyVar> = V["field"] extends { readonly closed: ClosedRoster }
 	? false
 	: V["field"]["kind"] extends "u64" | "i64"
 		? true
 		: false
 
+/**
+ * Whether a variable's OWN field is ORDERABLE (u64/i64/bool) — the one gate
+ * every order-comparison side, `min`/`max` input, and Arg key reads. Bool
+ * orders: `false < true`, the strict 0/1 encoding IS the order (ruled R3),
+ * exactly the engine's operand screen
+ * (`bumbledb/crates/bumbledb/src/ir/validate/context.rs`); bool has no
+ * closed variant, so the closed exclusion rides in {@link NumericVarOk}.
+ */
+type OrderVarOk<V extends AnyVar> = V["field"]["kind"] extends "bool" ? true : NumericVarOk<V>
+
 /** Whether a variable's OWN field is interval-typed. */
 type IntervalVarOk<V extends AnyVar> = V["field"]["kind"] extends "interval" ? true : false
 
@@ -554,8 +567,8 @@ type OrderSideOk<T> = T extends AnyVar
 		? IntervalVarOk<V>
 		: true
 
-/** One point side's judgment. */
-type PointSideOk<T> = T extends AnyVar ? OrderVarOk<T> : true
+/** One point side's judgment (numeric only — a point lives in the interval's element domain, never bool). */
+type PointSideOk<T> = T extends AnyVar ? NumericVarOk<T> : true
 
 /** One interval side's judgment. */
 type IntervalSideOk<T> = T extends AnyVar ? IntervalVarOk<T> : true
@@ -677,8 +690,18 @@ type EqParams<L, R> = L extends AnyVar
 			: never
 	: never
 
-/** An order side's params contribution (order params are always `bigint`). */
-type OrderSideParams<T> = T extends Param<infer P extends string> ? { readonly [Q in P]: bigint } : never
+/**
+ * An order side's params contribution, typed by the SIBLING side — the
+ * runtime anchors a param to its sibling variable's field, so a bool var
+ * orders against a `boolean` param; every var-less pairing stays `bigint`.
+ */
+type OrderSideParams<T, Sib> =
+	T extends Param<infer P extends string>
+		? { readonly [Q in P]: Sib extends AnyVar ? Infer<Sib["field"]> : bigint }
+		: never
+
+/** The point side's params contribution (a point is always `bigint`). */
+type PointParams<T> = T extends Param<infer P extends string> ? { readonly [Q in P]: bigint } : never
 
 /** An interval side's params contribution. */
 type IntervalSideParams<T> = T extends Param<infer P extends string> ? { readonly [Q in P]: IntervalValue } : never
@@ -697,9 +720,9 @@ type CondParams<C> = [AnyTreeChild] extends [C]
 		? Op extends "eq" | "ne"
 			? EqParams<L, R>
 			: Op extends "lt" | "le" | "gt" | "ge"
-				? OrderSideParams<L> | OrderSideParams<R>
+				? OrderSideParams<L, R> | OrderSideParams<R, L>
 				: Op extends "pointIn"
-					? IntervalSideParams<L> | OrderSideParams<R>
+					? IntervalSideParams<L> | PointParams<R>
 					: Op extends "allen"
 						? IntervalSideParams<L> | IntervalSideParams<R> | MaskParams<M>
 						: never
@@ -749,6 +772,7 @@ export type {
 	MatchShape,
 	NotAtom,
 	NotIdbAtom,
+	NumericVarOk,
 	OrderSide,
 	OrderVarOk,
 	ParamUse,

package/src/query/find.ts

@@ -21,7 +21,7 @@
 
 import type { Infer } from "#fields.ts"
 import type { SchemaClasses } from "#law.ts"
-import type { IntervalVarOk, OrderVarOk } from "#query/atom.ts"
+import type { IntervalVarOk, NumericVarOk, OrderVarOk } from "#query/atom.ts"
 import type { AnyVar, Duration, MintSlotOf } from "#query/scope.ts"
 
 /** One aggregate operator name of the find vocabulary. */
@@ -71,20 +71,21 @@ function countDistinct<const V extends AnyVar>(over: V): Agg<"countDistinct", V>
 }
 
 /**
- * Exact checked sum over an orderable (u64/i64) variable — wide
- * accumulator, one finalize range check; overflow is the engine's typed
- * runtime error — or over the measure (`r.sum(r.duration(w))`).
+ * Exact checked sum over a NUMERIC (u64/i64) variable — wide accumulator,
+ * one finalize range check; overflow is the engine's typed runtime error —
+ * or over the measure (`r.sum(r.duration(w))`). Bool stays refused: a
+ * quantifier is not an addition (R3).
  */
 function sum<const O extends AnyVar | Duration>(over: O): Agg<"sum", O> {
 	return aggregate("sum", over, undefined)
 }
 
-/** Minimum over an orderable variable or the measure (orderable types only). */
+/** Minimum over an orderable variable (u64/i64/bool — over bool, `Min` is the ALL quantifier; R3) or the measure. */
 function min<const O extends AnyVar | Duration>(over: O): Agg<"min", O> {
 	return aggregate("min", over, undefined)
 }
 
-/** Maximum over an orderable variable or the measure (orderable types only). */
+/** Maximum over an orderable variable (u64/i64/bool — over bool, `Max` is the ANY quantifier; R3) or the measure. */
 function max<const O extends AnyVar | Duration>(over: O): Agg<"max", O> {
 	return aggregate("max", over, undefined)
 }
@@ -116,7 +117,22 @@ function pack<const V extends AnyVar>(over: V): Agg<"pack", V> {
 	return aggregate("pack", over, undefined)
 }
 
-/** A fold input's judgment: an orderable variable, or the measure of an interval variable. */
+/**
+ * A `sum` input's judgment: a NUMERIC variable — Sum over bool stays
+ * refused, a quantifier is not an addition (R3) — or the measure of an
+ * interval variable.
+ */
+type SumOverOk<O> = O extends AnyVar
+	? NumericVarOk<O>
+	: O extends Duration<infer V extends AnyVar>
+		? IntervalVarOk<V>
+		: false
+
+/**
+ * A `min`/`max` input's judgment: an ORDERABLE variable — bool folds:
+ * `Max` is Any and `Min` is All, the two quantifiers as the 0/1 encoding's
+ * extremes (R3) — or the measure of an interval variable.
+ */
 type FoldOverOk<O> = O extends AnyVar
 	? OrderVarOk<O>
 	: O extends Duration<infer V extends AnyVar>
@@ -136,15 +152,17 @@ type FindEntryOk<E> = E extends AnyVar
 			? true
 			: E extends Agg<"countDistinct", AnyVar>
 				? true
-				: E extends Agg<"sum" | "min" | "max", infer O>
-					? FoldOverOk<O>
-					: E extends Agg<"argMax" | "argMin", AnyVar, infer K extends AnyVar>
-						? OrderVarOk<K> extends true
-							? true
-							: false
-						: E extends Agg<"pack", infer V extends AnyVar>
-							? IntervalVarOk<V>
-							: false
+				: E extends Agg<"sum", infer O>
+					? SumOverOk<O>
+					: E extends Agg<"min" | "max", infer O>
+						? FoldOverOk<O>
+						: E extends Agg<"argMax" | "argMin", AnyVar, infer K extends AnyVar>
+							? OrderVarOk<K> extends true
+								? true
+								: false
+							: E extends Agg<"pack", infer V extends AnyVar>
+								? IntervalVarOk<V>
+								: false
 
 /** The validated find record (intersect with the inferred entries — errors land on the offending key). */
 type CheckFind<F extends FindShape> = {

package/src/schema.ts

@@ -306,7 +306,7 @@ function schema<const Rels extends SchemaRelations, const Stmts extends readonly
 		 */
 		if (!isStatement(statement)) {
 			throw errors.new(
-				`schema ${name}: a statement is minted only by key/contained/mirrors/window — a structural literal skips the construction-time arity and roster walls`
+				`schema ${name}: a statement is minted only by key/contained/mirrors/capacity — a structural literal skips the construction-time arity and roster walls`
 			)
 		}
 		const rendered = renderStatement(statement)

package/src/spec.ts

@@ -72,10 +72,10 @@ type LiteralSetSpec =
 	| { readonly kind: "many"; readonly literals: readonly LiteralSpec[] }
 
 /**
- * One side of a containment or window: `R(fields… | field == literal…)`,
- * all names. `projection` is π in the statement's written order (positional
- * pairing with the other side); `selection` is σ as (field, literal-or-set)
- * pairs, read conjunctively.
+ * One side of a containment or capacity statement:
+ * `R(fields… | field == literal…)`, all names. `projection` is π in the
+ * statement's written order (positional pairing with the other side);
+ * `selection` is σ as (field, literal-or-set) pairs, read conjunctively.
  */
 interface SideSpec {
 	readonly relation: string
@@ -84,16 +84,43 @@ interface SideSpec {
 }
 
 /**
- * A cardinality window's bounds — the canonical-utterance law's surviving
- * spellings only, since the SDK's `Count` constructors make every banned
- * spelling unwritable or a construction error: `exact` is `{n}` (`{0}` the
- * exclusion), `range` is `{lo..hi}` with lo < hi, `floor` is `{lo..*}` with
- * lo ≥ 2.
+ * One capacity bound: a non-negative literal, a u64 field of the TARGET
+ * row (the dependent bound — per-group capacity read at judge time), or
+ * the interval-measure of a TARGET-row field (`Duration(span)`). Names,
+ * not ids — the spec is the name-level wire; the engine resolves bound
+ * names against the target's FULL roster (C1), never the projection.
  */
-type WindowSpec =
-	| { readonly kind: "exact"; readonly n: bigint }
-	| { readonly kind: "range"; readonly lo: bigint; readonly hi: bigint }
-	| { readonly kind: "floor"; readonly lo: bigint }
+type CapacityBoundSpec =
+	| { readonly kind: "lit"; readonly value: bigint }
+	| { readonly kind: "field"; readonly field: string }
+	| { readonly kind: "durationField"; readonly field: string }
+
+/**
+ * A capacity statement's weight — a TOTAL sum (C4: `unit` is a case, not
+ * an absence): the count instance (`unit`), a u64 field of the SOURCE row
+ * (`field`), or a SOURCE-row interval's measure (`durationField`). The
+ * wire always carries it — a unit statement crosses as `{ kind: "unit" }`,
+ * never by omission.
+ */
+type WeightSpec =
+	| { readonly kind: "unit" }
+	| { readonly kind: "field"; readonly field: string }
+	| { readonly kind: "durationField"; readonly field: string }
+
+/**
+ * A capacity statement's window — the canonical-utterance law's surviving
+ * spellings, per-aggregate where weight-sensitive (design § 6), since the
+ * SDK's `within()` mint makes every banned spelling unwritable or a
+ * construction error: `exact` is `{n}` (`{0}` the exclusion on the unit
+ * instance, "total is zero" on a weighted one), `range` is `{lo..hi}` with
+ * lo < hi (`{0..hi}` the canonical ceiling; the hi slot admits a dependent
+ * bound — C6: hi only), `floor` is `{lo..*}` (`{1..*}` legal on weighted
+ * statements only).
+ */
+type CapacityWindowSpec =
+	| { readonly kind: "exact"; readonly n: CapacityBoundSpec }
+	| { readonly kind: "range"; readonly lo: CapacityBoundSpec; readonly hi: CapacityBoundSpec }
+	| { readonly kind: "floor"; readonly lo: CapacityBoundSpec }
 
 /**
  * One field: name, structural type, host newtype name — the field's
@@ -148,8 +175,10 @@ interface RelationSpec {
  * One dependency statement, tagged by form. `==` is not a variant: a
  * bidirectional containment is `containment` with `bidirectional: true`,
  * lowered by the engine to the two adjacent containments (`source <=
- * target` first). `cardinality` is B-family, target-left: the target is the
- * per-group parent, the source is counted.
+ * target` first). `capacity` reads as the operator does (C2 — target,
+ * weight, window, source): the target is the per-group parent, the source
+ * is the weighed side, and the weight is ALWAYS present (`unit` the count
+ * instance).
  */
 type StatementSpec =
 	| { readonly kind: "fd"; readonly relation: string; readonly projection: readonly string[] }
@@ -160,9 +189,10 @@ type StatementSpec =
 			readonly bidirectional: boolean
 	  }
 	| {
-			readonly kind: "cardinality"
+			readonly kind: "capacity"
 			readonly target: SideSpec
-			readonly window: WindowSpec
+			readonly weight: WeightSpec
+			readonly window: CapacityWindowSpec
 			readonly source: SideSpec
 	  }
 
@@ -308,22 +338,58 @@ function renderLiteralSet(set: LiteralSetSpec): string {
 }
 
 /**
- * Renders window bounds in their one canonical spelling: `{n}` exact
+ * Renders one capacity bound in its one canonical spelling: a literal as
+ * digits, a dependent bound bare by field name, an interval-measure bound
+ * as `Duration(field)` — the spellings the engine's renderer emits.
+ */
+function renderCapacityBound(bound: CapacityBoundSpec): string {
+	switch (bound.kind) {
+		case "lit":
+			return bound.value.toString()
+		case "field":
+			return bound.field
+		case "durationField":
+			return `Duration(${bound.field})`
+	}
+}
+
+/**
+ * Renders a capacity window in its one canonical spelling: `{n}` exact
  * (`{0}` the exclusion), `{lo..hi}`, `{lo..*}` — the spelling set the
- * engine's renderer emits for sealed statements.
+ * engine's renderer emits for sealed statements, bounds through
+ * {@link renderCapacityBound}.
  */
-function renderWindow(window: WindowSpec): string {
+function renderCapacityWindow(window: CapacityWindowSpec): string {
 	switch (window.kind) {
 		case "exact":
-			return `{${window.n}}`
+			return `{${renderCapacityBound(window.n)}}`
 		case "range":
-			return `{${window.lo}..${window.hi}}`
+			return `{${renderCapacityBound(window.lo)}..${renderCapacityBound(window.hi)}}`
 		case "floor":
-			return `{${window.lo}..*}`
+			return `{${renderCapacityBound(window.lo)}..*}`
+	}
+}
+
+/**
+ * Renders a capacity weight as the operator's bracket: the unit weight
+ * renders NOTHING — the count utterance `<={lo..hi}` falls out of the one
+ * printer, never a second "legacy" arm — a field weight as `[field]`, an
+ * interval measure as `[Duration(field)]`.
+ */
+function renderWeight(weight: WeightSpec): string {
+	switch (weight.kind) {
+		case "unit":
+			return ""
+		case "field":
+			return `[${weight.field}]`
+		case "durationField":
+			return `[Duration(${weight.field})]`
 	}
 }
 
 export type {
+	CapacityBoundSpec,
+	CapacityWindowSpec,
 	ClosedSpec,
 	FieldSpec,
 	LiteralSetSpec,
@@ -335,6 +401,6 @@ export type {
 	StatementSpec,
 	ValueSpec,
 	ValueTypeSpec,
-	WindowSpec
+	WeightSpec
 }
-export { renderLiteral, renderLiteralSet, renderWindow }
+export { renderCapacityBound, renderCapacityWindow, renderLiteral, renderLiteralSet, renderWeight }