@bjornpagen/bumbledb 0.6.0 → 0.7.0

package/src/query/atom.ts

@@ -41,11 +41,12 @@ import type {
 	MatchOwner,
 	MintSlotOf,
 	Param,
+	ParamsRecord,
 	ParamValueAt,
 	SetParam,
 	ShapeOf
 } from "#query/scope.ts"
-import { isTerm } from "#query/scope.ts"
+import { inferred, isTerm } from "#query/scope.ts"
 import type { FieldsShape } from "#relation.ts"
 
 /**
@@ -154,6 +155,8 @@ type RuleItem =
 			readonly kind: "idb"
 			readonly rec: RecData
 			readonly bindings: ReadonlyArray<{ readonly key: string; readonly ref: AnyVar }>
+			/** `true` on a negated finished-stratum atom (`r.not(rec, {...})`): probed through its anti-probe, binds nothing. */
+			readonly negated: boolean
 	  }
 	| { readonly kind: "cond"; readonly cond: CondData }
 
@@ -282,6 +285,35 @@ interface NotAtom<R extends MatchOwner, B> {
 	readonly bindings: B
 }
 
+/**
+ * A recursive predicate as a NEGATION target — the structural half of the
+ * rec reference (`data` carries rules, never fields, so an EDB or closed
+ * owner can never match it and the `not()` overloads stay disjoint).
+ */
+interface RecTarget {
+	readonly name: string
+	readonly data: RecData
+	readonly [inferred]?: { readonly params: ParamsRecord; readonly head: HeadShapeOf }
+}
+
+/** The head signature a threaded rec target carries (`undefined` before its first rule seals one). */
+type HeadShapeOf = Readonly<Record<string, ClassedField>> | undefined
+
+/**
+ * One negated FINISHED-STRATUM atom — negation OF a lower stratum is
+ * engine-legal (the strata judge refuses only negation *through* a cycle:
+ * a finished set is what keeps the operator monotone), and this value is
+ * its one spelling: `r.not(reach, { c })` in an output rule rejects every
+ * binding the finished stratum extends, through the engine's anti-probe.
+ * Binds nothing, only rejects — every variable it names must be positively
+ * bound in the rule (the same safety rule as EDB negation).
+ */
+interface NotIdbAtom<Target extends RecTarget, B> {
+	readonly cond: "notIdb"
+	readonly target: Target
+	readonly bindings: B
+}
+
 /** Any comparison value. */
 type AnyCmp = Cmp<CmpKind, unknown, unknown, unknown>
 
@@ -291,8 +323,11 @@ type AnyTreeChild = AnyCmp | Tree<readonly AnyTreeChild[]>
 /** Any negated-atom value. */
 type AnyNotAtom = NotAtom<MatchOwner, unknown>
 
-/** Any `.where` input: a comparison, a condition tree, or a negated atom. */
-type AnyCond = AnyCmp | Tree<readonly AnyTreeChild[]> | AnyNotAtom
+/** Any negated finished-stratum value. */
+type AnyNotIdbAtom = NotIdbAtom<RecTarget, unknown>
+
+/** Any `.where` input: a comparison, a condition tree, or a negated atom (EDB, closed, or finished stratum). */
+type AnyCond = AnyCmp | Tree<readonly AnyTreeChild[]> | AnyNotAtom | AnyNotIdbAtom
 
 /** What `eq`'s right side accepts (`ParamSet` is `Eq`-only — the IR's rule). */
 type EqRight = AnyVar | Param<string> | SetParam<string> | bigint | string | boolean | Uint8Array | IntervalValue
@@ -465,14 +500,34 @@ function or<const C extends readonly AnyTreeChild[]>(...children: C): Tree<C> {
  * rejects every binding some matching fact extends. A negated atom binds
  * nothing, only rejects: every variable it names must be positively bound
  * in the rule, a construction-time wall (the engine's safety refusal stands
- * behind it). A CLOSED owner is legal here too.
+ * behind it). A CLOSED owner is legal here too — and so is a FINISHED
+ * STRATUM: `not(reach, { c })` in an output rule negates the rec's
+ * finished set (a named record over its head keys, variables only — the
+ * same wall `idb()` holds), the one spelling of the engine-legal
+ * complement query (`(n) | Node(id: n), !reach(n);` on the Rust surface).
  */
