@bjornpagen/bumbledb 0.11.0 → 0.12.2

package/src/query/lower.ts

@@ -114,7 +114,7 @@ type HeadShape = Readonly<Record<string, ClassedField>> | undefined
 
 /**
  * One finished rule as a plain value: the runtime data plus the inferred
- * row/params carrier (and, for an interior or recursive rule, the head
+ * row/params carrier (and, for an interior or rec rule, the head
  * record of classed slots an `.interior(name)` join pairs against).
  * `.rule(...)` consumes it.
  */
@@ -265,7 +265,7 @@ interface InteriorRuleChain<
 	find<const F extends FindShape>(entries: F & CheckRecFind<F>): RuleValue<RowOfFind<F>, P, HeadRecordOf<Classes, F>>
 }
 
-/** The rule builder a `recursive("reach", { base, rec })` arm receives. */
+/** The rule builder a `.reach("reach", { base, rec })` arm receives. */
 interface RecRuleScope<Rels extends SchemaRelations, Classes extends SchemaClasses = SchemaClasses> extends TermOps {
 	match<R extends QueryRelation<Rels>, const B extends MatchShape<MatchFields<R>>>(
 		relation: R,
@@ -278,10 +278,10 @@ interface RecRuleScope<Rels extends SchemaRelations, Classes extends SchemaClass
 }
 
 /**
- * The chain of a recursive arm. `.interior("reach", …)` is the self-atom
+ * The chain of a rec arm. `.interior("reach", …)` is the self-atom
  * on rec arms (and a prior interior on either list). `find` takes bound
  * variables only — aggregates and the measure are unrepresentable in a
- * recursive head.
+ * rec head.
  */
 interface RecRuleChain<
 	Rels extends SchemaRelations,
@@ -303,18 +303,31 @@ interface RecRuleChain<
 }
 
 /** A query's runtime description — everything lowering, the wire marshal, and answer decode read. */
-interface QueryData {
-	/** Named interiors in declaration order (DAG). */
-	readonly interiors: readonly InteriorData[]
-	/** The optional linear rec. */
-	readonly rec: RecData | null
-	/** The main rules in written order (multiple rules = set union). */
-	readonly rules: readonly RuleData[]
-	/** The head columns (every rule derives the same head; written order = answer column order). */
-	readonly finds: readonly FindColumn[]
-	/** The registered params in first-use order across the query walk (= dense `ParamId`s). */
-	readonly params: readonly ParamEntry[]
-}
+type QueryData =
+	| {
+			readonly kind: "cq"
+			/** Named interiors in declaration order (DAG). */
+			readonly interiors: readonly InteriorData[]
+			/** The main rules in written order (multiple rules = set union). */
+			readonly rules: readonly RuleData[]
+			/** The head columns (every rule derives the same head; written order = answer column order). */
+			readonly finds: readonly FindColumn[]
+			/** The registered params in first-use order across the query walk (= dense `ParamId`s). */
+			readonly params: readonly ParamEntry[]
+	  }
+	| {
+			readonly kind: "reach"
+			/** Named interiors in declaration order (DAG). */
+			readonly interiors: readonly InteriorData[]
+			/** The linear rec (base and rec arms nonempty by type). */
+			readonly rec: RecData
+			/** The main rules in written order (multiple rules = set union). */
+			readonly rules: readonly RuleData[]
+			/** The head columns (every rule derives the same head; written order = answer column order). */
+			readonly finds: readonly FindColumn[]
+			/** The registered params in first-use order across the query walk (= dense `ParamId`s). */
+			readonly params: readonly ParamEntry[]
+	  }
 
 /**
  * An inert query value. `Row` is the inferred answer-row object type;
@@ -335,8 +348,8 @@ interface Query<
 	): Query<Rels, Row | RowOf<RV>, Flatten<Params & ParamsOf<RV>>, Classes>
 	/** Construction error: interiors precede main rules. Uncallable after `.rule()`. */
 	interior(name: string, ...builds: never[]): never
-	/** Construction error: recursive precedes main rules. Uncallable after `.rule()`. */
-	recursive(name: string, arms: never): never
+	/** Construction error: reach precedes main rules. Uncallable after `.rule()`. */
+	reach(name: string, arms: never): never
 	readonly [inferred]?: { readonly row: Row; readonly params: Params }
 }
 
