@bjornpagen/bumbledb 1.3.0 → 2.0.0-rc.1

package/src/changes.ts

@@ -1,43 +1,34 @@
 import type { Scope } from "effect"
 import { Effect, Exit, Option, Stream } from "effect"
-import { drainClose, releaseOwner } from "#close.ts"
-import { isClosedMember, membersAgree } from "#closed.ts"
-import type { SchemaId } from "#compile.ts"
-import { Schema as CoreSchema, schemaTables } from "#compile.ts"
-import type { ChangeRecordWire, ChangesHandle, ChangesWire, DraftHandle } from "#db-native.ts"
-import { dbNative } from "#db-native.ts"
-import { SdkInvariantError } from "#errors.ts"
-import { lower } from "#lower.ts"
-import { type AnyRelation, type Fact, relationFields } from "#relation.ts"
-import type { CellValue } from "#rows.ts"
-import { factCellsOf, factOfCells, hostCellCharge } from "#rows.ts"
-import { nativeOperationWith, runtimeHandle } from "#runtime.ts"
-import type { CloseReport } from "#runtime-errors.ts"
-import { argumentError, DbError } from "#runtime-errors.ts"
-import type { AnySchema, SchemaRelation } from "#schema.ts"
-import type { Rel } from "#shape.ts"
-import { bytesValue, recordValue } from "#values.ts"
-
-/**
- * `ChangeSet` — the engine's checked immutable delta:
- * schema-fingerprint-bound canonical native bytes with
- * one-command `(add, remove ∖ add)` normalization and exact same-fact
- * add-wins. Immutable and reusable while open; sealing/submitting it later
- * retains the SAME native value — no second JS row walk ever happens.
- */
-/** Counts of distinct fact additions and removals, never input events. */
-interface ChangeCounts {
-	readonly added: bigint
-	readonly removed: bigint
-}
+import { isClosedMember, membersAgree } from "./closed.ts"
+import type { SchemaId } from "./compile.ts"
+import { compiledOf, schemaTables } from "./compile.ts"
+import { argumentError, DbError, dbError, internalError } from "./errors.ts"
+import type { ChangesRef, DraftRef } from "./native/addon.ts"
+import { addon } from "./native/addon.ts"
+import type { ChangeCounts, ChangeKindOut, ChangeRecordOut, ChangesOut } from "./native/binding.d.ts"
+import { call, drain, release, scoped } from "./native/op.ts"
+import { type AnyRelation, type Fact, relationFields } from "./relation.ts"
+import type { CellValue } from "./rows.ts"
+import { factCellsOf, factOfCells, hostCellCharge } from "./rows.ts"
+import { runtimeHandle } from "./runtime.ts"
+import type { AnySchema, SchemaRelation } from "./schema.ts"
+import { schemaDescriptor } from "./schema.ts"
+import type { Rel } from "./shape.ts"
+import { bytesValue, recordValue } from "./values.ts"
 
 /** A relation-name-discriminated union of plain, fully typed facts. */
 type ChangeRecord<S extends AnySchema> = {
 	[N in keyof S["relations"]]: S["relations"][N] extends AnyRelation
-		? { readonly relation: N; readonly kind: "add" | "remove"; readonly fact: Fact<S["relations"][N]> }
+		? { readonly relation: N; readonly kind: ChangeKindOut; readonly fact: Fact<S["relations"][N]> }
 		: never
 }[keyof S["relations"]]
 