-function not<R extends MatchOwner, const B extends MatchShape<MatchFields<R>>>(
-	relation: R,
+function not<R extends MatchOwner, const B extends MatchShape<MatchFields<R>>>(relation: R, bindings: B): NotAtom<R, B>
+function not<Target extends RecTarget, const B extends Readonly<Record<string, AnyVar>>>(
+	target: Target,
 	bindings: B
-): NotAtom<R, B> {
-	const value: NotAtom<R, B> = { cond: "not", relation, bindings }
-	return Object.freeze(value)
+): NotIdbAtom<Target, B>
+function not(
+	relation: MatchOwner | RecTarget,
+	bindings: Readonly<Record<string, unknown>>
+): NotAtom<MatchOwner, unknown> | NotIdbAtom<RecTarget, unknown> {
+	if (isRecTarget(relation)) {
+		return Object.freeze({ cond: "notIdb" as const, target: relation, bindings })
+	}
+	return Object.freeze({ cond: "not" as const, relation, bindings })
+}
+
+/**
+ * THE negation-target discriminant: a rec's runtime data carries its rules,
+ * a relation's its fields (and a closed relation's its handle roster) — the
+ * shapes are disjoint by construction, so the dispatch is total.
+ */
+function isRecTarget(value: MatchOwner | RecTarget): value is RecTarget {
+	return "rules" in value.data
 }
 
 /**
@@ -532,6 +587,49 @@ type NotOk<Classes extends SchemaClasses, F extends FieldsShape, CR, B> = false
 	? false
 	: true
 
+/** Reads a rec target's sealed head signature off its inference slot (`undefined` on an unthreaded handle). */
+type RecHeadOf<T> = T extends { readonly [inferred]?: infer S }
+	? Exclude<S, undefined> extends { readonly head: infer H }
+		? H
+		: undefined
+	: undefined
+
+/** Reads a rec target's params record off its inference slot. */
+type RecParamsOf<T> = T extends { readonly [inferred]?: infer S }
+	? Exclude<S, undefined> extends { readonly params: infer P }
+		? P
+		: never
+	: never
+
+/** One negated finished-stratum position's judgment: a variable, class-equal to its head slot when the head is carried. */
+type NotIdbBindingOk<Classes extends SchemaClasses, HeadSlot, V> = V extends AnyVar
+	? HeadSlot extends ClassedField
+		? JoinOk<HeadSlot, MintSlotOf<Classes, V>> extends true
+			? true
+			: false
+		: true
+	: false
+
+/**
+ * The whole negated finished-stratum atom's judgment — the negation twin of
+ * the `idb()` chain's `CheckIdbBindings`: when the target carries its head
+ * (a threaded rec handle), the bindings record's key set must EXACTLY equal
+ * the head's and each variable must be class-equal to its head slot; an
+ * unthreaded handle still takes variables only.
+ */
+type NotIdbOk<Classes extends SchemaClasses, Head, B> =
+	Head extends Readonly<Record<string, ClassedField>>
+		? [keyof B] extends [keyof Head]
+			? [keyof Head] extends [keyof B]
+				? false extends { [K in keyof B]: NotIdbBindingOk<Classes, Head[K & keyof Head], B[K]> }[keyof B]
+					? false
+					: true
+				: false
+			: false
+		: false extends { [K in keyof B]: B[K] extends AnyVar ? true : false }[keyof B]
+			? false
+			: true
+
 /**
  * One condition's judgment — the type-level twin of the engine's comparison
  * roster: class-equal joins (off the mint slots), orderable order sides (an
@@ -561,9 +659,11 @@ type CondOkBool<Classes extends SchemaClasses, C> = [AnyTreeChild] extends [C]
 			? false extends CondOkBool<Classes, Ch[number]>
 				? false
 				: true
-			: C extends NotAtom<infer R extends MatchOwner, infer B>
-				? NotOk<Classes, MatchFields<R>, ClassRecordOf<Classes, R["name"]>, B>
-				: false
+			: C extends NotIdbAtom<infer T extends RecTarget, infer B>
+				? NotIdbOk<Classes, RecHeadOf<T>, B>
+				: C extends NotAtom<infer R extends MatchOwner, infer B>
+					? NotOk<Classes, MatchFields<R>, ClassRecordOf<Classes, R["name"]>, B>
+					: false
 
 /** The validated `.where` argument (intersect with the inferred condition type). */
 type CheckCond<Classes extends SchemaClasses, C> = CondOkBool<Classes, C> extends true ? C : never
@@ -605,9 +705,11 @@ type CondParams<C> = [AnyTreeChild] extends [C]
 						: never
 		: C extends Tree<infer Ch extends readonly AnyTreeChild[]>
 			? CondParams<Ch[number]>
-			: C extends NotAtom<infer R extends MatchOwner, infer B>
-				? BindParams<MatchFields<R>, B>
-				: never
+			: C extends NotIdbAtom<infer T extends RecTarget, unknown>
+				? RecParamsOf<T>
+				: C extends NotAtom<infer R extends MatchOwner, infer B>
+					? BindParams<MatchFields<R>, B>
+					: never
 
 /** The flattened params record one bindings record contributes. */
 type BindParamsShape<F extends FieldsShape, B> = ShapeOf<BindParams<F, B>>
@@ -646,11 +748,13 @@ export type {
 	MatchOwner,
 	MatchShape,
 	NotAtom,
+	NotIdbAtom,
 	OrderSide,
 	OrderVarOk,
 	ParamUse,
 	PointSide,
 	RecData,
+	RecTarget,
 	RuleData,
 	RuleItem,
 	SlotAt,

package/src/query/lower.ts

@@ -48,6 +48,7 @@ import type {
 	HeadTermIr,
 	PredicateDefIr,
 	ProgramIr,
+	QueryParam,
 	RuleIr,
 	TaggedValue,
 	TermIr
@@ -251,6 +252,16 @@ interface OutputRuleScope<Rels extends SchemaRelations, Classes extends SchemaCl
 		relation: R,
 		bindings: B & CheckBindings<Classes, MatchFields<R>, ClassRecordOf<Classes, R["name"]>, B>
 	): OutputRuleChain<Rels, BindParamsShape<MatchFields<R>, B>, Classes>
+	/**
+	 * A rule may START with the finished stratum: an idb atom is a positive
+	 * occurrence exactly as the engine represents it, so its variables ground
+	 * — the identity projection `(c) | reach(c);` is spellable with no
+	 * re-grounding join over a domain relation.
+	 */
+	idb<Target extends RecRef<string, ParamsRecord>, const B extends Readonly<Record<string, AnyVar>>>(
+		target: Target,
+		bindings: B & CheckIdbBindings<Classes, HeadOf<Target>, B>
+	): OutputRuleChain<Rels, ParamsOf<Target>, Classes>
 }
 
 /** The chain of an output rule: atoms, predicates, `idb` joins over the program's recs, then the head. */
@@ -687,6 +698,14 @@ function advanceWhere(context: ChainContext, state: RuleBuildState, cond: AnyCon
 	if (typeof cond !== "object" || cond === null || !("cond" in cond)) {
 		throw errors.new("where() takes a comparison, an and()/or() tree, or a negated atom")
 	}
+	if (cond.cond === "notIdb") {
+		const bindings: Readonly<Record<string, unknown>> = Object.fromEntries(
+			Object.entries(cond.bindings ?? {}).filter(function defined([, value]) {
+				return value !== undefined
+			})
+		)
+		return notIdbAdvance(context, state, cond.target, bindings)
+	}
 	if (cond.cond === "not") {
 		const relation: MatchOwner = cond.relation
 		const bindings: Readonly<Record<string, unknown>> = Object.fromEntries(
@@ -710,8 +729,21 @@ function advanceWhere(context: ChainContext, state: RuleBuildState, cond: AnyCon
 	})
 }
 
-/** Extends a rule state with one `idb` atom (a named record over head keys; vars validated at completion). */
-function advanceIdb(state: RuleBuildState, rec: RecData, bindings: Readonly<Record<string, unknown>>): RuleBuildState {
+/**
+ * Extends a rule state with one `idb` atom (a named record over head keys;
+ * vars validated at completion). A POSITIVE idb atom is a positive
+ * occurrence exactly as the engine represents it (`check_atoms` walks Idb
+ * and Edb in one loop), so its variables GROUND: they enter the rule's
+ * boundness set, may ride the head, and satisfy negation safety — the
+ * idb-only identity projection of a finished stratum is spellable with no
+ * re-grounding join. A NEGATED one binds nothing, only rejects.
+ */
+function advanceIdb(
+	state: RuleBuildState,
+	rec: RecData,
+	bindings: Readonly<Record<string, unknown>>,
+	negated: boolean
+): RuleBuildState {
 	const resolved: Array<{ readonly key: string; readonly ref: AnyVar }> = []
 	for (const [key, value] of Object.entries(bindings)) {
 		if (value === undefined) {
@@ -724,12 +756,18 @@ function advanceIdb(state: RuleBuildState, rec: RecData, bindings: Readonly<Reco
 		}
 		resolved.push(Object.freeze({ key, ref: value }))
 	}
+	const bound = new Set(state.bound)
+	if (!negated) {
+		for (const binding of resolved) {
+			bound.add(binding.ref)
+		}
+	}
 	return Object.freeze({
 		items: Object.freeze([
 			...state.items,
-			Object.freeze({ kind: "idb" as const, rec, bindings: Object.freeze(resolved) })
+			Object.freeze({ kind: "idb" as const, rec, bindings: Object.freeze(resolved), negated })
 		]),
-		bound: state.bound,
+		bound,
 		paramUses: state.paramUses
 	})
 }
@@ -963,16 +1001,23 @@ function validateCond(context: ChainContext, bound: ReadonlySet<AnyVar>, cond: C
 
 /**
  * Validates one `idb` item: every head column of the rec is bound exactly
- * once (a missing or extra key is a pointed error), every bound variable is
- * positively bound by a relation atom of the rule, and each variable joins
- * its head column's classed slot. When the rec's own rule 0 is in flight
+ * once (a missing or extra key is a pointed error) and each variable joins
+ * its head column's classed slot. A POSITIVE idb atom GROUNDS its
+ * variables (a positive occurrence, exactly the engine's representation),
+ * so no boundness precondition exists; a NEGATED one binds nothing — its
+ * variables must be positively bound elsewhere in the rule, the same
+ * safety rule as EDB negation. When the rec's own rule 0 is in flight
  * (`rec.rules[0]` absent), the completing rule's OWN find columns ARE the
  * head.
  */
 function validateIdb(
 	context: ChainContext,
 	bound: ReadonlySet<AnyVar>,
-	item: { readonly rec: RecData; readonly bindings: ReadonlyArray<{ readonly key: string; readonly ref: AnyVar }> },
+	item: {
+		readonly rec: RecData
+		readonly bindings: ReadonlyArray<{ readonly key: string; readonly ref: AnyVar }>
+		readonly negated: boolean
+	},
 	columns: readonly FindColumn[]
 ): void {
 	const label = contextLabel(context)
@@ -999,9 +1044,9 @@ function validateIdb(
 		}
 	}
 	for (const binding of item.bindings) {
-		if (!bound.has(binding.ref)) {
+		if (item.negated && !bound.has(binding.ref)) {
 			throw errors.new(
-				`${label}: idb ${item.rec.name} names the variable ${binding.ref.label}, but no relation atom of the rule binds it — an idb atom is a join position; bind the variable through the theory's own relation first`
+				`${label}: negated idb ${item.rec.name} names the variable ${binding.ref.label}, but no positive atom of the rule binds it — a negated atom binds nothing, only rejects (the safety rule)`
 			)
 		}
 		const headColumn = headColumns.find(function byName(column) {
@@ -1075,6 +1120,7 @@ interface RawChain {
 /** The runtime rule-builder shape beneath every typed scope. */
 interface RawScope extends TermOps {
 	match(relation: MatchOwner, bindings: Readonly<Record<string, unknown>>): RawChain
+	idb(target: RecRef<string, ParamsRecord>, bindings: Readonly<Record<string, unknown>>): RawChain
 }
 
 /** Which rule family a chain builds — plus the schema's runtime class map and theory value (the join judge's authority). */
@@ -1112,14 +1158,43 @@ function idbAdvance(
 				`rec ${context.self.name}: a recursive rule's idb target must be the rec itself — the self-recursion-only cut (mutual recursion is unwritable; fold a finished stratum in the output rules)`
 			)
 		}
-		return advanceIdb(state, context.self, bindings)
+		return advanceIdb(state, context.self, bindings, false)
 	}
 	if (!context.program.recs.includes(target.data)) {
 		throw errors.new(
 			`idb ${target.name}: the rec was declared by a different program — rec identity is the membership rule`
 		)
 	}
-	return advanceIdb(state, target.data, bindings)
+	return advanceIdb(state, target.data, bindings, false)
+}
+
+/**
+ * Validates and records one NEGATED finished-stratum atom — output rules
+ * only: there every rec is a finished set before the output's operator
+ * runs (negation OF lower strata is engine-legal; the strata judge refuses
+ * only negation *through* a cycle, which the rec-context refusal here
+ * makes unwritable).
+ */
+function notIdbAdvance(
+	context: ChainContext,
+	state: RuleBuildState,
+	target: { readonly name: string; readonly data: RecData },
+	bindings: Readonly<Record<string, unknown>>
+): RuleBuildState {
+	if (context.kind === "query") {
+		throw errors.new("idb is a program construct — declare recs and outputs through program(), never a plain query()")
+	}
+	if (context.kind === "rec") {
+		throw errors.new(
+			`rec ${context.self.name}: a recursive rule negates no stratum — self-negation is negation through the cycle (a finished set is what keeps the operator monotone), and a finished stratum's fold belongs in the output rules`
+		)
+	}
+	if (!context.program.recs.includes(target.data)) {
+		throw errors.new(
+			`idb ${target.name}: the rec was declared by a different program — rec identity is the membership rule`
+		)
+	}
+	return advanceIdb(state, target.data, bindings, true)
 }
 
 /** Classifies one find record per the context (a recursive head projects bound variables only). */
@@ -1165,6 +1240,9 @@ function makeRawScope(context: ChainContext): RawScope {
 		...termOps,
 		match(relation, bindings) {
 			return makeRawChain(context, advanceMatch(context, EMPTY_RULE, relation, bindings))
+		},
+		idb(target, bindings) {
+			return makeRawChain(context, idbAdvance(context, EMPTY_RULE, target, bindings))
 		}
 	}
 	Object.freeze(scope)
@@ -1259,7 +1337,7 @@ function paramRegistryOf(recs: readonly RecData[], rules: readonly RuleData[]):
 			shape: ParamEntry["shape"]
 			anchor: ParamEntry["anchor"]
 			op: ParamEntry["op"]
-			members: ParamEntry["members"]
+			members: readonly string[] | undefined
 			orderOp: "lt" | "le" | "gt" | "ge" | "pointIn" | undefined
 		}
 	>()
@@ -1323,7 +1401,30 @@ function paramRegistryOf(recs: readonly RecData[], rules: readonly RuleData[]):
 			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 })
+			/**
+			 * A membership array's handle names are program constants, so the
+			 * entry stores the resolved IMAGE: each name rides the one
+			 * roster-verification point (`taggedHandleId`, through
+			 * `taggedCmpLiteral`) exactly once, HERE — an out-of-roster name
+			 * fails at build, and every execute returns this frozen value by
+			 * reference.
+			 */
+			let membership: QueryParam | undefined
+			if (entry.members !== undefined) {
+				const anchor = entry.anchor
+				if (anchor === undefined) {
+					throw errors.new(`query param ${name} lost its membership anchor`)
+				}
+				membership = Object.freeze({
+					kind: "set" as const,
+					values: Object.freeze(
+						entry.members.map(function tagMember(member, index) {
+							return Object.freeze(taggedCmpLiteral(`membership array ${name}[${index}]`, anchor, member, entry.op))
+						})
+					)
+				})
+			}
+			return Object.freeze({ name, shape: entry.shape, anchor: entry.anchor, op: entry.op, membership })
 		})
 	)
 }
