@bjornpagen/bumbledb 1.3.1 → 2.0.0

package/src/query/run.ts

@@ -1,11 +1,34 @@
-import { AuthoringError, SdkInvariantError } from "#errors.ts"
-import type { QueryParam, TaggedValue } from "#native.ts"
-import type { FindColumn } from "#query/atom.ts"
-import { taggedCmpLiteral } from "#query/lower.ts"
-import type { ParamEntry } from "#query/scope.ts"
-import type { CellValue } from "#rows.ts"
-import { decodeCell, handleOf, setOwnField } from "#rows.ts"
-import { arrayValue, recordValue } from "#values.ts"
+import { AuthoringError, internalError } from "../errors.ts"
+import type { CellIn, ParamIn } from "../native/binding.d.ts"
+import type { CellValue } from "../rows.ts"
+import { decodeCell, handleOf, setOwnField } from "../rows.ts"
+import type { QueryParam, TaggedValue } from "../spec.ts"
+import { arrayValue, recordValue } from "../values.ts"
+import type { FindColumn } from "./atom.ts"
+import { taggedCmpLiteral } from "./lower.ts"
+import type { ParamEntry } from "./scope.ts"
+
+const CELL = {
+	bool: "Bool",
+	u64: "U64",
+	i64: "I64",
+	f64: "F64",
+	string: "String",
+	uuid: "Uuid",
+	fixedBytes: "FixedBytes",
+	intervalU64: "IntervalU64",
+	intervalI64: "IntervalI64",
+	intervalF64: "IntervalF64"
+} as const
+
+/** One tagged value as the addon's data-plane `CellIn`. */
+function cellIn(value: TaggedValue): CellIn {
+	return { ...value, kind: CELL[value.kind] } as CellIn
+}
+
+function paramIn(param: QueryParam): ParamIn {
+	return param.kind === "set" ? { kind: "Set", values: param.values.map(cellIn) } : cellIn(param)
+}
 
 function wireValue(entry: ParamEntry, context: string, value: unknown): TaggedValue {
 	if (entry.anchor === undefined) {
@@ -16,15 +39,15 @@ function wireValue(entry: ParamEntry, context: string, value: unknown): TaggedVa
 	return taggedCmpLiteral(context, entry.anchor, value, entry.op)
 }
 
-function wireParams(entries: readonly ParamEntry[], supplied: Readonly<Record<string, unknown>>): QueryParam[] {
+function wireParams(entries: readonly ParamEntry[], supplied: Readonly<Record<string, unknown>>): ParamIn[] {
 	const input = recordValue(
 		"query parameters",
 		supplied,
 		entries.filter((entry) => entry.membership === undefined).map((entry) => entry.name)
 	)
-	return entries.map(function wireOne(entry): QueryParam {
+	return entries.map(function wireOne(entry): ParamIn {
 		if (entry.membership !== undefined) {
-			return entry.membership
+			return paramIn(entry.membership)
 		}
 		const value = input[entry.name]
 		if (value === undefined) {
@@ -32,13 +55,13 @@ function wireParams(entries: readonly ParamEntry[], supplied: Readonly<Record<st
 		}
 		if (entry.shape === "set") {
 			return {
-				kind: "set",
-				values: arrayValue(`param ${entry.name}`, value, function wireElement(context, element) {
-					return wireValue(entry, context, element)
-				})
+				kind: "Set",
+				values: [
+					...arrayValue(`param ${entry.name}`, value, (context, element) => cellIn(wireValue(entry, context, element)))
+				]
 			}
 		}
-		return wireValue(entry, `param ${entry.name}`, value)
+		return cellIn(wireValue(entry, `param ${entry.name}`, value))
 	})
 }
 
@@ -63,15 +86,13 @@ function isAnswerRow<Row>(
 function decodeAnswers<Row>(finds: readonly FindColumn[], rows: readonly (readonly CellValue[])[]): Row[] {
 	return rows.map(function decodeRow(row) {
 		if (row.length !== finds.length) {
-			throw new SdkInvariantError({
-				message: `query answer arity ${row.length} does not match the ${finds.length} find columns`
-			})
+			throw internalError(`query answer arity ${row.length} does not match the ${finds.length} find columns`)
 		}
 		const decoded: Record<string, unknown> = {}
 		finds.forEach(function decodeColumn(column, ordinal) {
 			const cell = row[ordinal]
 			if (cell === undefined) {
-				throw new SdkInvariantError({ message: `query answer cell ${ordinal} (${column.name}) is absent` })
+				throw internalError(`query answer cell ${ordinal} (${column.name}) is absent`)
 			}
 			if (column.slot !== undefined) {
 				setOwnField(decoded, column.name, decodeCell(`query answer column ${column.name}`, column.slot.field, cell))
@@ -85,7 +106,7 @@ function decodeAnswers<Row>(finds: readonly FindColumn[], rows: readonly (readon
 		})
 		Object.freeze(decoded)
 		if (!isAnswerRow<Row>(finds, decoded)) {
-			throw new SdkInvariantError({ message: "query answer row is not a complete find record" })
+			throw internalError("query answer row is not a complete find record")
 		}
 		return decoded
 	})

package/src/query/scope.ts

@@ -1,18 +1,18 @@
-import type { AnyClosed } from "#closed.ts"
-import { memberDescriptor, sealedFieldsOf } from "#closed.ts"
-import { AuthoringError, SdkInvariantError } from "#errors.ts"
-import type { AnyField, Infer, SignatureOf } from "#fields.ts"
-import { rosterOf, signaturesAgree } from "#fields.ts"
-import type { Same, SameLen } from "#judgment.ts"
-import type { ClassLookup, ClassRecordOf, SchemaClasses } from "#law.ts"
-import type { QueryParam } from "#native.ts"
-import type { FindColumn } from "#query/atom.ts"
-import type { AnyRelation } from "#relation.ts"
-import type { FieldsOf } from "#selection.ts"
-
-const term: unique symbol = Symbol("bumbledb.query.term")
-
-const inferred: unique symbol = Symbol("bumbledb.query.inferred")
+import type { AnyClosed } from "../closed.ts"
+import { memberDescriptor, sealedFieldsOf } from "../closed.ts"
+import { AuthoringError, internalError } from "../errors.ts"
+import type { AnyField, Infer, SignatureOf } from "../fields.ts"
+import { rosterOf, signaturesAgree } from "../fields.ts"
+import type { Same, SameLen } from "../judgment.ts"
+import type { ClassLookup, ClassRecordOf, SchemaClasses } from "../law.ts"
+import type { AnyRelation } from "../relation.ts"
+import type { FieldsOf } from "../selection.ts"
+import type { QueryParam } from "../spec.ts"
+import type { FindColumn } from "./atom.ts"
+
+const term: unique symbol = Symbol("bdb.query.term")
+
+const inferred: unique symbol = Symbol("bdb.query.inferred")
 
 type MatchOwner = AnyRelation | AnyClosed
 
@@ -58,11 +58,10 @@ type VarsOf<R extends MatchOwner> = {
  * mintable variable inhabits. So an aliased or function-returned record
  * carrying an extra key (`{...v(Account), extra: otherVar }` — shapes
  * excess-property checking never sees, it covers inline literals only)
- * fails the intersection and falls to the general form's judgment: the
- * pre-0.16.0 compile refusal, restored. The identity record `v(rel)` still
- * unifies for GENERIC `R` — the judgment is intersections and index
- * constraints only, no deferred conditional anywhere, so the full-binding
- * law (50-generic-binding.md, "The ruling") stands untouched.
+ * fails the intersection and falls to the general form's compile refusal.
+ * The identity record `v(rel)` still unifies for GENERIC `R`: the judgment
+ * is intersections and index constraints only, with no deferred
+ * conditional, so the full-binding law holds.
  */
 type ExactVars<R extends MatchOwner, B> = {
 	readonly [K in keyof B]: Var<AnyField, R["name"], K & keyof MatchFields<R> & string>
@@ -80,21 +79,9 @@ function varsMinted<R extends MatchOwner>(owner: R, record: Readonly<Record<stri
 	})
 }
 
-/**
- * Mints a FRESH batch of query variables over an atom owner's
- * statically-known columns — one variable per sealed column
- * (`sealedFieldsOf`: a closed owner mints `id` first, then payload columns),
- * each frozen and each defined by OWN-property definition (object-protocol
- * column names must work, the `closed` precedent). Every `v` call mints
- * new objects, so two batches are two variables; property access within one
- * batch is stable by construction (the record is an eager frozen record,
- * never a Proxy). Variable identity is the object reference: destructure
- * what you need (`const { id, holder } = v(Account)`) and reuse a value
- * across binding positions to join.
- */
 /**
  * A schema-bound query template used as a relation-expression source
- * (chapter 34's nonrecursive composition): structurally, the query value's
+ * (nonrecursive composition): structurally, the query value's
  * own frozen data. Detection is structural so `scope.ts` needs no runtime
  * import of the query module.
  */
@@ -194,6 +181,11 @@ function importFacadeOfOwner(owner: object): ImportFacade | undefined {
 	return facadeByOwner.get(owner)
 }
 
+/**
+ * Mints fresh query variables, one per column of a relation, closed roster or imported query
+ * (a closed owner's `id` first). Each call mints new variables; reusing one across binding
+ * positions joins, so destructure what you need: `const { id, holder } = v(Account)`.
+ */
 function v<R extends MatchOwner>(owner: R): VarsOf<R>
 function v<Q extends ImportedSource>(imported: Q): ImportVars<Q>
 function v(owner: MatchOwner | ImportedSource): Readonly<Record<string, AnyVar>> {
@@ -203,7 +195,7 @@ function v(owner: MatchOwner | ImportedSource): Readonly<Record<string, AnyVar>>
 		for (const [columnName, column] of facade.columns) {
 			const slot = column.slot
 			if (slot === undefined) {
-				throw new SdkInvariantError({ message: `v(query): facade column ${columnName} lost its slot` })
+				throw internalError(`v(query): facade column ${columnName} lost its slot`)
 			}
 			const variable: AnyVar = Object.freeze({
 				[term]: "var" as const,
@@ -230,7 +222,7 @@ function v(owner: MatchOwner | ImportedSource): Readonly<Record<string, AnyVar>>
 	}
 	Object.freeze(record)
 	if (!varsMinted(member, record)) {
-		throw new SdkInvariantError({ message: `v(${member.name}): variable-record minting incomplete` })
+		throw internalError(`v(${member.name}): variable-record minting incomplete`)
 	}
 	return record
 }
@@ -305,8 +297,8 @@ type ClosedHandles<F extends AnyField> = F extends {
 
 /**
  * Two closed ids anti-join when their handle vectors carry the same Peano
- * length ({@link SameLen}: zero equals zero, successor recurses on
- * successor). A bare field has no vector and proves nothing.
+ * length ({@link SameLen}: zero equals zero, n + 1 recurses on n). A bare
+ * field has no vector and proves nothing.
  */
 type ClosedIdOk<A extends AnyField, B extends AnyField> = [ClosedHandles<A>] extends [never]
 	? false

package/src/query/segments.ts

@@ -1,7 +1,7 @@
-import { AuthoringError } from "#errors.ts"
-import type { IntervalElementKind, IntervalField } from "#fields.ts"
-import { type AnyVar, isTerm, term } from "#query/scope.ts"
-import { recordValue } from "#values.ts"
+import { AuthoringError } from "../errors.ts"
+import type { IntervalElementKind, IntervalField } from "../fields.ts"
+import { recordValue } from "../values.ts"
+import { type AnyVar, isTerm, term } from "./scope.ts"
 
 type IntervalVar<E extends IntervalElementKind = IntervalElementKind> = AnyVar & { readonly field: IntervalField<E> }
 type SegmentOp = "intersection" | "difference"

package/src/relation.ts

@@ -1,13 +1,13 @@
-import { AuthoringError } from "#errors.ts"
+import { AuthoringError } from "./errors.ts"
 import {
 	type AnyField,
 	assertDeclarationOrderKey,
 	assertDeclarationRecord,
 	fieldDescriptor,
 	type Infer
-} from "#fields.ts"
-import { descriptorCache } from "#immutable.ts"
-import { recordValue } from "#values.ts"
+} from "./fields.ts"
+import { descriptorCache } from "./immutable.ts"
+import { recordValue } from "./values.ts"
 
 /** Ordinary relations are structural declarations. Field order defines native ordinals. */
 interface Relation<Name extends string = string, Fields extends FieldsShape = FieldsShape> {

package/src/result.ts

@@ -1,101 +1,74 @@
 import { Effect, Option, Stream } from "effect"
-import { drainClose, releaseOwner } from "#close.ts"
-import type { CursorHandle, ResultHandle } from "#db-native.ts"
-import { dbNative } from "#db-native.ts"
-import type { FindColumn } from "#query/atom.ts"
-import { decodeAnswers } from "#query/run.ts"
-import type { CellValue } from "#rows.ts"
-import { nativeOperationWith } from "#runtime.ts"
-import type { CloseReport, DbError } from "#runtime-errors.ts"
+import type { DbError } from "./errors.ts"
+import type { CursorRef, ResultRef } from "./native/addon.ts"
+import { addon } from "./native/addon.ts"
+import { call, scoped } from "./native/op.ts"
+import type { FindColumn } from "./query/atom.ts"
+import { decodeAnswers } from "./query/run.ts"
+import type { CellValue } from "./rows.ts"
 
 /**
- * One complete answer set, sealed after evaluation and independent of its
- * source snapshot. collect() explicitly materializes all rows into JS and
- * leaves the result available. pages() consumes it once through bounded
- * delivery batches; it does not stream query execution.
- *
- * The stream owns its cursor through Effect scope. Early termination,
- * failure, interruption and EOF close/drain it. Creating the stream does
- * not spend the result; running it twice fails with SpentHandle.
+ * One complete answer set, sealed after evaluation and independent of its snapshot. `collect`
+ * reads every row and leaves the result readable. `pages` spends the result once through
+ * bounded batches; the stream owns its cursor, so ending it early releases the cursor, and
+ * running it a second time fails with `SpentHandle`.
  */
 interface CompleteResult<A> {
 	collect(): Effect.Effect<ReadonlyArray<A>, DbError>
 	pages(): Stream.Stream<ReadonlyArray<A>, DbError>
-	close(): Effect.Effect<CloseReport>
 }
 
-interface ResultInternal {
-	readonly handle: ResultHandle
+function decodePage<A>(finds: readonly FindColumn[], rows: readonly (readonly CellValue[])[]): ReadonlyArray<A> {
+	return Object.freeze(decodeAnswers<A>(finds, rows))
 }
 
-const resultInternals = new WeakMap<object, ResultInternal>()
+class CompleteResultLive<A> implements CompleteResult<A> {
+	readonly #handle: ResultRef
+	readonly #finds: readonly FindColumn[]
 
-/** Private cross-module accessor (scope finalizers in db.ts reach the handle). */
-function internalResult(value: object): ResultInternal | undefined {
-	return resultInternals.get(value)
-}
+	constructor(handle: ResultRef, finds: readonly FindColumn[]) {
+		this.#handle = handle
+		this.#finds = finds
+	}
 
-function decodePage<A>(finds: readonly FindColumn[], rows: readonly (readonly CellValue[])[]): ReadonlyArray<A> {
-	// Owned ordinary records in declared column order — the same fields and
-	// shapes on every page (stable row shape; no Proxy, no per-row fiber).
-	return Object.freeze(decodeAnswers<A>(finds, rows))
-}
+	collect(): Effect.Effect<ReadonlyArray<A>, DbError> {
+		const handle = this.#handle
+		const finds = this.#finds
+		return call(
+			"CompleteResult.collect",
+			(done) => addon.runtimeResultCollect(handle, done),
+			(lease) => decodePage<A>(finds, addon.runtimeRowsTake(lease))
+		).pipe(Effect.withSpan("CompleteResult.collect"))
+	}
 
-/**
- * Internal constructor: `db.ts` publishes results through this after
- * execution completes. Each delivery has independent cooperative cancellation.
- */
-function makeCompleteResult<A>(handle: ResultHandle, finds: readonly FindColumn[]): CompleteResult<A> {
-	const value: CompleteResult<A> = {
-		collect() {
-			return Effect.suspend(() =>
-				nativeOperationWith(
-					"CompleteResult.collect",
-					(callback) => dbNative.runtimeResultCollect(handle, callback),
-					dbNative.runtimeRowsTake,
-					(rows) => decodePage<A>(finds, rows)
+	pages(): Stream.Stream<ReadonlyArray<A>, DbError> {
+		const handle = this.#handle
+		const finds = this.#finds
+		return Stream.unwrap(
+			Effect.gen(function* () {
+				const cursor: CursorRef = yield* scoped(
+					"ResultCursor.release",
+					call("CompleteResult.pages", (done) => addon.runtimeResultCursor(handle, done), addon.runtimeCursorTake),
+					(owned) => (done) => addon.runtimeCursorClose(owned, done)
 				)
-			)
-		},
-		pages() {
-			return Stream.unwrap(
-				Effect.gen(function* () {
-					const cursor: CursorHandle = yield* Effect.acquireRelease(
-						nativeOperationWith(
-							"CompleteResult.pages",
-							(callback) => dbNative.runtimeResultCursor(handle, callback),
-							dbNative.runtimeCursorTake,
-							(taken) => taken
-						),
-						(taken) => releaseOwner("ResultCursor.close", (callback) => dbNative.runtimeCursorClose(taken, callback)),
-						{ interruptible: true }
-					)
-					return Stream.paginate(undefined, () =>
-						nativeOperationWith(
-							"CompleteResult.page",
-							(callback) => dbNative.runtimeCursorNext(cursor, callback),
-							dbNative.runtimePageTake,
-							(page) => page
-						).pipe(
-							Effect.map((page) => {
-								if (page === null) {
-									return [[], Option.none<undefined>()] as const
-								}
-								return [[decodePage<A>(finds, page)], Option.some(undefined)] as const
-							})
+				return Stream.paginate(undefined, () =>
+					call("CompleteResult.page", (done) => addon.runtimeCursorNext(cursor, done), addon.runtimePageTake).pipe(
+						Effect.map((page) =>
+							page === null
+								? ([[], Option.none<undefined>()] as const)
+								: ([[decodePage<A>(finds, page)], Option.some(undefined)] as const)
 						)
 					)
-				})
-			)
-		},
-		close() {
-			return drainClose("CompleteResult.close", (callback) => dbNative.runtimeResultClose(handle, callback))
-		}
+				)
+			})
+		).pipe(Stream.withSpan("CompleteResult.pages"))
+	}
+
+	/** The native result behind `value`, when `value` is a result this SDK made. */
+	static handle(value: object): ResultRef | undefined {
+		return #handle in value ? (value as CompleteResultLive<unknown>).#handle : undefined
 	}
-	Object.freeze(value)
-	resultInternals.set(value, { handle })
-	return value
 }
 
 export type { CompleteResult }
-export { internalResult, makeCompleteResult }
+export { CompleteResultLive }

package/src/rows.ts

@@ -1,46 +1,20 @@
-import { AuthoringError, SdkInvariantError } from "#errors.ts"
+import { AuthoringError, internalError } from "./errors.ts"
 /**
- * The row codec: fact object ⇄ positional cell array by field
- * ordinal, schema-directed, in ONE place. The write side lowers named host
- * objects to rows in the relation's field-declaration order (declaration
- * order = ordinal ids); the read side decodes owned rows back to named
- * objects of BARE structural values. This module is the one fact⇄row
- * projector. It covers all value types: bool, u64, i64,
- * f64, uuid, str, bytes<N>, discrete intervals and dense float intervals,
- * plus the closed-handle bijection (name ⇄ declaration-order row id).
- *
- * Cells here are OWNED plain host values; the native boundary re-judges
- * every crossing against its resident sealed roster. Shape misuse throws
- * the pure {@link AuthoringError}; the Effect ingestion boundary catches
- * and types it (never an untracked partial draft). SharedArrayBuffer-backed
- * views are refused before any copy. Host length is judged before string
- * scans and byte copies.
+ * The one fact ⇄ row projector: named host objects to positional cells in field-declaration order
+ * and back, for every value type plus the closed-handle bijection (name ⇄ declaration-order id).
+ * Cells are owned host values that the native boundary checks again; shape misuse throws
+ * `AuthoringError`. SharedArrayBuffer-backed views are refused before any copy.
  */
-import type { AnyClosedRoster, AnyField } from "#fields.ts"
-import { literalShapeError, rosterOf } from "#fields.ts"
-import { type AnyRelation, type Fact, relationFields } from "#relation.ts"
-import { fieldValue, recordValue } from "#values.ts"
-
-/**
- * One owned cell at the private bridge boundary. The declared sealed field
- * type disambiguates the union: `string` is text, an `uuid` in its
- * canonical hyphenated UUID spelling, or a closed handle
- * before lowering (closed handles cross as `bigint` row ids),
- * `Uint8Array` is `bytes<N>`, `{ start, end }` bigints are a discrete
- * interval and numbers a dense float interval.
- */
-type CellValue =
-	| boolean
-	| bigint
-	| number
-	| string
-	| Uint8Array
-	| { readonly start: bigint; readonly end: bigint }
-	| { readonly start: number; readonly end: number }
+import type { AnyClosedRoster, AnyField } from "./fields.ts"
+import { literalShapeError, rosterOf } from "./fields.ts"
+import type { CellValue } from "./native/binding.d.ts"
+import { type AnyRelation, type Fact, relationFields } from "./relation.ts"
+import { fieldValue, recordValue } from "./values.ts"
 
+/** Row-major cells for `rows` rows, in sealed field order. */
 interface FlatRows {
 	readonly rows: bigint
-	readonly cells: readonly CellValue[]
+	readonly cells: CellValue[]
 }
 
 function recordOf(fact: object): Readonly<Record<string, unknown>> {
@@ -141,7 +115,7 @@ function decodeCell(context: string, field: AnyField, cell: unknown): unknown {
 	try {
 		return fieldValue(context, field, cell)
 	} catch (cause) {
-		if (cause instanceof AuthoringError) throw new SdkInvariantError({ message: cause.message })
+		if (cause instanceof AuthoringError) throw internalError(cause.message)
 		throw cause
 	}
 }
@@ -162,24 +136,22 @@ function isCompleteFact<R extends AnyRelation>(
 function factOfCells<R extends AnyRelation>(relation: R, row: readonly unknown[]): Fact<R> {
 	const data = relation
 	if (row.length !== relationFields(data).length) {
-		throw new SdkInvariantError({
-			message: `relation ${data.name}: row arity ${row.length} does not match the ${relationFields(data).length} declared fields`
-		})
+		throw internalError(
+			`relation ${data.name}: row arity ${row.length} does not match the ${relationFields(data).length} declared fields`
+		)
 	}
 	const decoded: Record<string, unknown> = {}
 	relationFields(data).forEach(function decodeOne(declared, ordinal) {
 		const cell = row[ordinal]
 		if (cell === undefined) {
-			throw new SdkInvariantError({
-				message: `relation ${data.name}: row cell ${ordinal} (${declared.name}) is absent`
-			})
+			throw internalError(`relation ${data.name}: row cell ${ordinal} (${declared.name}) is absent`)
 		}
 		const value = decodeCell(`relation ${data.name} field ${declared.name}`, declared.field, cell)
 		setOwnField(decoded, declared.name, value)
 	})
 	Object.freeze(decoded)
 	if (!isCompleteFact(relation, decoded)) {
-		throw new SdkInvariantError({ message: `relation ${data.name}: decoded row is not a complete fact` })
+		throw internalError(`relation ${data.name}: decoded row is not a complete fact`)
 	}
 	return decoded
 }