+/**
+ * The engine's checked immutable delta: schema-fingerprint-bound canonical native bytes with
+ * one-command `(add, remove ∖ add)` normalization and exact same-fact add-wins. Reusable while
+ * open; submitting it retains the same native value, so no second row walk happens.
+ */
 interface ChangeSet<S extends AnySchema> {
 	readonly schemaId: SchemaId
 	/** Distinct requested actions; use judge for effective counts against a store. */
@@ -51,26 +42,18 @@ interface ChangeSet<S extends AnySchema> {
 	toBytes(): Effect.Effect<Uint8Array, DbError>
 	/** Commutative add-wins composition into one command, not sequential replay. */
 	compose(other: ChangeSet<S>): Effect.Effect<ChangeSet<S>, DbError, Scope.Scope>
-	close(): Effect.Effect<CloseReport>
 }
 
 /**
- * `ChangeDraft` — the scoped, database-free construction capability.
- * Every method constructs a LAZY effect; execution reads the then-current
- * iterable again on every sequential rerun (no hidden
- * memoization, no automatic retry, no iterator replay). Input must stay
- * stable from an ingestion effect's execution start through its Exit;
- * after successful ingestion the accepted native bytes are independent.
- * Failure/interruption SPENDS the draft and initiates tracked drain.
- * Concurrent/reentrant construction refuses and spends/drains the draft.
- * `finish` consumes the draft; later ingestion or a second finish refuses
- * through the spent capability state.
+ * A scoped, database-free change draft. Each method returns a lazy effect that reads its iterable
+ * when it runs (every rerun reads it again); accepted rows are copied, so later mutation of the
+ * input changes nothing. A failure, an interruption or concurrent use spends the draft; `finish`
+ * consumes it.
  */
 interface ChangeDraft<S extends AnySchema> {
 	insert<R extends Rel<S>>(relation: R, rows: Iterable<Fact<R>>): Effect.Effect<void, DbError>
 	delete<R extends Rel<S>>(relation: R, rows: Iterable<Fact<R>>): Effect.Effect<void, DbError>
 	finish(): Effect.Effect<ChangeSet<S>, DbError, Scope.Scope>
-	close(): Effect.Effect<CloseReport>
 }
 
 /**
@@ -84,32 +67,19 @@ const CHUNK_BYTES = 65536n
 const CHUNK_ROWS = 4096
 
 interface DraftState {
-	readonly handle: DraftHandle
+	readonly handle: DraftRef
 	readonly theory: AnySchema
 	spent: boolean
 	inFlight: boolean
 }
 
-interface ChangesInternal {
-	readonly handle: ChangesHandle
-	readonly schemaId: SchemaId
-	closed: boolean
-}
-
-const changesInternals = new WeakMap<object, ChangesInternal>()
-
-/** Private cross-module accessor (db.apply retains the native ChangeSet). */
-function internalChanges(value: object): ChangesInternal | undefined {
-	return changesInternals.get(value)
-}
-
 function refusal(operation: string, reason: "SpentHandle" | "ClosedHandle" | "InvalidArgument"): DbError {
 	return new DbError({ operation, reason: { _tag: reason } })
 }
 
 interface Chunk {
 	readonly rows: bigint
-	readonly cells: readonly CellValue[]
+	readonly cells: CellValue[]
 	readonly done: boolean
 	readonly leftover: object | undefined
 }
@@ -168,16 +138,13 @@ function pullChunk(relation: AnyRelation, iterator: Iterator<object>, pending: o
 	return { rows, cells, done: false, leftover }
 }
 
-function spendAndDrain(state: DraftState, operation: string): Effect.Effect<void> {
+function spendAndDrain(state: DraftState): Effect.Effect<void> {
 	return Effect.suspend(() => {
 		if (state.spent) {
 			return Effect.void
 		}
 		state.spent = true
-		// Tracked drain: join the native close transition; the report is
-		// diagnostic here (the ingestion failure itself is the caller's
-		// error), but native Closing accounting is never dropped.
-		return drainClose(operation, (callback) => dbNative.runtimeDraftClose(state.handle, callback)).pipe(Effect.asVoid)
+		return drain((done) => addon.runtimeDraftClose(state.handle, done)).pipe(Effect.asVoid)
 	})
 }
 
@@ -187,7 +154,7 @@ function ingest(
 	relation: AnyRelation,
 	rows: Iterable<object>
 ): Effect.Effect<void, DbError> {
-	const verb = operation === "ChangeDraft.insert" ? dbNative.runtimeDraftInsert : dbNative.runtimeDraftDelete
+	const verb = operation === "ChangeDraft.insert" ? addon.runtimeDraftInsert : addon.runtimeDraftDelete
 	return Effect.gen(function* () {
 		if (state.spent) {
 			return yield* Effect.fail(refusal(operation, "SpentHandle"))
@@ -195,7 +162,7 @@ function ingest(
 		if (state.inFlight) {
 			// Reentrant construction refuses AND spends/drains — there is
 			// no implicit queue.
-			yield* spendAndDrain(state, operation)
+			yield* spendAndDrain(state)
 			return yield* Effect.fail(refusal(operation, "SpentHandle"))
 		}
 		if (!membersAgree(state.theory.relations[relation.name], relation)) {
@@ -219,18 +186,19 @@ function ingest(
 					const chunk = yield* Effect.try({
 						try: () => pullChunk(relation, iterator, leftover),
 						catch: (cause) => argumentError(operation, cause)
-					}).pipe(Effect.catch((error) => spendAndDrain(state, operation).pipe(Effect.andThen(Effect.fail(error)))))
+					}).pipe(Effect.catch((error) => spendAndDrain(state).pipe(Effect.andThen(Effect.fail(error)))))
 					leftover = chunk.leftover
 					done = chunk.done && leftover === undefined
 					if (chunk.rows === 0n) {
 						continue
 					}
 					yield* eventLoopTurn()
-					yield* nativeOperationWith(
+					yield* call(
 						operation,
 						(callback) => verb(state.handle, relationId, chunk.rows, chunk.cells, callback),
-						dbNative.runtimeReportTake,
-						() => undefined
+						(lease) => {
+							addon.runtimeStagedTake(lease)
+						}
 					).pipe(
 						Effect.catch((error) =>
 							Effect.sync(() => {
@@ -252,18 +220,18 @@ function ingest(
 			if (state.spent || Exit.isSuccess(exit)) {
 				return Effect.void
 			}
-			return spendAndDrain(state, operation)
+			return spendAndDrain(state)
 		})
 	})
 }
 
 function decodeChangeRecord<S extends AnySchema>(
 	relations: readonly SchemaRelation[],
-	record: ChangeRecordWire
+	record: ChangeRecordOut
 ): ChangeRecord<S> {
 	const relation = relations[record.relation]
-	if (relation === undefined || isClosedMember(relation) || (record.kind !== "add" && record.kind !== "remove")) {
-		throw new SdkInvariantError({ message: "ChangeSet.records: invalid native record descriptor" })
+	if (relation === undefined || isClosedMember(relation)) {
+		throw internalError("ChangeSet.records: invalid native record descriptor")
 	}
 	// Relation id resolves through this schema's own ordered roster. The
 	// shared projector validates all field values before this union seam.
@@ -275,28 +243,25 @@ function decodeChangeRecord<S extends AnySchema>(
 }
 
 function changeRecords<S extends AnySchema>(
-	handle: ChangesHandle,
+	handle: ChangesRef,
 	relations: readonly SchemaRelation[]
 ): Stream.Stream<ChangeRecord<S>, DbError> {
 	return Stream.unwrap(
 		Effect.gen(function* () {
 			const cursor = yield* Effect.acquireRelease(
-				nativeOperationWith(
+				call(
 					"ChangeSet.records",
-					(callback) => dbNative.runtimeChangesCursor(handle, callback),
-					dbNative.runtimeChangesCursorTake,
-					(value) => value
+					(callback) => addon.runtimeChangesCursor(handle, callback),
+					addon.runtimeChangesCursorTake
 				),
-				(value) =>
-					releaseOwner("ChangeCursor.close", (callback) => dbNative.runtimeChangesCursorClose(value, callback)),
+				(value) => release("ChangeCursor.close", (callback) => addon.runtimeChangesCursorClose(value, callback)),
 				{ interruptible: true }
 			)
 			return Stream.paginate(undefined, () =>
-				nativeOperationWith(
+				call(
 					"ChangeSet.records",
-					(callback) => dbNative.runtimeChangesCursorNext(cursor, callback),
-					dbNative.runtimeChangePageTake,
-					(page) => page
+					(callback) => addon.runtimeChangesCursorNext(cursor, callback),
+					addon.runtimeChangePageTake
 				).pipe(
 					Effect.map((page) =>
 						page === null
@@ -312,68 +277,59 @@ function changeRecords<S extends AnySchema>(
 function acquireChanges<S extends AnySchema>(
 	theory: S,
 	schemaId: SchemaId,
-	acquire: Effect.Effect<ChangesWire, DbError>
+	acquire: Effect.Effect<ChangesOut, DbError>
 ): Effect.Effect<ChangeSet<S>, DbError, Scope.Scope> {
-	return Effect.acquireRelease(
-		acquire.pipe(Effect.map((wire) => makeChangeSet(theory, wire, schemaId))),
-		(changes) =>
-			Effect.suspend(() => {
-				const internal = changesInternals.get(changes)
-				if (internal === undefined) return Effect.void
-				internal.closed = true
-				return releaseOwner("ChangeSet.close", (callback) => dbNative.runtimeChangesClose(internal.handle, callback))
-			}),
-		{ interruptible: true }
+	return Effect.map(
+		scoped("ChangeSet.release", acquire, (wire) => (done) => addon.runtimeChangesClose(wire.changes, done)),
+		(wire): ChangeSet<S> => new ChangeSetLive(theory, wire, schemaId)
 	)
 }
 
-function makeChangeSet<S extends AnySchema>(theory: S, wire: ChangesWire, schemaId: SchemaId): ChangeSet<S> {
-	const handle = wire.changes
-	const relations = Object.values(theory.relations)
-	const internal: ChangesInternal = { handle, schemaId, closed: false }
-	const value: ChangeSet<S> = {
-		schemaId,
-		counts: Object.freeze({ ...wire.counts }),
-		byteLength: wire.byteLength,
-		records() {
-			return changeRecords<S>(handle, relations)
-		},
-		toBytes() {
-			return nativeOperationWith(
-				"ChangeSet.toBytes",
-				(callback) => dbNative.runtimeChangesBytes(handle, callback),
-				dbNative.runtimeBytesTake,
-				(bytes) => bytes
-			)
-		},
-		compose(other) {
-			return Effect.suspend(() => {
-				const right = internalChanges(other)
-				if (right === undefined || right.schemaId !== schemaId)
-					return Effect.fail(refusal("ChangeSet.compose", "InvalidArgument"))
-				if (internal.closed || right.closed) return Effect.fail(refusal("ChangeSet.compose", "ClosedHandle"))
-				return acquireChanges(
-					theory,
-					schemaId,
-					nativeOperationWith(
-						"ChangeSet.compose",
-						(callback) => dbNative.runtimeChangesCompose(handle, right.handle, callback),
-						dbNative.runtimeChangesTake,
-						(result) => result
-					)
-				)
-			})
-		},
-		close() {
-			return Effect.suspend(() => {
-				internal.closed = true
-				return drainClose("ChangeSet.close", (callback) => dbNative.runtimeChangesClose(handle, callback))
-			})
-		}
+class ChangeSetLive<S extends AnySchema> implements ChangeSet<S> {
+	readonly #theory: S
+	readonly #handle: ChangesRef
+	readonly schemaId: SchemaId
+	readonly counts: ChangeCounts
+	readonly byteLength: bigint
+
+	constructor(theory: S, wire: ChangesOut, schemaId: SchemaId) {
+		this.#theory = theory
+		this.#handle = wire.changes
+		this.schemaId = schemaId
+		this.counts = Object.freeze({ ...wire.counts })
+		this.byteLength = wire.byteLength
+	}
+
+	records(): Stream.Stream<ChangeRecord<S>, DbError> {
+		return changeRecords<S>(this.#handle, Object.values(this.#theory.relations)).pipe(
+			Stream.withSpan("ChangeSet.records")
+		)
+	}
+
+	toBytes(): Effect.Effect<Uint8Array, DbError> {
+		const handle = this.#handle
+		return call("ChangeSet.toBytes", (done) => addon.runtimeChangesBytes(handle, done), addon.runtimeBytesTake).pipe(
+			Effect.withSpan("ChangeSet.toBytes")
+		)
+	}
+
+	compose(other: ChangeSet<S>): Effect.Effect<ChangeSet<S>, DbError, Scope.Scope> {
+		const left = this.#handle
+		const right = ChangeSetLive.handle(other, this.schemaId)
+		if (right === undefined) return Effect.fail(refusal("ChangeSet.compose", "InvalidArgument"))
+		return acquireChanges(
+			this.#theory,
+			this.schemaId,
+			call("ChangeSet.compose", (done) => addon.runtimeChangesCompose(left, right, done), addon.runtimeChangesTake)
+		).pipe(Effect.withSpan("ChangeSet.compose"))
+	}
+
+	/** The native change set behind `value`, when `value` is one this SDK made for `schemaId`. */
+	static handle(value: object, schemaId: SchemaId): ChangesRef | undefined {
+		if (!(#handle in value)) return undefined
+		const changes = value as unknown as ChangeSetLive<AnySchema>
+		return changes.schemaId === schemaId ? changes.#handle : undefined
 	}
-	Object.freeze(value)
-	changesInternals.set(value, internal)
-	return value
 }
 
 function makeDraft<S extends AnySchema>(theory: S, state: DraftState, schemaId: SchemaId): ChangeDraft<S> {
@@ -393,25 +349,18 @@ function makeDraft<S extends AnySchema>(theory: S, state: DraftState, schemaId:
 						return yield* Effect.fail(refusal("ChangeDraft.finish", "SpentHandle"))
 					}
 					if (state.inFlight) {
-						yield* spendAndDrain(state, "ChangeDraft.finish")
+						yield* spendAndDrain(state)
 						return yield* Effect.fail(refusal("ChangeDraft.finish", "SpentHandle"))
 					}
 					// Finish CONSUMES the draft, success or failure.
 					state.spent = true
-					return yield* nativeOperationWith(
+					return yield* call(
 						"ChangeDraft.finish",
-						(callback) => dbNative.runtimeDraftFinish(state.handle, callback),
-						dbNative.runtimeChangesTake,
-						(value) => value
+						(callback) => addon.runtimeDraftFinish(state.handle, callback),
+						addon.runtimeChangesTake
 					)
 				})
 			)
-		},
-		close() {
-			return Effect.suspend(() => {
-				state.spent = true
-				return drainClose("ChangeDraft.close", (callback) => dbNative.runtimeDraftClose(state.handle, callback))
-			})
 		}
 	}
 	return Object.freeze(draft)
@@ -420,73 +369,61 @@ function makeDraft<S extends AnySchema>(theory: S, state: DraftState, schemaId:
 /**
  * `ChangeSet.builder(schema)` — lazy scoped acquisition of a
  * database-free draft. Requires the acquired
- * `NativeRuntime`; the draft's native resources release with its scope, and
+ * `Bumble`; the draft's native resources release with its scope, and
  * the scope finalizer surfaces incomplete/failed teardown as a
  * `CloseFailure` defect.
  */
 const builder = Effect.fn("ChangeSet.builder")(function* <S extends AnySchema>(schema: S) {
-	const handle = yield* runtimeHandle()
-	const compiled = yield* CoreSchema.compile(schema)
-	const spec = lower(compiled.schema)
-	return yield* Effect.acquireRelease(
-		Effect.gen(function* () {
-			const draftHandle = yield* nativeOperationWith(
-				"ChangeSet.builder",
-				(callback) => dbNative.runtimeDraftOpen(handle, spec, callback),
-				dbNative.runtimeDraftTake,
-				(value) => value
-			)
-			const state: DraftState = {
-				handle: draftHandle,
-				theory: compiled.schema,
+	const handle = yield* runtimeHandle
+	const theory = yield* Effect.try({
+		try: () => schemaDescriptor(schema),
+		catch: (cause) => argumentError("ChangeSet.builder", cause)
+	})
+	const compiled = compiledOf(theory)
+	const state = yield* scoped(
+		"ChangeDraft.release",
+		Effect.try({
+			try: (): DraftState => ({
+				handle: addon.runtimeDraftOpen(handle, compiled.handle),
+				theory,
 				spent: false,
 				inFlight: false
-			}
-			const draft = makeDraft(compiled.schema, state, compiled.schemaId)
-			draftStates.set(draft, state)
-			return draft
-		}),
-		(draft) =>
-			Effect.suspend(() => {
-				const state = draftStates.get(draft)
-				if (state === undefined) {
-					return Effect.void
-				}
-				// Idempotent: repeated close joins the same native
-				// transition; the finalizer runs it unconditionally so an
-				// abandoned draft is always drained.
-				state.spent = true
-				return releaseOwner("ChangeDraft.close", (callback) => dbNative.runtimeDraftClose(state.handle, callback))
 			}),
-		{ interruptible: true }
+			catch: (cause) => dbError("ChangeSet.builder", cause)
+		}),
+		(owned) => (done) => {
+			owned.spent = true
+			addon.runtimeDraftClose(owned.handle, done)
+		}
 	)
+	return makeDraft(theory as S, state, compiled.schemaId)
 })
 
-// The draft value → state registry lets the scope finalizer reach the
-// native handle without exposing it on the public capability.
-const draftStates = new WeakMap<object, DraftState>()
-
 /** Parse canonical native bytes, owning the input when the Effect starts. */
 const fromBytes = Effect.fn("ChangeSet.fromBytes")(function* <S extends AnySchema>(schema: S, bytes: Uint8Array) {
 	const ownedBytes = yield* Effect.try({
 		try: () => bytesValue("ChangeSet.fromBytes", bytes),
 		catch: (cause) => argumentError("ChangeSet.fromBytes", cause)
 	})
-	const handle = yield* runtimeHandle()
-	const compiled = yield* CoreSchema.compile(schema)
+	const handle = yield* runtimeHandle
+	const theory = yield* Effect.try({
+		try: () => schemaDescriptor(schema),
+		catch: (cause) => argumentError("ChangeSet.fromBytes", cause)
+	})
+	const compiled = compiledOf(theory)
 	return yield* acquireChanges(
-		compiled.schema,
+		theory as S,
 		compiled.schemaId,
-		nativeOperationWith(
+		call(
 			"ChangeSet.fromBytes",
-			(callback) => dbNative.runtimeChangesParse(handle, lower(compiled.schema), ownedBytes, callback),
-			dbNative.runtimeChangesTake,
-			(wire) => wire
+			(done) => addon.runtimeChangesParse(handle, compiled.handle, ownedBytes, done),
+			addon.runtimeChangesTake
 		)
 	)
 })
 
 const ChangeSet = Object.freeze({ builder, fromBytes })
 
-export type { ChangeCounts, ChangeDraft, ChangeRecord }
-export { ChangeSet, internalChanges }
+export type { ChangeCounts } from "./native/binding.d.ts"
+export type { ChangeDraft, ChangeRecord }
+export { ChangeSet, ChangeSetLive }

package/src/closed.ts

@@ -1,4 +1,4 @@
-import { AuthoringError } from "#errors.ts"
+import { AuthoringError } from "./errors.ts"
 import {
 	type AnyField,
 	assertDeclarationOrderKey,
@@ -8,8 +8,8 @@ import {
 	type Infer,
 	ownHandles,
 	signaturesAgree
-} from "#fields.ts"
-import { descriptorCache } from "#immutable.ts"
+} from "./fields.ts"
+import { descriptorCache } from "./immutable.ts"
 import {
 	type AnyRelation,
 	type FieldsShape,
@@ -17,8 +17,8 @@ import {
 	type RelationField,
 	relationDescriptor,
 	relationFields
-} from "#relation.ts"
-import { fieldValue, recordValue } from "#values.ts"
+} from "./relation.ts"
+import { fieldValue, recordValue } from "./values.ts"
 
 type PayloadField = AnyField
 type PayloadColumns = FieldsShape & { readonly id?: never }