@@ -353,37 +366,38 @@ type QueryRow<Q extends AnyQuery> = RowOf<Q>
 type QueryParams<Q extends AnyQuery> = ParamsOf<Q>
 
 /**
- * The entry value of `query(S)`: interiors, then optional recursive, then
- * the first `.rule` mints the query. `interior` / `recursive` exist only
- * while `Rec` is `null`; `.recursive()` moves the type parameter.
+ * The entry value of `query(S)`: interiors, then reach (moves to
+ * {@link QueryReachStart}), then the first `.rule` mints the query.
+ * `interior` / `reach` exist only on this CQ start.
  */
 type QueryStart<
 	Rels extends SchemaRelations,
 	Classes extends SchemaClasses = SchemaClasses,
-	P extends ParamsRecord = Record<never, never>,
-	Rec extends RecData | null = null
+	P extends ParamsRecord = Record<never, never>
 > = {
 	rule<RV extends AnyRuleValue>(
 		build: (r: QueryRuleScope<Rels, Classes>) => RV
 	): Query<Rels, RowOf<RV>, Flatten<P & ParamsOf<RV>>, Classes>
-} & (Rec extends null
-	? {
-			interior<const Builds extends readonly InteriorBuild<Rels, Classes>[]>(
-				name: string,
-				...builds: Builds
-			): QueryStart<Rels, Classes, Flatten<P & BuildsParams<Builds>>, null>
-			recursive<
-				const Base extends readonly RecBuild<Rels, Classes>[],
-				const Step extends readonly RecBuild<Rels, Classes>[]
-			>(
-				name: string,
-				arms: { readonly base: Base; readonly rec: Step }
-			): QueryStart<Rels, Classes, Flatten<P & BuildsParams<Base> & BuildsParams<Step>>, RecData>
-		}
-	: {
-			interior: never
-			recursive: never
-		})
+	interior<const Builds extends readonly InteriorBuild<Rels, Classes>[]>(
+		name: string,
+		...builds: Builds
+	): QueryStart<Rels, Classes, Flatten<P & BuildsParams<Builds>>>
+	reach<const Base extends readonly RecBuild<Rels, Classes>[], const Step extends readonly RecBuild<Rels, Classes>[]>(
+		name: string,
+		arms: { readonly base: Base; readonly rec: Step }
+	): QueryReachStart<Rels, Classes, Flatten<P & BuildsParams<Base> & BuildsParams<Step>>>
+}
+
+/** After `.reach()`: interior/reach are unrepresentable; only `.rule` remains. */
+type QueryReachStart<
+	Rels extends SchemaRelations,
+	Classes extends SchemaClasses = SchemaClasses,
+	P extends ParamsRecord = Record<never, never>
+> = {
+	rule<RV extends AnyRuleValue>(
+		build: (r: QueryRuleScope<Rels, Classes>) => RV
+	): Query<Rels, RowOf<RV>, Flatten<P & ParamsOf<RV>>, Classes>
+}
 
 /** The frozen constructor vocabulary every rule builder spreads. */
 const termOps: TermOps = Object.freeze({
@@ -1080,10 +1094,9 @@ interface RawScope extends TermOps {
 }
 
 /** The declared derived tables a chain may name. */
-interface DerivedEnv {
-	readonly interiors: readonly InteriorData[]
-	readonly rec: RecHandle | RecHead | RecData | null
-}
+type DerivedEnv =
+	| { readonly interiors: readonly InteriorData[] }
+	| { readonly interiors: readonly InteriorData[]; readonly rec: RecHandle | RecHead | RecData }
 
 /** Which rule family a chain builds — plus the schema's runtime class map and theory value (the join judge's authority). */
 type ChainContext = { readonly classes: SchemaClasses; readonly theory: AnySchema } & DerivedEnv &
@@ -1102,12 +1115,17 @@ function contextLabel(context: ChainContext): string {
 		case "interior":
 			return `interior ${context.self} rule`
 		case "rec-base":
-			return `recursive ${context.self.name} base`
+			return `rec ${context.self.name} base`
 		case "rec-arm":
-			return `recursive ${context.self.name} rec`
+			return `rec ${context.self.name} rec`
 	}
 }
 
+/** RecHandle is name-only staging; RecHead/RecData carry the sealed finds. */
+function isRecHead(rec: RecHandle | RecHead | RecData): rec is RecHead {
+	return Array.isArray((rec as RecHead).finds)
+}
+
 /** Resolves a derived-table name against the context's visible tables. */
 function lookupDerived(context: ChainContext, name: string): DerivedTable {
 	const interior = context.interiors.find(function byName(candidate) {
@@ -1121,19 +1139,18 @@ function lookupDerived(context: ChainContext, name: string): DerivedTable {
 		}
 		return interior
 	}
-	if (context.rec !== null && context.rec.name === name) {
+	const rec = "rec" in context ? context.rec : undefined
+	if (rec !== undefined && rec.name === name) {
 		if (context.kind === "interior") {
 			throw errors.new(`interior ${context.self}: interiors cannot read the rec — this cut's interiors are a prefix`)
 		}
 		if (context.kind === "rec-base") {
-			throw errors.new(
-				`recursive ${context.rec.name}: a base arm does not read the rec — self-atoms belong on rec arms`
-			)
+			throw errors.new(`rec ${rec.name}: a base arm does not read the rec — self-atoms belong on rec arms`)
 		}
-		if (!("finds" in context.rec)) {
-			throw errors.new(`recursive ${context.rec.name}: rec arms resolve the rec head after base arms seal it`)
+		if (!isRecHead(rec)) {
+			throw errors.new(`rec ${rec.name}: rec arms resolve the rec head after base arms seal it`)
 		}
-		return context.rec
+		return rec
 	}
 	throw errors.new(`${contextLabel(context)}: no derived table named ${name} is in scope`)
 }
@@ -1161,7 +1178,7 @@ function notInteriorAdvance(
 ): RuleBuildState {
 	if (context.kind === "rec-base" || context.kind === "rec-arm") {
 		throw errors.new(
-			`recursive ${context.self.name}: a recursive rule negates no table — self-negation is negation through the cycle (a finished set is what keeps the operator monotone), and a finished table's fold belongs in the main rules`
+			`rec ${context.self.name}: a rec rule negates no table — self-negation is negation through the cycle (a finished set is what keeps the operator monotone), and a finished table's fold belongs in the main rules`
 		)
 	}
 	return advanceInterior(state, lookupDerived(context, name), bindings, "negatedInterior")
@@ -1176,9 +1193,9 @@ function findColumns(context: ChainContext, entries: Readonly<Record<string, unk
 			continue
 		}
 		if (derivedHead && !(isTerm(entry) && entry[term] === "var")) {
-			const who = context.kind === "interior" ? `interior ${context.self}` : `recursive ${context.self.name}`
+			const who = context.kind === "interior" ? `interior ${context.self}` : `rec ${context.self.name}`
 			throw errors.new(
-				`${who}: a recursive head projects bound variables only — aggregates and the measure read finished sets (unwritable here)`
+				`${who}: a rec head projects bound variables only — aggregates and the measure read finished sets (unwritable here)`
 			)
 		}
 		columns.push(findColumnOf(name, entry))
@@ -1295,7 +1312,7 @@ function makeRecRuleScope<Rels extends SchemaRelations, Classes extends SchemaCl
 					...env
 				})
 	if (!isTypedScope<RecRuleScope<Rels, Classes>>(raw)) {
-		throw errors.new("recursive rule builder construction incomplete")
+		throw errors.new("rec rule builder construction incomplete")
 	}
 	return raw
 }
@@ -1342,7 +1359,7 @@ function renderParamAnchor(roster: ClosedRoster | undefined): string {
  */
 function paramRegistryOf(
 	interiors: readonly InteriorData[],
-	rec: RecData | null,
+	rec: RecData | undefined,
 	rules: readonly RuleData[]
 ): readonly ParamEntry[] {
 	const order: string[] = []
@@ -1398,7 +1415,7 @@ function paramRegistryOf(
 			fold(rule.paramUses)
 		}
 	}
-	if (rec !== null) {
+	if (rec !== undefined) {
 		for (const rule of rec.base) {
 			fold(rule.paramUses)
 		}
@@ -1449,7 +1466,7 @@ interface RawQuery {
 	readonly data: QueryData
 	rule(build: (r: RawScope) => RuleValue<never, never>): RawQuery
 	interior(name: string, ...builds: never[]): never
-	recursive(name: string, arms: never): never
+	reach(name: string, arms: never): never
 }
 
 /** Asserts every rule in a list derives the same head (name, aggregate shape, closed slice, class). */
@@ -1495,12 +1512,13 @@ function afterMainError(what: string): Error {
  * Assembles the runtime query value over completed rules: every rule must
  * derive the SAME head (name and aggregate shape, position for position —
  * the decode labels and the engine's alignment rule agree), and the param
- * registry folds in query-walk order.
+ * registry folds in query-walk order. CQ lowering does not mention rec;
+ * Reach carries RecData by value.
  */
 function makeRawQuery(
 	theory: AnySchema,
 	interiors: readonly InteriorData[],
-	rec: RecData | null,
+	rec: RecData | undefined,
 	rules: readonly RuleData[]
 ): RawQuery {
 	assertAlignedHeads("a query", rules)
@@ -1508,14 +1526,27 @@ function makeRawQuery(
 	if (first === undefined) {
 		throw errors.new("a query needs at least one rule")
 	}
-	const env: DerivedEnv = { interiors, rec }
-	const data: QueryData = Object.freeze({
-		interiors: Object.freeze([...interiors]),
-		rec,
-		rules: Object.freeze([...rules]),
-		finds: first.finds,
-		params: paramRegistryOf(interiors, rec, rules)
-	})
+	const env: DerivedEnv = rec === undefined ? { interiors } : { interiors, rec }
+	const frozenInteriors = Object.freeze([...interiors])
+	const frozenRules = Object.freeze([...rules])
+	const params = paramRegistryOf(interiors, rec, rules)
+	const data: QueryData =
+		rec === undefined
+			? Object.freeze({
+					kind: "cq" as const,
+					interiors: frozenInteriors,
+					rules: frozenRules,
+					finds: first.finds,
+					params
+				})
+			: Object.freeze({
+					kind: "reach" as const,
+					interiors: frozenInteriors,
+					rec,
+					rules: frozenRules,
+					finds: first.finds,
+					params
+				})
 	const value: RawQuery = {
 		schema: theory,
 		data,
@@ -1526,8 +1557,8 @@ function makeRawQuery(
 		interior() {
 			throw afterMainError("interior")
 		},
-		recursive() {
-			throw afterMainError("recursive")
+		reach() {
+			throw afterMainError("reach")
 		}
 	}
 	Object.freeze(value)
@@ -1537,7 +1568,7 @@ function makeRawQuery(
 function makeQuery<Rels extends SchemaRelations, Row, P extends ParamsRecord, Classes extends SchemaClasses>(
 	theory: Schema<Rels, Classes>,
 	interiors: readonly InteriorData[],
-	rec: RecData | null,
+	rec: RecData | undefined,
 	rules: readonly RuleData[]
 ): Query<Rels, Row, P, Classes> {
 	return makeRawQuery(theory, interiors, rec, rules) as unknown as Query<Rels, Row, P, Classes>
@@ -1573,24 +1604,24 @@ function collectRec<Rels extends SchemaRelations, Classes extends SchemaClasses>
 	recBuilds: readonly RecBuild<Rels, Classes>[]
 ): RecData {
 	if (baseBuilds.length === 0) {
-		throw errors.new(`query: recursive ${name} has no base arms`)
+		throw errors.new(`query: rec ${name} has no base arms`)
 	}
 	if (recBuilds.length === 0) {
-		throw errors.new(`query: recursive ${name} has no rec arms`)
+		throw errors.new(`query: rec ${name} has no rec arms`)
 	}
 	const handle: RecHandle = Object.freeze({ name })
 	const baseEnv: DerivedEnv = { interiors, rec: handle }
 	const base = baseBuilds.map(function buildBase(buildOne) {
 		return buildOne(makeRecRuleScope<Rels, Classes>(theory, baseEnv, handle, "rec-base")).rule
 	})
-	assertAlignedHeads(`recursive ${name}`, base)
+	assertAlignedHeads(`rec ${name}`, base)
 	const first = base[0]
 	if (first === undefined) {
-		throw errors.new(`query: recursive ${name} has no base arms`)
+		throw errors.new(`query: rec ${name} has no base arms`)
 	}
 	const firstFind = first.finds[0]
 	if (firstFind === undefined) {
-		throw errors.new(`query: recursive ${name} has no head`)
+		throw errors.new(`query: rec ${name} has no head`)
 	}
 	const finds: RecHead["finds"] = [firstFind, ...first.finds.slice(1)]
 	const head: RecHead = Object.freeze({ name, finds })
@@ -1598,10 +1629,10 @@ function collectRec<Rels extends SchemaRelations, Classes extends SchemaClasses>
 	const rec = recBuilds.map(function buildRec(buildOne) {
 		return buildOne(makeRecRuleScope<Rels, Classes>(theory, recEnv, head, "rec-arm")).rule
 	})
-	assertAlignedHeads(`recursive ${name}`, [...base, ...rec])
+	assertAlignedHeads(`rec ${name}`, [...base, ...rec])
 	const firstRec = rec[0]
 	if (firstRec === undefined) {
-		throw errors.new(`query: recursive ${name} has no rec arms`)
+		throw errors.new(`query: rec ${name} has no rec arms`)
 	}
 	const sealedBase: RecData["base"] = [first, ...base.slice(1)]
 	const sealedRec: RecData["rec"] = [firstRec, ...rec.slice(1)]
@@ -1614,24 +1645,17 @@ function collectRec<Rels extends SchemaRelations, Classes extends SchemaClasses>
 	return recData
 }
 
-/** Builds the query start (interiors, then optional rec, then the first main rule). */
-function makeQueryStart<
-	Rels extends SchemaRelations,
-	Classes extends SchemaClasses,
-	P extends ParamsRecord,
-	Rec extends RecData | null
->(theory: Schema<Rels, Classes>, interiors: readonly InteriorData[], rec: Rec): QueryStart<Rels, Classes, P, Rec> {
-	const env: DerivedEnv = { interiors, rec }
+/** Builds the CQ query start (interiors, then reach or the first main rule). */
+function makeQueryStart<Rels extends SchemaRelations, Classes extends SchemaClasses, P extends ParamsRecord>(
+	theory: Schema<Rels, Classes>,
+	interiors: readonly InteriorData[]
+): QueryStart<Rels, Classes, P> {
+	const env: DerivedEnv = { interiors }
 	const start = {
 		interior<const Builds extends readonly InteriorBuild<Rels, Classes>[]>(
 			name: string,
 			...builds: Builds
-		): QueryStart<Rels, Classes, Flatten<P & BuildsParams<Builds>>, null> {
-			if (rec !== null) {
-				throw errors.new(
-					"query: interior after recursive is unwritable — declaration order is interiors, then rec, then main"
-				)
-			}
+		): QueryStart<Rels, Classes, Flatten<P & BuildsParams<Builds>>> {
 			if (
 				interiors.some(function sameName(interior) {
 					return interior.name === name
@@ -1643,35 +1667,48 @@ function makeQueryStart<
 				throw errors.new("query: an interior needs a name")
 			}
 			const data = collectInterior(theory, env, name, builds)
-			return makeQueryStart<Rels, Classes, Flatten<P & BuildsParams<Builds>>, null>(theory, [...interiors, data], null)
+			return makeQueryStart<Rels, Classes, Flatten<P & BuildsParams<Builds>>>(theory, [...interiors, data])
 		},
-		recursive<
-			const Base extends readonly RecBuild<Rels, Classes>[],
-			const Step extends readonly RecBuild<Rels, Classes>[]
-		>(
+		reach<const Base extends readonly RecBuild<Rels, Classes>[], const Step extends readonly RecBuild<Rels, Classes>[]>(
 			name: string,
 			arms: { readonly base: Base; readonly rec: Step }
-		): QueryStart<Rels, Classes, Flatten<P & BuildsParams<Base> & BuildsParams<Step>>, RecData> {
-			if (rec !== null) {
-				throw errors.new("query: a second recursive is unwritable — this cut admits one linear rec")
-			}
+		): QueryReachStart<Rels, Classes, Flatten<P & BuildsParams<Base> & BuildsParams<Step>>> {
 			if (
 				interiors.some(function sameName(interior) {
 					return interior.name === name
 				})
 			) {
-				throw errors.new(`query: interior and recursive share the name ${name}`)
+				throw errors.new(`query: interior and rec share the name ${name}`)
 			}
 			if (name.length === 0) {
-				throw errors.new("query: recursive needs a name")
+				throw errors.new("query: reach needs a name")
 			}
 			const data = collectRec(theory, interiors, name, arms.base, arms.rec)
-			return makeQueryStart<Rels, Classes, Flatten<P & BuildsParams<Base> & BuildsParams<Step>>, RecData>(
+			return makeQueryReachStart<Rels, Classes, Flatten<P & BuildsParams<Base> & BuildsParams<Step>>>(
 				theory,
 				interiors,
 				data
 			)
 		},
+		rule<RV extends AnyRuleValue>(
+			build: (r: QueryRuleScope<Rels, Classes>) => RV
+		): Query<Rels, RowOf<RV>, Flatten<P & ParamsOf<RV>>, Classes> {
+			const built = build(makeQueryRuleScope<Rels, Classes>(theory, env))
+			return makeQuery<Rels, RowOf<RV>, Flatten<P & ParamsOf<RV>>, Classes>(theory, interiors, undefined, [built.rule])
+		}
+	}
+	Object.freeze(start)
+	return start as unknown as QueryStart<Rels, Classes, P>
+}
+
+/** Builds the Reach query start (rec sealed; only the first main rule remains). */
+function makeQueryReachStart<Rels extends SchemaRelations, Classes extends SchemaClasses, P extends ParamsRecord>(
+	theory: Schema<Rels, Classes>,
+	interiors: readonly InteriorData[],
+	rec: RecData
+): QueryReachStart<Rels, Classes, P> {
+	const env: DerivedEnv = { interiors, rec }
+	const start = {
 		rule<RV extends AnyRuleValue>(
 			build: (r: QueryRuleScope<Rels, Classes>) => RV
 		): Query<Rels, RowOf<RV>, Flatten<P & ParamsOf<RV>>, Classes> {
@@ -1680,12 +1717,12 @@ function makeQueryStart<
 		}
 	}
 	Object.freeze(start)
-	return start as unknown as QueryStart<Rels, Classes, P, Rec>
+	return start as unknown as QueryReachStart<Rels, Classes, P>
 }
 
 /**
  * Opens a query over a schema: `query(S).rule(r => ...)`, optionally with
- * `interior` / `recursive` first. Each `.rule` adds one conjunctive rule;
+ * `interior` / `reach` first. Each `.rule` adds one conjunctive rule;
  * multiple rules are the set union. The schema's law-computed class map and
  * theory value ride into every rule builder — the join walls compare
  * against the mint slots off it.
@@ -1693,7 +1730,7 @@ function makeQueryStart<
 function query<Rels extends SchemaRelations, Classes extends SchemaClasses>(
 	theory: Schema<Rels, Classes>
 ): QueryStart<Rels, Classes> {
-	return makeQueryStart<Rels, Classes, Record<never, never>, null>(theory, [], null)
+	return makeQueryStart<Rels, Classes, Record<never, never>>(theory, [])
 }
 
 /**
@@ -2088,9 +2125,9 @@ function lowerRule(ctx: LowerContext, rule: RuleData): RuleIr {
 }
 
 /**
- * Lowers a query value to the bridge's `QueryIr` — pure and stable: interiors
- * in declaration order, optional rec, then main. Every registered param must
- * carry a field anchor by now.
+ * Lowers a query value to the bridge's `QueryIr` — pure and stable:
+ * interiors in declaration order, then CQ or Reach, then main. Every
+ * registered param must carry a field anchor by now.
  */
 function lowerQuery(q: AnyQuery): ParsedQuery {
 	const theory = q.schema
@@ -2102,7 +2139,7 @@ function lowerQuery(q: AnyQuery): ParsedQuery {
 	q.data.interiors.forEach(function assignInteriorId(interior, index) {
 		interiorIds.set(interior.name, index)
 	})
-	if (q.data.rec !== null) {
+	if (q.data.kind === "reach") {
 		interiorIds.set(q.data.rec.name, q.data.interiors.length)
 	}
 	const paramIds = new Map<string, number>()
@@ -2117,31 +2154,35 @@ function lowerQuery(q: AnyQuery): ParsedQuery {
 		params.set(entry.name, entry)
 	})
 	const ctx: LowerContext = { theory, relationIds, interiorIds, paramIds, params }
+	const interiors = q.data.interiors.map(function lowerInterior(interior) {
+		return {
+			head: interior.finds.map(headTermOf),
+			rules: interior.rules.map(function lowerInteriorRule(rule) {
+				return lowerRule(ctx, rule)
+			})
+		}
+	})
+	const head = q.data.finds.map(headTermOf)
+	const rules = q.data.rules.map(function lowerMainRule(rule) {
+		return lowerRule(ctx, rule)
+	})
+	if (q.data.kind === "cq") {
+		return parseQueryIr({ kind: "cq", interiors, head, rules })
+	}
 	return parseQueryIr({
-		interiors: q.data.interiors.map(function lowerInterior(interior) {
-			return {
-				head: interior.finds.map(headTermOf),
-				rules: interior.rules.map(function lowerInteriorRule(rule) {
-					return lowerRule(ctx, rule)
-				})
-			}
-		}),
-		rec:
-			q.data.rec === null
-				? null
-				: {
-						head: q.data.rec.finds.map(headTermOf),
-						base: q.data.rec.base.map(function lowerBase(rule) {
-							return lowerRule(ctx, rule)
-						}),
-						rec: q.data.rec.rec.map(function lowerRecArm(rule) {
-							return lowerRule(ctx, rule)
-						})
-					},
-		head: q.data.finds.map(headTermOf),
-		rules: q.data.rules.map(function lowerMainRule(rule) {
-			return lowerRule(ctx, rule)
-		})
+		kind: "reach",
+		interiors,
+		rec: {
+			head: q.data.rec.finds.map(headTermOf),
+			base: q.data.rec.base.map(function lowerBase(rule) {
+				return lowerRule(ctx, rule)
+			}),
+			rec: q.data.rec.rec.map(function lowerRecArm(rule) {
+				return lowerRule(ctx, rule)
+			})
+		},
+		head,
+		rules
 	})
 }
 
@@ -2156,6 +2197,7 @@ export type {
 	Query,
 	QueryData,
 	QueryParams,
+	QueryReachStart,
 	QueryRelation,
 	QueryRow,
 	QueryRuleChain,

package/src/query/parse-ir.ts

@@ -1,8 +1,8 @@
 /**
- * Host shape parse for the wire `QueryIr`: rec/main nonempty, aggregate
- * finds split (Count has no `over`; folds require it), head/find
- * alignment. The engine validator remains the one roster authority —
- * this parse refuses only shape the host type can see.
+ * Host shape parse for the wire `QueryIr`: CQ/Reach eliminator, rec/main
+ * nonempty, aggregate finds split (Count has no `over`; folds require
+ * it), head/find alignment. The engine validator remains the one roster
+ * authority — this parse refuses only shape the host type can see.
  */
 
 import * as errors from "@superbuilders/errors"
@@ -17,7 +17,7 @@ function parseQueryIr(ir: QueryIr): ParsedQuery {
 	ir.interiors.forEach(function checkInterior(interior, index) {
 		align(`interior ${index}`, interior.head, interior.rules)
 	})
-	if (ir.rec !== null) {
+	if (ir.kind === "reach") {
 		if (ir.rec.base.length === 0) {
 			throw errors.new("parseQueryIr: rec base is empty")
 		}

package/src/relation.ts

@@ -20,6 +20,16 @@ import { type LiteralSetSpec, type LiteralSpec, renderLiteral } from "#spec.ts"
 /** Flattens an intersection into one displayed object type (hover legibility). */
 type Flatten<T> = { [K in keyof T]: T[K] }
 
+/**
+ * An optional property that may be omitted OR explicitly `undefined`.
+ * `Partial<T>` under `exactOptionalPropertyTypes` is omit-only (`key?: T`),
+ * which rejects `key: T | undefined` — insert must accept both (omit-to-mint,
+ * and a host binding that is already `bigint | undefined`).
+ */
+type ExactOptional<T> = {
+	[K in keyof T]?: T[K] | undefined
+}
+
 /**
  * Resolves one selection entry to its lowered literal set: a plain ARRAY
  * (detected by `Array.isArray` — no field's value type is an array;
@@ -180,9 +190,12 @@ type FreshKeys<R extends AnyRelation> = {
 /**
  * The inferred row object type of a relation as INSERTED: fresh fields
  * optional — omitted, the engine mints; supplied, identity is preserved
- * (the ETL resupply idiom).
+ * (the ETL resupply idiom). Explicit `undefined` is the same as omit
+ * (`exactOptionalPropertyTypes`: `id?: bigint | undefined`, not omit-only).
  */
-type InsertFact<R extends AnyRelation> = Flatten<Omit<Fact<R>, FreshKeys<R>> & Partial<Pick<Fact<R>, FreshKeys<R>>>>
+type InsertFact<R extends AnyRelation> = Flatten<
+	Omit<Fact<R>, FreshKeys<R>> & ExactOptional<Pick<Fact<R>, FreshKeys<R>>>
+>
 
 /**
  * Declares one relation: `relation("Account", { id: u64.fresh,