@bjornpagen/bumbledb 0.1.0 → 0.3.0

package/src/query/select.ts

@@ -1,106 +1,87 @@
 /**
- * Select entries and aggregates (PRD-08) — the head vocabulary, mirroring
- * the IR's aggregate roster exactly (`bumbledb/crates/bumbledb/src/ir.rs`
- * `AggOp`/`FindTerm`; `docs/architecture/20-query-ir.md` § aggregation):
- * `count` (nullary), `countDistinct`, `sum`/`min`/`max` (over a u64/i64
- * variable or the measure), `argmax`/`argmin` (arg-restriction: carried
- * value + orderable key; a tie yields every attaining row), and `pack`
- * (the coalescing fold — RELATION-SHAPED: one answer row per (group,
- * maximal segment), the result position interval-typed). Grouping is
+ * Select entries and aggregates, STRUCTURAL edition — the head vocabulary,
+ * mirroring the IR's aggregate roster exactly
+ * (`bumbledb/crates/bumbledb/src/ir.rs` `AggOp`/`FindTerm`;
+ * `docs/architecture/20-query-ir.md` § aggregation): `count` (nullary),
+ * `countDistinct`, `sum`/`min`/`max` (over an orderable variable or the
+ * measure), `argMax`/`argMin` (arg-restriction: carried value + orderable
+ * key; a tie yields every attaining row), and `pack` (the coalescing fold —
+ * RELATION-SHAPED: one answer row per (group, maximal segment), the result
+ * position interval-typed). Aggregates name their variables — `r.sum("m")`
+ * — and are typed by the rule environment at `.select`. Grouping is
  * implicit: the non-aggregate select entries are the group key; over empty
  * input an all-aggregate select yields the EMPTY SET, never a zero row.
+ * The creation quarantine is representational: a head position is a var
+ * name, the measure, or an aggregate — no minting or arithmetic term
+ * exists to spell (permanent law).
  */
 
-import type { IntervalValue } from "#brand.ts"
-import { phantom } from "#brand.ts"
-import type { Duration } from "#query/atom.ts"
-import type { AnyVar, Flatten, Var } from "#query/scope.ts"
-import { term } from "#query/scope.ts"
-
-/** The three folds the measure admits (and the plain-variable folds). */
-type FoldOp = "sum" | "min" | "max"
-
-/** One aggregate's runtime description. */
-type AggregateData =
-	| { readonly op: "count" }
-	| { readonly op: "countDistinct"; readonly over: AnyVar }
-	| { readonly op: "fold"; readonly fold: FoldOp; readonly over: AnyVar | Duration }
-	| {
-			readonly op: "arg"
-			readonly direction: "argMax" | "argMin"
-			readonly key: AnyVar
-			readonly over: AnyVar
-	  }
-	| { readonly op: "pack"; readonly over: AnyVar }
+import type { Infer } from "#fields.ts"
+import type { IntervalVarOk, OrderVarOk } from "#query/atom.ts"
+import type { Duration, EnvShape, ShapeOf } from "#query/scope.ts"
+
+/** One aggregate operator name of the select vocabulary. */
+type AggOpName = "count" | "countDistinct" | "sum" | "min" | "max" | "argMax" | "argMin" | "pack"
 
 /**
- * One aggregate select value; the phantom carries the answer column's
- * host type (`count`/`countDistinct` → `bigint` whatever they counted;
- * folds carry their input's type; the Arg forms the carried payload's
- * type; `pack` its interval type).
+ * One aggregate select VALUE: the op, the variable name (or measure) it
+ * folds, and — for the Arg forms — the orderable key's variable name. The
+ * runtime representation carries the types; the rule environment types the
+ * result at `.select`.
  */
