@bjornpagen/bumbledb 0.5.0 → 0.7.0

package/src/query/predicate.ts

@@ -5,31 +5,39 @@
  *
  *   program(S, (p) => {
  *     const reach = p.rec("reach")
- *     reach.rule((r) => r.match(Node, { id: r.var("c") })
- *       .where(r.eq(r.var("c"), r.param("root"))).select("c"))
- *     reach.rule((r) => r.match(Parent, { child: r.var("c"), parent: r.var("m") })
- *       .idb(reach, r.var("m")).select("c"))
- *     return p.output((r) => r.match(Posting, { account: r.var("a"), minor: r.var("m") })
- *       .idb(reach, r.var("a")).select(r.sum("m")))
+ *     reach.rule((r) => {
+ *       const n = v(Node)
+ *       return r.match(Node, { id: n.id }).where(r.eq(n.id, r.param("root"))).find({ c: n.id })
+ *     })
+ *     reach.rule((r) => {
+ *       const e = v(Parent)
+ *       return r.match(Parent, { child: e.child, parent: e.parent }).idb(reach, { c: e.parent }).find({ c: e.child })
+ *     })
+ *     return p.output((r) => {
+ *       const post = v(Posting)
+ *       return r.match(Posting, { account: post.account, minor: post.minor })
+ *         .idb(reach, { c: post.account }).find({ total: r.sum(post.minor) })
+ *     })
  *   })
  *
  * `p.rec(name)` declares one recursive predicate (declaration order = its
  * dense `PredId`); `rec.rule(...)` attaches one clause — its builder's
  * `idb` accepts ONLY the rec itself (the self-recursion cut as a
- * type-level boundary: mutual recursion is unwritable) and its head
- * projects bound variable NAMES only (aggregation/measure through a cycle
- * is unrepresentable — the strata judge's roster, made unwritable);
+ * type-level boundary: mutual recursion is unwritable) and its `find` head
+ * projects bound variables only (aggregation/measure through a cycle is
+ * unrepresentable — the strata judge's roster, made unwritable);
  * `p.output(...)` seals the recs and builds the output rules, whose `idb`
- * folds any FINISHED stratum (recipe 25's form). The rec value `.rule`
- * returns carries the params its rules used — thread it into the output's
- * `idb` and the program's inferred `Params` stays exactly the params the
- * rules use. Everything deeper — strata legality, signature sealing, the
- * three oracles — is the ENGINE's judge, surfacing typed at prepare.
+ * folds any FINISHED stratum by NAMED record over its head keys (recipe
+ * 25's form). The rec value `.rule` returns carries the params its rules
+ * used — thread it into the output's `idb` and the program's inferred
+ * `Params` stays exactly the params the rules use. Everything deeper —
+ * strata legality, signature sealing, the three oracles — is the ENGINE's
+ * judge, surfacing typed at prepare.
  */
 
 import * as errors from "@superbuilders/errors"
 import type { SchemaClasses } from "#law.ts"
-import type { RecData, RuleData, SelectColumn } from "#query/atom.ts"
+import type { RecData } from "#query/atom.ts"
 import type {
 	AnyRuleValue,
 	HeadOf,
@@ -45,7 +53,7 @@ import type {
 	RuleValue
 } from "#query/lower.ts"
 import { makeOutputRuleScope, makeQuery, makeRawScope } from "#query/lower.ts"
-import type { ClassedField, Flatten, ParamsRecord, ShapeOf } from "#query/scope.ts"
+import type { Flatten, ParamsRecord, ShapeOf } from "#query/scope.ts"
 import { fieldJoins, inferred, renderFieldKind } from "#query/scope.ts"
 import type { Schema, SchemaRelations } from "#schema.ts"
 
@@ -112,20 +120,6 @@ interface RawRec<Name extends string> {
 	rule(build: (r: RawScope) => RuleValue<never, never>): RawRec<Name>
 }
 
-/**
- * The classed slot one rec head column binds, through the rule's own
- * environment: a rec head projects bound variable NAMES only (the strata
- * roster's unwritability), so every column is a projected var and its
- * slot is the var's first positive binding.
- */
-function recHeadSlotOf(rule: RuleData, column: SelectColumn): ClassedField | undefined {
-	const entry = column.entry
-	if (entry.kind === "var") {
-		return rule.varFields[entry.over]
-	}
-	return undefined
-}
-
 /** Builds the runtime rec handle over shared rec data. */
 function makeRawRec<Name extends string>(state: ProgramState, name: Name, data: RecData): RawRec<Name> {
 	const rec: RawRec<Name> = {
@@ -137,13 +131,13 @@ function makeRawRec<Name extends string>(state: ProgramState, name: Name, data:
 					`rec ${name}: the program's output is already declared — recursive rules attach before p.output`
 				)
 			}
-			const built = build(makeRawScope({ kind: "rec", self: data, classes: state.classes }))
+			const built = build(makeRawScope({ kind: "rec", self: data, classes: state.classes, theory: state.theory }))
 			const head = data.rules[0]
 			if (head !== undefined) {
-				const declared = head.select.map(function columnName(column) {
+				const declared = head.finds.map(function columnName(column) {
 					return column.name
 				})
-				const candidate = built.rule.select.map(function columnName(column) {
+				const candidate = built.rule.finds.map(function columnName(column) {
 					return column.name
 				})
 				if (declared.join(", ") !== candidate.join(", ")) {
@@ -153,21 +147,19 @@ function makeRawRec<Name extends string>(state: ProgramState, name: Name, data:
 				}
 				// The law-class wall on the sealed head: names alone do not
 				// align value spaces. Every rule must bind each head column
-				// at a slot that JOINS rule 0's (the sealing rule — the one
-				// slot every downstream idb pairing class-checks against),
-				// under the same fieldJoins judgment every reuse site
-				// enforces; otherwise a later rule feeds (say) bare weights
-				// into a column the idb joins as Node ids.
-				built.rule.select.forEach(function verifyHeadSlot(column, position) {
-					const lead = head.select[position]
+				// at a classed mint slot that JOINS rule 0's (the sealing rule
+				// — the one slot every downstream idb pairing class-checks
+				// against), under the same fieldJoins judgment every reuse
+				// site enforces; otherwise a later rule feeds (say) bare
+				// weights into a column the idb joins as Node ids.
+				built.rule.finds.forEach(function verifyHeadSlot(column, position) {
+					const lead = head.finds[position]
 					if (lead === undefined) {
 						return
 					}
-					const leadSlot = recHeadSlotOf(head, lead)
-					const slot = recHeadSlotOf(built.rule, column)
-					if (leadSlot !== undefined && slot !== undefined && !fieldJoins(leadSlot, slot)) {
+					if (lead.slot !== undefined && column.slot !== undefined && !fieldJoins(lead.slot, column.slot)) {
 						throw errors.new(
-							`rec ${name}: every rule derives the same head — the head column ${lead.name} is bound at ${renderFieldKind(leadSlot)} in rule 0 but at ${renderFieldKind(slot)} in this rule (a head column joins only class-equal slots; bare pairs only with bare)`
+							`rec ${name}: every rule derives the same head — the head column ${lead.name} is bound at ${renderFieldKind(lead.slot)} in rule 0 but at ${renderFieldKind(column.slot)} in this rule (a head column joins only class-equal slots; bare pairs only with bare)`
 						)
 					}
 				})
@@ -221,7 +213,7 @@ function program<
 	Classes extends SchemaClasses,
 	Q extends Query<Rels, unknown, ParamsRecord, Classes>
 >(theory: Schema<Rels, Classes>, build: (p: ProgramScope<Rels, Classes>) => Q): Q {
-	const state: ProgramState = { recs: [], classes: theory.classes, sealed: false }
+	const state: ProgramState = { recs: [], classes: theory.classes, theory, sealed: false }
 	const names = new Set<string>()
 	const made: { query: unknown } = { query: undefined }
 	const scope: ProgramScope<Rels, Classes> = {

package/src/query/run.ts

@@ -10,7 +10,7 @@
  * select column IS a row (the trusted read seam), and nothing is asserted
  * on any value. A CLOSED answer column decodes id → handle NAME through
  * the marshal's one bijection (`handleOf` — the same read half every fact
- * decode rides; the column's roster rides `SelectColumn.closed`), so query
+ * decode rides; the column's roster rides `FindColumn.closed`), so query
  * rows speak the vocabulary exactly as scans and gets do. Answers are
  * SETS — no order or limit exists anywhere; hosts sort. The `Prepared`
  * VALUE itself (no lifecycle, GC-reclaimed plan) lives in `#db.ts`.
@@ -19,7 +19,7 @@
 import * as errors from "@superbuilders/errors"
 import { handleOf } from "#marshal.ts"
 import type { FactValue, QueryParam, TaggedValue } from "#native.ts"
-import type { SelectColumn } from "#query/atom.ts"
+import type { FindColumn } from "#query/atom.ts"
 import { ALLEN_ALL_BITS } from "#query/atom.ts"
 import { taggedCmpLiteral } from "#query/lower.ts"
 import type { ParamEntry } from "#query/scope.ts"
@@ -48,21 +48,16 @@ function wireValue(entry: ParamEntry, context: string, value: unknown): TaggedVa
  * is a typed error naming the param; values tag by the anchoring use's
  * structural type; a set param takes a readonly array (the empty set is
  * legal and matches nothing — the engine's rule). A MEMBERSHIP-ARRAY
- * entry (`members` present — a literal set folded into the program) is
- * supplied by the SDK itself: each handle name rides the one
- * roster-verification point (`taggedHandleId`, through `wireValue`) and
- * crosses as the same `{ kind: "set", values }` a bound `r.inSet` param
- * crosses as — the host's params object is never consulted for it.
+ * entry (`membership` present — a literal set folded into the program) is
+ * a program constant the registry already resolved through the one
+ * roster-verification point at BUILD time: it crosses as its prebuilt
+ * frozen `{ kind: "set", values }` by reference — the host's params object
+ * is never consulted for it, and no per-execute work exists.
  */
 function wireParams(entries: readonly ParamEntry[], supplied: Readonly<Record<string, unknown>>): QueryParam[] {
 	return entries.map(function wireOne(entry): QueryParam {
-		if (entry.members !== undefined) {
-			return {
-				kind: "set",
-				values: entry.members.map(function wireMember(member, index) {
-					return wireValue(entry, `membership array ${entry.name}[${index}]`, member)
-				})
-			}
+		if (entry.membership !== undefined) {
+			return entry.membership
 		}
 		const value = supplied[entry.name]
 		if (value === undefined) {
@@ -94,10 +89,10 @@ function wireParams(entries: readonly ParamEntry[], supplied: Readonly<Record<st
  * re-derive).
  */
 function isAnswerRow<Row>(
-	select: readonly SelectColumn[],
+	finds: readonly FindColumn[],
 	decoded: Readonly<Record<string, FactValue>>
 ): decoded is Readonly<Record<string, FactValue>> & Row {
-	return select.every(function present(column) {
+	return finds.every(function present(column) {
 		return decoded[column.name] !== undefined
 	})
 }
@@ -109,13 +104,13 @@ function isAnswerRow<Row>(
  * NAME through the marshal's bijection — an out-of-roster id is the same
  * pointed throw a fact decode gives, never a silent fallback.
  */
-function decodeAnswers<Row>(select: readonly SelectColumn[], rows: FactValue[][]): Row[] {
+function decodeAnswers<Row>(finds: readonly FindColumn[], rows: FactValue[][]): Row[] {
 	return rows.map(function decodeRow(row) {
-		if (row.length !== select.length) {
-			throw errors.new(`query answer arity ${row.length} does not match the ${select.length} select columns`)
+		if (row.length !== finds.length) {
+			throw errors.new(`query answer arity ${row.length} does not match the ${finds.length} find columns`)
 		}
 		const decoded: Record<string, FactValue> = {}
-		select.forEach(function decodeCell(column, ordinal) {
+		finds.forEach(function decodeCell(column, ordinal) {
 			const cell = row[ordinal]
 			if (cell === undefined) {
 				throw errors.new(`query answer cell ${ordinal} (${column.name}) is absent`)
@@ -124,8 +119,8 @@ function decodeAnswers<Row>(select: readonly SelectColumn[], rows: FactValue[][]
 				column.closed === undefined ? cell : handleOf(`query answer column ${column.name}`, column.closed, cell)
 		})
 		Object.freeze(decoded)
-		if (!isAnswerRow<Row>(select, decoded)) {
-			throw errors.new("query answer row is not a complete select record")
+		if (!isAnswerRow<Row>(finds, decoded)) {
+			throw errors.new("query answer row is not a complete find record")
 		}
 		return decoded
 	})

package/src/query/scope.ts

@@ -1,26 +1,43 @@
 /**
- * Query scope terms, LAW-TYPED edition: string-named variables and
- * parameters as plain frozen values. A `Var` is a NAME — it is typed by the
- * field slot it first binds (the descriptor AND the slot's law-computed
- * CLASS, read off the schema's class map through the rule builder's
- * environment), reuse of the name within one rule IS the join, and a
- * class-mismatched reuse is a compile error: a var joins only class-equal
- * slots, and BARE PAIRS ONLY WITH BARE (ruling 3 — a slot in no law has no
- * class and never joins a classed slot; the deliberate sum-domain pointer
- * stays legal against other bare slots). Params are query-global by name
- * and typed BY USE: the field position or comparison sibling that anchors
- * a param types it, the query's inferred `Params` object is exactly the
- * params the rules use, and a param value that no rule uses simply never
- * registers — the query executes under its own inferred type (the
- * bug-hunt law). This module also owns the environment/typing utilities
- * the whole surface shares: the env shape (var name → classed slot), the
- * class-equality judgment {@link JoinOk} with its runtime twin
- * {@link fieldJoins}, and the record-folding helpers `Params` and `Row`
- * inference ride.
+ * Query scope terms, REFERENCE-IDENTITY edition: a query variable is an
+ * OBJECT, minted fresh by {@link v} over a relation's statically-known
+ * columns. `v(relation)` returns a record of fresh variables — one per
+ * column, each typed at mint by its column's descriptor AND the mint
+ * coordinate (the owner relation name and the column name), so
+ * destructuring preserves every literal and every class
+ * (`const { id, holder } = v(Account)`). Variable IDENTITY is the object
+ * reference: reusing the same var value across binding positions IS the
+ * join, and a name-collision join is unrepresentable (two `v()` calls mint
+ * two distinct batches, so two same-named vars are two variables). Params
+ * stay STRING-named — their names are the execute() params object's runtime
+ * keys, an honest load-bearing channel, not a lie.
+ *
+ * THE DESIGN THEOREM. {@link JoinOk} is an EQUALITY (kind, class, width,
+ * element, roster), so judging every binding position against the
+ * variable's MINT slot ({@link MintSlotOf}) makes all cross-binding joins
+ * mutually class-equal by transitivity — the env/sibling checks the
+ * name-keyed edition needed are subsumed, deleted rather than ported. The
+ * one check representation cannot carry is BOUNDNESS (is this var positively
+ * bound in this rule): TypeScript types cannot see object identity, so
+ * boundness moves from the type tier to construction-time walls only — an
+ * explicit essential-vs-accidental concession; every runtime twin is
+ * preserved.
+ *
+ * This module also owns the environment/typing utilities the whole surface
+ * shares: the join descriptor {@link ClassedField}, the mint-slot machinery
+ * ({@link MintSlotOf}/{@link MintClassOf}), the class-equality judgment
+ * {@link JoinOk} with its runtime twin {@link fieldJoins}, and the
+ * record-folding helpers `Params` and `Row` inference ride.
  */
 
+import * as errors from "@superbuilders/errors"
+import type { AnyClosed } from "#closed.ts"
+import { sealedFieldsOf } from "#closed.ts"
 import type { AnyField, Infer } from "#fields.ts"
 import { rosterOf } from "#fields.ts"
+import type { ClassLookup, ClassRecordOf, SchemaClasses } from "#law.ts"
+import type { QueryParam } from "#native.ts"
+import type { AnyRelation, RelationFields } from "#relation.ts"
 
 /**
  * The runtime discriminant of query term values. Host literals (bigints,
@@ -38,17 +55,47 @@ const term: unique symbol = Symbol("bumbledb.query.term")
 const inferred: unique symbol = Symbol("bumbledb.query.inferred")
 
 /**
- * A query variable — a NAME. Its type comes from the field it first binds
- * in the rule (the builder's environment); reusing the name joins, and a
- * cross-domain reuse is a compile error. Identity is the name, strictly
- * rule-scoped: the same name in two rules names two unrelated variables
- * (exactly as the IR scopes `VarId`).
+ * What a query atom matches over: an ordinary relation or a CLOSED
+ * vocabulary (ψ query atoms — the engine folds a resolvable closed atom
+ * into a plan-constant member set at prepare, or joins the L1-resident
+ * virtual image when the shape does not fold; the SDK never pre-folds and
+ * never knows which — transparency is the contract).
  */
-interface Var<Name extends string = string> {
+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
+ * value's OWN roster-carrying descriptor, at its precise type) first, then
+ * the declared payload columns read through the typed `columns` carrier.
+ * The runtime twin is `sealedFieldsOf` in `#closed.ts`.
+ */
+type MatchFields<R extends MatchOwner> = R extends AnyClosed
+	? { readonly id: R["id"] } & R["columns"]
+	: R extends AnyRelation
+		? RelationFields<R>
+		: never
+
+/**
+ * A query variable — an OBJECT minted by {@link v}. Identity is the object
+ * reference: reuse of the same value across binding positions is the join,
+ * strictly rule-scoped (each rule numbers its own dense `VarId`s). The type
+ * carries the mint COORDINATE — `RN` the owner relation name literal, `K`
+ * the column name literal — and `F` the mint descriptor, so the mint slot
+ * (descriptor + law-computed class) is recoverable at every binding
+ * position for the join judgment.
+ */
+interface Var<F extends AnyField = AnyField, RN extends string = string, K extends string = string> {
 	readonly [term]: "var"
-	readonly name: Name
+	readonly owner: MatchOwner & { readonly name: RN }
+	readonly column: K
+	readonly field: F
+	readonly label: string
 }
 
+/** Any query variable, whatever its descriptor and mint coordinate. */
+type AnyVar = Var
+
 /**
  * A scalar query parameter — `r.param("root")`. The name is the key of the
  * typed params object `execute` takes; the type is the element type of the
@@ -86,14 +133,13 @@ interface MaskParam<Name extends string = string> {
 /**
  * The measure of an interval-typed variable (`ir::Term::Measure`):
  * `|[s, e)| = e − s`, u64 — legal as one side of an order comparison, as a
- * select entry, and as the input of `sum`/`min`/`max`; every other position
- * is unwritable, exactly as the IR rejects it typed. A ray has no finite
- * measure — the engine's `MeasureOfRay` execution error; exclude rays first
- * (`allen` against a bounded window).
+ * find entry, and as the input of `sum`/`min`/`max`; every other position
+ * is unwritable, exactly as the IR rejects it typed. Carries the interval
+ * variable it measures BY REFERENCE.
  */
-interface Duration<Name extends string = string> {
+interface Duration<V extends AnyVar = AnyVar> {
 	readonly [term]: "duration"
-	readonly name: Name
+	readonly over: V
 }
 
 /** Any scope term value. */
@@ -104,10 +150,55 @@ function isTerm(value: unknown): value is AnyTerm {
 	return typeof value === "object" && value !== null && term in value
 }
 
-/** Builds one variable term. */
-function makeVar<const Name extends string>(name: Name): Var<Name> {
-	const value: Var<Name> = { [term]: "var", name }
-	return Object.freeze(value)
+/**
+ * The record of fresh variables `v(owner)` mints — one per statically-known
+ * column, each typed by its column's descriptor and mint coordinate.
+ */
+type VarsOf<R extends MatchOwner> = {
+	readonly [K in keyof MatchFields<R> & string]: Var<MatchFields<R>[K], R["name"], K>
+}
+
+/**
+ * The trusted admission seam of the variable-record mint (the pattern's
+ * home is `isTypedScope` in `#query/lower.ts`): the checkable fact — one own
+ * enumerable variable per sealed column — is verified before the record is
+ * admitted at its computed {@link VarsOf} type.
+ */
+function varsMinted<R extends MatchOwner>(owner: R, record: Readonly<Record<string, AnyVar>>): record is VarsOf<R> {
+	return sealedFieldsOf(owner).every(function columnMinted(declared) {
+		return Object.hasOwn(record, declared.name)
+	})
+}
+
+/**
+ * Mints a FRESH batch of query variables over an atom owner's
+ * statically-known columns — one variable per sealed column
+ * (`sealedFieldsOf`: a closed owner mints `id` first, then payload columns),
+ * each frozen and each defined by OWN-property definition (object-protocol
+ * column names must work, the `closed()` precedent). Every `v()` call mints
+ * new objects, so two batches are two variables; property access within one
+ * batch is stable by construction (the record is an eager frozen record,
+ * never a Proxy). Variable identity is the object reference: destructure
+ * what you need (`const { id, holder } = v(Account)`) and reuse a value
+ * across binding positions to join.
+ */
+function v<R extends MatchOwner>(owner: R): VarsOf<R> {
+	const record: Record<string, AnyVar> = {}
+	for (const declared of sealedFieldsOf(owner)) {
+		const variable: AnyVar = Object.freeze({
+			[term]: "var" as const,
+			owner,
+			column: declared.name,
+			field: declared.field,
+			label: `${owner.name}.${declared.name}`
+		})
+		Object.defineProperty(record, declared.name, { value: variable, enumerable: true })
+	}
+	Object.freeze(record)
+	if (!varsMinted(owner, record)) {
+		throw errors.new(`v(${owner.name}): variable-record minting incomplete`)
+	}
+	return record
 }
 
 /** Builds one scalar-parameter term. */
@@ -128,19 +219,17 @@ function makeMaskParam<const Name extends string>(name: Name): MaskParam<Name> {
 	return Object.freeze(value)
 }
 
-/** Builds one measure term over an interval-typed variable's name. */
-function makeDuration<const Name extends string>(name: Name): Duration<Name> {
-	const value: Duration<Name> = { [term]: "duration", name }
+/** Builds one measure term over an interval-typed variable reference. */
+function makeDuration<const V extends AnyVar>(over: V): Duration<V> {
+	const value: Duration<V> = { [term]: "duration", over }
 	return Object.freeze(value)
 }
 
 /**
  * One bound field slot: the field's descriptor plus the slot's
  * law-computed CLASS (`undefined` = bare — the slot is in no law). The one
- * shape the rule environment carries per variable, at the TYPE level (env
- * entries hold the schema type's class-map lookups) and at RUNTIME alike
- * (the rule's `varFields` record holds exactly this shape, read off the
- * schema value's frozen class map) — one shape, two tiers, one walk.
+ * shape every join judgment compares, at the TYPE level (a variable's mint
+ * slot, a binding position's slot) and at RUNTIME alike.
  */
 interface ClassedField {
 	readonly field: AnyField
@@ -148,11 +237,25 @@ interface ClassedField {
 }
 
 /**
- * A rule's typing environment: variable name → the classed slot it first
- * bound. Purely a TYPE — the runtime twin is the rule's `varFields`
- * record, and the two are built by the same walk.
+ * A variable's law-computed CLASS at the TYPE level: its column's class,
+ * read off the schema type's class map through the mint coordinate the
+ * variable carries (`RN.K`). `undefined` = bare.
  */
-type EnvShape = Record<string, ClassedField>
+type MintClassOf<Classes extends SchemaClasses, V> =
+	V extends Var<AnyField, infer RN extends string, infer K extends string>
+		? ClassLookup<ClassRecordOf<Classes, RN>, K>
+		: never
+
+/**
+ * A variable's MINT slot: the descriptor it was minted at plus its
+ * law-computed class. The one slot every binding position judges against —
+ * because {@link JoinOk} is an equality, judging each position against the
+ * mint slot makes every cross-binding join transitively class-equal.
+ */
+type MintSlotOf<Classes extends SchemaClasses, V extends AnyVar> = {
+	readonly field: V["field"]
+	readonly class: MintClassOf<Classes, V>
+}
 
 /** A params object type — what `execute` takes and inference carries. */
 type ParamsRecord = Readonly<Record<string, unknown>>
@@ -177,24 +280,28 @@ type WidthOf<F extends AnyField> = F extends { readonly width: infer W } ? W : u
 /** Reads an interval descriptor's element kind; `undefined` on scalar kinds. */
 type ElementOf<F extends AnyField> = F extends { readonly element: infer E } ? E : undefined
 
-/** Reads a closed reference's handle union; `undefined` on every non-closed kind (the roster IS descriptor structure). */
+/**
+ * Reads a closed reference's vocabulary name literal paired with its handle
+ * union; `undefined` on every non-closed kind (the roster IS descriptor
+ * structure). The name literal is the type-tier encoding of the runtime's
+ * roster VALUE-IDENTITY judgment ({@link fieldJoins}): two same-shaped
+ * vocabularies are distinct rosters, so they mismatch here exactly as they
+ * refuse at runtime.
+ */
 type RosterOf<F extends AnyField> = F extends {
-	readonly closed: { readonly handles: readonly (infer H extends string)[] }
+	readonly closed: { readonly name: infer N extends string; readonly handles: readonly (infer H extends string)[] }
 }
-	? H
+	? readonly [N, H]
 	: undefined
 
 /**
  * The join judgment: two bound slots join iff their descriptors' structure
  * agrees (kind, width label, interval element, and the closed ROSTER — a
  * closed reference pairs only with the same vocabulary, never with a bare
- * u64: the roster keys every closed judgment downstream, so a join across
- * it would decode/order/translate incoherently by binding order) AND their
- * law-computed classes agree — same class name joins, and bare
- * (`undefined`) pairs only with bare (ruling 3: a field in no law has no
- * class; a bare↔classed pairing refuses). The class names come off the
- * SCHEMA type's class map — the statements are the typing; no descriptor
- * label beyond the roster exists to compare.
+ * u64) AND their law-computed classes agree — same class name joins, and
+ * bare (`undefined`) pairs only with bare (ruling 3). The class names come
+ * off the SCHEMA type's class map; no descriptor label beyond the roster
+ * exists to compare.
  */
 type JoinOk<A extends ClassedField, B extends ClassedField> = [
 	A["field"]["kind"],
@@ -218,10 +325,9 @@ type JoinOk<A extends ClassedField, B extends ClassedField> = [
  * The runtime twin of {@link JoinOk}: two bound slots join iff descriptor
  * structure and class agree — the same comparison the type tier makes,
  * judged on the honest runtime values (the descriptor, the roster by VALUE
- * IDENTITY — vocabulary identity is value identity — and the schema
- * value's frozen class map). The rule builders throw through this on a
- * class-unequal variable reuse, so the wall holds for untyped callers too,
- * not only where the compiler can see.
+ * IDENTITY, and the schema value's frozen class map). The rule builders
+ * throw through this on a class-unequal reuse, so the wall holds for untyped
+ * callers too.
  */
 function fieldJoins(a: ClassedField, b: ClassedField): boolean {
 	const widthA = "width" in a.field ? a.field.width : undefined
@@ -242,9 +348,8 @@ function fieldJoins(a: ClassedField, b: ClassedField): boolean {
 /**
  * Renders one bound slot for join-mismatch diagnostics — the structural
  * kind in the schema grammar's spelling (a closed reference names its
- * vocabulary: the roster is part of the structure being compared) plus the
- * slot's law-computed class (`u64 in class Holder.id`; a lawless slot
- * renders `bare`).
+ * vocabulary) plus the slot's law-computed class (`u64 in class Holder.id`;
+ * a lawless slot renders `bare`).
  */
 function renderFieldKind(slot: ClassedField): string {
 	const field = slot.field
@@ -266,11 +371,7 @@ function renderFieldKind(slot: ClassedField): string {
  * What a PARAM anchored at field `F` accepts at execution: the field's
  * bare value type, exactly — at a CLOSED-reference field that is the
  * handle-name union (`"DirectPass" | "Failed"`), translated name → row id
- * at execute through the one roster-verification point
- * (`taggedHandleId`). At an interval field the engine resolves the
- * bivalent anchor to the INTERVAL reading (value equality) — the point
- * reading of a param is spelled `pointIn(r.param(...), w)`, whose sibling
- * anchors it element-typed.
+ * at execute through the one roster-verification point (`taggedHandleId`).
  */
 type ParamValueAt<F extends AnyField> = Infer<F>
 
@@ -281,31 +382,34 @@ type InferredOf<T> = T extends { readonly [inferred]?: infer S } ? Exclude<S, un
  * One registered parameter of a query, as the wire marshal reads it: the
  * name, the wire shape, the field descriptor (or the measure) that anchored
  * it, and the comparison op the anchor came from (`"binding"` for atom
- * positions) — the op keeps literal tagging op-aware at `pointIn`
- * (the bug-hunt fix, preserved). `anchor` is `undefined` only on a query
- * built but not yet anchored by any rule; lowering and the wire both refuse
- * that state typed. `members` is present exactly on a MEMBERSHIP-ARRAY
- * entry (a literal set at a closed field, folded into the program): the
- * SDK itself translates and supplies the set at every execute — the entry
- * is never read from, and never demanded of, the host's params object.
+ * positions). `anchor` is `undefined` only on a query built but not yet
+ * anchored by any rule. `membership` is present exactly on a
+ * MEMBERSHIP-ARRAY entry: the FROZEN wire param, already resolved through
+ * the one roster-verification point at BUILD time (the entry stores the
+ * image, never the pre-image — no per-execute re-translation exists, and an
+ * out-of-roster handle name fails where the mistake was made).
  */
 interface ParamEntry {
 	readonly name: string
 	readonly shape: "value" | "set" | "mask"
 	readonly anchor: AnyField | "measure" | undefined
 	readonly op: "binding" | "eq" | "ne" | "lt" | "le" | "gt" | "ge" | "pointIn" | "allen"
-	readonly members: readonly string[] | undefined
+	readonly membership: QueryParam | undefined
 }
 
 export type {
 	AnyTerm,
+	AnyVar,
 	ClassedField,
 	Duration,
-	EnvShape,
 	Flatten,
 	InferredOf,
 	JoinOk,
 	MaskParam,
+	MatchFields,
+	MatchOwner,
+	MintClassOf,
+	MintSlotOf,
 	Param,
 	ParamEntry,
 	ParamsRecord,
@@ -313,17 +417,7 @@ export type {
 	SetParam,
 	ShapeOf,
 	UnionToIntersection,
-	Var
-}
-export {
-	fieldJoins,
-	inferred,
-	isTerm,
-	makeDuration,
-	makeMaskParam,
-	makeParam,
-	makeSetParam,
-	makeVar,
-	renderFieldKind,
-	term
+	Var,
+	VarsOf
 }
+export { fieldJoins, inferred, isTerm, makeDuration, makeMaskParam, makeParam, makeSetParam, renderFieldKind, term, v }

package/src/relation.ts

@@ -14,7 +14,7 @@
  */
 
 import * as errors from "@superbuilders/errors"
-import { type AnyField, assertDeclarationOrderKey, type Infer, literalOf } from "#fields.ts"
+import { type AnyField, assertDeclarationOrderKey, assertDeclarationRecord, type Infer, literalOf } from "#fields.ts"
 import { type LiteralSetSpec, type LiteralSpec, renderLiteral } from "#spec.ts"
 
 /** Flattens an intersection into one displayed object type (hover legibility). */
@@ -198,6 +198,8 @@ function relation<const Name extends string, Fields extends FieldsShape>(
 	name: Name,
 	fields: Fields
 ): Relation<Name, Fields> {
+	assertDeclarationOrderKey("relation", name)
+	assertDeclarationRecord(`relation ${name} fields`, fields)
 	const ordered: RelationField[] = []
 	for (const [fieldName, field] of Object.entries(fields)) {
 		assertDeclarationOrderKey(`relation ${name} field`, fieldName)