@bjornpagen/bumbledb 0.1.0 → 0.2.0

package/src/index.ts

@@ -1,21 +1,21 @@
 /**
  * @bjornpagen/bumbledb — the type-theoretic TypeScript SDK for the
- * bumbledb embedded relational engine. Public surface: the type kernel
- * (brands, fields, `relation()`, `closed()` — PRD-05), the statement
+ * bumbledb embedded relational engine. Public surface: the structural type
+ * kernel (fields with schema-level domain labels, `relation()`,
+ * `closed()`), the statement
  * algebra with `schema()` and `SchemaSpec` lowering (PRD-06), the `Db`
  * runtime (path-cached stores, transactions, typed violations, scoped
  * snapshot reads, the witnessed write loop with `abandon` — PRD-07, zero
- * closables), the query surface (Datalog as values: scoped vars/params,
- * atoms, negation, conditions, aggregates, engine recursion via predicates,
- * `db.prepare` as a plain value — PRD-08), and the exhume surface
+ * closables), the query surface (Datalog as values, kysely-shaped:
+ * `query(S).rule(r => r.match(...).where(...).select(...))` with
+ * string-named domain-typed vars, params typed by use, negation,
+ * conditions, aggregates, and stratified recursion via `program()`/`rec` —
+ * `db.prepare` as a plain value), and the exhume surface
  * (`Db.exhume` — the one schema-independent read path: the store's
- * self-described shapes and raw facts by name, deliberately untyped —
- * course-serialization PRD-02). The raw native bridge is not exported (the
- * PRD-03 stub died here as scheduled).
+ * self-described shapes and raw facts by name, typed at bare structural
+ * values, deliberately schema-free). The raw native bridge is not exported.
  */
 
