@bjornpagen/bumbledb 0.10.0 → 0.12.0

package/src/index.ts

@@ -5,24 +5,22 @@
  * never declared: THE LAWS TYPE THE COLUMNS, `schema()` computing every
  * field's equivalence class FROM the statement list at both tiers), 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, kysely-shaped:
+ * runtime (exclusive-lock stores, transactions, typed violations, scoped
+ * snapshot reads, one-shot `write`/`writeFrom` with `abandon` — PRD-07, zero
+ * closables), the query surface (kysely-shaped:
  * `query(S).rule(r => { const { id, name } = v(Holder); return r.match(Holder, { id, name }).find({ name }) })` —
  * variables minted by `v()` and joined by OBJECT REFERENCE (reuse is the
  * join), the head a `find` RECORD whose keys name the answer columns
  * (renames are real), params still STRING-named, plus negation,
- * conditions, aggregates, and stratified recursion via `program()`/`rec` —
+ * conditions, aggregates, and interiors / one linear rec via
+ * `q.interior` / `q.reach` —
  * `db.prepare` as a plain value; the comparison/connective builders are
  * also free exports, and the free names `eq`/`not`/`and`/`or` collide with
  * common host identifiers — import aliasing is the answer; the SDK does
  * not rename for collision-avoidance), the exhume surface
  * (`Db.exhume` — the one schema-independent read path: the store's
  * self-described shapes and raw facts by name, typed at bare structural
- * values, deliberately schema-free), and the answer-ordering helpers
- * (`by`/`desc` — sort keys as data for the language's own `.sort`; answers
- * are sets, the engine never orders, and limit is the language's own
- * `.slice`). The raw native bridge is not exported.
+ * values, deliberately schema-free). The raw native bridge is not exported.
  */
 
 export type {
@@ -63,7 +61,7 @@ export type {
 	Violation,
 	WriteResult
 } from "#db.ts"
-export { abandon, Db, ErrNewtypeMismatch, ErrWitnessedLivelock, WITNESSED_ATTEMPT_CAP } from "#db.ts"
+export { abandon, Db, ErrGenerationMoved, ErrNewtypeMismatch } from "#db.ts"
 export type {
 	Exhumed,
 	ExhumedAxiom,
@@ -112,21 +110,14 @@ export { bool, bytes, i64, interval, span, str, u64 } from "#fields.ts"
 export type { ClassesOf, ClassWall, LawfulStatements, RelationClasses, SchemaClasses } from "#law.ts"
 export { lower, lowerClosed, lowerRelation } from "#lower.ts"
 export type { KeyFact, Minted } from "#marshal.ts"
-export type {
-	FactValue,
-	OccurrenceDrift,
-	ProgramIr,
-	Staleness,
-	StatementKindTag
-} from "#native.ts"
-export type { Desc, EngineOrderable, SortKey } from "#order.ts"
-export { by, desc } from "#order.ts"
+export type { FactValue, ParsedQuery, QueryIr, StatementKindTag } from "#native.ts"
 
 export type {
 	AnyCond,
 	BindingInput,
 	Cmp,
 	FindColumn,
+	InteriorData,
 	MatchShape,
 	NotAtom,
 	RecData,
@@ -138,29 +129,25 @@ export type { Agg, FindEntry } from "#query/find.ts"
 export type {
 	AnyQuery,
 	AnyRuleValue,
-	OutputRuleChain,
-	OutputRuleScope,
 	Query,
 	QueryData,
 	QueryParams,
+	QueryReachStart,
 	QueryRelation,
 	QueryRow,
 	QueryRuleChain,
 	QueryRuleScope,
 	QueryStart,
-	RecRef,
 	RecRuleChain,
 	RecRuleScope,
 	RuleValue,
 	TermOps
 } from "#query/lower.ts"
 export { lowerQuery, query } from "#query/lower.ts"
-export type { ProgramScope, Rec } from "#query/predicate.ts"
-export { program } from "#query/predicate.ts"
+export { parseQueryIr } from "#query/parse-ir.ts"
 export type {
 	ClassedField,
 	Duration,
-	MaskParam,
 	MatchFields,
 	MatchOwner,
 	Param,

package/src/lower.ts

@@ -96,7 +96,14 @@ function lowerStatement(statement: Statement): StatementSpec {
 				kind: "containment",
 				source: lowerFace(data.source),
 				target: lowerFace(data.target),
-				bidirectional: data.bidirectional
+				bidirectional: false
+			}
+		case "mirrors":
+			return {
+				kind: "containment",
+				source: lowerFace(data.source),
+				target: lowerFace(data.target),
+				bidirectional: true
 			}
 		case "capacity":
 			return {

package/src/native.ts

@@ -41,7 +41,7 @@ type ExhumeHandle = { readonly __brand: "bumbledb.exhume" }
  */
 type TxHandle = { readonly __brand: "bumbledb.tx" }
 
-/** One prepared query/program (plan pinned at prepare). */
+/** One prepared query (plan pinned at prepare). */
 type PreparedHandle = { readonly __brand: "bumbledb.prepared" }
 
 /** A half-open interval `[start, end)` as it crosses the boundary. */
@@ -60,10 +60,9 @@ type FactValue = boolean | bigint | string | Uint8Array | IntervalValue
 
 /**
  * One tagged engine value — the 1:1 mirror of `bumbledb::Value` for the
- * positions no schema field directs (IR literals, query params). The spec's
- * `ValueSpec` vocabulary plus the bind-time-only Allen mask.
+ * positions no schema field directs (IR literals, query params).
  */
-type TaggedValue = ValueSpec | { readonly kind: "allenMask"; readonly mask: number }
+type TaggedValue = ValueSpec
 
 /**
  * One positional execution argument: a tagged scalar, or a param SET
@@ -72,27 +71,44 @@ type TaggedValue = ValueSpec | { readonly kind: "allenMask"; readonly mask: numb
 type QueryParam = TaggedValue | { readonly kind: "set"; readonly values: readonly TaggedValue[] }
 
 /**
- * The IR mirror (`bumbledb::ir`, 1:1): relations, fields, predicates, and
+ * The IR mirror (`bumbledb::ir`, 1:1): relations, fields, interiors, and
  * params by NUMERIC id — the SDK resolves names through the manifest and
- * sends ids; the bridge never sees names in queries. A plain query is sent
- * as its degenerate one-predicate program.
+ * sends ids; the bridge never sees names in queries. Q1 is a tagged sum:
+ * CQ carries no rec; Reach carries `rec` by value.
  */
-interface ProgramIr {
-	readonly predicates: readonly PredicateDefIr[]
-	readonly output: number
-}
+type QueryIr =
+	| {
+			readonly kind: "cq"
+			readonly interiors: readonly InteriorIr[]
+			readonly head: readonly HeadTermIr[]
+			readonly rules: readonly RuleIr[]
+	  }
+	| {
+			readonly kind: "reach"
+			readonly interiors: readonly InteriorIr[]
+			readonly rec: RecIr
+			readonly head: readonly HeadTermIr[]
+			readonly rules: readonly RuleIr[]
+	  }
 
-/** One predicate: the head shape its rules align against, and the rules. */
-interface PredicateDefIr {
+/** One named interior: the head shape its rules align against, and the rules. */
+interface InteriorIr {
 	readonly head: readonly HeadTermIr[]
 	readonly rules: readonly RuleIr[]
 }
 
+/** The linear rec on a Reach query: shared head, base arms, rec arms. */
+interface RecIr {
+	readonly head: readonly HeadTermIr[]
+	readonly base: readonly RuleIr[]
+	readonly rec: readonly RuleIr[]
+}
+
 /** One head position: a plain variable slot or an aggregate-op kind. */
 type HeadTermIr = { readonly kind: "var" } | { readonly kind: "aggregate"; readonly op: HeadOpIr }
 
 /** The var-free aggregate-op kind at a head position. */
-type HeadOpIr = "sum" | "min" | "max" | "count" | "countDistinct" | "argMax" | "argMin" | "pack"
+type HeadOpIr = "sum" | "min" | "max" | "count" | "pack"
 
 /** One rule: conjunctive body, anti-join atoms, condition trees. */
 interface RuleIr {
@@ -102,12 +118,23 @@ interface RuleIr {
 	readonly conditions: readonly ConditionTreeIr[]
 }
 
-/** One find term (mirrors `ir::FindTerm`). */
+/** One find term (mirrors `ir::FindTerm`). Count carries no `over`; folds require it. */
+type FoldOpIr = { readonly kind: "sum" } | { readonly kind: "min" } | { readonly kind: "max" }
+
+type ArgOpIr = FoldOpIr | { readonly kind: "pack" }
+
 type FindTermIr =
 	| { readonly kind: "var"; readonly var: number }
-	| { readonly kind: "aggregate"; readonly op: AggOpIr; readonly over?: number }
+	| { readonly kind: "aggregate"; readonly op: { readonly kind: "count" } }
+	| { readonly kind: "aggregate"; readonly op: ArgOpIr; readonly over: number }
 	| { readonly kind: "measure"; readonly var: number }
-	| { readonly kind: "aggregateMeasure"; readonly op: AggOpIr; readonly over: number }
+	| { readonly kind: "aggregateMeasure"; readonly op: FoldOpIr; readonly over: number }
+
+/** Host brand: only {@link parseQueryIr} and `lowerQuery` inhabit this. Phantom — not a runtime key. */
+declare const parsedQueryBrand: unique symbol
+
+/** A `QueryIr` that passed the host shape parse (rec/main nonempty, aggregate finds split). */
+type ParsedQuery = QueryIr & { readonly [parsedQueryBrand]: true }
 
 /** One aggregate operator (mirrors `ir::AggOp`; Arg ops carry their key). */
 type AggOpIr =
@@ -115,15 +142,12 @@ type AggOpIr =
 	| { readonly kind: "min" }
 	| { readonly kind: "max" }
 	| { readonly kind: "count" }
-	| { readonly kind: "countDistinct" }
-	| { readonly kind: "argMax"; readonly key: number }
-	| { readonly kind: "argMin"; readonly key: number }
 	| { readonly kind: "pack" }
 
-/** Where an atom draws its facts: a stored relation or a program predicate. */
+/** Where an atom draws its facts: a stored relation or a derived table. */
 type AtomSourceIr =
 	| { readonly kind: "edb"; readonly relation: number }
-	| { readonly kind: "idb"; readonly pred: number }
+	| { readonly kind: "interior"; readonly interior: number }
 
 /**
  * One atom: named-field bindings as `[fieldId, term]` pairs; absence of a
@@ -142,11 +166,6 @@ type TermIr =
 	| { readonly kind: "literal"; readonly value: TaggedValue }
 	| { readonly kind: "measure"; readonly var: number }
 
-/** The `Allen` comparison's mask position: a literal mask or a param. */
-type MaskTermIr =
-	| { readonly kind: "literal"; readonly mask: number }
-	| { readonly kind: "param"; readonly param: number }
-
 /** One comparison operator (mirrors `ir::CmpOp`). */
 type CmpOpIr =
 	| { readonly kind: "eq" }
@@ -155,7 +174,7 @@ type CmpOpIr =
 	| { readonly kind: "le" }
 	| { readonly kind: "gt" }
 	| { readonly kind: "ge" }
-	| { readonly kind: "allen"; readonly mask: MaskTermIr }
+	| { readonly kind: "allen"; readonly mask: number }
 	| { readonly kind: "pointIn" }
 
 /** One comparison condition. */
@@ -236,14 +255,27 @@ interface ViolationFact {
  * accumulates in u128 and the value crosses WHOLE as bigint (C3:
  * truncation is unrepresentable).
  */
-interface Violation {
-	readonly statementId: number
-	readonly kind: StatementKindTag
-	readonly canonical: string
-	readonly direction?: "sourceUnsatisfied" | "targetRequired"
-	readonly measure?: bigint
-	readonly facts: readonly ViolationFact[]
-}
+type Violation =
+	| {
+			readonly statementId: number
+			readonly kind: "functionality"
+			readonly canonical: string
+			readonly facts: readonly ViolationFact[]
+	  }
+	| {
+			readonly statementId: number
+			readonly kind: "containment"
+			readonly canonical: string
+			readonly direction: "sourceUnsatisfied" | "targetRequired"
+			readonly facts: readonly ViolationFact[]
+	  }
+	| {
+			readonly statementId: number
+			readonly kind: "capacity"
+			readonly canonical: string
+			readonly measure: bigint
+			readonly facts: readonly ViolationFact[]
+	  }
 
 /**
  * `dbCreate`/`dbOpen`'s domain outcome. `schemaError` spans both spec
@@ -349,7 +381,8 @@ interface Explain {
 	readonly subsumed: ReadonlyArray<Readonly<Record<string, unknown>>>
 	readonly dead: ReadonlyArray<Readonly<Record<string, unknown>>>
 	readonly rules: ReadonlyArray<Readonly<Record<string, unknown>>>
-	readonly strata: ReadonlyArray<Readonly<Record<string, unknown>>>
+	readonly interiors: ReadonlyArray<Readonly<Record<string, unknown>>>
+	readonly reach?: Readonly<Record<string, unknown>>
 }
 
 interface Native {
@@ -494,13 +527,13 @@ interface Native {
 	txAbort(tx: TxHandle): void
 
 	/**
-	 * Prepares a program (IR as data, ids only; plan pinned at prepare).
+	 * Prepares a query (IR as data, ids only; plan pinned at prepare).
 	 * Roster errors return as data.
 	 */
-	dbPrepare(db: DbHandle, program: ProgramIr): PrepareResult
+	dbPrepare(db: DbHandle, query: ParsedQuery): PrepareResult
 	/**
 	 * Executes against a snapshot with positional params. One-copy owned
-	 * rows out, column order = the program's head order; answers are a set
+	 * rows out, column order = the query's head order; answers are a set
 	 * — the host sorts.
 	 */
 	preparedExecute(prepared: PreparedHandle, snap: SnapshotHandle, params: readonly QueryParam[]): FactValue[][]
@@ -608,6 +641,7 @@ function bridged<T>(context: string, run: () => T): T {
 
 export type {
 	AggOpIr,
+	ArgOpIr,
 	AtomIr,
 	AtomSourceIr,
 	CmpOpIr,
@@ -621,22 +655,24 @@ export type {
 	Explain,
 	FactValue,
 	FindTermIr,
+	FoldOpIr,
 	HeadOpIr,
 	HeadTermIr,
+	InteriorIr,
 	IntervalValue,
 	Manifest,
 	ManifestField,
 	ManifestRelation,
 	ManifestRow,
 	ManifestStatement,
-	MaskTermIr,
 	Native,
 	OccurrenceDrift,
-	PredicateDefIr,
+	ParsedQuery,
 	PreparedHandle,
 	PrepareResult,
-	ProgramIr,
+	QueryIr,
 	QueryParam,
+	RecIr,
 	RuleIr,
 	SnapshotHandle,
 	SnapshotOpened,