@bjornpagen/bumbledb 1.3.0 → 2.0.0-rc.1

package/src/codec.ts

@@ -1,41 +1,26 @@
 import { Effect, Schema as EffectSchema, Result } from "effect"
-import { membersAgree } from "#closed.ts"
-import { schemaTables } from "#compile.ts"
-import { dbNative } from "#db-native.ts"
-import { AuthoringError } from "#errors.ts"
-import type { AnyField } from "#fields.ts"
-import { lower } from "#lower.ts"
-import { type AnyRelation, type Fact, relationDescriptor, relationFields } from "#relation.ts"
-import type { CellValue } from "#rows.ts"
-import { factOfCells, flatRowsOf } from "#rows.ts"
-import { nativeOperationWith, runtimeHandle } from "#runtime.ts"
-import { argumentError, DbError } from "#runtime-errors.ts"
-import type { AnySchema } from "#schema.ts"
-import { schemaDescriptor } from "#schema.ts"
-import type { Rel } from "#shape.ts"
-import { f64BitsHex } from "#spec.ts"
-import { fieldValue, recordValue } from "#values.ts"
+import { membersAgree } from "./closed.ts"
+import { compiledOf, schemaTables } from "./compile.ts"
+import { AuthoringError, argumentError, DbError } from "./errors.ts"
+import { type AnyField, fieldDescriptor, type Infer } from "./fields.ts"
+import { addon } from "./native/addon.ts"
+import { call } from "./native/op.ts"
+import { type AnyRelation, type Fact, relationDescriptor, relationFields } from "./relation.ts"
+import type { CellValue } from "./rows.ts"
+import { factOfCells, flatRowsOf } from "./rows.ts"
+import { runtimeHandle } from "./runtime.ts"
+import type { AnySchema } from "./schema.ts"
+import { schemaDescriptor } from "./schema.ts"
+import type { Rel } from "./shape.ts"
+import { f64BitsHex } from "./spec.ts"
+import { fieldValue, recordValue } from "./values.ts"
 
 /**
- * Boundary row codecs, derived from the core relation descriptors — never a
- * second hand-maintained field roster.
- *
- * Two layers:
- *
- * 1. The CANONICAL native row codec: `encodeRows`/`decodeRows` run the
- *    same native implementation the engine, log and migrations
- *    share (owned bytes in, owned typed rows out; untrusted input cannot
- *    inject native capabilities). Effect-only, `NativeRuntime` required.
- * 2. The schema-tagged JSON VALUE form for HTTP/export boundaries
- *    (chapter 30): every `f64` — finite included — is
- *    `{"$f64":"<16 lowercase hex digits>"}` of canonical binary64 bits;
- *    integers are canonical decimal strings; `Uuid` is canonical UUID;
- *    bytes use ONE strict lowercase-hex encoding; intervals are
- *    `{start,end}` in their element encoding; closed references are handle
- *    names. `JSON.stringify` of raw numbers is NOT the database value
- *    wire codec — it loses infinities/NaN and cannot encode BigInt.
- *    Decoders reject malformed widths, unknown tags and noncanonical
- *    representations. These are pure bounded per-row functions.
+ * Row codecs derived from the relation descriptors: the canonical native row codec
+ * (`encodeRows`/`decodeRows`, the engine's own bytes) and the schema-tagged JSON value form for
+ * HTTP/export boundaries, where an `f64` is `{"$f64":"<16 hex>"}` of its canonical bits (raw JSON
+ * numbers lose infinities and NaN), integers are decimal strings, bytes are lowercase hex and
+ * closed references are handle names. Decoders reject anything noncanonical.
  */
 
 /** The typed row shape: a schema plus one of its relations. */
