@bjornpagen/bumbledb 0.20.2 → 1.0.0

package/src/errors.ts

@@ -0,0 +1,50 @@
+import { Data } from "effect"
+
+/**
+ * Pure authoring refusals and SDK-invariant defects. These are the ONLY
+ * non-`DbError` throw families in the core package: chapter 35 permits
+ * programmer-facing AST misuse to throw synchronously (no I/O ever), and a
+ * contradiction between SDK and native state is a defect, not a domain
+ * outcome. Every operational failure of effectful work is the single
+ * `DbError` tagged-reason class in `#runtime-errors.ts` — the old
+ * per-surface `Err*` wrapper family is deleted (duplicate error wrappers
+ * are banned by C02/C10).
+ */
+
+/** A pure schema, query, parameter, or value-authoring refusal. */
+export class AuthoringError extends Data.TaggedError("AuthoringError")<{
+	readonly message: string
+}> {}
+
+/** A contradiction in an SDK/native result, not an application refusal. */
+export class SdkInvariantError extends Data.TaggedError("SdkInvariantError")<{
+	readonly message: string
+}> {}
+
+export class NativeLoadError extends Data.TaggedError("NativeLoadError")<{
+	readonly package: string
+	readonly operation: "resolve" | "load"
+	readonly message: string
+	readonly cause: unknown
+}> {}
+
+/** A native bridge call's contextual failure; the exact thrown value is retained. */
+export class NativeOperationError extends Data.TaggedError("NativeOperationError")<{
+	readonly operation: string
+	readonly cause: unknown
+}> {
+	override get message(): string {
+		const cause = this.cause
+		const detail =
+			typeof cause === "object" && cause !== null && "message" in cause && typeof cause.message === "string"
+				? cause.message
+				: String(cause)
+		return `${this.operation}: ${detail}`
+	}
+}
+
+export class NativeReportedError extends Data.TaggedError("NativeReportedError")<{
+	readonly kind: string
+	readonly message: string
+	readonly cause: unknown
+}> {}

package/src/face.ts

@@ -1,5 +1,5 @@
-import * as errors from "@superbuilders/errors"
 import type { AnyClosed, AnySelectedClosed, PayloadField } from "#closed.ts"
+import { AuthoringError } from "#errors.ts"
 import type { AnyField, SignatureOf } from "#fields.ts"
 import type { Same } from "#judgment.ts"
 import type { AnyRelation, AnySelected, FieldsShape, RelationFields, SelectionBinding } from "#relation.ts"
@@ -121,7 +121,7 @@ function on<S extends FaceSource>(source: S, fields: string | readonly string[])
 	})
 	const value = Object.freeze({ source, projection, data })
 	if (!faceMinted<S, readonly string[]>(value, source, projection)) {
-		throw errors.new(`face over ${parts.owner.name}: face construction incomplete`)
+		throw new AuthoringError({ message: `face over ${parts.owner.name}: face construction incomplete` })
 	}
 	return value
 }

package/src/fields.ts

@@ -1,17 +1,19 @@
-import * as errors from "@superbuilders/errors"
 import { regex } from "arkregex"
+import { Result } from "effect"
+import { AuthoringError } from "#errors.ts"
+import { DbError } from "#runtime-errors.ts"
 import type { LiteralSpec } from "#spec.ts"
