@bjornpagen/bumbledb 0.2.0 → 0.3.0

package/src/face.ts

@@ -4,16 +4,23 @@
  * position, `on(Booking, ["room", "during"])` the composite/pointwise
  * position (one spelling, arity-generic), `on(Account.where({ kind:
  * Kind.Savings }), "id")` the σ-carrying source, `on(Kind, "id")` a closed
- * relation's sealed shape opened through its synthetic `id`. Projection is
+ * relation's sealed shape opened through its synthetic `id`,
+ * `on(Kind.where({ mastered: true }), "id")` the ψ-selected closed source
+ * (the selection lowered as-is — the ENGINE folds it against the sealed
+ * extension at validate, never the SDK). Projection is
  * positional: tuple order is preserved in the type, and the statement
  * constructors pair the two sides' tuples by arity ({@link SameArity}) AND
- * by domain ({@link SameDomains}) — the domain wall of the structural
- * design: every projected field's domain LABEL is read off the schema type
- * (`F["domain"]`, the S1 kernel) and compared positionwise by
- * string-literal equality, never by any value brand.
+ * by structural shape ({@link SameShapes}) — every projected field's
+ * kind/width/element triple is read off the schema type (the minimal
+ * kernel: descriptors are pure structure) and compared positionwise. There
+ * is no domain to compare at construction — domains are LAW-BORN: the
+ * statements themselves define the equivalence classes, and `schema()` is
+ * where they aggregate and get judged (the one-generator-per-class wall).
  */
 
-import type { AnyClosed, PayloadField } from "#closed.ts"
+import * as errors from "@superbuilders/errors"
+import type { AnyClosed, AnySelectedClosed, PayloadField } from "#closed.ts"
+import type { AnyField } from "#fields.ts"
 import type { AnyRelation, AnySelected, FieldsShape, RelationFields, SelectionBinding } from "#relation.ts"
 import { renderLiteralSet } from "#spec.ts"
 