@@ -58,7 +43,7 @@ function checkedRowShape<R extends AnyRelation>(operation: string, input: RowSha
 	if (relationId === undefined || !membersAgree(schema.relations[relation.name], relation)) {
 		throw new AuthoringError({ message: `${operation}: relation is not declared in the schema` })
 	}
-	return { relation, relationId, spec: lower(schema) }
+	return { relation, relationId, schema: compiledOf(schema).handle }
 }
 
 function invalid(operation: string): DbError {
@@ -141,7 +126,8 @@ function decodeTaggedF64(value: unknown): number | undefined {
 }
 
 /** Decode representation, then judge the value through the shared interpreter. */
-function decodeBoundaryValue(context: string, field: AnyField, input: unknown): unknown {
+function decodeBoundaryValue<F extends AnyField>(context: string, field: F, input: unknown): Infer<F>
+function decodeBoundaryValue(context: string, field: AnyField, input: unknown): Infer<AnyField> {
 	if ("closed" in field) return fieldValue(context, field, input)
 	let decoded: unknown = input
 	switch (field.kind) {
@@ -167,6 +153,35 @@ function decodeBoundaryValue(context: string, field: AnyField, input: unknown):
 	return fieldValue(context, field, decoded)
 }
 
+/** The host-value schema, using the same interpreter as facts and row codecs. */
+function fieldSchema<F extends AnyField>(field: F) {
+	const descriptor = fieldDescriptor("fieldSchema", field)
+	return EffectSchema.declare((value: unknown): value is Infer<F> => {
+		try {
+			fieldValue("fieldSchema", descriptor, value)
+			return true
+		} catch {
+			return false
+		}
+	})
+}
+
+/** Encode one field's host value in the canonical JSON-boundary form. */
+function encodeBoundaryField<F extends AnyField>(field: F, value: Infer<F>): Result.Result<unknown, DbError> {
+	return Result.try({
+		try: () => encodeBoundaryValue("encodeBoundaryField", fieldDescriptor("encodeBoundaryField", field), value),
+		catch: (cause) => argumentError("encodeBoundaryField", cause)
+	})
+}
+
+/** Strict JSON-boundary decoding, returning the field's canonical host value. */
+function decodeBoundaryField<F extends AnyField>(field: F, input: unknown): Result.Result<Infer<F>, DbError> {
+	return Result.try({
+		try: () => decodeBoundaryValue("decodeBoundaryField", fieldDescriptor("decodeBoundaryField", field), input),
+		catch: (cause) => argumentError("decodeBoundaryField", cause)
+	})
+}
+
 /** Pure schema-tagged JSON encoding of complete rows. */
 function encodeBoundaryRows<R extends AnyRelation>(
 	relation: R,
@@ -241,7 +256,7 @@ function rowSchema<R extends AnyRelation>(relation: R) {
 }
 
 /**
- * The canonical native row codec (chapter 35 roster): owned bytes
+ * The canonical native row codec: owned bytes
  * out, owned typed rows back in — the same implementation log sealing and
  * migrations use. Binding parameters is ingestion: input must stay stable
  * through execution, and no native work starts before the checked owned
@@ -251,8 +266,8 @@ const encodeRows = Effect.fn("encodeRows")(function* <R extends AnyRelation>(
 	shape: RowShape<R>,
 	rows: Iterable<Fact<R>>
 ) {
-	const runtime = yield* runtimeHandle()
-	const { relation, relationId, spec } = yield* Effect.try({
+	const runtime = yield* runtimeHandle
+	const { relation, relationId, schema } = yield* Effect.try({
 		try: () => checkedRowShape("encodeRows", shape),
 		catch: (cause) => argumentError("encodeRows", cause)
 	})
@@ -260,30 +275,41 @@ const encodeRows = Effect.fn("encodeRows")(function* <R extends AnyRelation>(
 		try: () => flatRowsOf(relation, rows as Iterable<object>),
 		catch: (cause) => argumentError("encodeRows", cause)
 	})
-	return yield* nativeOperationWith(
+	return yield* call(
 		"encodeRows",
-		(callback) => dbNative.runtimeEncodeRows(runtime, spec, relationId, flat.rows, flat.cells, callback),
-		dbNative.runtimeBytesTake,
-		(bytes) => bytes
+		(callback) => addon.runtimeEncodeRows(runtime, schema, relationId, flat.rows, flat.cells, callback),
+		addon.runtimeBytesTake
 	)
 })
 
 const decodeRows = Effect.fn("decodeRows")(function* <R extends AnyRelation>(shape: RowShape<R>, input: Uint8Array) {
-	const runtime = yield* runtimeHandle()
-	const { relation, relationId, spec } = yield* Effect.try({
+	const runtime = yield* runtimeHandle
+	const { relation, relationId, schema } = yield* Effect.try({
 		try: () => checkedRowShape("decodeRows", shape),
 		catch: (cause) => argumentError("decodeRows", cause)
 	})
 	if (!(input instanceof Uint8Array) || !(input.buffer instanceof ArrayBuffer)) {
 		return yield* Effect.fail(invalid("decodeRows"))
 	}
-	return yield* nativeOperationWith(
+	return yield* call(
 		"decodeRows",
-		(callback) => dbNative.runtimeDecodeRows(runtime, spec, relationId, input, callback),
-		dbNative.runtimeRowsTake,
-		(rows) => Object.freeze(rows.map((row) => factOfCells(relation, row as readonly CellValue[])))
+		(callback) => addon.runtimeDecodeRows(runtime, schema, relationId, input, callback),
+		(lease) =>
+			((rows) => Object.freeze(rows.map((row) => factOfCells(relation, row as readonly CellValue[]))))(
+				addon.runtimeRowsTake(lease)
+			)
 	)
 })
 
 export type { RowShape }
-export { decodeBoundaryRows, decodeRows, encodeBoundaryRows, encodeRows, rowSchema, rowShape }
+export {
+	decodeBoundaryField,
+	decodeBoundaryRows,
+	decodeRows,
+	encodeBoundaryField,
+	encodeBoundaryRows,
+	encodeRows,
+	fieldSchema,
+	rowSchema,
+	rowShape
+}

package/src/compile.ts

@@ -1,88 +1,67 @@
-import { Effect } from "effect"
-import { isClosedMember, membersAgree } from "#closed.ts"
-import { dbNative } from "#db-native.ts"
-import { SdkInvariantError } from "#errors.ts"
-import { isImmutable, snapshotData } from "#immutable.ts"
-import type { SchemaClasses } from "#law.ts"
-import { lower } from "#lower.ts"
-import type { SealedDescriptor } from "#native.ts"
-import type { AnyRelation } from "#relation.ts"
-import { nativeOperationWith, runtimeHandle } from "#runtime.ts"
-import { argumentError } from "#runtime-errors.ts"
-import type { AnySchema, Schema as SchemaDeclaration, SchemaRelations } from "#schema.ts"
-import { schemaDescriptor } from "#schema.ts"
-import { type KeyStatement, type Statement, statementDescriptor } from "#statements.ts"
-
 /**
- * `SchemaId` — the engine's canonical schema fingerprint as lowercase hex.
- * Independent of database identity; ordinary structural text. Native
- * boundaries verify the fingerprint wherever it grants admission.
+ * A schema is compiled by the engine when it is defined. The compiled handle, descriptor and
+ * fingerprint ride with the schema value; the engine's diagnostics come back as authoring errors
+ * that name the schema's own relations and statements.
  */
-type SchemaId = string
+import { Schema as EffectSchema } from "effect"
+import { isClosedMember, membersAgree } from "./closed.ts"
+import { AuthoringError, internalError } from "./errors.ts"
+import { isImmutable } from "./immutable.ts"
+import { lower } from "./lower.ts"
+import type { SchemaRef } from "./native/addon.ts"
+import { addon } from "./native/addon.ts"
+import type { SchemaDescriptorOut, SchemaDiagnostic } from "./native/binding.d.ts"
+import type { AnyRelation } from "./relation.ts"
+import type { AnySchema } from "./schema.ts"
+import { type KeyStatement, renderStatement, type Statement, statementDescriptor } from "./statements.ts"
 
-/**
- * `CompiledSchema<S>` — bounded detached immutable descriptor data plus the
- * canonical `schemaId`. NOT a tenant handle or a second
- * user-authored schema: it needs no native finalizer, holds no native
- * resource, and open/create/build compile through the same implementation —
- * prior compilation is optional, never a mandatory prepare ceremony.
- */
-interface CompiledSchema<S extends AnySchema> {
-	readonly schema: S
+/** The engine's schema fingerprint: 64 lowercase hex digits, independent of any database. */
+const SchemaId = EffectSchema.String.check(EffectSchema.isPattern(/^[0-9a-f]{64}$/)).pipe(
+	EffectSchema.brand("SchemaId")
+)
+type SchemaId = typeof SchemaId.Type
+
+interface Compiled {
+	readonly handle: SchemaRef
+	readonly descriptor: SchemaDescriptorOut
 	readonly schemaId: SchemaId
-	readonly descriptor: SealedDescriptor
 }
 
 /**
- * Pure declaration-order tables shared by the whole core surface: relation
- * ids (declaration order = ids), materialized statement ids (closed
- * relations' auto-handle keys FIRST in relation-declaration order, then
- * declared statements in declaration order with `mirrors` occupying two
- * consecutive slots, source-first — the theory's `StatementId` law).
- * Every declared statement retains its own native identity; no key is
- * privileged by its position in the declaration.
+ * Declaration-order tables: relation ids, and each declared statement's first materialized
+ * statement id (closed relations' id keys come first; `mirrors` takes two consecutive ids).
  */
 interface SchemaTables {
 	readonly relationIds: ReadonlyMap<string, number>
 	readonly statementIds: ReadonlyMap<Statement, number>
 }
 
-function declaredWidth(statement: Statement): number {
-	return statement.kind === "mirrors" ? 2 : 1
-}
-
 function tablesOf(theory: AnySchema): SchemaTables {
 	const relationIds = new Map<string, number>()
 	const statementIds = new Map<Statement, number>()
-	let autoKeys = 0
-	Object.entries(theory.relations).forEach(function assignRelation([name, member], ordinal) {
+	let offset = 0
+	Object.entries(theory.relations).forEach(([name, member], ordinal) => {
 		relationIds.set(name, ordinal)
-		if (isClosedMember(member)) {
-			autoKeys += 1
-		}
+		if (isClosedMember(member)) offset += 1
 	})
-	let offset = autoKeys
 	for (const statement of theory.statements) {
 		statementIds.set(statement, offset)
-		offset += declaredWidth(statement)
+		offset += statement.kind === "mirrors" ? 2 : 1
 	}
 	return Object.freeze({ relationIds, statementIds })
 }
 
-const compiledCache = new WeakMap<AnySchema, SchemaTables>()
+const tablesCache = new WeakMap<AnySchema, SchemaTables>()
 
-/** Memoized pure tables (per schema value identity; no native work). */
 function schemaTables(theory: AnySchema): SchemaTables {
-	const cached = compiledCache.get(theory)
-	if (cached !== undefined) {
-		return cached
-	}
+	const cached = tablesCache.get(theory)
+	if (cached !== undefined) return cached
 	const built = tablesOf(theory)
-	if (isImmutable(theory)) compiledCache.set(theory, built)
+	if (isImmutable(theory)) tablesCache.set(theory, built)
 	return built
 }
 
-/** Resolve a logical key declaration, never an opaque constructor token. */
+/** Resolves a key declaration to the schema's own statement and its statement id. */
 function declaredKey<R extends AnyRelation>(
 	theory: AnySchema,
 	input: KeyStatement<R>
@@ -104,68 +83,67 @@ function declaredKey(
 	return undefined
 }
 
-function admitSchemaId(fingerprint: string): SchemaId {
-	if (typeof fingerprint !== "string" || !/^[0-9a-f]{64}$/.test(fingerprint)) {
-		throw new SdkInvariantError({ message: "Schema.compile: the engine returned no canonical fingerprint" })
+function explain(theory: AnySchema, diagnostic: SchemaDiagnostic): string {
+	if (diagnostic._tag === "Schema") {
+		const cited = [diagnostic.statement, diagnostic.conflict].flatMap((cite) =>
+			cite === undefined ? [] : [cite.spelling]
+		)
+		return cited.length === 0 ? diagnostic.message : `${diagnostic.message} — ${cited.join("; ")}`
 	}
-	return fingerprint
+	const relations = Object.keys(theory.relations)
+	return diagnostic.issues
+		.map((issue) => {
+			const at = [
+				issue.relation === undefined ? undefined : `relation ${relations[issue.relation] ?? issue.relation}`,
+				issue.row === undefined ? undefined : `row ${issue.row}`,
+				issue.statement === undefined
+					? undefined
+					: (() => {
+							const statement = theory.statements[issue.statement]
+							return statement === undefined ? `statement ${issue.statement}` : renderStatement(statement)
+						})()
+			].filter((part) => part !== undefined)
+			return at.length === 0 ? issue.message : `${issue.message} — ${at.join(", ")}`
+		})
+		.join("; ")
 }
 
-/**
- * Effectful native schema admission/compilation: a
- * schema declaration is pure metadata and never a claim its theory has been
- * admitted. Runs on the shared executor, requires the
- * acquired {@link NativeRuntime}, and yields detached immutable descriptor
- * data plus the canonical schema identity. No database is opened and no
- * native finalizer is created.
- */
-const compile = Effect.fn("Schema.compile")(function* <S extends AnySchema>(schema: S) {
-	const owned = yield* Effect.try({
-		try: () => schemaDescriptor(schema),
-		catch: (cause) => argumentError("Schema.compile", cause)
-	})
-	const spec = yield* Effect.try({ try: () => lower(owned), catch: (cause) => argumentError("Schema.compile", cause) })
-	const handle = yield* runtimeHandle()
-	const descriptor = yield* nativeOperationWith(
-		"Schema.compile",
-		(callback) => dbNative.runtimeSchemaCompile(handle, spec, callback),
-		dbNative.runtimeSchemaTake,
-		(value) => value
-	)
-	const ownedDescriptor = snapshotData(descriptor)
-	const compiled: CompiledSchema<S> = Object.freeze({
-		get schema() {
-			return snapshotData(owned)
-		},
-		schemaId: admitSchemaId(descriptor.fingerprint),
-		get descriptor() {
-			return snapshotData(ownedDescriptor)
+const decodeSchemaId = EffectSchema.decodeUnknownOption(SchemaId)
+
+/** Compiles `theory` with the engine; an engine refusal throws `AuthoringError`. */
+function compileSchema(theory: AnySchema): Compiled {
+	const compiled = addon.compileSchema(JSON.stringify(lower(theory)))
+	switch (compiled._tag) {
+		case "Compiled": {
+			const schemaId = decodeSchemaId(compiled.descriptor.fingerprint)
+			if (schemaId._tag === "None") throw internalError("compileSchema: the engine returned no fingerprint")
+			return Object.freeze({ handle: compiled.schema, descriptor: compiled.descriptor, schemaId: schemaId.value })
 		}
-	})
-	return compiled
-})
+		case "Invalid":
+			throw new AuthoringError({ message: `schema ${theory.name}: ${explain(theory, compiled.diagnostic)}` })
+		case "Malformed":
+			throw internalError(`compileSchema: ${compiled.path}: ${compiled.message}`)
+	}
+}
 
-/**
- * The declaration-tier `Schema<Rels, Classes>` TYPE (from `#schema.ts`),
- * re-aliased LOCALLY so the one name carries both meanings through a
- * SINGLE export specifier below — a local `type` + `const` merge is the
- * plain TypeScript type/value merge, with no same-name pair of export
- * declarations for any checker to refuse (the earlier
- * `export type { Schema } from "#schema.ts"` beside `export { Schema }`
- * spelled the type meaning twice at the barrel; this spelling cannot).
- */
-type Schema<Rels extends SchemaRelations, Classes extends SchemaClasses = SchemaClasses> = SchemaDeclaration<
-	Rels,
-	Classes
->
+const compiledSchemas = new WeakMap<AnySchema, Compiled>()
 
-/**
- * The core `Schema` namespace (import as `BumbleSchema` when Effect Schema
- * is also in scope). The `Schema<Rels>` type remains the pure
- * declaration from `#schema.ts` (the local alias above); this value owns
- * the effectful half. One exported name, two meanings.
- */
-const Schema = Object.freeze({ compile })
+/** Records the compiled form of a schema value `schema()` produced. */
+function registerCompiled(theory: AnySchema): void {
+	compiledSchemas.set(theory, compileSchema(theory))
+}
+
+/** Whether `value` is a schema value `schema()` produced (and so has a compiled form). */
+function isCompiledSchema(value: unknown): value is AnySchema {
+	return typeof value === "object" && value !== null && compiledSchemas.has(value as AnySchema)
+}
+
+/** The engine's compiled form of `theory`; every schema value `schema()` produced has one. */
+function compiledOf(theory: AnySchema): Compiled {
+	const compiled = compiledSchemas.get(theory)
+	if (compiled === undefined) throw internalError("compiledOf: the schema was not produced by schema()")
+	return compiled
+}
 
-export type { CompiledSchema, SchemaId, SchemaTables }
-export { declaredKey, Schema, schemaTables }
+export type { Compiled, SchemaTables }
+export { compiledOf, declaredKey, isCompiledSchema, registerCompiled, SchemaId, schemaTables }