@bjornpagen/bumbledb 1.2.0 → 1.2.1

package/src/query/lower.ts

@@ -100,6 +100,8 @@ type RowOf<T> = InferredOf<T> extends { readonly row: infer R } ? R : never
 
 type HeadShape = Readonly<Record<string, ClassedField>> | undefined
 
+type HeadOf<T> = InferredOf<T> extends { readonly head: infer H extends HeadShape } ? H : HeadShape
+
 interface RuleValue<Row, P extends ParamsRecord, Head extends HeadShape = undefined> {
 	readonly rule: RuleData
 	readonly [inferred]?: { readonly row: Row; readonly params: P; readonly head: Head }
@@ -225,7 +227,12 @@ interface QueryRuleChain<
 		bindings: B & CheckInteriorBindings<B>
 	): QueryRuleChain<Rels, P, Classes>
 
-	find<const F extends FindShape>(entries: F & CheckFind<F>): RuleValue<RowOfFind<F>, P>
+	/** A record of variables is already a valid projection, including v(rel)
+	 * for a generic relation. Aggregate judgments remain on the general form. */
+	find<const F extends Readonly<Record<string, AnyVar>>>(
+		entries: F
+	): RuleValue<RowOfFind<F>, P, HeadRecordOf<Classes, F>>
+	find<const F extends FindShape>(entries: F & CheckFind<F>): RuleValue<RowOfFind<F>, P, HeadRecordOf<Classes, F>>
 }
 
 interface InteriorRuleScope<Rels extends SchemaRelations, Classes extends SchemaClasses = SchemaClasses>
@@ -292,6 +299,9 @@ interface InteriorRuleChain<
 	 * Nonrecursive derived stages emit aggregate/computed outputs too
 	 * (C05): only the RECURSIVE head stays projection-only.
 	 */
+	find<const F extends Readonly<Record<string, AnyVar>>>(
+		entries: F
+	): RuleValue<RowOfFind<F>, P, HeadRecordOf<Classes, F>>
 	find<const F extends FindShape>(entries: F & CheckFind<F>): RuleValue<RowOfFind<F>, P, HeadRecordOf<Classes, F>>
 }
 
@@ -355,6 +365,9 @@ interface RecRuleChain<
 		name: string,
 		bindings: B & CheckInteriorBindings<B>
 	): RecRuleChain<Rels, P, Classes>
+	find<const F extends Readonly<Record<string, AnyVar>>>(
+		entries: F
+	): RuleValue<RowOfFind<F>, P, HeadRecordOf<Classes, F>>
 	find<const F extends FindShape>(entries: F & CheckRecFind<F>): RuleValue<RowOfFind<F>, P, HeadRecordOf<Classes, F>>
 }
 
@@ -388,22 +401,23 @@ interface Query<
 	Rels extends SchemaRelations,
 	Row,
 	Params extends ParamsRecord,
-	Classes extends SchemaClasses = SchemaClasses
+	Classes extends SchemaClasses = SchemaClasses,
+	Head extends HeadShape = HeadShape
 > {
 	readonly schema: Schema<Rels, Classes>
 	readonly data: QueryData
 
 	rule<RV extends AnyRuleValue>(
 		build: (r: QueryRuleScope<Rels, Classes>) => RV
-	): Query<Rels, Row | RowOf<RV>, Flatten<Params & ParamsOf<RV>>, Classes>
+	): Query<Rels, Row | RowOf<RV>, Flatten<Params & ParamsOf<RV>>, Classes, Head | HeadOf<RV>>
 
 	/** A diagnostic name for composition/tracing — never a schema relation. */
-	named(label: string): Query<Rels, Row, Params, Classes>
+	named(label: string): Query<Rels, Row, Params, Classes, Head>
 
 	interior(name: string, ...builds: never[]): never
 
 	reach(name: string, arms: never): never