+import { Uuid } from "#uuid.ts"
 
 const INTEGER_INDEX_NAME = regex("^(?:0|[1-9][0-9]*)$")
 
 /**
- * A half-open interval `[start, end)` as a plain value object — the ONE
- * interval value type, whatever the field's element type or width label.
- * The ray is representable (`end` = the element type's MAX_END); widths
- * and signedness are NOT modeled on the value — they are descriptor-type
- * labels the engine judges at the typed write boundary. Interval fields
- * derive no order (the Rust refusal,,
- * so no comparators exist on the value type.
+ * A half-open integer interval `[start, end)` as a plain value object —
+ * the ONE discrete interval value type, whatever the field's element type
+ * or width label. The ray is representable (`end` = the element type's
+ * MAX_END); widths and signedness are NOT modeled on the value — they are
+ * descriptor-type labels the engine judges at the typed write boundary.
+ * Interval fields derive no order, so no comparators exist on the value.
  */
 interface IntervalValue {
 	readonly start: bigint
@@ -19,17 +21,55 @@ interface IntervalValue {
 }
 
 /**
- * Constructs an interval literal — the `start..end` spelling. Half-open
- * and nonempty by construction: `start >= end` is a typed construction
- * error (parse, don't validate — the same invariant Rust's
- * `Interval::new` enforces at the host boundary). The value is bare and
- * structural: it is assignable to any interval field.
+ * A half-open dense float interval `[start, end)` as a plain value object
+ * (chapter 11): two canonical binary64 bounds on the dense numeric line.
+ * NaN is never an endpoint, signed zero is normalized at the checked
+ * constructor and again by the native boundary, and strict `start < end`
+ * makes empty spans unrepresentable through {@link span}. Infinite bounds
+ * denote a missing bound, not a member point.
  */
-function span(start: bigint, end: bigint): IntervalValue {
-	if (start >= end) {
-		throw errors.new(`interval is half-open and nonempty: start must be < end (got ${start}..${end})`)
+interface FloatIntervalValue {
+	readonly start: number
+	readonly end: number
+}
+
+/**
+ * Constructs a checked interval literal — the `start..end` spelling.
+ * Half-open and nonempty by construction. This is one of chapter 35's
+ * "checked small interval constructors": genuinely fallible pure parsing
+ * returns `Result` (use `Effect.fromResult(span(...))` inside a generator),
+ * never hidden I/O and never a thrown domain outcome.
+ *
+ * Two element domains, selected by argument type: `span(0n, 60n)` is a
+ * discrete integer interval; `span(0.5, 1.5)` is a dense float interval
+ * with canonical endpoints (NaN refused, `-0` normalized to `+0`,
+ * `-Infinity` legal only as the lower bound and `+Infinity` only as the
+ * upper bound — both enforced by strict numeric `start < end`).
+ */
+function span(start: bigint, end: bigint): Result.Result<IntervalValue, DbError>
+function span(start: number, end: number): Result.Result<FloatIntervalValue, DbError>
+function span(
+	start: bigint | number,
+	end: bigint | number
+): Result.Result<IntervalValue, DbError> | Result.Result<FloatIntervalValue, DbError> {
+	if (typeof start === "bigint" && typeof end === "bigint") {
+		if (start >= end) {
+			return Result.fail(new DbError({ operation: "span", reason: { _tag: "InvalidArgument" } }))
+		}
+		return Result.succeed(Object.freeze({ start, end }))
+	}
+	if (typeof start === "number" && typeof end === "number") {
+		if (Number.isNaN(start) || Number.isNaN(end)) {
+			return Result.fail(new DbError({ operation: "span", reason: { _tag: "InvalidArgument" } }))
+		}
+		const lo = Object.is(start, -0) ? 0 : start
+		const hi = Object.is(end, -0) ? 0 : end
+		if (!(lo < hi)) {
+			return Result.fail(new DbError({ operation: "span", reason: { _tag: "InvalidArgument" } }))
+		}
+		return Result.succeed(Object.freeze({ start: lo, end: hi }))
 	}
-	return Object.freeze({ start, end })
+	return Result.fail(new DbError({ operation: "span", reason: { _tag: "InvalidArgument" } }))
 }
 
 /**
@@ -56,27 +96,37 @@ interface StrField {
 	readonly kind: "str"
 }
 
-interface FreshU64Field {
-	readonly kind: "u64"
-	readonly fresh: true
-}
-
 interface U64Field {
 	readonly kind: "u64"
-	readonly fresh: FreshU64Field
 }
 
 interface I64Field {
 	readonly kind: "i64"
 }
 
+interface F64Field {
+	readonly kind: "f64"
+}
+
+/**
+ * The application-owned 128-bit identity scalar (chapter 30/34): sixteen
+ * exact bytes, spelled as the canonical hyphenated UUID {@link Uuid}
+ * host value. There is no `fresh` mark anywhere: the database issues no
+ * identity, and key laws are declared statements.
+ */
+interface UuidField {
+	readonly kind: "uuid"
+}
+
 interface BytesField<Width extends number = number> {
 	readonly kind: "bytes"
 	readonly width: Width
 }
 
+type IntervalElementKind = "u64" | "i64" | "f64"
+
 interface IntervalField<
-	Element extends "u64" | "i64" = "u64" | "i64",
+	Element extends IntervalElementKind = IntervalElementKind,
 	Width extends bigint | undefined = bigint | undefined
 > {
 	readonly kind: "interval"
@@ -96,8 +146,9 @@ type AnyField =
 	| BoolField
 	| StrField
 	| U64Field
-	| FreshU64Field
 	| I64Field
+	| F64Field
+	| UuidField
 	| BytesField
 	| IntervalField
 	| AnyClosedIdField
@@ -131,20 +182,26 @@ type Infer<F extends AnyField> = F extends { readonly kind: "bool" }
 				? bigint
 				: F extends { readonly kind: "i64" }
 					? bigint
-					: F extends { readonly kind: "bytes" }
-						? Uint8Array
-						: F extends { readonly kind: "interval" }
-							? IntervalValue
-							: never
+					: F extends { readonly kind: "f64" }
+						? number
+						: F extends { readonly kind: "uuid" }
+							? Uuid
+							: F extends { readonly kind: "bytes" }
+								? Uint8Array
+								: F extends { readonly kind: "interval"; readonly element: "f64" }
+									? FloatIntervalValue
+									: F extends { readonly kind: "interval" }
+										? IntervalValue
+										: never
 
 /**
  * The typed shape refusal shared by every literal machine — the selection
- * lowering here, the row marshaler (`marshal.ts`), and the query-literal
+ * lowering here, the row codec (`rows.ts`), and the query-literal
  * tagger (`query/lower.ts`) all throw through this ONE voice; reached only
  * through ill-typed input (the well-typed surfaces make it unrepresentable).
  */
 function literalShapeError(context: string, expected: string, value: unknown): Error {
-	return errors.new(`${context}: expected ${expected}, got ${typeof value}`)
+	return new AuthoringError({ message: `${context}: expected ${expected}, got ${typeof value}` })
 }
 
 function rosterOf(field: AnyField | undefined): AnyClosedRoster | undefined {
@@ -196,17 +253,48 @@ function isIntervalValue(value: unknown): value is IntervalValue {
 	)
 }
 
+function isFloatIntervalValue(value: unknown): value is FloatIntervalValue {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"start" in value &&
+		"end" in value &&
+		typeof value.start === "number" &&
+		typeof value.end === "number"
+	)
+}
+
 function handleLiteral(closed: AnyClosedRoster, value: unknown): LiteralSpec {
 	if (typeof value !== "string") {
 		throw literalShapeError("selection literal", `a ${closed.name} handle name (string)`, value)
 	}
 	if (!closed.handles.includes(value)) {
-		throw errors.new(`"${value}" is not a handle of ${closed.name} — the roster is ${closed.handles.join(", ")}`)
+		throw new AuthoringError({
+			message: `"${value}" is not a handle of ${closed.name} — the roster is ${closed.handles.join(", ")}`
+		})
 	}
 	return { kind: "handle", handle: value }
 }
 
-function intervalLiteral(element: "u64" | "i64", value: unknown): LiteralSpec {
+function intervalLiteral(element: IntervalElementKind, value: unknown): LiteralSpec {
+	if (element === "f64") {
+		if (!isFloatIntervalValue(value)) {
+			throw literalShapeError("selection literal", "float interval ({ start, end } numbers)", value)
+		}
+		if (Number.isNaN(value.start) || Number.isNaN(value.end) || !(value.start < value.end)) {
+			throw new AuthoringError({
+				message: "selection literal: a float interval is half-open and nonempty with non-NaN canonical endpoints"
+			})
+		}
+		return {
+			kind: "value",
+			value: {
+				kind: "intervalF64",
+				start: Object.is(value.start, -0) ? 0 : value.start,
+				end: Object.is(value.end, -0) ? 0 : value.end
+			}
+		}
+	}
 	if (!isIntervalValue(value)) {
 		throw literalShapeError("selection literal", "interval ({ start, end } bigints)", value)
 	}
@@ -218,55 +306,76 @@ function intervalLiteral(element: "u64" | "i64", value: unknown): LiteralSpec {
 
 function assertDeclarationOrderKey(where: string, name: string): void {
 	if (INTEGER_INDEX_NAME.test(name)) {
-		throw errors.new(
-			`${where}: name ${name} is an integer index — JavaScript object keys re-order integer indices, breaking the declaration-order law; use a non-numeric name`
-		)
+		throw new AuthoringError({
+			message: `${where}: name ${name} is an integer index — JavaScript object keys re-order integer indices, breaking the declaration-order law; use a non-numeric name`
+		})
 	}
 	if (name.includes(".")) {
-		throw errors.new(
-			`${where}: name ${name} contains a dot — the law classes key on the \`relation.field\` coordinate, so a dotted name would alias unrelated slots (macro parity: Rust identifiers cannot contain dots); use a dot-free name`
-		)
+		throw new AuthoringError({
+			message: `${where}: name ${name} contains a dot — the law classes key on the \`relation.field\` coordinate, so a dotted name would alias unrelated slots (macro parity: Rust identifiers cannot contain dots); use a dot-free name`
+		})
 	}
 }
 
 function assertDeclarationRecord(where: string, record: object): void {
 	const proto = Object.getPrototypeOf(record)
 	if (proto !== Object.prototype && proto !== null) {
-		throw errors.new(
-			`${where}: the declaration record's prototype was replaced — a plain \`__proto__: {...}\` entry is the prototype setter, so its key silently vanishes from the declaration; spell it computed (["__proto__"]: {...}) to declare it as data`
-		)
+		throw new AuthoringError({
+			message: `${where}: the declaration record's prototype was replaced — a plain \`__proto__: {...}\` entry is the prototype setter, so its key silently vanishes from the declaration; spell it computed (["__proto__"]: {...}) to declare it as data`
+		})
 	}
 }
 
-const freshU64: FreshU64Field = Object.freeze({ kind: "u64", fresh: true })
-
-const u64: U64Field = Object.freeze({ kind: "u64", fresh: freshU64 })
+const u64: U64Field = Object.freeze({ kind: "u64" })
 
 const i64: I64Field = Object.freeze({ kind: "i64" })
 
+/** Binary64. The native value boundary canonicalizes NaN and signed zero. */
+const f64: F64Field = Object.freeze({ kind: "f64" })
+
+/** The application-owned 128-bit identity scalar; no fresh mark exists. */
+const uuid: UuidField = Object.freeze({ kind: "uuid" })
+
 const bool: BoolField = Object.freeze({ kind: "bool" })
 
 const str: StrField = Object.freeze({ kind: "str" })
 
 function bytes<const Width extends number>(width: Width): BytesField<Width> {
 	if (!Number.isInteger(width) || width < 1 || width > 64) {
-		throw errors.new(`bytes width must be an integer in 1..=64 (got ${width}) — the range is pinned at declaration`)
+		throw new AuthoringError({
+			message: `bytes width must be an integer in 1..=64 (got ${width}) — the range is pinned at declaration`
+		})
 	}
 	return Object.freeze({ kind: "bytes", width })
 }
 
-function interval<Element extends U64Field | I64Field>(element: Element): IntervalField<Element["kind"], undefined>
+function interval<Element extends U64Field | I64Field | F64Field>(
+	element: Element
+): IntervalField<Element["kind"], undefined>
 function interval<Element extends U64Field | I64Field, const Width extends bigint>(
 	element: Element,
 	width: Width
 ): IntervalField<Element["kind"], Width>
-function interval(element: U64Field | I64Field, width?: bigint): IntervalField<"u64" | "i64", bigint | undefined> {
+function interval(
+	element: U64Field | I64Field | F64Field,
+	width?: bigint
+): IntervalField<IntervalElementKind, bigint | undefined> {
 	const elementKind = element.kind
-	if (elementKind !== "u64" && elementKind !== "i64") {
-		throw errors.new(`interval element must be the u64 or i64 field constructor (got ${elementKind})`)
+	if (elementKind !== "u64" && elementKind !== "i64" && elementKind !== "f64") {
+		throw new AuthoringError({
+			message: `interval element must be the u64, i64 or f64 field constructor (got ${elementKind})`
+		})
+	}
+	if (width !== undefined && elementKind === "f64") {
+		throw new AuthoringError({
+			message:
+				"interval(f64) takes no width — a fixed-width float interval is unrepresentable (rounded start + width is not an exact fixed length on the dense line); applications supply two checked bounds"
+		})
 	}
 	if (width !== undefined && width < 1n) {
-		throw errors.new(`interval width must be >= 1 (got ${width}) — w >= 1 is pinned at declaration`)
+		throw new AuthoringError({
+			message: `interval width must be >= 1 (got ${width}) — w >= 1 is pinned at declaration`
+		})
 	}
 	return Object.freeze({ kind: "interval", element: elementKind, width })
 }
@@ -305,6 +414,18 @@ function literalOf(field: AnyField, value: unknown): LiteralSpec {
 			}
 			return { kind: "value", value: { kind: "string", value } }
 		}
+		case "f64": {
+			if (typeof value !== "number") {
+				throw literalShapeError("selection literal", "number", value)
+			}
+			return { kind: "value", value: { kind: "f64", value } }
+		}
+		case "uuid": {
+			if (!Uuid.isUuid(value)) {
+				throw literalShapeError("selection literal", "a UUID (canonical UUID text)", value)
+			}
+			return { kind: "value", value: { kind: "uuid", value } }
+		}
 		case "bytes": {
 			if (!(value instanceof Uint8Array)) {
 				throw literalShapeError("selection literal", "Uint8Array", value)
@@ -325,22 +446,27 @@ export type {
 	ClosedHandleTuple,
 	ClosedIdField,
 	ClosedRoster,
-	FreshU64Field,
+	F64Field,
+	FloatIntervalValue,
 	I64Field,
 	Infer,
+	IntervalElementKind,
 	IntervalField,
 	IntervalValue,
 	SignatureOf,
 	StrField,
-	U64Field
+	U64Field,
+	UuidField
 }
 export {
 	assertDeclarationOrderKey,
 	assertDeclarationRecord,
 	bool,
 	bytes,
+	f64,
 	i64,
 	interval,
+	isFloatIntervalValue,
 	isIntervalValue,
 	literalOf,
 	literalShapeError,
@@ -349,5 +475,6 @@ export {
 	signaturesAgree,
 	span,
 	str,
-	u64
+	u64,
+	uuid
 }