@bjornpagen/bumbledb 0.3.0 → 0.5.0

package/src/query/lower.ts

@@ -26,8 +26,9 @@
  */
 
 import * as errors from "@superbuilders/errors"
-import type { AnyField } from "#fields.ts"
-import { assertDeclarationOrderKey } from "#fields.ts"
+import { sealedFieldsOf } from "#closed.ts"
+import type { AnyField, ClosedRoster } from "#fields.ts"
+import { assertDeclarationOrderKey, isIntervalValue, literalShapeError, rosterOf } from "#fields.ts"
 import type { ClassRecordOf, SchemaClasses } from "#law.ts"
 import type {
 	AtomIr,
@@ -68,7 +69,7 @@ import type {
 	SelectEntryData,
 	TreeData
 } from "#query/atom.ts"
-import { allen, and, covers, eq, ge, gt, le, lt, ne, not, or, pointIn } from "#query/atom.ts"
+import { allen, and, eq, ge, gt, le, lt, ne, not, or, pointIn } from "#query/atom.ts"
 import type {
 	ClassedField,
 	EnvShape,
@@ -88,13 +89,12 @@ import {
 	makeParam,
 	makeSetParam,
 	makeVar,
-	makeVars,
 	renderFieldKind,
 	term
 } from "#query/scope.ts"
 import type { CheckNameSelect, CheckSelect, RowOfNameSelect, RowOfSelect, SelectEntry } from "#query/select.ts"
 import { argMax, argMin, count, countDistinct, max, min, pack, sum } from "#query/select.ts"
-import type { FieldsShape, RelationField } from "#relation.ts"
+import type { FieldsShape } from "#relation.ts"
 import type { AnySchema, Schema, SchemaRelations } from "#schema.ts"
 
 /**
@@ -198,8 +198,6 @@ type CheckIdbVars<Env extends EnvShape, V, Head extends HeadShape = undefined> =
 interface TermOps {
 	/** Declares/names one variable: typed by the field it first binds; reuse joins. */
 	readonly var: typeof makeVar
-	/** Mints several variables at once — `const { service, w } = r.vars("service", "w")`: each name typed exactly; duplicates refuse. */
-	readonly vars: typeof makeVars
 	/** Names one scalar parameter: typed by its use; the key of the execute params object. */
 	readonly param: typeof makeParam
 	/** Names one ∈-set parameter (the IR's `ParamSet`): bound to a readonly array at execution. */
@@ -215,7 +213,6 @@ interface TermOps {
 	readonly gt: typeof gt
 	readonly ge: typeof ge
 	readonly pointIn: typeof pointIn
-	readonly covers: typeof covers
 	readonly allen: typeof allen
 	readonly and: typeof and
 	readonly or: typeof or
@@ -431,7 +428,6 @@ interface QueryStart<Rels extends SchemaRelations, Classes extends SchemaClasses
 /** The frozen constructor vocabulary every rule builder spreads. */
 const termOps: TermOps = Object.freeze({
 	var: makeVar,
-	vars: makeVars,
 	param: makeParam,
 	inSet: makeSetParam,
 	maskParam: makeMaskParam,
@@ -443,7 +439,6 @@ const termOps: TermOps = Object.freeze({
 	gt,
 	ge,
 	pointIn,
-	covers,
 	allen,
 	and,
 	or,
@@ -480,19 +475,54 @@ interface ResolvedBindings {
 }
 
 /**
- * The ordered matchable fields of an atom owner — the runtime twin of the
- * type tier's `MatchFields`: a relation's declared fields; a closed
- * relation's SEALED shape, the synthetic `id` (the value's own
- * roster-carrying descriptor, by identity) at ordinal 0 and the declared
- * payload columns at declared index + 1 (the sealed shift, mirroring
- * `spec.rs`'s resolver — a `ClosedColumn` is structurally a
- * {@link RelationField}). The lowering golden pins this mapping.
+ * Judges one membership ARRAY at a binding position — legal exactly at a
+ * CLOSED-reference field (the owner ruling: ordinary u64/str membership is
+ * spelled through `r.inSet` params; literal arrays are the closed
+ * vocabulary's spelling), holding ≥ 2 DISTINCT handle names (the
+ * degenerate sets are refusals: empty selects nothing, one element is the
+ * bare literal respelled, and a duplicate member is the same respelling in
+ * disguise — write each member once). The returned name is
+ * CONTENT-ADDRESSED (vocabulary + the member SET — the key sorts a copy,
+ * so two spellings of one set, reordered or not, share one dense
+ * `ParamId`); the members are shape-checked strings here and
+ * roster-verified at the one verification point (`taggedHandleId`) when
+ * the SDK supplies the set at execute — the same moment a bound `r.inSet`
+ * param's members are judged.
  */
-function matchFieldsOf(owner: MatchOwner): readonly RelationField[] {
-	if ("axioms" in owner) {
-		return [Object.freeze({ name: "id", field: owner.id }), ...owner.data.columns]
+function membershipSet(
+	context: string,
+	field: AnyField,
+	value: readonly unknown[]
+): { readonly name: string; readonly members: readonly string[] } {
+	const roster = rosterOf(field)
+	if (roster === undefined) {
+		throw errors.new(
+			`${context}: a membership array is the closed-reference spelling — ordinary field membership is a bound ∈-set param (r.inSet)`
+		)
 	}
-	return owner.data.fields
+	if (value.length === 0) {
+		throw errors.new(`${context}: an empty membership array selects nothing — write the query you mean`)
+	}
+	if (value.length === 1) {
+		throw errors.new(
+			`${context}: a one-element membership array is the bare literal respelled — write the literal (the canonical-utterance law: one meaning, one spelling)`
+		)
+	}
+	const seen = new Set<string>()
+	const members = value.map(function memberName(member) {
+		if (typeof member !== "string") {
+			throw literalShapeError(context, `a ${roster.name} handle name (string)`, member)
+		}
+		if (seen.has(member)) {
+			throw errors.new(
+				`${context}: the membership array spells ${member} twice — write it once (the canonical-utterance law: one meaning, one spelling)`
+			)
+		}
+		seen.add(member)
+		return member
+	})
+	const key = [...members].sort()
+	return { name: `∈ ${roster.name} ${JSON.stringify(key)}`, members: Object.freeze(members) }
 }
 
 /**
@@ -514,7 +544,7 @@ function resolveBindings(
 	const vars: Array<{ readonly name: string; readonly slot: ClassedField }> = []
 	const uses: ParamUse[] = []
 	const relationClasses = classes[relation.name]
-	const ordered = matchFieldsOf(relation)
+	const ordered = sealedFieldsOf(relation)
 	for (const [fieldName, value] of Object.entries(bindings)) {
 		if (value === undefined) {
 			continue
@@ -539,14 +569,26 @@ function resolveBindings(
 				case "param": {
 					bound = Object.freeze({ kind: "param" as const, name: value.name })
 					uses.push(
-						Object.freeze({ name: value.name, shape: "value" as const, anchor: declared.field, op: "binding" as const })
+						Object.freeze({
+							name: value.name,
+							shape: "value" as const,
+							anchor: declared.field,
+							op: "binding" as const,
+							members: undefined
+						})
 					)
 					break
 				}
 				case "setParam": {
 					bound = Object.freeze({ kind: "setParam" as const, name: value.name })
 					uses.push(
-						Object.freeze({ name: value.name, shape: "set" as const, anchor: declared.field, op: "binding" as const })
+						Object.freeze({
+							name: value.name,
+							shape: "set" as const,
+							anchor: declared.field,
+							op: "binding" as const,
+							members: undefined
+						})
 					)
 					break
 				}
@@ -559,6 +601,18 @@ function resolveBindings(
 						`${context}.${fieldName}: the measure is not a field-typed value — it lives in comparisons and select entries`
 					)
 			}
+		} else if (Array.isArray(value)) {
+			const set = membershipSet(`${context}.${fieldName}`, declared.field, value)
+			bound = Object.freeze({ kind: "literalSet" as const, name: set.name, members: set.members })
+			uses.push(
+				Object.freeze({
+					name: set.name,
+					shape: "set" as const,
+					anchor: declared.field,
+					op: "binding" as const,
+					members: set.members
+				})
+			)
 		} else {
 			bound = Object.freeze({ kind: "literal" as const, value })
 		}
@@ -651,7 +705,8 @@ function sideUses(
 			name: side.name,
 			shape: side.kind === "param" ? ("value" as const) : ("set" as const),
 			anchor,
-			op
+			op,
+			members: undefined
 		})
 	)
 }
@@ -671,7 +726,13 @@ function condDataOf(cond: AnyCond, varFields: Readonly<Record<string, ClassedFie
 			} else if (isTerm(maskValue) && maskValue[term] === "maskParam") {
 				mask = Object.freeze({ kind: "param" as const, name: maskValue.name })
 				uses.push(
-					Object.freeze({ name: maskValue.name, shape: "mask" as const, anchor: undefined, op: "allen" as const })
+					Object.freeze({
+						name: maskValue.name,
+						shape: "mask" as const,
+						anchor: undefined,
+						op: "allen" as const,
+						members: undefined
+					})
 				)
 			} else {
 				throw errors.new("allen: the mask position takes a 13-bit mask number or a maskParam")
@@ -742,14 +803,27 @@ function isAggregateEntry(
 	return typeof value === "object" && value !== null && "agg" in value
 }
 
-/** Classifies one select entry into its named answer column. */
+/**
+ * Classifies one select entry into its named answer column. The `closed`
+ * slice is resolved LATER, at rule completion (`completeRule`), where the
+ * rule's `varFields` are in hand — until then every column is provisionally
+ * bare.
+ */
 function selectColumnOf(entry: unknown): SelectColumn {
 	if (typeof entry === "string") {
-		return Object.freeze({ name: entry, entry: Object.freeze({ kind: "var" as const, over: entry }) })
+		return Object.freeze({
+			name: entry,
+			entry: Object.freeze({ kind: "var" as const, over: entry }),
+			closed: undefined
+		})
 	}
 	if (isTerm(entry)) {
 		if (entry[term] === "duration") {
-			return Object.freeze({ name: entry.name, entry: Object.freeze({ kind: "measure" as const, over: entry.name }) })
+			return Object.freeze({
+				name: entry.name,
+				entry: Object.freeze({ kind: "measure" as const, over: entry.name }),
+				closed: undefined
+			})
 		}
 		throw errors.new(
 			`query select: a ${entry[term]} is not projectable — select takes variable names, duration(v), or aggregates`
@@ -768,7 +842,11 @@ function aggregateColumnOf(entry: {
 	readonly key: unknown
 }): SelectColumn {
 	function column(name: string, agg: AggData): SelectColumn {
-		return Object.freeze({ name, entry: Object.freeze({ kind: "aggregate" as const, agg: Object.freeze(agg) }) })
+		return Object.freeze({
+			name,
+			entry: Object.freeze({ kind: "aggregate" as const, agg: Object.freeze(agg) }),
+			closed: undefined
+		})
 	}
 	const over = entry.over
 	switch (entry.agg) {
@@ -809,6 +887,26 @@ function aggregateColumnOf(entry: {
 	}
 }
 
+/**
+ * The orderable ban's pointed refusal (`docs/architecture/10-data-model.md`
+ * § orderability): a closed reference is equality-and-membership only —
+ * its declaration-id order is an encoding accident, so every
+ * order-comparison and fold position refuses it. The construction-time
+ * twin of the type tier's `OrderVarOk` exclusion, so the wall holds for
+ * untyped callers too (the engine cannot backstop this one: the wire IR
+ * carries plain u64s, no rosters).
+ */
+function closedOrderError(context: string, position: string, vocabulary: string): Error {
+	return errors.new(
+		`${context}: ${position} is a ${vocabulary} reference — declaration order is an accident, not semantics: vocabularies do not order (docs/architecture/10-data-model.md; equality, membership, and counting remain)`
+	)
+}
+
+/** The comparison ops under the orderable ban (order roster + point membership — every order-comparison position). */
+function isOrderOp(op: CmpKind | "binding"): op is "lt" | "le" | "gt" | "ge" | "pointIn" {
+	return op === "lt" || op === "le" || op === "gt" || op === "ge" || op === "pointIn"
+}
+
 /** Requires a var name to be bound by a relation atom of the rule. */
 function assertBound(context: string, varFields: Readonly<Record<string, ClassedField>>, name: string): ClassedField {
 	const slot = varFields[name]
@@ -841,7 +939,11 @@ function validateCond(context: string, varFields: Readonly<Record<string, Classe
 	if (cond.kind === "cmp") {
 		for (const side of [cond.lhs, cond.rhs]) {
 			if (side.kind === "var") {
-				assertBound(context, varFields, side.name)
+				const slot = assertBound(context, varFields, side.name)
+				const roster = rosterOf(slot.field)
+				if (isOrderOp(cond.op) && roster !== undefined) {
+					throw closedOrderError(context, `the ${cond.op} side ${side.name}`, roster.name)
+				}
 			}
 			if (side.kind === "measure") {
 				assertIntervalBound(context, varFields, side.name)
@@ -887,22 +989,63 @@ function validateColumn(
 			return
 		case "fold": {
 			if (typeof agg.over === "string") {
-				assertBound(`${context} select ${column.name}`, varFields, agg.over)
+				const slot = assertBound(`${context} select ${column.name}`, varFields, agg.over)
+				const roster = rosterOf(slot.field)
+				if (roster !== undefined) {
+					throw closedOrderError(`${context} select ${column.name}`, `the ${agg.fold} input ${agg.over}`, roster.name)
+				}
 				return
 			}
 			assertIntervalBound(`${context} select ${column.name}`, varFields, agg.over.duration)
 			return
 		}
-		case "arg":
+		case "arg": {
 			assertBound(`${context} select ${column.name}`, varFields, agg.over)
-			assertBound(`${context} select ${column.name}`, varFields, agg.key)
+			const key = assertBound(`${context} select ${column.name}`, varFields, agg.key)
+			const keyRoster = rosterOf(key.field)
+			if (keyRoster !== undefined) {
+				throw closedOrderError(
+					`${context} select ${column.name}`,
+					`the ${agg.direction} key ${agg.key}`,
+					keyRoster.name
+				)
+			}
 			return
+		}
 		case "pack":
 			assertIntervalBound(`${context} select ${column.name}`, varFields, agg.over)
 			return
 	}
 }
 
+/**
+ * Resolves the roster one select column decodes through: a projected var,
+ * or an Arg-carried payload, bound at a closed-referencing field carries
+ * that field's roster (read off `varFields` — the same slot the domain
+ * machinery reads), and `decodeAnswers` lifts the column's row ids back to
+ * handle NAMES through it — the runtime twin of the row type's `Infer`
+ * claim. Every other entry decodes bare: counts are counts, the measure
+ * and `pack` are never closed, and a closed FOLD is banned outright
+ * ({@link closedOrderError}) before this resolution runs.
+ */
+function selectClosedOf(
+	varFields: Readonly<Record<string, ClassedField>>,
+	entry: SelectEntryData
+): ClosedRoster | undefined {
+	let over: string | undefined
+	if (entry.kind === "var") {
+		over = entry.over
+	} else if (entry.kind === "aggregate" && entry.agg.op === "arg") {
+		over = entry.agg.over
+	} else {
+		over = undefined
+	}
+	if (over === undefined) {
+		return undefined
+	}
+	return rosterOf(varFields[over]?.field)
+}
+
 /**
  * Completes one rule: classifies the select record (written order = answer
  * column order, names must be declaration-order-safe keys), and validates
@@ -969,7 +1112,15 @@ function completeRule(context: string, state: RuleBuildState, columns: readonly
 	}
 	return Object.freeze({
 		items: state.items,
-		select: Object.freeze([...columns]),
+		select: Object.freeze(
+			columns.map(function enrichColumn(column): SelectColumn {
+				return Object.freeze({
+					name: column.name,
+					entry: column.entry,
+					closed: selectClosedOf(state.varFields, column.entry)
+				})
+			})
+		),
 		varFields: state.varFields,
 		paramUses: state.paramUses
 	})
@@ -1091,10 +1242,12 @@ function makeRawScope(context: ChainContext): RawScope {
 }
 
 /**
- * The one trusted admission seam of the rule builders (the `relation()`
- * `refsComplete` pattern): the raw builder is one runtime shape for every
- * context, and this guard verifies the checkable fact — the builder verbs
- * exist — before the value is admitted at its TYPED face. The type-level
+ * The rule builders' trusted admission seam — THE home of the
+ * trusted-admission-seam pattern the other mint guards cite (the face,
+ * class-map, axiom-readback, rec-handle, and query-value seams): the raw
+ * builder is one runtime shape for every context, and this guard verifies
+ * the checkable fact — the builder verbs exist — before the value is
+ * admitted at its TYPED face. The type-level
  * judgments (domain-equal joins, boundness, the recursion cut) live in the
  * interfaces themselves; the runtime twin of every one of them is a
  * construction-time validation in this module.
@@ -1132,6 +1285,11 @@ interface ProgramState {
 	sealed: boolean
 }
 
+/** Renders one head column's closed slice for the rule-alignment check's diagnostics. */
+function renderClosedSlice(closed: ClosedRoster | undefined): string {
+	return closed === undefined ? "a bare value" : `a ${closed.name} reference`
+}
+
 /** Renders one head column's signature for the rule-alignment check. */
 function headSignature(column: SelectColumn): string {
 	const entry = column.entry
@@ -1148,32 +1306,104 @@ function headSignature(column: SelectColumn): string {
 	return `${column.name}:${agg.op}`
 }
 
+/**
+ * The classed slot one answer column's VALUES flow from, resolved through
+ * the rule's own binding environment: a projected var's first-binding slot,
+ * or an Arg-carried payload's (`argMax`/`argMin` carry `over` verbatim —
+ * the same two shapes the closed slice lifts). Counts, folds, `pack` and
+ * the measure derive numbers/intervals rather than carrying a slot's ids,
+ * so they resolve no slot (`undefined`).
+ */
+function headSlotOf(rule: RuleData, column: SelectColumn): ClassedField | undefined {
+	const entry = column.entry
+	if (entry.kind === "var") {
+		return rule.varFields[entry.over]
+	}
+	if (entry.kind === "aggregate" && entry.agg.op === "arg") {
+		return rule.varFields[entry.agg.over]
+	}
+	return undefined
+}
+
+/** The roster a param anchor carries: present exactly on a closed-reference field anchor (rides THE one `rosterOf` reader). */
+function anchorRosterOf(anchor: AnyField | "measure" | undefined): ClosedRoster | undefined {
+	return anchor === "measure" ? undefined : rosterOf(anchor)
+}
+
+/** Renders one param anchor's closedness for the registry's coherence diagnostics. */
+function renderParamAnchor(roster: ClosedRoster | undefined): string {
+	return roster === undefined ? "a non-closed position" : `a ${roster.name} reference`
+}
+
 /**
  * Folds every rule's param uses (recs in declaration order first, output
  * rules last — exactly the lowering walk) into the query's registry:
  * first use mints the dense `ParamId`, the first FIELD-ANCHORED use types
- * the wire, and one name must keep one shape.
+ * the wire, and one name must keep one shape AND one closedness — every
+ * anchored use of one name must agree on the roster (value identity), so a
+ * param anchored at a closed reference is GUARANTEED to ride the one
+ * roster-verification point (`taggedHandleId`) at execute; a name anchored
+ * both at a closed reference and at a non-closed position (or at two
+ * vocabularies) is refused here, because the wire would translate only the
+ * first anchor's reading (the type tier intersects the uses to `never`;
+ * this is its runtime twin for untyped callers). A param whose anchor is a
+ * CLOSED reference must never sit in an order-comparison position — the
+ * anchor types its value a handle name and the engine would order the
+ * translated row ids, so the pairing is refused here too (the registry is
+ * the one place a name's every use and its anchoring field meet).
  */
 function paramRegistryOf(recs: readonly RecData[], rules: readonly RuleData[]): readonly ParamEntry[] {
 	const order: string[] = []
-	const byName = new Map<string, { shape: ParamEntry["shape"]; anchor: ParamEntry["anchor"]; op: ParamEntry["op"] }>()
+	const byName = new Map<
+		string,
+		{
+			shape: ParamEntry["shape"]
+			anchor: ParamEntry["anchor"]
+			op: ParamEntry["op"]
+			members: ParamEntry["members"]
+			orderOp: "lt" | "le" | "gt" | "ge" | "pointIn" | undefined
+		}
+	>()
 	function fold(uses: readonly ParamUse[]): void {
 		for (const use of uses) {
 			const existing = byName.get(use.name)
 			if (existing === undefined) {
 				order.push(use.name)
-				byName.set(use.name, { shape: use.shape, anchor: use.anchor, op: use.op })
+				byName.set(use.name, {
+					shape: use.shape,
+					anchor: use.anchor,
+					op: use.op,
+					members: use.members,
+					orderOp: isOrderOp(use.op) ? use.op : undefined
+				})
 				continue
 			}
+			if ((existing.members === undefined) !== (use.members === undefined)) {
+				throw errors.new(
+					`query param ${use.name} collides with a membership array's registry entry — name the param differently`
+				)
+			}
 			if (existing.shape !== use.shape) {
 				throw errors.new(
 					`query param ${use.name} is used both as a ${existing.shape} param and a ${use.shape} param — one name, one shape`
 				)
 			}
+			if (existing.anchor !== undefined && use.anchor !== undefined) {
+				const registered = anchorRosterOf(existing.anchor)
+				const anchored = anchorRosterOf(use.anchor)
+				if (registered !== anchored) {
+					throw errors.new(
+						`query param ${use.name} is anchored at ${renderParamAnchor(registered)} and at ${renderParamAnchor(anchored)} — a closed-anchored param translates handle names through ONE roster (one name, one domain); name the params differently`
+					)
+				}
+			}
 			if (existing.anchor === undefined && use.anchor !== undefined) {
 				existing.anchor = use.anchor
 				existing.op = use.op
 			}
+			if (existing.orderOp === undefined && isOrderOp(use.op)) {
+				existing.orderOp = use.op
+			}
 		}
 	}
 	for (const rec of recs) {
@@ -1190,7 +1420,11 @@ function paramRegistryOf(recs: readonly RecData[], rules: readonly RuleData[]):
 			if (entry === undefined) {
 				throw errors.new(`query param ${name} lost its registry entry`)
 			}
-			return Object.freeze({ name, shape: entry.shape, anchor: entry.anchor, op: entry.op })
+			const anchorRoster = anchorRosterOf(entry.anchor)
+			if (entry.orderOp !== undefined && anchorRoster !== undefined) {
+				throw closedOrderError(`query param ${name}`, `its ${entry.orderOp} use's anchor`, anchorRoster.name)
+			}
+			return Object.freeze({ name, shape: entry.shape, anchor: entry.anchor, op: entry.op, members: entry.members })
 		})
 	)
 }
@@ -1221,6 +1455,36 @@ function makeRawQuery(theory: AnySchema, recs: readonly RecData[], rules: readon
 				`every rule of a query derives the same head — rule 0 selects (${signature}), rule ${index} selects (${candidate})`
 			)
 		}
+		// The closed slice is part of the head too: one answer column decodes
+		// through one roster, so a union whose rules bind a column at
+		// different vocabularies (or one closed, one bare — the ids would
+		// mistranslate silently) is refused pointed. Vocabulary identity is
+		// value identity, the SDK's membership rule everywhere.
+		rule.select.forEach(function verifyClosedSlice(column, position) {
+			const lead = first.select[position]
+			if (lead !== undefined && column.closed !== lead.closed) {
+				throw errors.new(
+					`every rule of a query derives the same head — the answer column ${lead.name} is ${renderClosedSlice(lead.closed)} in rule 0 but ${renderClosedSlice(column.closed)} in rule ${index} (one column decodes through one roster)`
+				)
+			}
+			// The law-class wall on the union head: one answer column is one
+			// value space, so the classed slot each rule binds the column at
+			// must join across rules — the SAME fieldJoins judgment every
+			// join/eq/negated-atom position enforces. The SDK holds this wall
+			// because the wire IR carries no domains: the engine cannot
+			// backstop it, and without it a union mixes (say) Holder ids and
+			// Account ids in one column the consumer reads as one id space.
+			if (lead === undefined) {
+				return
+			}
+			const leadSlot = headSlotOf(first, lead)
+			const slot = headSlotOf(rule, column)
+			if (leadSlot !== undefined && slot !== undefined && !fieldJoins(leadSlot, slot)) {
+				throw errors.new(
+					`every rule of a query derives the same head — the answer column ${lead.name} unions domain-unequal fields: bound at ${renderFieldKind(leadSlot)} in rule 0 but at ${renderFieldKind(slot)} in rule ${index} (a union column joins only class-equal slots; bare pairs only with bare)`
+				)
+			}
+		})
 	})
 	const data: QueryData = Object.freeze({
 		recs: Object.freeze([...recs]),
@@ -1241,7 +1505,7 @@ function makeRawQuery(theory: AnySchema, recs: readonly RecData[], rules: readon
 }
 
 /**
- * The query values' trusted admission seam (the `refsComplete` pattern):
+ * The query values' trusted admission seam (the {@link isTypedScope} pattern):
  * the checkable fact — the value was assembled over the identical theory —
  * is verified before the raw value is admitted at its typed face.
  */
@@ -1287,43 +1551,31 @@ function query<Rels extends SchemaRelations, Classes extends SchemaClasses>(
 	return start
 }
 
-/** The typed shape refusal of the literal tagger — a genuine failure, never data. */
-function literalShapeError(context: string, expected: string, value: unknown): Error {
-	return errors.new(`${context}: expected ${expected}, got ${typeof value}`)
-}
-
-/** Narrows an interval-shaped literal (a plain `{ start, end }` bigint pair). */
-function isIntervalShaped(value: unknown): value is { readonly start: bigint; readonly end: bigint } {
-	return (
-		typeof value === "object" &&
-		value !== null &&
-		"start" in value &&
-		"end" in value &&
-		typeof value.start === "bigint" &&
-		typeof value.end === "bigint"
-	)
-}
-
 /**
- * Tags one closed-reference literal: the bare handle id, verified against
- * the roster (the belt the type level cannot provide — structural values
- * make any bigint spellable here) and tagged u64 — queries cross ids,
- * never handle names.
+ * Tags one closed-reference literal: the handle NAME, verified against the
+ * roster (the belt the wide fallback type cannot provide — structural
+ * values make any string spellable here) and translated to its
+ * declaration-order row id, tagged u64 — queries cross ids, never handle
+ * names; the wire is untouched. THE single roster-verification point of
+ * the query surface: atom-binding literals, comparison literals,
+ * execute-time params, and membership-array members all reach it (never
+ * duplicate the check per call site).
  */
 function taggedHandleId(
 	context: string,
 	closed: { readonly name: string; readonly handles: readonly string[] },
 	value: unknown
 ): TaggedValue {
-	if (typeof value !== "bigint") {
-		throw literalShapeError(context, `a ${closed.name} handle id (bigint)`, value)
+	if (typeof value !== "string") {
+		throw literalShapeError(context, `a ${closed.name} handle name (string)`, value)
 	}
-	if (closed.handles[Number(value)] === undefined) {
+	const id = closed.handles.indexOf(value)
+	if (id < 0) {
 		throw errors.new(
-			`${context}: closed relation ${closed.name} has no handle with id ${value} (roster holds ${closed.handles.length})`
+			`${context}: "${value}" is not a handle of ${closed.name} — the roster is ${closed.handles.join(", ")}`
 		)
 	}
-	return { kind: "u64", value }
+	return { kind: "u64", value: BigInt(id) }
 }
 
 /**
@@ -1338,7 +1590,7 @@ function taggedAtElementDomain(context: string, element: "u64" | "i64", value: u
 		}
 		return { kind: "i64", value }
 	}
-	if (isIntervalShaped(value)) {
+	if (isIntervalValue(value)) {
 		if (element === "u64") {
 			return { kind: "intervalU64", start: value.start, end: value.end }
 		}
@@ -1356,8 +1608,9 @@ function taggedAtElementDomain(context: string, element: "u64" | "i64", value: u
  * tagged u64 after a roster verification.
  */
 function taggedLiteral(context: string, field: AnyField, value: unknown): TaggedValue {
-	if ("closed" in field) {
-		return taggedHandleId(context, field.closed, value)
+	const roster = rosterOf(field)
+	if (roster !== undefined) {
+		return taggedHandleId(context, roster, value)
 	}
 	switch (field.kind) {
 		case "bool": {
@@ -1382,6 +1635,18 @@ function taggedLiteral(context: string, field: AnyField, value: unknown): Tagged
 			if (typeof value !== "string") {
 				throw literalShapeError(context, "string", value)
 			}
+			/**
+			 * The marshal's bijection law at the query seam (`marshal.ts`
+			 * cellOf): a lone surrogate would be lossily replaced with
+			 * U+FFFD at the bridge's UTF-8 crossing and silently match a
+			 * fact the typed write surface can never store — distinct JS
+			 * strings collapsing to one wire query. This is the single
+			 * seam every query string literal, string param
+			 * (`taggedCmpLiteral`), and membership member lowers through.
+			 */
+			if (!value.isWellFormed()) {
+				throw literalShapeError(context, "well-formed string", value)
+			}
 			return { kind: "string", value }
 		}
 		case "bytes": {
@@ -1399,11 +1664,11 @@ function taggedLiteral(context: string, field: AnyField, value: unknown): Tagged
  * Tags one host literal at a COMPARISON or PARAM position, where the
  * SIBLING anchors the type: a measure sibling is u64, an interval-field
  * sibling contributes its element domain (so both a point literal in
- * `covers` and a `span` literal in `allen` tag correctly), a scalar
+ * `pointIn` and a `span` literal in `allen` tag correctly), a scalar
  * sibling its own type. At `pointIn` the operand order is interval-left,
  * point-right (`ir::CmpOp::PointIn`), so an interval-shaped literal
- * beside a scalar element-typed sibling is the LEGAL lhs of
- * `covers(span(...), t)` and tags as the interval of the sibling's
+ * beside a scalar element-typed sibling is the LEGAL interval operand of
+ * `pointIn(t, span(...))` and tags as the interval of the sibling's
  * element domain; under every other operator an interval shape against a
  * scalar sibling stays refused (the engine's IllegalComparison — the
  * bug-hunt fix, preserved op-aware).
@@ -1420,14 +1685,14 @@ function taggedCmpLiteral(
 		}
 		return { kind: "u64", value }
 	}
-	if (!("closed" in sibling) && sibling.kind === "interval") {
+	if (rosterOf(sibling) === undefined && sibling.kind === "interval") {
 		return taggedAtElementDomain(context, sibling.element, value)
 	}
 	if (
 		op === "pointIn" &&
-		!("closed" in sibling) &&
+		rosterOf(sibling) === undefined &&
 		(sibling.kind === "u64" || sibling.kind === "i64") &&
-		isIntervalShaped(value)
+		isIntervalValue(value)
 	) {
 		return taggedAtElementDomain(context, sibling.kind, value)
 	}
@@ -1477,7 +1742,7 @@ function paramIdOf(ctx: LowerContext, name: string): number {
  * Lowers one EDB atom (either polarity). A CLOSED owner lowers through the
  * same edb source — its ordinal is its record-declaration slot exactly like
  * an ordinary relation's — with field ordinals over the SEALED shape: `id`
- * at 0, each payload column at its declared index + 1 (`matchFieldsOf`
+ * at 0, each payload column at its declared index + 1 (`sealedFieldsOf`
  * carries the shift; the lowering golden pins it).
  */
 function lowerAtom(ctx: LowerContext, atom: AtomData, ids: VarIds): AtomIr {
@@ -1491,7 +1756,7 @@ function lowerAtom(ctx: LowerContext, atom: AtomData, ids: VarIds): AtomIr {
 	if (relationId === undefined) {
 		throw errors.new(`query lowering: relation ${atom.relation.name} has no ordinal`)
 	}
-	const ordered = matchFieldsOf(atom.relation)
+	const ordered = sealedFieldsOf(atom.relation)
 	const bindings: Array<readonly [number, TermIr]> = atom.bindings.map(function lowerBinding(binding) {
 		const ordinal = ordered.findIndex(function byName(candidate) {
 			return candidate.name === binding.field
@@ -1504,7 +1769,12 @@ function lowerAtom(ctx: LowerContext, atom: AtomData, ids: VarIds): AtomIr {
 	return { source: { kind: "edb", relation: relationId }, bindings }
 }
 
-/** Lowers one binding term. */
+/**
+ * Lowers one binding term. A membership ARRAY (`literalSet`) lowers to the
+ * existing param-set term over its content-addressed registry entry — the
+ * program IR is byte-identical to the same set spelled `r.inSet`; the SDK
+ * supplies the translated member set itself at execute (`wireParams`).
+ */
 function lowerBindingTerm(ctx: LowerContext, context: string, binding: BindingEntry, ids: VarIds): TermIr {
 	const bound = binding.term
 	switch (bound.kind) {
@@ -1514,6 +1784,8 @@ function lowerBindingTerm(ctx: LowerContext, context: string, binding: BindingEn
 			return { kind: "param", param: paramIdOf(ctx, bound.name) }
 		case "setParam":
 			return { kind: "paramSet", param: paramIdOf(ctx, bound.name) }
+		case "literalSet":
+			return { kind: "paramSet", param: paramIdOf(ctx, bound.name) }
 		case "literal":
 			return { kind: "literal", value: taggedLiteral(context, binding.data, bound.value) }
 	}