@bjornpagen/bumbledb 0.3.0 → 0.5.0

package/dist/query/lower.js

@@ -25,14 +25,14 @@
  * pre-checked here.
  */
 import * as errors from "@superbuilders/errors";
-import { assertDeclarationOrderKey } from "#fields.ts";
-import { allen, and, covers, eq, ge, gt, le, lt, ne, not, or, pointIn } from "#query/atom.ts";
-import { fieldJoins, inferred, isTerm, makeDuration, makeMaskParam, makeParam, makeSetParam, makeVar, makeVars, renderFieldKind, term } from "#query/scope.ts";
+import { sealedFieldsOf } from "#closed.ts";
+import { assertDeclarationOrderKey, isIntervalValue, literalShapeError, rosterOf } from "#fields.ts";
+import { allen, and, eq, ge, gt, le, lt, ne, not, or, pointIn } from "#query/atom.ts";
+import { fieldJoins, inferred, isTerm, makeDuration, makeMaskParam, makeParam, makeSetParam, makeVar, renderFieldKind, term } from "#query/scope.ts";
 import { argMax, argMin, count, countDistinct, max, min, pack, sum } from "#query/select.ts";
 /** The frozen constructor vocabulary every rule builder spreads. */
 const termOps = Object.freeze({
     var: makeVar,
-    vars: makeVars,
     param: makeParam,
     inSet: makeSetParam,
     maskParam: makeMaskParam,
@@ -44,7 +44,6 @@ const termOps = Object.freeze({
     gt,
     ge,
     pointIn,
-    covers,
     allen,
     and,
     or,
@@ -65,19 +64,44 @@ const EMPTY_RULE = Object.freeze({
     paramUses: Object.freeze([])
 });
 /**
- * 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) {
-    if ("axioms" in owner) {
-        return [Object.freeze({ name: "id", field: owner.id }), ...owner.data.columns];
+function membershipSet(context, field, value) {
+    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();
+    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) };
 }
 /**
  * Resolves a bindings record against an atom owner's matchable fields (a
@@ -93,7 +117,7 @@ function resolveBindings(context, relation, bindings, classes) {
     const vars = [];
     const uses = [];
     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;
@@ -115,12 +139,24 @@ function resolveBindings(context, relation, bindings, classes) {
                 }
                 case "param": {
                     bound = Object.freeze({ kind: "param", name: value.name });
-                    uses.push(Object.freeze({ name: value.name, shape: "value", anchor: declared.field, op: "binding" }));
+                    uses.push(Object.freeze({
+                        name: value.name,
+                        shape: "value",
+                        anchor: declared.field,
+                        op: "binding",
+                        members: undefined
+                    }));
                     break;
                 }
                 case "setParam": {
                     bound = Object.freeze({ kind: "setParam", name: value.name });
-                    uses.push(Object.freeze({ name: value.name, shape: "set", anchor: declared.field, op: "binding" }));
+                    uses.push(Object.freeze({
+                        name: value.name,
+                        shape: "set",
+                        anchor: declared.field,
+                        op: "binding",
+                        members: undefined
+                    }));
                     break;
                 }
                 case "maskParam":
@@ -129,6 +165,17 @@ function resolveBindings(context, relation, bindings, classes) {
                     throw errors.new(`${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", name: set.name, members: set.members });
+            uses.push(Object.freeze({
+                name: set.name,
+                shape: "set",
+                anchor: declared.field,
+                op: "binding",
+                members: set.members
+            }));
+        }
         else {
             bound = Object.freeze({ kind: "literal", value });
         }
@@ -207,7 +254,8 @@ function sideUses(op, side, sibling, varFields, uses) {
         name: side.name,
         shape: side.kind === "param" ? "value" : "set",
         anchor,
-        op
+        op,
+        members: undefined
     }));
 }
 /** Lowers one condition VALUE to its runtime data, recording param uses. */
@@ -225,7 +273,13 @@ function condDataOf(cond, varFields, uses) {
             }
             else if (isTerm(maskValue) && maskValue[term] === "maskParam") {
                 mask = Object.freeze({ kind: "param", name: maskValue.name });
-                uses.push(Object.freeze({ name: maskValue.name, shape: "mask", anchor: undefined, op: "allen" }));
+                uses.push(Object.freeze({
+                    name: maskValue.name,
+                    shape: "mask",
+                    anchor: undefined,
+                    op: "allen",
+                    members: undefined
+                }));
             }
             else {
                 throw errors.new("allen: the mask position takes a 13-bit mask number or a maskParam");
@@ -286,14 +340,27 @@ function advanceIdb(state, rec, vars) {
 function isAggregateEntry(value) {
     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) {
     if (typeof entry === "string") {
-        return Object.freeze({ name: entry, entry: Object.freeze({ kind: "var", over: entry }) });
+        return Object.freeze({
+            name: entry,
+            entry: Object.freeze({ kind: "var", over: entry }),
+            closed: undefined
+        });
     }
     if (isTerm(entry)) {
         if (entry[term] === "duration") {
-            return Object.freeze({ name: entry.name, entry: Object.freeze({ kind: "measure", over: entry.name }) });
+            return Object.freeze({
+                name: entry.name,
+                entry: Object.freeze({ kind: "measure", over: entry.name }),
+                closed: undefined
+            });
         }
         throw errors.new(`query select: a ${entry[term]} is not projectable — select takes variable names, duration(v), or aggregates`);
     }
@@ -305,7 +372,11 @@ function selectColumnOf(entry) {
 /** Classifies one aggregate select entry. */
 function aggregateColumnOf(entry) {
     function column(name, agg) {
-        return Object.freeze({ name, entry: Object.freeze({ kind: "aggregate", agg: Object.freeze(agg) }) });
+        return Object.freeze({
+            name,
+            entry: Object.freeze({ kind: "aggregate", agg: Object.freeze(agg) }),
+            closed: undefined
+        });
     }
     const over = entry.over;
     switch (entry.agg) {
@@ -345,6 +416,22 @@ function aggregateColumnOf(entry) {
             throw errors.new(`unknown aggregate ${entry.agg}`);
     }
 }
+/**
+ * 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, position, vocabulary) {
+    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) {
+    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, varFields, name) {
     const slot = varFields[name];
@@ -373,7 +460,11 @@ function validateCond(context, varFields, cond) {
     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);
@@ -412,21 +503,56 @@ function validateColumn(context, varFields, column) {
             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, entry) {
+    let over;
+    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
@@ -485,7 +611,13 @@ function completeRule(context, state, columns) {
     }
     return Object.freeze({
         items: state.items,
-        select: Object.freeze([...columns]),
+        select: Object.freeze(columns.map(function enrichColumn(column) {
+            return Object.freeze({
+                name: column.name,
+                entry: column.entry,
+                closed: selectClosedOf(state.varFields, column.entry)
+            });
+        })),
         varFields: state.varFields,
         paramUses: state.paramUses
     });
@@ -561,10 +693,12 @@ function makeRawScope(context) {
     return scope;
 }
 /**
- * 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.
@@ -588,6 +722,10 @@ function makeOutputRuleScope(program) {
     }
     return raw;
 }
+/** Renders one head column's closed slice for the rule-alignment check's diagnostics. */
+function renderClosedSlice(closed) {
+    return closed === undefined ? "a bare value" : `a ${closed.name} reference`;
+}
 /** Renders one head column's signature for the rule-alignment check. */
 function headSignature(column) {
     const entry = column.entry;
@@ -603,11 +741,48 @@ function headSignature(column) {
     }
     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, column) {
+    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) {
+    return anchor === "measure" ? undefined : rosterOf(anchor);
+}
+/** Renders one param anchor's closedness for the registry's coherence diagnostics. */
+function renderParamAnchor(roster) {
+    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, rules) {
     const order = [];
@@ -617,16 +792,35 @@ function paramRegistryOf(recs, rules) {
             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) {
@@ -642,7 +836,11 @@ function paramRegistryOf(recs, rules) {
         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 });
     }));
 }
 /**
@@ -662,6 +860,32 @@ function makeRawQuery(theory, recs, rules) {
         if (candidate !== signature) {
             throw errors.new(`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 = Object.freeze({
         recs: Object.freeze([...recs]),
@@ -681,7 +905,7 @@ function makeRawQuery(theory, recs, rules) {
     return value;
 }
 /**
- * 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.
  */
@@ -713,33 +937,25 @@ function query(theory) {
     Object.freeze(start);
     return start;
 }
-/** The typed shape refusal of the literal tagger — a genuine failure, never data. */
-function literalShapeError(context, expected, value) {
-    return errors.new(`${context}: expected ${expected}, got ${typeof value}`);
-}
-/** Narrows an interval-shaped literal (a plain `{ start, end }` bigint pair). */
-function isIntervalShaped(value) {
-    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, closed, value) {
-    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) {
-        throw errors.new(`${context}: closed relation ${closed.name} has no handle with id ${value} (roster holds ${closed.handles.length})`);
+    const id = closed.handles.indexOf(value);
+    if (id < 0) {
+        throw errors.new(`${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) };
 }
 /**
  * Tags one literal in an interval element domain: a bigint tags as the
@@ -753,7 +969,7 @@ function taggedAtElementDomain(context, element, value) {
         }
         return { kind: "i64", value };
     }
-    if (isIntervalShaped(value)) {
+    if (isIntervalValue(value)) {
         if (element === "u64") {
             return { kind: "intervalU64", start: value.start, end: value.end };
         }
@@ -770,8 +986,9 @@ function taggedAtElementDomain(context, element, value) {
  * tagged u64 after a roster verification.
  */
 function taggedLiteral(context, field, value) {
-    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": {
@@ -796,6 +1013,18 @@ function taggedLiteral(context, field, value) {
             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": {
@@ -812,11 +1041,11 @@ function taggedLiteral(context, field, value) {
  * 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).
@@ -828,13 +1057,13 @@ function taggedCmpLiteral(context, sibling, value, op) {
         }
         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);
     }
     return taggedLiteral(context, sibling, value);
@@ -866,7 +1095,7 @@ function paramIdOf(ctx, name) {
  * 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, atom, ids) {
@@ -878,7 +1107,7 @@ function lowerAtom(ctx, atom, ids) {
     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 = atom.bindings.map(function lowerBinding(binding) {
         const ordinal = ordered.findIndex(function byName(candidate) {
             return candidate.name === binding.field;
@@ -890,7 +1119,12 @@ function lowerAtom(ctx, atom, ids) {
     });
     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, context, binding, ids) {
     const bound = binding.term;
     switch (bound.kind) {
@@ -900,6 +1134,8 @@ function lowerBindingTerm(ctx, context, binding, ids) {
             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) };
     }