-interface Aggregate<R> {
-	readonly aggregate: AggregateData
-	readonly [phantom]?: R
+interface Agg<
+	Op extends AggOpName,
+	Over extends string | Duration<string> | undefined,
+	Key extends string | undefined = undefined
+> {
+	readonly agg: Op
+	readonly over: Over
+	readonly key: Key
 }
 
-/** What a select record's values may be: a projection, a measure, or an aggregate. */
-type SelectEntryInput = AnyVar | Duration | Aggregate<unknown>
-
-/** The select record: answer column name to entry, written order = column order. */
-type SelectShape = Readonly<Record<string, SelectEntryInput>>
+/** Any aggregate select value. */
+type AnyAgg = Agg<AggOpName, string | Duration<string> | undefined, string | undefined>
 
-/** One select entry's answer type. */
-type SelectValue<T> = T extends { readonly aggregate: AggregateData; readonly [phantom]?: infer R }
-	? Exclude<R, undefined>
-	: T extends { readonly measure: AnyVar }
-		? bigint
-		: T extends { readonly [term]: "var"; readonly [phantom]?: infer V }
-			? Exclude<V, undefined>
-			: never
+/** One select entry: a projected var name, the measure, or an aggregate. */
+type SelectEntry = string | Duration<string> | AnyAgg
 
-/** The inferred answer-row object type of a select record. */
-type RowOf<Sel extends SelectShape> = Flatten<{ [K in keyof Sel]: SelectValue<Sel[K]> }>
+/** Builds one aggregate value. */
+function aggregate<
+	Op extends AggOpName,
+	Over extends string | Duration<string> | undefined,
+	Key extends string | undefined
+>(op: Op, over: Over, key: Key): Agg<Op, Over, Key> {
+	return Object.freeze({ agg: op, over, key })
+}
 
-/** Nullary count: |the group's set of distinct full bindings|, `bigint`. */
-function count(): Aggregate<bigint> {
-	return Object.freeze({ aggregate: Object.freeze({ op: "count" as const }) })
+/** Nullary count: |the group's set of distinct full bindings|, `bigint`; the answer column is named `count`. */
+function count(): Agg<"count", undefined> {
+	return aggregate("count", undefined, undefined)
 }
 
-/** |the distinct values of `over` across the group|, `bigint`; legal over every type. */
-function countDistinct<V>(over: Var<V>): Aggregate<bigint> {
-	return Object.freeze({ aggregate: Object.freeze({ op: "countDistinct" as const, over }) })
+/** |the distinct values of the named variable across the group|, `bigint`; legal over every type. */
+function countDistinct<const N extends string>(over: N): Agg<"countDistinct", N> {
+	return aggregate("countDistinct", over, undefined)
 }
 
 /**
- * Exact checked sum over a u64/i64 variable (wide accumulator, one
- * finalize range check — overflow is the engine's typed runtime error,
- * never a wrap), or over the measure (`sum(duration(v))`).
+ * Exact checked sum over an orderable (u64/i64) variable — wide
+ * accumulator, one finalize range check; overflow is the engine's typed
+ * runtime error, never a wrap — or over the measure
+ * (`r.sum(r.duration("w"))`).
  */
-function sum<V extends bigint>(over: Var<V>): Aggregate<V>
-function sum(over: Duration): Aggregate<bigint>
-function sum(over: Var<bigint> | Duration): Aggregate<bigint> {
-	return Object.freeze({
-		aggregate: Object.freeze({ op: "fold" as const, fold: "sum" as const, over })
-	})
+function sum<const N extends string | Duration<string>>(over: N): Agg<"sum", N> {
+	return aggregate("sum", over, undefined)
 }
 
-/** Minimum over a u64/i64 variable or the measure (orderable types only). */
-function min<V extends bigint>(over: Var<V>): Aggregate<V>
-function min(over: Duration): Aggregate<bigint>
-function min(over: Var<bigint> | Duration): Aggregate<bigint> {
-	return Object.freeze({
-		aggregate: Object.freeze({ op: "fold" as const, fold: "min" as const, over })
-	})
+/** Minimum over an orderable variable or the measure (orderable types only). */
+function min<const N extends string | Duration<string>>(over: N): Agg<"min", N> {
+	return aggregate("min", over, undefined)
 }
 
-/** Maximum over a u64/i64 variable or the measure (orderable types only). */
-function max<V extends bigint>(over: Var<V>): Aggregate<V>
-function max(over: Duration): Aggregate<bigint>
-function max(over: Var<bigint> | Duration): Aggregate<bigint> {
-	return Object.freeze({
-		aggregate: Object.freeze({ op: "fold" as const, fold: "max" as const, over })
-	})
+/** Maximum over an orderable variable or the measure (orderable types only). */
+function max<const N extends string | Duration<string>>(over: N): Agg<"max", N> {
+	return aggregate("max", over, undefined)
 }
 
 /**
@@ -111,17 +92,13 @@ function max(over: Var<bigint> | Duration): Aggregate<bigint> {
  * direction; Arg and fold aggregates never mix (both the engine's typed
  * rules).
  */
-function argmax<K extends bigint, V>(key: Var<K>, value: Var<V>): Aggregate<V> {
-	return Object.freeze({
-		aggregate: Object.freeze({ op: "arg" as const, direction: "argMax" as const, key, over: value })
-	})
+function argMax<const V extends string, const K extends string>(value: V, key: K): Agg<"argMax", V, K> {
+	return aggregate("argMax", value, key)
 }
 
-/** Arg-restriction toward the minimum of `key`; rules as {@link argmax}. */
-function argmin<K extends bigint, V>(key: Var<K>, value: Var<V>): Aggregate<V> {
-	return Object.freeze({
-		aggregate: Object.freeze({ op: "arg" as const, direction: "argMin" as const, key, over: value })
-	})
+/** Arg-restriction toward the minimum of `key`; rules as {@link argMax}. */
+function argMin<const V extends string, const K extends string>(value: V, key: K): Agg<"argMin", V, K> {
+	return aggregate("argMin", value, key)
 }
 
 /**
@@ -132,9 +109,107 @@ function argmin<K extends bigint, V>(key: Var<K>, value: Var<V>): Aggregate<V> {
  * input's element type. At most one `pack` per select, never beside a
  * fold or an Arg entry (the engine's typed rules).
  */
-function pack<IV extends IntervalValue>(over: Var<IV>): Aggregate<IV> {
-	return Object.freeze({ aggregate: Object.freeze({ op: "pack" as const, over }) })
+function pack<const N extends string>(over: N): Agg<"pack", N> {
+	return aggregate("pack", over, undefined)
+}
+
+/** A fold input's judgment: an orderable variable, or the measure of an interval variable. */
+type FoldOverOk<Env extends EnvShape, O> = O extends string
+	? OrderVarOk<Env, O>
+	: O extends Duration<infer N extends string>
+		? IntervalVarOk<Env, N>
+		: false
+
+/**
+ * One select entry's judgment against the rule environment: projected
+ * names must be bound, the measure and `pack` demand interval-typed
+ * variables, folds and Arg keys demand orderable ones.
+ */
+type SelectEntryOk<Env extends EnvShape, E> = E extends string
+	? E extends keyof Env
+		? true
+		: false
+	: E extends Duration<infer N extends string>
+		? IntervalVarOk<Env, N>
+		: E extends Agg<"count", undefined>
+			? true
+			: E extends Agg<"countDistinct", infer O extends string>
+				? O extends keyof Env
+					? true
+					: false
+				: E extends Agg<"sum" | "min" | "max", infer O>
+					? FoldOverOk<Env, O>
+					: E extends Agg<"argMax" | "argMin", infer O extends string, infer K extends string>
+						? [O extends keyof Env ? true : false, OrderVarOk<Env, K>] extends [true, true]
+							? true
+							: false
+						: E extends Agg<"pack", infer O extends string>
+							? IntervalVarOk<Env, O>
+							: false
+
+/** The validated select tuple (intersect with the inferred entries — errors land on the offending argument). */
+type CheckSelect<Env extends EnvShape, S> = {
+	readonly [I in keyof S]: SelectEntryOk<Env, S[I]> extends true ? S[I] : never
 }
 
-export type { Aggregate, AggregateData, FoldOp, RowOf, SelectEntryInput, SelectShape, SelectValue }
-export { argmax, argmin, count, countDistinct, max, min, pack, sum }
+/** The validated names-only select tuple of a RECURSIVE rule (aggregates and the measure are unwritable there). */
+type CheckNameSelect<Env extends EnvShape, S> = {
+	readonly [I in keyof S]: S[I] extends keyof Env ? S[I] : never
+}
+
+/**
+ * One select entry's answer-column fragment: the column is named by the
+ * variable it projects or folds (`count` names its column `count`), and
+ * its type reflects the entry — `count`/`countDistinct` are `bigint`
+ * whatever they counted, folds carry their input's type, the measure is
+ * `bigint`, the Arg forms carry the payload's type, `pack` its interval
+ * type.
+ */
+type SelectEntryRow<Env extends EnvShape, E> = E extends string
+	? { readonly [K in E]: Infer<Env[E & keyof Env]["field"]> }
+	: E extends Duration<infer N extends string>
+		? { readonly [K in N]: bigint }
+		: E extends Agg<"count", undefined>
+			? { readonly count: bigint }
+			: E extends Agg<"countDistinct", infer O extends string>
+				? { readonly [K in O]: bigint }
+				: E extends Agg<"sum" | "min" | "max", infer O>
+					? O extends string
+						? { readonly [K in O]: Infer<Env[O & keyof Env]["field"]> }
+						: O extends Duration<infer N extends string>
+							? { readonly [K in N]: bigint }
+							: never
+					: E extends Agg<"argMax" | "argMin", infer O extends string, string>
+						? { readonly [K in O]: Infer<Env[O & keyof Env]["field"]> }
+						: E extends Agg<"pack", infer O extends string>
+							? { readonly [K in O]: Infer<Env[O & keyof Env]["field"]> }
+							: never
+
+/** The inferred answer-row object type of a select tuple. */
+type RowOfSelect<Env extends EnvShape, S extends readonly SelectEntry[]> = ShapeOf<SelectEntryRow<Env, S[number]>>
+
+/**
+ * One projected name's answer-column fragment — a NAKED parameter, so the
+ * judgment distributes per name (the union of a multi-name select never
+ * smears into one column's type), mirroring {@link SelectEntryRow}.
+ */
+type NameSelectRow<Env extends EnvShape, N> = N extends string
+	? { readonly [K in N]: Infer<Env[K & keyof Env]["field"]> }
+	: never
+
+/** The inferred answer-row object type of a names-only (recursive-rule) select tuple. */
+type RowOfNameSelect<Env extends EnvShape, S extends readonly string[]> = ShapeOf<NameSelectRow<Env, S[number]>>
+
+export type {
+	Agg,
+	AggOpName,
+	AnyAgg,
+	CheckNameSelect,
+	CheckSelect,
+	RowOfNameSelect,
+	RowOfSelect,
+	SelectEntry,
+	SelectEntryOk,
+	SelectEntryRow
+}
+export { argMax, argMin, count, countDistinct, max, min, pack, sum }

package/src/relation.ts

@@ -1,31 +1,30 @@
 /**
  * `relation()` — the ordinary-relation half of the theory's signature. A
  * relation value is a frozen plain object carrying its name, its ordered
- * field metadata (declaration order = ordinal ids, the macro's law), typed
- * field references (`R.fields.holder`), and — since selections are the
- * relation's own vocabulary — `where()`, which resolves a selection into
- * lowered bindings eagerly (handles re-verified against their roster at
+ * field descriptors (declaration order = ordinal ids, the macro's law),
+ * typed field references (`R.fields.holder`), and — since selections are
+ * the relation's own vocabulary — `where()`, which resolves a selection
+ * into lowered bindings eagerly (handles verified against their roster at
  * construction). `Fact<>`/`InsertFact<>` are the inferred row object
- * types: fresh fields are optional on insert input (omit-to-mint) and
- * present on read (resupply-to-preserve-identity), typed exactly.
+ * types at BARE structural value types (no brands): fresh fields are
+ * optional on insert input (omit-to-mint) and present on read
+ * (resupply-to-preserve-identity), typed exactly.
  */
 
 import * as errors from "@superbuilders/errors"
-import { phantom } from "#brand.ts"
 import type { OneOf } from "#face.ts"
-import { type AnyField, assertDeclarationOrderKey, type FieldData, type FieldValue, literalOf } from "#fields.ts"
+import { type AnyField, assertDeclarationOrderKey, type Infer, literalOf } from "#fields.ts"
 import type { LiteralSetSpec, LiteralSpec } from "#spec.ts"
 
 /** Flattens an intersection into one displayed object type (hover legibility). */
 type Flatten<T> = { [K in keyof T]: T[K] }
 
 /**
- * The one nominal step of `relation()`: the reference record is built by
+ * The one trusted seam of `relation()`: the reference record is built by
  * iterating the declared fields, and this guard verifies the checkable
  * facts — one reference per declared field, each carrying its own name —
- * before the record is admitted as the typed {@link FieldRefs}. The
- * phantom halves (brands) are carried by construction; this is the
- * module's single trusted seam, the macro-emission analog.
+ * before the record is admitted as the typed {@link FieldRefs} (the
+ * macro-emission analog).
  */
 function refsComplete<RName extends string, Fields extends FieldsShape>(
 	refs: Record<string, unknown>,
@@ -44,7 +43,7 @@ function refsComplete<RName extends string, Fields extends FieldsShape>(
  * `oneOf` signature — the one-element set is unwritable); anything else is
  * the bare literal.
  */
-function resolveEntry(field: FieldData, entry: unknown): LiteralSetSpec {
+function resolveEntry(field: AnyField, entry: unknown): LiteralSetSpec {
 	if (typeof entry === "object" && entry !== null && "literals" in entry && Array.isArray(entry.literals)) {
 		const literals: LiteralSpec[] = entry.literals.map(function lowerSetLiteral(literal: unknown) {
 			return Object.freeze(literalOf(field, literal))
@@ -58,7 +57,10 @@ function resolveEntry(field: FieldData, entry: unknown): LiteralSetSpec {
  * Resolves a whole `where()` selection against the declared fields, in the
  * selection's written order (macro parity: σ is spelled, not sorted). An
  * empty selection is the bare relation respelled and rejected (the
- * canonical-utterance law).
+ * canonical-utterance law). THE one selection resolver — `closed()`'s
+ * `where()` resolves its payload columns through this same machine (a
+ * `ClosedColumn` is structurally a {@link RelationField}), so both surfaces
+ * share one vocabulary and one error voice.
  */
 function resolveSelection(
 	name: string,
@@ -86,29 +88,29 @@ function resolveSelection(
 	return Object.freeze(bindings)
 }
 
-/** The field block of a relation: field name to field constructor value. */
+/** The field block of a relation: field name to field descriptor. */
 type FieldsShape = Record<string, AnyField>
 
 /**
  * A typed field reference (`Account.fields.holder`) — the value statements,
- * selections, and queries address a field through; its hover shows the
- * field's brand in the phantom position.
+ * selections, and queries address a field through. Purely positional
+ * (relation name + field name); the field's descriptor is read off the
+ * relation's schema type structurally.
  */
-interface FieldRef<Rel extends string, Name extends string, V> {
+interface FieldRef<Rel extends string, Name extends string> {
 	readonly relation: Rel
 	readonly field: Name
-	readonly [phantom]?: V
 }
 
 /** The typed field-reference record of a relation. */
 type FieldRefs<RName extends string, Fields extends FieldsShape> = {
-	readonly [K in keyof Fields & string]: FieldRef<RName, K, FieldValue<Fields[K]>>
+	readonly [K in keyof Fields & string]: FieldRef<RName, K>
 }
 
-/** One declared field: name plus its runtime description, in declaration order. */
+/** One declared field: name plus its descriptor, in declaration order. */
 interface RelationField {
 	readonly name: string
-	readonly field: FieldData
+	readonly field: AnyField
 }
 
 /** A relation's runtime description. */
@@ -128,15 +130,14 @@ interface SelectionBinding {
 }
 
 /**
- * The `where()` argument: per field, a branded literal of that field's
- * type (a closed handle constant IS such a literal — it carries the closed
- * relation's brand, so it is legal exactly where the field is that closed
- * relation's id type), an `oneOf(a, b, ...)` literal set, or a `span(start,
- * end)` interval literal. Equality-only by construction: no operator
- * parameter exists anywhere.
+ * The `where()` argument: per field, a bare structural literal of that
+ * field's value type (a closed handle constant IS such a literal — a
+ * bigint verified against the roster at construction), an `oneOf(a, b,
+ * ...)` literal set, or a `span(start, end)` interval literal.
+ * Equality-only by construction: no operator parameter exists anywhere.
  */
 type SelectionInput<Fields extends FieldsShape> = {
-	readonly [K in keyof Fields]?: FieldValue<Fields[K]> | OneOf<FieldValue<Fields[K]>>
+	readonly [K in keyof Fields]?: Infer<Fields[K]> | OneOf<Infer<Fields[K]>>
 }
 
 /** A relation with a selection applied — what `on()` consumes as a σ-carrying source. */
@@ -163,25 +164,21 @@ interface AnySelected {
 }
 
 /** Extracts a relation's field block type. */
-type RelationFields<R extends AnyRelation> = R extends Relation<string, infer F> ? F : never
+type RelationFields<R extends AnyRelation> = R extends Relation<string, infer F extends FieldsShape> ? F : never
 
 /**
  * The inferred row object type of a relation as READ: every field present,
- * branded. Closed relations have no `Fact` — they are unwritable, and the
- * type constraint refuses them because a closed value lacks the relation
- * shape.
+ * at its BARE structural value type ({@link Infer}). Closed relations have
+ * no `Fact` — they are unwritable, and the type constraint refuses them
+ * because a closed value lacks the relation shape.
  */
 type Fact<R extends AnyRelation> = {
-	[K in keyof RelationFields<R>]: FieldValue<RelationFields<R>[K]>
+	[K in keyof RelationFields<R>]: Infer<RelationFields<R>[K]>
 }
 
-/** The field names of `R` that carry the fresh mint mark. */
+/** The field names of `R` whose descriptor type carries the fresh mint mark. */
 type FreshKeys<R extends AnyRelation> = {
-	[K in keyof RelationFields<R>]: RelationFields<R>[K] extends {
-		readonly data: { readonly minted: true }
-	}
-		? K
-		: never
+	[K in keyof RelationFields<R>]: RelationFields<R>[K] extends { readonly fresh: true } ? K : never
 }[keyof RelationFields<R>]
 
 /**
@@ -192,11 +189,14 @@ type FreshKeys<R extends AnyRelation> = {
 type InsertFact<R extends AnyRelation> = Flatten<Omit<Fact<R>, FreshKeys<R>> & Partial<Pick<Fact<R>, FreshKeys<R>>>>
 
 /**
- * Declares one relation: `relation("Account", { id: AccountId.fresh,
- * holder: HolderId, ... })` — every field references a declared newtype
- * (`const AccountId = u64.newtype("AccountId")`) or a bare constructor.
- * Field declaration order is ordinal-id order (macro parity); the returned
- * value is frozen and side-effect free.
+ * Declares one relation: `relation("Account", { id: u64.fresh,
+ * holder: u64, kind: Kind.id, ... })` — every field is a pure-structure
+ * descriptor (the constructor values themselves; domains are never
+ * declared: `schema()` computes them from the statements). Field
+ * declaration order is ordinal-id order (macro parity), carried at BOTH
+ * levels: the type level by the fields object, the value level by the
+ * frozen `data.fields` list — the law the schema-level class naming leans
+ * on. The returned value is frozen and side-effect free.
  */
 function relation<const Name extends string, Fields extends FieldsShape>(
 	name: Name,
@@ -205,7 +205,7 @@ function relation<const Name extends string, Fields extends FieldsShape>(
 	const ordered: RelationField[] = []
 	for (const [fieldName, field] of Object.entries(fields)) {
 		assertDeclarationOrderKey(`relation ${name} field`, fieldName)
-		ordered.push(Object.freeze({ name: fieldName, field: field.data }))
+		ordered.push(Object.freeze({ name: fieldName, field }))
 	}
 	const data: RelationData = Object.freeze({ name, fields: Object.freeze(ordered) })
 	const refs: Record<string, unknown> = {}
@@ -249,4 +249,4 @@ export type {
 	SelectionBinding,
 	SelectionInput
 }
-export { relation }
+export { relation, resolveSelection }