-export type { Brand, Interval, IntervalValue } from "#brand.ts"
-export { span } from "#brand.ts"
 export type {
 	AnyClosed,
 	AxiomRow,
@@ -63,34 +63,35 @@ export type {
 	Face,
 	FaceArityMismatch,
 	FaceData,
+	FaceDomainMismatch,
+	FaceDomains,
 	FaceFields,
 	FaceOwner,
 	FaceSource,
 	OneOf,
-	SameArity
+	SameArity,
+	SameDomains
 } from "#face.ts"
 export { on, oneOf } from "#face.ts"
 export type {
 	AnyField,
 	BoolField,
+	BytesCtor,
 	BytesField,
-	BytesNewtype,
 	ClosedIdField,
 	ClosedRoster,
-	Field,
-	FieldData,
-	FieldValue,
-	FreshU64Newtype,
+	FreshU64Field,
+	I64Ctor,
 	I64Field,
-	I64Newtype,
 	Infer,
+	IntervalCtor,
 	IntervalField,
-	IntervalNewtype,
+	IntervalValue,
 	StrField,
-	U64Field,
-	U64Newtype
+	U64Ctor,
+	U64Field
 } from "#fields.ts"
-export { bool, bytes, i64, interval, str, u64 } from "#fields.ts"
+export { bool, bytes, i64, interval, span, str, u64 } from "#fields.ts"
 export { lower, lowerClosed, lowerRelation } from "#lower.ts"
 export type { KeyFact, Minted } from "#marshal.ts"
 export type {
@@ -102,51 +103,41 @@ export type {
 } from "#native.ts"
 
 export type {
-	AnyBodyItem,
-	AnyCondition,
-	ComparisonItem,
-	ConditionTreeItem,
-	Duration,
-	MatchAtom,
-	MatchInput,
-	TermInput
+	AnyCond,
+	BindingInput,
+	Cmp,
+	MatchShape,
+	NotAtom,
+	RecData,
+	RuleData,
+	SelectColumn,
+	Tree
 } from "#query/atom.ts"
-
-export {
-	ALLEN,
-	allen,
-	and,
-	covers,
-	duration,
-	ge,
-	gt,
-	is,
-	le,
-	lt,
-	match,
-	ne,
-	not,
-	or
-} from "#query/atom.ts"
-
+export { ALLEN } from "#query/atom.ts"
 export type {
 	AnyQuery,
+	AnyRuleValue,
+	OutputRuleChain,
+	OutputRuleScope,
 	Query,
-	QueryBuild,
+	QueryData,
 	QueryParams,
+	QueryRelation,
 	QueryRow,
-	Scope
+	QueryRuleChain,
+	QueryRuleScope,
+	QueryStart,
+	RecRef,
+	RecRuleChain,
+	RecRuleScope,
+	RuleValue,
+	TermOps
 } from "#query/lower.ts"
 export { lowerQuery, query } from "#query/lower.ts"
-export type {
-	Predicate,
-	PredicateBindings,
-	PredicateRuleInput,
-	PredicateSelf
-} from "#query/predicate.ts"
-export type { MaskParam, Param, ParamSet, ParamsRecord, Var } from "#query/scope.ts"
-export type { Aggregate, RowOf, SelectShape } from "#query/select.ts"
-export { argmax, argmin, count, countDistinct, max, min, pack, sum } from "#query/select.ts"
+export type { ProgramScope, Rec } from "#query/predicate.ts"
+export { program } from "#query/predicate.ts"
+export type { Duration, MaskParam, Param, ParamEntry, ParamsRecord, SetParam, Var } from "#query/scope.ts"
+export type { Agg, SelectEntry } from "#query/select.ts"
 export type {
 	AnyRelation,
 	AnySelected,
@@ -181,5 +172,5 @@ export type {
 	WindowSpec
 } from "#spec.ts"
 export { renderLiteral, renderLiteralSet, renderWindow } from "#spec.ts"
-export type { KeyStatement, Statement, StatementData } from "#statements.ts"
+export type { KeyData, KeyStatement, Statement, StatementData } from "#statements.ts"
 export { contained, key, mirrors, renderStatement, window } from "#statements.ts"

package/src/lower.ts

@@ -10,9 +10,18 @@
 
 import type { AnyClosed } from "#closed.ts"
 import type { FaceData } from "#face.ts"
+import type { AnyField } from "#fields.ts"
 import type { AnyRelation } from "#relation.ts"
 import type { AnySchema, SchemaRelation } from "#schema.ts"
-import type { FieldSpec, RelationSpec, SchemaSpec, SideSpec, StatementSpec } from "#spec.ts"
+import type {
+	FieldSpec,
+	LiteralSetSpec,
+	RelationSpec,
+	SchemaSpec,
+	SideSpec,
+	StatementSpec,
+	ValueTypeSpec
+} from "#spec.ts"
 import type { Statement } from "#statements.ts"
 
 /**
@@ -23,13 +32,53 @@ function isClosedMember(member: SchemaRelation): member is AnyClosed {
 	return "handles" in member.data
 }
 
+/**
+ * Lowers one field descriptor's structural type to the wire
+ * {@link ValueTypeSpec}: the S1 kind tags map 1:1 onto the `ValueType`
+ * vocabulary (`str` spells `string`, `bytes` spells `fixedBytes` with its
+ * width label as `len`; intervals carry element and width labels through).
+ */
+function valueTypeOf(field: AnyField): ValueTypeSpec {
+	switch (field.kind) {
+		case "bool":
+			return { kind: "bool" }
+		case "u64":
+			return { kind: "u64" }
+		case "i64":
+			return { kind: "i64" }
+		case "str":
+			return { kind: "string" }
+		case "bytes":
+			return { kind: "fixedBytes", len: field.width }
+		case "interval":
+			return { kind: "interval", element: field.element, width: field.width }
+	}
+}
+
+/**
+ * Lowers one field descriptor to its {@link FieldSpec}: the structural
+ * type, the DOMAIN label as the wire's `newtype` (the macro's `as NewType`
+ * name — carried for engine handle resolution, dropped at descriptor
+ * lowering, never fingerprinted), and the structural fresh mark (`fresh`
+ * is the literal `true` exactly on a fresh-marked u64 — on an unmarked one
+ * the property holds the marked descriptor, never `true`).
+ */
+function lowerField(name: string, field: AnyField): FieldSpec {
+	return {
+		name,
+		valueType: valueTypeOf(field),
+		newtype: field.domain,
+		fresh: "fresh" in field && field.fresh === true
+	}
+}
+
 /** Lowers one face to a `SideSpec`: names only, σ as (field, set) pairs. */
 function lowerFace(face: FaceData): SideSpec {
 	return {
 		relation: face.owner.name,
 		projection: [...face.projection],
-		selection: face.selection.map(function lowerBinding(binding) {
-			return [binding.field, binding.set] as const
+		selection: face.selection.map(function lowerBinding(binding): readonly [string, LiteralSetSpec] {
+			return [binding.field, binding.set]
 		})
 	}
 }
@@ -67,13 +116,8 @@ function lowerStatement(statement: Statement): StatementSpec {
  * declaration order, `extension: undefined` (the option is the kind).
  */
 function lowerRelation(relation: AnyRelation): RelationSpec {
-	const fields: FieldSpec[] = relation.data.fields.map(function lowerField(declared) {
-		return {
-			name: declared.name,
-			valueType: declared.field.type,
-			newtype: declared.field.newtype,
-			fresh: declared.field.minted
-		}
+	const fields: FieldSpec[] = relation.data.fields.map(function lowerDeclared(declared) {
+		return lowerField(declared.name, declared.field)
 	})
 	return { name: relation.name, newtype: undefined, fields, extension: undefined }
 }
@@ -81,23 +125,21 @@ function lowerRelation(relation: AnyRelation): RelationSpec {
 /**
  * Lowers one closed relation to its `RelationSpec` fragment: declared
  * intrinsic columns only (the engine materializes the synthetic `id`),
- * the relation's own name as its handle newtype, and the ground axioms in
- * declaration order (row id = index) — the literals were already lowered
- * at `closed()` construction.
+ * the HANDLE DOMAIN as its handle newtype — the `id` descriptor's own
+ * `` `${name}Id` `` label (Rust's `closed relation Kind as KindId`), the
+ * same string every referencing field carries, which is exactly how the
+ * engine resolves a handle literal back to its roster — and the ground
+ * axioms in declaration order (row id = index); the literals were already
+ * lowered at `closed()` construction.
  */
 function lowerClosed(member: AnyClosed): RelationSpec {
 	const fields: FieldSpec[] = member.data.columns.map(function lowerColumn(column) {
-		return {
-			name: column.name,
-			valueType: column.field.type,
-			newtype: column.field.newtype,
-			fresh: false
-		}
+		return lowerField(column.name, column.field)
 	})
 	const extension = member.data.rows.map(function lowerRow(row) {
 		return { handle: row.handle, values: row.values }
 	})
-	return { name: member.name, newtype: member.name, fields, extension }
+	return { name: member.name, newtype: member.id.domain, fields, extension }
 }
 
 /**

package/src/marshal.ts

@@ -1,24 +1,39 @@
 /**
- * The marshal layer (PRD-07): fact object ⇄ positional `FactValue[]` by
- * field ordinal, schema-directed, in ONE place only. The write side lowers
- * named host objects to rows in the relation's field-declaration order
+ * The marshal layer: fact object ⇄ positional `FactValue[]` by field
+ * ordinal, schema-directed, in ONE place only. The write side lowers named
+ * host objects to rows in the relation's field-declaration order
  * (declaration order = ordinal ids, the macro's law); the read side decodes
- * rows back to named objects with brands applied by assertion — the store
- * is the proof carrier: a row the engine admitted IS a legal fact of its
- * relation, so readback asserts the brand instead of re-judging the value
- * (the same trust direction as Rust's typed readback). Shape mismatches
- * here are genuine failures and THROW typed; they are never domain data.
+ * rows back to named objects of BARE structural values — the marshal
+ * boundary is pure both ways. CAST-FREE, LITERALLY: with structural values
+ * there is no brand to assert on the way out (the historical "one
+ * sanctioned marshal cast" died with the brand era), so product code
+ * carries zero casts — the only trusted seams are the completeness
+ * PREDICATES below, which verify the checkable half (every declared field
+ * present) and rely on the store as the proof carrier for the rest: a row
+ * the engine admitted IS a legal fact of its relation (the same trust
+ * direction as Rust's typed readback). Shape mismatches here are genuine
+ * failures and THROW typed; they are never domain data.
  */
 
 import * as errors from "@superbuilders/errors"
-import type { FieldData } from "#fields.ts"
+import type { AnyField } from "#fields.ts"
 import type { FactValue } from "#native.ts"
 import type { AnyRelation, Fact, FreshKeys, RelationData } from "#relation.ts"
 
+/**
+ * The fresh-mark probe: `true` exactly for a `.fresh`-marked u64 descriptor
+ * (the S1 kernel's one structural mark — an unmarked u64's `fresh` property
+ * holds the MARKED descriptor, so the probe compares against the literal
+ * `true`, never truthiness).
+ */
+function isFreshField(field: AnyField): boolean {
+	return "fresh" in field && field.fresh === true
+}
+
 /**
  * The inferred object type `tx.insert` returns: one property per
- * fresh-marked field of `R`, carrying the minted (or resupplied) branded
- * id. A relation with no fresh field returns the empty object.
+ * fresh-marked field of `R`, carrying the minted (or resupplied) id as a
+ * bare `bigint`. A relation with no fresh field returns the empty object.
  */
 type Minted<R extends AnyRelation> = { [K in FreshKeys<R>]: Fact<R>[K] }
 
@@ -30,7 +45,8 @@ type Minted<R extends AnyRelation> = { [K in FreshKeys<R>]: Fact<R>[K] }
  * relation's primary key is always its fresh field. When `R` carries a
  * fresh field the type demands exactly that field; otherwise the primary
  * key lives in the schema's statement list, which the type system cannot
- * see (statements are untyped values), so the type admits any partial fact
+ * see (the schema's statement list is not carried in the schema's type,
+ * only in the KeyStatement values themselves), so the type admits any partial fact
  * and the projection is verified at runtime — a missing key field throws
  * naming the projection.
  */
@@ -66,12 +82,13 @@ function recordOf(fact: object): Record<string, unknown> {
 
 /**
  * Marshals one host cell at its field position to the natural wire value,
- * schema-directed by the field's structural type (never guessed). Brands
- * are phantoms, so the runtime values are exactly the wire's natural JS
- * values; only widths and domains are left to the engine's own judge.
+ * schema-directed by the field descriptor's structural kind (never
+ * guessed). Values are bare, so the runtime values ARE the wire's natural
+ * JS values; widths and domain labels are the engine's own judgment at the
+ * write boundary.
  */
-function cellOf(context: string, field: FieldData, value: unknown): FactValue {
-	switch (field.type.kind) {
+function cellOf(context: string, field: AnyField, value: unknown): FactValue {
+	switch (field.kind) {
 		case "bool": {
 			if (typeof value !== "boolean") {
 				throw cellShapeError(context, "boolean", value)
@@ -85,7 +102,7 @@ function cellOf(context: string, field: FieldData, value: unknown): FactValue {
 			}
 			return value
 		}
-		case "string": {
+		case "str": {
 			if (typeof value !== "string") {
 				throw cellShapeError(context, "string", value)
 			}
@@ -101,7 +118,7 @@ function cellOf(context: string, field: FieldData, value: unknown): FactValue {
 			}
 			return value
 		}
-		case "fixedBytes": {
+		case "bytes": {
 			if (!(value instanceof Uint8Array)) {
 				throw cellShapeError(context, "Uint8Array", value)
 			}
@@ -162,11 +179,11 @@ function keyRowOf(
 
 /**
  * The read-side trusted seam: a decoded row carrying every declared field
- * IS a fact of its relation — the engine admitted it, so the brand is
- * asserted, not re-derived. The checkable half (completeness) is verified;
- * the phantom half (brands) is carried by the store's own judgment.
+ * IS a fact of its relation — the engine admitted the row, and the values
+ * are BARE structural values, so nothing is asserted beyond presence (no
+ * brand exists to re-derive; the store is the proof carrier).
  */
-function isBrandedFact<R extends AnyRelation>(
+function isCompleteFact<R extends AnyRelation>(
 	relation: R,
 	decoded: Readonly<Record<string, FactValue>>
 ): decoded is Readonly<Record<string, FactValue>> & Fact<R> {
@@ -178,21 +195,22 @@ function isBrandedFact<R extends AnyRelation>(
 /**
  * The insert-return trusted seam: the collected fresh cells of one insert
  * (minted by the engine or resupplied by the caller) are the relation's
- * branded fresh ids — same assertion direction as {@link isBrandedFact}.
+ * fresh ids as bare bigints — same presence-only direction as
+ * {@link isCompleteFact}.
  */
 function isMintedFresh<R extends AnyRelation>(
 	relation: R,
 	minted: Readonly<Record<string, FactValue>>
 ): minted is Readonly<Record<string, FactValue>> & Minted<R> {
 	return relation.data.fields.every(function presentWhenFresh(declared) {
-		return !declared.field.minted || minted[declared.name] !== undefined
+		return !isFreshField(declared.field) || minted[declared.name] !== undefined
 	})
 }
 
 /**
- * Unmarshals one positional row to the relation's named, branded, frozen
- * fact object — the inverse of {@link rowOf}, ordinal-directed by the same
- * declaration order.
+ * Unmarshals one positional row to the relation's named, frozen fact object
+ * of bare structural values — the inverse of {@link rowOf},
+ * ordinal-directed by the same declaration order.
  */
 function factOf<R extends AnyRelation>(relation: R, row: readonly FactValue[]): Fact<R> {
 	const data = relation.data
@@ -210,11 +228,11 @@ function factOf<R extends AnyRelation>(relation: R, row: readonly FactValue[]):
 		decoded[declared.name] = cell
 	})
 	Object.freeze(decoded)
-	if (!isBrandedFact(relation, decoded)) {
+	if (!isCompleteFact(relation, decoded)) {
 		throw errors.new(`relation ${data.name}: decoded row is not a complete fact`)
 	}
 	return decoded
 }
 
 export type { KeyFact, Minted }
-export { cellOf, factOf, isMintedFresh, keyRowOf, recordOf, rowOf }
+export { cellOf, factOf, isFreshField, isMintedFresh, keyRowOf, recordOf, rowOf }

package/src/native.ts

@@ -479,8 +479,8 @@ const SHIPPED_PLATFORMS = "darwin-arm64"
  * It resolves the per-platform binary package by name (see
  * {@link loadNativeBinding}); the addon never crosses as a relative path.
  * createRequire is the only unflagged Node-API addon loader in ESM, and this
- * file is the package's single sanctioned FFI boundary
- * (docs/road-to-1.0.0/prd-03-arch-split-packaging.md).
+ * file is the package's single sanctioned FFI boundary (the arch-split
+ * packaging ruling).
  */
 const requireNative = createRequire(import.meta.url)