@@ -21,10 +28,21 @@ import { renderLiteralSet } from "#spec.ts"
 const emptySelection: readonly SelectionBinding[] = Object.freeze([])
 
 /**
- * Splits a face source into its owner and σ: a selected relation carries
- * its own bindings (`relation` is the discriminant — the property exists on
- * no relation or closed value, and `closed()` reserves the name against
- * handle collisions); a bare relation or closed relation carries none.
+ * The OWNER a face source resolves to: a selected relation — ordinary σ or
+ * closed ψ, one shape — projects from its underlying relation; a bare
+ * relation or closed relation is its own owner. The type-level twin of
+ * {@link faceParts}'s split, and what a statement's face `data` carries at
+ * its EXACT type — `schema()`'s law-typing reads the owner's literal name
+ * (and the projection tuple) straight off the statement type.
+ */
+type OwnerOf<S extends FaceSource> = S extends AnySelected | AnySelectedClosed ? S["relation"] : S
+
+/**
+ * Splits a face source into its owner and σ: a selected relation — ordinary
+ * σ or closed ψ, one shape — carries its own bindings (`relation` is the
+ * discriminant — the property exists on no relation or closed value, and
+ * `closed()` reserves the name against handle collisions); a bare relation
+ * or closed relation carries none.
  */
 function faceParts(source: FaceSource): {
 	readonly owner: FaceOwner
@@ -60,10 +78,17 @@ function oneOf<V>(first: V, second: V, ...rest: V[]): OneOf<V> {
 /** The relation a face projects from — ordinary or closed. */
 type FaceOwner = AnyRelation | AnyClosed
 
-/** A face's runtime description: owner, π (written order), σ (resolved bindings). */
-interface FaceData {
-	readonly owner: FaceOwner
-	readonly projection: readonly string[]
+/**
+ * A face's runtime description: owner, π (written order), σ (resolved
+ * bindings). Generic over the owner and projection so a STATEMENT value
+ * carries its paired coordinates at their exact types — the honest runtime
+ * properties (`owner.name`, `projection`) ARE the type-level carrier
+ * `schema()`'s law-typing reads; the defaults are the wide shape every
+ * renderer and lowering walk consumes.
+ */
+interface FaceData<O extends FaceOwner = FaceOwner, P extends readonly string[] = readonly string[]> {
+	readonly owner: O
+	readonly projection: P
 	readonly selection: readonly SelectionBinding[]
 }
 
@@ -72,70 +97,92 @@ interface FaceData {
  * selected relation, or closed relation `on()` was handed — the statement
  * constructors resolve each projected field's DOMAIN through it), and `P`
  * is the projection tuple as written (its length is the positional-pairing
- * arity). Both are honest runtime properties, not phantoms.
+ * arity). Both are honest runtime properties, not phantoms — and `data`
+ * carries the resolved owner at its exact type, which is what a statement
+ * value hands to `schema()`'s law-typing.
  */
 interface Face<S extends FaceSource, P extends readonly string[]> {
 	readonly source: S
 	readonly projection: P
-	readonly data: FaceData
+	readonly data: FaceData<OwnerOf<S>, P>
 }
 
 /** Any face value, whatever its source and projection. */
 type AnyFace = Face<FaceSource, readonly string[]>
 
-/** What `on()` accepts: a relation, a selected relation, or a closed relation. */
-type FaceSource = AnyRelation | AnyClosed | AnySelected
+/** What `on()` accepts: a relation, a closed relation, or either with a selection applied. */
+type FaceSource = AnyRelation | AnyClosed | AnySelected | AnySelectedClosed
 
 /**
  * The field names a face over `S` may project: a relation's declared
  * fields; a selected relation's underlying fields; a closed relation's
- * SEALED shape — the synthetic `id` plus its declared payload columns
- * (`docs/architecture/70-api.md`: statement field names address the sealed
- * shape).
+ * SEALED shape — the synthetic `id` plus its declared payload columns,
+ * bare or ψ-selected alike (`docs/architecture/70-api.md`: statement field
+ * names address the sealed shape).
  */
 type FaceFields<S extends FaceSource> = S extends AnySelected
 	? keyof S["relation"]["fields"] & string
-	: S extends AnyRelation
-		? keyof S["fields"] & string
-		: S extends { readonly axioms: Readonly<Record<string, infer Row>> }
-			? "id" | (keyof Row & string)
-			: never
-
-/** One field's domain label within a declared field block (`undefined` when the name is foreign). */
-type DomainIn<Fields extends FieldsShape, K extends string> = K extends keyof Fields ? Fields[K]["domain"] : undefined
-
-/**
- * The domain LABEL of one projected field, read structurally off the
- * source's schema type — an ordinary or selected relation's field carries
- * its S1 descriptor's `domain`; a closed relation's synthetic `id` carries
- * the handle domain (`"KindId"`), and its payload columns carry their own
- * declared descriptors' labels through the closed value's typed `columns`
- * carrier (whose runtime twin is the frozen `columns` record the mint
- * carries), so a same-label closed-payload ↔ relation-field pairing
- * compiles and a mismatched one refuses — the identical wall every other
- * face position gets. The lowering carries the same label to the engine,
- * which stays the final authority.
- */
-type ProjectedDomain<S extends FaceSource, K extends string> = S extends AnySelected
-	? DomainIn<RelationFields<S["relation"]>, K>
-	: S extends AnyRelation
-		? DomainIn<RelationFields<S>, K>
-		: S extends {
-					readonly id: { readonly domain: infer D extends string }
-					readonly columns: infer Cols extends Record<string, PayloadField>
-				}
-			? K extends "id"
-				? D
-				: DomainIn<Cols, K>
-			: undefined
-
-/** The positionwise domain-label tuple of a projection over `S`. */
-type DomainsOf<S extends FaceSource, P extends readonly string[]> = {
-	readonly [I in keyof P]: ProjectedDomain<S, P[I] & string>
+	: S extends AnySelectedClosed
+		? "id" | (keyof S["relation"]["columns"] & string)
+		: S extends AnyRelation
+			? keyof S["fields"] & string
+			: S extends { readonly axioms: Readonly<Record<string, infer Row>> }
+				? "id" | (keyof Row & string)
+				: never
+
+/**
+ * One descriptor's structural comparand: the kind/width/element triple —
+ * exactly the structure the minimal kernel carries, compared exactly as the
+ * engine's Q1 law pairs positions (`schema/validate.rs`): a `bytes` width is
+ * bound (bytes<16> vs bytes<32> mismatch), while an INTERVAL width is FREE —
+ * the pointwise judgments quantify over points, which carry an element
+ * domain and not a width, so `interval(u64)` pairs with `interval(u64, 1n)`
+ * (recipe 9's extent/slot mirrors, recipe 29's mixed-width zones) and the
+ * width slot reads `undefined` for every interval. Elements stay bound:
+ * u64-vs-i64 interval pairs still mismatch.
+ */
+type ShapeOf<F extends AnyField> = readonly [
+	F["kind"],
+	F extends { readonly element: unknown } ? undefined : F extends { readonly width: infer W } ? W : undefined,
+	F extends { readonly element: infer E } ? E : undefined
+]
+
+/** One field's structural shape within a declared field block (`undefined` when the name is foreign). */
+type ShapeIn<Fields extends FieldsShape, K extends string> = K extends keyof Fields ? ShapeOf<Fields[K]> : undefined
+
+/**
+ * The structural SHAPE of one projected field, read off the source's
+ * schema type — an ordinary or selected relation's field contributes its
+ * descriptor's triple; a closed relation (bare or ψ-selected) contributes
+ * its synthetic `id` as a u64 and its payload columns' declared
+ * descriptors' triples through the closed value's typed `columns` carrier
+ * (whose runtime twin is the frozen `columns` record the mint carries).
+ * The engine stays the final authority at `Db.create`/`Db.open`.
+ */
+type ProjectedShape<S extends FaceSource, K extends string> = S extends AnySelected
+	? ShapeIn<RelationFields<S["relation"]>, K>
+	: S extends AnySelectedClosed
+		? K extends "id"
+			? ShapeOf<S["relation"]["id"]>
+			: ShapeIn<S["relation"]["columns"], K>
+		: S extends AnyRelation
+			? ShapeIn<RelationFields<S>, K>
+			: S extends {
+						readonly id: infer Id extends AnyField
+						readonly columns: infer Cols extends Record<string, PayloadField>
+					}
+				? K extends "id"
+					? ShapeOf<Id>
+					: ShapeIn<Cols, K>
+				: undefined
+
+/** The positionwise structural-shape tuple of a projection over `S`. */
+type ShapesOf<S extends FaceSource, P extends readonly string[]> = {
+	readonly [I in keyof P]: ProjectedShape<S, P[I] & string>
 }
 
-/** The domain-label tuple a face projects, positionwise — the comparand of {@link SameDomains}. */
-type FaceDomains<F extends AnyFace> = F extends Face<infer S, infer P> ? DomainsOf<S, P> : never
+/** The shape tuple a face projects, positionwise — the comparand of {@link SameShapes}. */
+type FaceShapes<F extends AnyFace> = F extends Face<infer S, infer P> ? ShapesOf<S, P> : never
 
 /** The projection arity of a face. */
 type Arity<F extends AnyFace> = F["projection"]["length"]
@@ -165,31 +212,35 @@ type SameArity<A extends AnyFace, B extends AnyFace> =
 		: FaceArityMismatch<Arity<A>, Arity<B>>
 
 /**
- * The legible domain-mismatch verdict: when the two faces of a containment,
- * bijection, or window project different domain labels at any position,
- * this type is intersected into the second face's parameter and names both
- * label tuples — a cross-domain pair is a COMPILE error, achieved by
- * string-literal comparison of descriptor shapes (the structural design's
- * ratified check), never by a value brand.
+ * The legible shape-mismatch verdict: when the two faces of a containment,
+ * bijection, or window project structurally incompatible fields at any
+ * position, this type is intersected into the second face's parameter and
+ * names both shape tuples — a u64 face against a str face, a bytes width
+ * mismatch, or an interval element mismatch is a COMPILE error.
  */
-interface FaceDomainMismatch<Left, Right> {
-	readonly "face domain mismatch — positionwise domain labels must be equal on both sides": readonly [Left, Right]
+interface FaceShapeMismatch<Left, Right> {
+	readonly "face shape mismatch — positionwise kind, width, and element must be equal on both sides": readonly [
+		Left,
+		Right
+	]
 }
 
 /**
  * Resolves to `unknown` (a no-op intersection) when the two faces project
- * positionwise-equal domain labels, and to {@link FaceDomainMismatch}
- * otherwise. Equality is mutual tuple assignability over string-literal
- * labels (`undefined` pairs only with `undefined` — an unlabeled field
- * links only unlabeled fields, mirroring Rust where `u64` and `u64 as
- * HolderId` are different host types).
- */
-type SameDomains<A extends AnyFace, B extends AnyFace> =
-	FaceDomains<A> extends FaceDomains<B>
-		? FaceDomains<B> extends FaceDomains<A>
+ * positionwise-equal structural shapes, and to {@link FaceShapeMismatch}
+ * otherwise. Equality is mutual tuple assignability over the
+ * kind/width/element triples. This is the whole construction-time wall —
+ * deliberately: there is no domain to compare here. The domain wall lives
+ * where domains are BORN: `schema()` computes every field's class from the
+ * statement list and holds the one-generator-per-class law, and query
+ * joins compare class names off the schema type.
+ */
+type SameShapes<A extends AnyFace, B extends AnyFace> =
+	FaceShapes<A> extends FaceShapes<B>
+		? FaceShapes<B> extends FaceShapes<A>
 			? unknown
-			: FaceDomainMismatch<FaceDomains<A>, FaceDomains<B>>
-		: FaceDomainMismatch<FaceDomains<A>, FaceDomains<B>>
+			: FaceShapeMismatch<FaceShapes<A>, FaceShapes<B>>
+		: FaceShapeMismatch<FaceShapes<A>, FaceShapes<B>>
 
 /**
  * Projects a face — one spelling, arity-generic: `on(Account, "holder")`
@@ -206,7 +257,7 @@ function on<S extends FaceSource, const P extends readonly [FaceFields<S>, ...Fa
 	source: S,
 	fields: P
 ): Face<S, P>
-function on(source: FaceSource, fields: string | readonly string[]): Face<FaceSource, readonly string[]> {
+function on<S extends FaceSource>(source: S, fields: string | readonly string[]): Face<S, readonly string[]> {
 	const projection: readonly string[] = Object.freeze(typeof fields === "string" ? [fields] : [...fields])
 	const parts = faceParts(source)
 	const data: FaceData = Object.freeze({
@@ -214,7 +265,33 @@ function on(source: FaceSource, fields: string | readonly string[]): Face<FaceSo
 		projection,
 		selection: parts.selection
 	})
-	return Object.freeze({ source, projection, data })
+	const value = Object.freeze({ source, projection, data })
+	if (!faceMinted<S, readonly string[]>(value, source, projection)) {
+		throw errors.new(`face over ${parts.owner.name}: face construction incomplete`)
+	}
+	return value
+}
+
+/**
+ * The trusted seam of the face mint (the `refsComplete` pattern): the
+ * checkable facts — the value carries exactly the source and projection it
+ * was built from, and `data.owner` is exactly the owner {@link faceParts}
+ * resolves for that source — are verified before the wide construction is
+ * admitted at the exact {@link Face} type (whose `data` claims the owner at
+ * its precise type, the carrier the schema-level law-typing reads).
+ */
+function faceMinted<S extends FaceSource, P extends readonly string[]>(
+	value: { readonly source: FaceSource; readonly projection: readonly string[]; readonly data: FaceData },
+	source: S,
+	projection: P
+): value is Face<S, P> {
+	const owner = "relation" in source ? source.relation : source
+	return (
+		value.source === source &&
+		value.projection === projection &&
+		value.data.owner === owner &&
+		value.data.projection === projection
+	)
 }
 
 /**
@@ -241,13 +318,14 @@ export type {
 	Face,
 	FaceArityMismatch,
 	FaceData,
-	FaceDomainMismatch,
-	FaceDomains,
 	FaceFields,
 	FaceOwner,
+	FaceShapeMismatch,
+	FaceShapes,
 	FaceSource,
 	OneOf,
+	OwnerOf,
 	SameArity,
-	SameDomains
+	SameShapes
 }
 export { on, oneOf, renderFace }