-	readonly [inferred]?: { readonly row: Row; readonly params: Params }
+	readonly [inferred]?: { readonly row: Row; readonly params: Params; readonly head: Head }
 }
 
 interface AnyQuery {
@@ -422,7 +436,7 @@ type QueryStart<
 > = {
 	rule<RV extends AnyRuleValue>(
 		build: (r: QueryRuleScope<Rels, Classes>) => RV
-	): Query<Rels, RowOf<RV>, Flatten<P & ParamsOf<RV>>, Classes>
+	): Query<Rels, RowOf<RV>, Flatten<P & ParamsOf<RV>>, Classes, HeadOf<RV>>
 	interior<const Builds extends readonly InteriorBuild<Rels, Classes>[]>(
 		name: string,
 		...builds: Builds
@@ -440,7 +454,7 @@ type QueryReachStart<
 > = {
 	rule<RV extends AnyRuleValue>(
 		build: (r: QueryRuleScope<Rels, Classes>) => RV
-	): Query<Rels, RowOf<RV>, Flatten<P & ParamsOf<RV>>, Classes>
+	): Query<Rels, RowOf<RV>, Flatten<P & ParamsOf<RV>>, Classes, HeadOf<RV>>
 }
 
 const termOps: TermOps = Object.freeze({
@@ -1774,13 +1788,19 @@ function makeRawQuery(
 	return value
 }
 
-function makeQuery<Rels extends SchemaRelations, Row, P extends ParamsRecord, Classes extends SchemaClasses>(
+function makeQuery<
+	Rels extends SchemaRelations,
+	Row,
+	P extends ParamsRecord,
+	Classes extends SchemaClasses,
+	Head extends HeadShape
+>(
 	theory: Schema<Rels, Classes>,
 	interiors: readonly InteriorData[],
 	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>
+): Query<Rels, Row, P, Classes, Head> {
+	return makeRawQuery(theory, interiors, rec, rules) as unknown as Query<Rels, Row, P, Classes, Head>
 }
 
 function collectInterior<Rels extends SchemaRelations, Classes extends SchemaClasses>(
@@ -1899,9 +1919,11 @@ function makeQueryStart<Rels extends SchemaRelations, Classes extends SchemaClas
 		},
 		rule<RV extends AnyRuleValue>(
 			build: (r: QueryRuleScope<Rels, Classes>) => RV
-		): Query<Rels, RowOf<RV>, Flatten<P & ParamsOf<RV>>, Classes> {
+		): Query<Rels, RowOf<RV>, Flatten<P & ParamsOf<RV>>, Classes, HeadOf<RV>> {
 			const built = build(makeQueryRuleScope<Rels, Classes>(theory, env))
-			return makeQuery<Rels, RowOf<RV>, Flatten<P & ParamsOf<RV>>, Classes>(theory, interiors, undefined, [built.rule])
+			return makeQuery<Rels, RowOf<RV>, Flatten<P & ParamsOf<RV>>, Classes, HeadOf<RV>>(theory, interiors, undefined, [
+				built.rule
+			])
 		}
 	}
 	Object.freeze(start)
@@ -1917,9 +1939,11 @@ function makeQueryReachStart<Rels extends SchemaRelations, Classes extends Schem
 	const start = {
 		rule<RV extends AnyRuleValue>(
 			build: (r: QueryRuleScope<Rels, Classes>) => RV
-		): Query<Rels, RowOf<RV>, Flatten<P & ParamsOf<RV>>, Classes> {
+		): Query<Rels, RowOf<RV>, Flatten<P & ParamsOf<RV>>, Classes, HeadOf<RV>> {
 			const built = build(makeQueryRuleScope<Rels, Classes>(theory, env))
-			return makeQuery<Rels, RowOf<RV>, Flatten<P & ParamsOf<RV>>, Classes>(theory, interiors, rec, [built.rule])
+			return makeQuery<Rels, RowOf<RV>, Flatten<P & ParamsOf<RV>>, Classes, HeadOf<RV>>(theory, interiors, rec, [
+				built.rule
+			])
 		}
 	}
 	Object.freeze(start)

package/src/query/scope.ts

@@ -122,9 +122,23 @@ function isImportedSource(value: unknown): value is ImportedSource {
 
 type RowOfImport<Q> = InferredOf<Q> extends { readonly row: infer R } ? R : never
 
+type HeadOfImport<Q> = InferredOf<Q> extends { readonly head: infer H } ? H : never
+
+/** Named imported slot so downstream declarations need not spell its private marker. */
+interface ImportedFieldVar<S extends ClassedField, K extends string> extends Var<S["field"], string, K> {
+	readonly [inferred]?: { readonly slot: S }
+}
+
+// Retain the same descriptor and carrier class as the runtime import facade.
+// A host bigint alone cannot distinguish i64 from u64 or a closed identifier.
+type ImportedVar<Q, K extends string> =
+	HeadOfImport<Q> extends Readonly<Record<K, infer S extends ClassedField>>
+		? ImportedFieldVar<S, K>
+		: Var<AnyField, string, K>
+
 type ImportVars<Q> = [RowOfImport<Q>] extends [never]
 	? Readonly<Record<string, Var<AnyField, string, string>>>
-	: { readonly [K in keyof RowOfImport<Q> & string]: Var<AnyField, string, K> }
+	: { readonly [K in keyof RowOfImport<Q> & string]: ImportedVar<Q, K> }
 
 interface ImportFacade {
 	/** The pseudo-owner every import var carries (structurally an owner). */
@@ -241,10 +255,11 @@ type MintClassOf<Classes extends SchemaClasses, V> =
 		? ClassLookup<ClassRecordOf<Classes, RN>, K>
 		: never
 
-type MintSlotOf<Classes extends SchemaClasses, V extends AnyVar> = {
-	readonly field: V["field"]
-	readonly class: MintClassOf<Classes, V>
-}
+type MintSlotOf<Classes extends SchemaClasses, V extends AnyVar> = [InferredOf<V>] extends [never]
+	? { readonly field: V["field"]; readonly class: MintClassOf<Classes, V> }
+	: InferredOf<V> extends { readonly slot: infer S extends ClassedField }
+		? S
+		: { readonly field: V["field"]; readonly class: MintClassOf<Classes, V> }
 
 type ParamsRecord = Readonly<Record<string, unknown>>
 
@@ -257,15 +272,8 @@ type UnionToIntersection<U> = (U extends unknown ? (member: U) => void : never)
 type ShapeOf<U> = [U] extends [never] ? Record<never, never> : Flatten<UnionToIntersection<U>>
 
 /**
- * A slot's identity for the positive-join judgment: the field's structural
- * signature ({@link SignatureOf} — the ONE interpreter, shared with the
- * face pairing wall) plus the slot's law class.
- */
-type SlotSignature<S extends ClassedField> = readonly [SignatureOf<S["field"]>, S["class"]]
-
-/**
- * A widened slot — a variable minted from an imported query template (its
- * facade columns carry `AnyField`) or fully generic code — cannot be judged
+ * A widened slot — an explicitly erased query template or fully generic
+ * code with no retained descriptor — cannot be judged
  * at the type tier. The degradation law applies: best effort degrades to
  * SILENT, never to a wrong refusal; the runtime join judgment (real
  * descriptors off the imported head's slots) stays authoritative.
@@ -273,7 +281,15 @@ type SlotSignature<S extends ClassedField> = readonly [SignatureOf<S["field"]>,
 type WidenedSlot<S extends ClassedField> = [AnyField] extends [S["field"]] ? true : false
 
 type JoinOk<A extends ClassedField, B extends ClassedField> =
-	WidenedSlot<A> extends true ? true : WidenedSlot<B> extends true ? true : Same<SlotSignature<A>, SlotSignature<B>>
+	WidenedSlot<A> extends true
+		? true
+		: WidenedSlot<B> extends true
+			? true
+			: Same<SignatureOf<A["field"]>, SignatureOf<B["field"]>> extends true
+				? string extends A["class"] | B["class"]
+					? true
+					: Same<A["class"], B["class"]>
+				: false
 
 type U64Wire<F extends AnyField> = F extends { readonly kind: "u64" }
 	? F extends { readonly closed: unknown }
@@ -390,6 +406,7 @@ export type {
 	ClassedField,
 	ExactVars,
 	Flatten,
+	ImportedFieldVar,
 	ImportedSource,
 	ImportVars,
 	InferredOf,

package/src/shape.ts

@@ -1,5 +1,5 @@
 import type { Query } from "#query/lower.ts"
-import type { ParamsRecord } from "#query/scope.ts"
+import type { inferred, ParamsRecord } from "#query/scope.ts"
 /**
  * Shared derived types: `S` is a
  * declared core schema value's type, `Rel<S>` its ordinary (writable)
@@ -24,7 +24,13 @@ type Key<K extends KeyStatement<AnyRelation, readonly string[]>> = Pick<
 	Extract<K["projection"][number], keyof Fact<K["owner"]>>
 >
 
-/** Immutable typed query template. */
-type QueryTemplate<S extends AnySchema, P extends ParamsRecord, A> = Query<S["relations"], A, P>
+/** The immutable executable view of a query. Readers consume its schema/data
+ * and inferred result/parameters, not the author's rule-building methods.
+ * Runtime schema identity remains authoritative for dynamically built schemas.
+ */
+type QueryTemplate<S extends AnySchema, P extends ParamsRecord, A> = Pick<
+	Query<S["relations"], A, P>,
+	"schema" | "data" | typeof inferred
+>
 
 export type { Key, QueryTemplate, Rel }