@@ -1828,7 +1929,8 @@ function lowerRule(ctx: LowerContext, rule: RuleData): RuleIr {
 				break
 			}
 			case "idb": {
-				atoms.push(lowerIdbAtom(ctx, item.rec, item.bindings, ids))
+				const bucket = item.negated ? negated : atoms
+				bucket.push(lowerIdbAtom(ctx, item.rec, item.bindings, ids))
 				break
 			}
 			case "cond": {

package/src/query/run.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) {

package/src/query/scope.ts

@@ -36,6 +36,7 @@ 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"
 
 /**
@@ -280,12 +281,17 @@ type WidthOf<F extends AnyField> = F extends { readonly width: infer W } ? W : u
 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
 
 /**
@@ -377,15 +383,18 @@ type InferredOf<T> = T extends { readonly [inferred]?: infer S } ? Exclude<S, un
  * 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). `anchor` is `undefined` only on a query built but not yet
- * anchored by any rule. `members` is present exactly on a MEMBERSHIP-ARRAY
- * entry.
+ * 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 {

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)

package/src/schema.ts

@@ -13,11 +13,11 @@ import * as errors from "@superbuilders/errors"
 import type { AnyClosed } from "#closed.ts"
 import { isClosedMember, sealedFieldOf } from "#closed.ts"
 import type { FaceData } from "#face.ts"
-import { assertDeclarationOrderKey, rosterOf } from "#fields.ts"
+import { assertDeclarationOrderKey, assertDeclarationRecord, rosterOf } from "#fields.ts"
 import { type ClassesOf, classesComplete, computeClasses, type LawfulStatements, type SchemaClasses } from "#law.ts"
 import type { AnyRelation } from "#relation.ts"
 import type { LiteralSetSpec, LiteralSpec } from "#spec.ts"
-import { renderStatement, type Statement } from "#statements.ts"
+import { isStatement, renderStatement, type Statement } from "#statements.ts"
 
 /**
  * Validates the relation record and collects the implied keys: the
@@ -27,6 +27,7 @@ import { renderStatement, type Statement } from "#statements.ts"
  * single spelling authority.
  */
 function collectImplied(name: string, relations: SchemaRelations): Set<string> {
+	assertDeclarationRecord(`schema ${name} relations`, relations)
 	const implied = new Set<string>()
 	for (const [recordKey, member] of Object.entries(relations)) {
 		assertDeclarationOrderKey(`schema ${name} relation`, recordKey)
@@ -297,6 +298,17 @@ function schema<const Rels extends SchemaRelations, const Stmts extends readonly
 	const implied = collectImplied(name, relations)
 	const seen = new Set<string>()
 	for (const statement of statements) {
+		/**
+		 * The untyped caller's half of the admission brand: the type tier
+		 * already refuses an unbranded structural literal, and this probe
+		 * refuses the same forgery at runtime — a statement that skipped the
+		 * construction-time arity and roster walls never enters the theory.
+		 */
+		if (!isStatement(statement)) {
+			throw errors.new(
+				`schema ${name}: a statement is minted only by key/contained/mirrors/window — a structural literal skips the construction-time arity and roster walls`
+			)
+		}
 		const rendered = renderStatement(statement)
 		verifyMembership(name, relations, statement, rendered)
 		if (implied.has(rendered)) {

package/src/spec.ts

@@ -118,19 +118,30 @@ interface RowSpec {
 }
 
 /**
- * One relation. `extension: rows` declares it closed (the option is the
- * kind); a closed relation's `fields` are its declared intrinsic columns
- * only — the synthetic (`id`, u64) handle field is materialized by the
- * engine's schema validation. `newtype` is the handle newtype of a closed
- * relation (the SDK emits the id's law-computed generator class,
- * `` `${name}.id` `` — the same label every referencing field carries by
- * law), undefined on an ordinary one.
+ * A relation's closedness as ONE sum (ruled 2026-07-23, R7): the handle
+ * newtype and the ground axioms travel together — the two illegal states
+ * (a roster without its newtype, a newtype without its roster) are
+ * unspellable on the wire exactly as they are unrepresentable in the
+ * fused Rust `RelationSpec`. `newtype` is the id's law-computed generator
+ * class (`` `${name}.id` `` — the same label every referencing field
+ * carries by law), which is how the engine resolves a handle literal back
+ * to its roster.
+ */
+interface ClosedSpec {
+	readonly newtype: string
+	readonly rows: readonly RowSpec[]
+}
+
+/**
+ * One relation. A present `closed` declares it closed (the option is the
+ * kind, one sum — R7); a closed relation's `fields` are its declared
+ * intrinsic columns only — the synthetic (`id`, u64) handle field is
+ * materialized by the engine's schema validation.
  */
 interface RelationSpec {
 	readonly name: string
-	readonly newtype: string | undefined
 	readonly fields: readonly FieldSpec[]
-	readonly extension: readonly RowSpec[] | undefined
+	readonly closed: ClosedSpec | undefined
 }
 
 /**
@@ -313,6 +324,7 @@ function renderWindow(window: WindowSpec): string {
 }
 
 export type {
+	ClosedSpec,
 	FieldSpec,
 	LiteralSetSpec,
 	LiteralSpec,