@bjornpagen/bumbledb 1.0.1 → 1.2.0

package/src/errors.ts

@@ -1,4 +1,4 @@
-import { Data } from "effect"
+import { Data, Schema } from "effect"
 
 /**
  * Pure authoring failures, SDK-invariant defects and internal native-boundary
@@ -8,8 +8,23 @@ import { Data } from "effect"
  */
 
 /** A pure schema, query, parameter, or value-authoring refusal. */
+export const AuthoringDiagnostic = Schema.Struct({
+	code: Schema.Literals([
+		"InvalidValue",
+		"InvalidRecord",
+		"UnknownField",
+		"MissingField",
+		"InvalidDeclaration",
+		"InvalidQuery"
+	]),
+	context: Schema.String,
+	expected: Schema.String
+})
+export type AuthoringDiagnostic = typeof AuthoringDiagnostic.Type
+
 export class AuthoringError extends Data.TaggedError("AuthoringError")<{
 	readonly message: string
+	readonly diagnostic?: AuthoringDiagnostic
 }> {}
 
 /** A contradiction in an SDK/native result, not an application refusal. */

package/src/face.ts

@@ -1,19 +1,24 @@
-import type { AnyClosed, AnySelectedClosed, PayloadField } from "#closed.ts"
+import type { AnyClosed } from "#closed.ts"
+import { memberDescriptor, sealedFieldOf } from "#closed.ts"
 import { AuthoringError } from "#errors.ts"
-import type { AnyField, SignatureOf } from "#fields.ts"
+import { type AnyField, assertDeclarationRecord, type SignatureOf } from "#fields.ts"
 import type { Same } from "#judgment.ts"
-import type { AnyRelation, AnySelected, FieldsShape, RelationFields, SelectionBinding } from "#relation.ts"
+import type { AnyRelation, FieldsShape } from "#relation.ts"
+import { type AnySelected, type FieldsOf, type SelectionBinding, selectionBindings } from "#selection.ts"
 import { renderLiteralSet } from "#spec.ts"
+import { arrayValue, recordValue } from "#values.ts"
 
 const emptySelection: readonly SelectionBinding[] = Object.freeze([])
 
-type OwnerOf<S extends FaceSource> = S extends AnySelected | AnySelectedClosed ? S["relation"] : S
+type OwnerOf<S extends FaceSource> = S extends AnySelected ? S["relation"] : S
 
 function faceParts(source: FaceSource): {
 	readonly owner: FaceOwner
 	readonly selection: readonly SelectionBinding[]
 } {
+	assertDeclarationRecord("face source", source)
 	if ("relation" in source) {
+		recordValue("selected relation", source, ["relation", "selection"])
 		return { owner: source.relation, selection: source.selection }
 	}
 	return { owner: source, selection: emptySelection }
@@ -21,31 +26,17 @@ function faceParts(source: FaceSource): {
 
 type FaceOwner = AnyRelation | AnyClosed
 
-interface FaceData<O extends FaceOwner = FaceOwner, P extends readonly string[] = readonly string[]> {
+interface Face<O extends FaceOwner = FaceOwner, P extends readonly string[] = readonly string[]> {
 	readonly owner: O
 	readonly projection: P
 	readonly selection: readonly SelectionBinding[]
 }
 
-interface Face<S extends FaceSource, P extends readonly string[]> {
-	readonly source: S
-	readonly projection: P
-	readonly data: FaceData<OwnerOf<S>, P>
-}
-
-type AnyFace = Face<FaceSource, readonly string[]>
+type AnyFace = Face<FaceOwner, readonly string[]>
 
-type FaceSource = AnyRelation | AnyClosed | AnySelected | AnySelectedClosed
+type FaceSource = AnyRelation | AnyClosed | AnySelected
 
-type FaceFields<S extends FaceSource> = S extends AnySelected
-	? keyof RelationFields<S["relation"]> & string
-	: S extends AnySelectedClosed
-		? "id" | (keyof S["relation"]["columns"] & string)
-		: S extends AnyRelation
-			? keyof RelationFields<S> & string
-			: S extends { readonly axioms: Readonly<Record<string, infer Row>> }
-				? "id" | (keyof Row & string)
-				: never
+type FaceFields<S extends FaceSource> = keyof FieldsOf<OwnerOf<S>> & string
 
 /**
  * The wire shape a face projects: the field's {@link SignatureOf} with an
@@ -61,28 +52,13 @@ type ShapeIn<Fields extends FieldsShape, K extends string> = K extends keyof Fie
 	? ProjectedSignature<Fields[K]>
 	: undefined
 
-type ProjectedShape<S extends FaceSource, K extends string> = S extends AnySelected
-	? ShapeIn<RelationFields<S["relation"]>, K>
-	: S extends AnySelectedClosed
-		? K extends "id"
-			? ProjectedSignature<S["relation"]["id"]>
-			: ShapeIn<S["relation"]["columns"], K>
-		: S extends AnyRelation
-			? ShapeIn<RelationFields<S>, K>
-			: S extends {
-						readonly id: infer Id extends AnyField
-						readonly columns: infer Cols extends Record<string, PayloadField>
-					}
-				? K extends "id"
-					? ProjectedSignature<Id>
-					: ShapeIn<Cols, K>
-				: undefined
+type ProjectedShape<S extends FaceSource, K extends string> = ShapeIn<FieldsOf<OwnerOf<S>>, K>
 
 type ShapesOf<S extends FaceSource, P extends readonly string[]> = {
 	readonly [I in keyof P]: ProjectedShape<S, P[I] & string>
 }
 
-type FaceShapes<F extends AnyFace> = F extends Face<infer S, infer P> ? ShapesOf<S, P> : never
+type FaceShapes<F extends AnyFace> = ShapesOf<F["owner"], F["projection"]>
 
 type Arity<F extends AnyFace> = F["projection"]["length"]
 
@@ -106,50 +82,45 @@ interface FaceShapeMismatch<Left, Right> {
 type SameShapes<A extends AnyFace, B extends AnyFace> =
 	Same<FaceShapes<A>, FaceShapes<B>> extends true ? unknown : FaceShapeMismatch<FaceShapes<A>, FaceShapes<B>>
 
-function on<S extends FaceSource, const F extends FaceFields<S>>(source: S, field: F): Face<S, readonly [F]>
+function on<S extends FaceSource, const F extends FaceFields<S>>(source: S, field: F): Face<OwnerOf<S>, readonly [F]>
 function on<S extends FaceSource, const P extends readonly [FaceFields<S>, ...FaceFields<S>[]]>(
 	source: S,
 	fields: P
-): Face<S, P>
-function on<S extends FaceSource>(source: S, fields: string | readonly string[]): Face<S, readonly string[]> {
-	const projection: readonly string[] = Object.freeze(typeof fields === "string" ? [fields] : [...fields])
+): Face<OwnerOf<S>, P>
+function on(source: FaceSource, fields: string | readonly string[]): AnyFace {
 	const parts = faceParts(source)
-	const data: FaceData = Object.freeze({
+	return faceDescriptor({
 		owner: parts.owner,
-		projection,
+		projection: typeof fields === "string" ? [fields] : fields,
 		selection: parts.selection
 	})
-	const value = Object.freeze({ source, projection, data })
-	if (!faceMinted<S, readonly string[]>(value, source, projection)) {
-		throw new AuthoringError({ message: `face over ${parts.owner.name}: face construction incomplete` })
-	}
-	return value
 }
 
-/**
- * The trusted admission seam of the face mint (the pattern's home is
- * `isTypedScope` in query/lower.ts): the
- * checkable facts — the value carries exactly the source and projection it
- * was built from, and `data.owner` is exactly the owner {@link faceParts}
- * resolves for that source — are verified before the wide construction is
- * admitted at the exact {@link Face} type (whose `data` claims the owner at
- * its precise type, the carrier the schema-level law-typing reads).
- */
-function faceMinted<S extends FaceSource, P extends readonly string[]>(
-	value: { readonly source: FaceSource; readonly projection: readonly string[]; readonly data: FaceData },
-	source: S,
-	projection: P
-): value is Face<S, P> {
-	const owner = "relation" in source ? source.relation : source
-	return (
-		value.source === source &&
-		value.projection === projection &&
-		value.data.owner === owner &&
-		value.data.projection === projection
-	)
+/** Own and check a structural face. No constructor-only admission token. */
+function faceDescriptor<F extends AnyFace>(input: F): F
+function faceDescriptor(input: unknown): AnyFace
+function faceDescriptor(raw: unknown): AnyFace {
+	const input = recordValue("face", raw, ["owner", "projection", "selection"])
+	const owner = memberDescriptor(input.owner)
+	const projection = arrayValue("face projection", input.projection, (_, value) => {
+		if (typeof value !== "string") throw new AuthoringError({ message: "face: expected a field name" })
+		return value
+	})
+	if (projection.length === 0) {
+		throw new AuthoringError({ message: "face: expected a nonempty projection" })
+	}
+	const projected = new Set<string>()
+	for (const field of projection) {
+		if (typeof field !== "string" || sealedFieldOf(owner, field) === undefined)
+			throw new AuthoringError({ message: `face ${owner.name}: unknown field ${String(field)}` })
+		if (projected.has(field)) throw new AuthoringError({ message: `face ${owner.name}: duplicate field ${field}` })
+		projected.add(field)
+	}
+	const selection = selectionBindings(owner, input.selection)
+	return Object.freeze({ owner, projection, selection })
 }
 
-function renderFace(face: FaceData): string {
+function renderFace(face: AnyFace): string {
 	const projection = face.projection.join(", ")
 	if (face.selection.length === 0) {
 		return `${face.owner.name}(${projection})`
@@ -167,7 +138,6 @@ export type {
 	Arity,
 	Face,
 	FaceArityMismatch,
-	FaceData,
 	FaceFields,
 	FaceOwner,
 	FaceShapeMismatch,
@@ -178,4 +148,4 @@ export type {
 	SameArity,
 	SameShapes
 }
-export { on, renderFace }
+export { faceDescriptor, on, renderFace }

package/src/fields.ts

@@ -1,9 +1,8 @@
 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"
+import type { Uuid } from "#uuid.ts"
+import { arrayValue, fieldValue, recordValue, taggedValueOf, U64_MAX } from "#values.ts"
 
 const INTEGER_INDEX_NAME = regex("^(?:0|[1-9][0-9]*)$")
 
@@ -23,54 +22,15 @@ interface IntervalValue {
 /**
  * A half-open dense float interval `[start, end)` as a plain value object:
  * 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.
+ * Field-directed validation rejects NaN endpoints and empty intervals and
+ * normalizes signed zero. Infinite bounds denote a missing bound, not a
+ * member point; a plain object alone is not evidence of validation.
  */
 interface FloatIntervalValue {
 	readonly start: number
 	readonly end: number
 }
 
-/**
- * Constructs a checked interval literal — the `start..end` spelling.
- * Half-open and nonempty by construction. 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 Result.fail(new DbError({ operation: "span", reason: { _tag: "InvalidArgument" } }))
-}
-
 /**
  * Nonempty declaration-order handle vector — the ONE roster carrier. The
  * handle union is `Handles[number]`, the ordinal of a handle is its tuple
@@ -187,11 +147,11 @@ type Infer<F extends AnyField> = F extends { readonly kind: "bool" }
 							? Uuid
 							: F extends { readonly kind: "bytes" }
 								? Uint8Array
-								: F extends { readonly kind: "interval"; readonly element: "f64" }
-									? FloatIntervalValue
-									: F extends { readonly kind: "interval" }
-										? IntervalValue
-										: never
+								: F extends { readonly kind: "interval"; readonly element: infer Element }
+									? Element extends "f64"
+										? FloatIntervalValue
+										: IntervalValue
+									: never
 
 /**
  * The typed shape refusal shared by every literal machine — the selection
@@ -263,47 +223,10 @@ function isFloatIntervalValue(value: unknown): value is FloatIntervalValue {
 	)
 }
 
-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 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: 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)
-	}
-	if (element === "u64") {
-		return { kind: "value", value: { kind: "intervalU64", start: value.start, end: value.end } }
-	}
-	return { kind: "value", value: { kind: "intervalI64", start: value.start, end: value.end } }
-}
-
 function assertDeclarationOrderKey(where: string, name: string): void {
+	if (typeof name !== "string" || !name.isWellFormed()) {
+		throw new AuthoringError({ message: `${where}: expected a well-formed Unicode name` })
+	}
 	if (INTEGER_INDEX_NAME.test(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`
@@ -317,12 +240,92 @@ function assertDeclarationOrderKey(where: string, name: string): void {
 }
 
 function assertDeclarationRecord(where: string, record: object): void {
+	if (typeof record !== "object" || record === null) {
+		throw new AuthoringError({ message: `${where}: expected a plain declaration record` })
+	}
 	const proto = Object.getPrototypeOf(record)
 	if (proto !== Object.prototype && proto !== null) {
 		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`
 		})
 	}
+	for (const key of Reflect.ownKeys(record)) {
+		const property = Object.getOwnPropertyDescriptor(record, key)
+		if (typeof key !== "string" || property?.enumerable !== true || !("value" in property)) {
+			throw new AuthoringError({ message: `${where}: declarations require enumerable own data fields` })
+		}
+	}
+}
+
+/** Own a checked roster; never freeze the caller's array. */
+function ownHandles<const H extends ClosedHandleTuple>(context: string, handles: H): H
+function ownHandles(context: string, handles: unknown): ClosedHandleTuple
+function ownHandles(context: string, handles: unknown): ClosedHandleTuple {
+	if (!Array.isArray(handles) || handles.length === 0) {
+		throw new AuthoringError({ message: `${context}: expected a nonempty handle tuple` })
+	}
+	const seen = new Set<string>()
+	const values = arrayValue(context, handles, (_, handle) => {
+		if (typeof handle !== "string") throw new AuthoringError({ message: `${context}: expected string handles` })
+		if (!handle.isWellFormed()) throw new AuthoringError({ message: `${context}: expected well-formed string handles` })
+		if (seen.has(handle)) throw new AuthoringError({ message: `${context}: duplicate handle ${handle}` })
+		seen.add(handle)
+		return handle
+	})
+	const first = values[0]
+	if (first === undefined) throw new AuthoringError({ message: `${context}: expected a nonempty handle tuple` })
+	return Object.freeze([first, ...values.slice(1)])
+}
+
+/** Checked structural field descriptors, shared by declaration boundaries. */
+function fieldDescriptor<F extends AnyField>(context: string, input: F): F
+function fieldDescriptor(context: string, input: unknown): AnyField
+function fieldDescriptor(context: string, input: unknown): AnyField {
+	if (typeof input !== "object" || input === null || !("kind" in input)) {
+		throw new AuthoringError({ message: `${context}: expected a field descriptor` })
+	}
+	assertDeclarationRecord(context, input)
+	switch (input.kind) {
+		case "bool":
+		case "str":
+		case "i64":
+		case "f64":
+		case "uuid":
+			recordValue(context, input, ["kind"])
+			return Object.freeze({ kind: input.kind })
+		case "u64": {
+			if (!("closed" in input)) {
+				recordValue(context, input, ["kind"])
+				return u64
+			}
+			recordValue(context, input, ["kind", "closed"])
+			const roster = recordValue(context, input.closed, ["name", "handles"])
+			if (typeof roster.name !== "string") throw new AuthoringError({ message: `${context}: expected a roster name` })
+			assertDeclarationOrderKey(context, roster.name)
+			return Object.freeze({
+				kind: "u64",
+				closed: Object.freeze({ name: roster.name, handles: ownHandles(context, roster.handles) })
+			})
+		}
+		case "bytes": {
+			const value = recordValue(context, input, ["kind", "width"])
+			if (typeof value.width !== "number") throw new AuthoringError({ message: `${context}: expected a bytes width` })
+			return bytes(value.width)
+		}
+		case "interval": {
+			const value = recordValue(context, input, ["kind", "element", "width"])
+			if (value.element !== "u64" && value.element !== "i64" && value.element !== "f64") {
+				throw new AuthoringError({ message: `${context}: expected an interval element kind` })
+			}
+			if (value.width === undefined) return interval({ kind: value.element })
+			if (value.element === "f64" || typeof value.width !== "bigint") {
+				throw new AuthoringError({ message: `${context}: only discrete intervals accept a bigint width` })
+			}
+			return interval({ kind: value.element }, value.width)
+		}
+		default:
+			throw new AuthoringError({ message: `${context}: unknown field kind` })
+	}
 }
 
 const u64: U64Field = Object.freeze({ kind: "u64" })
@@ -371,69 +374,19 @@ function interval(
 				"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) {
+	if (width !== undefined && (typeof width !== "bigint" || width < 1n || width > U64_MAX)) {
 		throw new AuthoringError({
-			message: `interval width must be >= 1 (got ${width}) — w >= 1 is pinned at declaration`
+			message: "interval width must be a bigint in 1..=u64::MAX"
 		})
 	}
 	return Object.freeze({ kind: "interval", element: elementKind, width })
 }
 
 function literalOf(field: AnyField, value: unknown): LiteralSpec {
-	const roster = rosterOf(field)
-	if (roster !== undefined) {
-		return handleLiteral(roster, value)
-	}
-	switch (field.kind) {
-		case "bool": {
-			if (typeof value !== "boolean") {
-				throw literalShapeError("selection literal", "boolean", value)
-			}
-			return { kind: "value", value: { kind: "bool", value } }
-		}
-		case "u64": {
-			if (typeof value !== "bigint") {
-				throw literalShapeError("selection literal", "bigint", value)
-			}
-			return { kind: "value", value: { kind: "u64", value } }
-		}
-		case "i64": {
-			if (typeof value !== "bigint") {
-				throw literalShapeError("selection literal", "bigint", value)
-			}
-			return { kind: "value", value: { kind: "i64", value } }
-		}
-		case "str": {
-			if (typeof value !== "string") {
-				throw literalShapeError("selection literal", "string", value)
-			}
-
-			if (!value.isWellFormed()) {
-				throw literalShapeError("selection literal", "well-formed string", value)
-			}
-			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)
-			}
-			return { kind: "value", value: { kind: "fixedBytes", value } }
-		}
-		case "interval":
-			return intervalLiteral(field.element, value)
+	if ("closed" in field) {
+		return { kind: "handle", handle: fieldValue("selection literal", field, value) }
 	}
+	return { kind: "value", value: taggedValueOf("selection literal", field, value) }
 }
 
 export type {
@@ -463,16 +416,17 @@ export {
 	bool,
 	bytes,
 	f64,
+	fieldDescriptor,
 	i64,
 	interval,
 	isFloatIntervalValue,
 	isIntervalValue,
 	literalOf,
 	literalShapeError,
+	ownHandles,
 	rosterOf,
 	rostersAgree,
 	signaturesAgree,
-	span,
 	str,
 	u64,
 	uuid

package/src/immutable.ts

@@ -0,0 +1,76 @@
+/** Only frozen plain data graphs are stable cache keys. Typed-array contents
+ * remain mutable even behind a frozen parent, so they never qualify. */
+const immutable = new WeakSet<object>()
+
+function isImmutable(input: unknown, visiting = new WeakSet<object>()): boolean {
+	if (typeof input !== "object" || input === null) return typeof input !== "function"
+	if (immutable.has(input)) return true
+	const prototype = Object.getPrototypeOf(input)
+	if (
+		(prototype !== Object.prototype && prototype !== null && prototype !== Array.prototype) ||
+		!Object.isFrozen(input) ||
+		visiting.has(input)
+	)
+		return false
+	visiting.add(input)
+	for (const name of Reflect.ownKeys(input)) {
+		const property = Object.getOwnPropertyDescriptor(input, name)
+		if (property === undefined || !("value" in property) || !isImmutable(property.value, visiting)) {
+			visiting.delete(input)
+			return false
+		}
+	}
+	visiting.delete(input)
+	immutable.add(input)
+	return true
+}
+
+/** Validation is never skipped for a mutable structural input. Validated
+ * immutable outputs can be reused without requiring constructor identity. */
+function descriptorCache<A extends object>(parse: (input: unknown) => A): (input: unknown) => A {
+	const cache = new WeakMap<object, A>()
+	return (input) => {
+		if (typeof input === "object" && input !== null) {
+			const found = cache.get(input)
+			if (found !== undefined) return found
+		}
+		const result = parse(input)
+		if (isImmutable(result)) {
+			cache.set(result, result)
+			if (typeof input === "object" && input !== null && isImmutable(input)) cache.set(input, result)
+		}
+		return result
+	}
+}
+
+/** Detached inspection data: share proven immutable branches, copy byte
+ * buffers and their parents, and preserve references within one snapshot.
+ * This is for already checked internal data, not an input validator. */
+function snapshotData<A>(input: A, onCopy?: (source: object, snapshot: object) => void): A
+function snapshotData(input: unknown, onCopy?: (source: object, snapshot: object) => void): unknown {
+	const copied = new WeakMap<object, object>()
+	function visit(value: unknown): unknown {
+		if (typeof value !== "object" || value === null || isImmutable(value)) return value
+		const existing = copied.get(value)
+		if (existing !== undefined) return existing
+		if (value instanceof Uint8Array) {
+			const bytes = Uint8Array.from(value)
+			copied.set(value, bytes)
+			return bytes
+		}
+		const result = Array.isArray(value) ? [] : Object.create(Object.getPrototypeOf(value))
+		copied.set(value, result)
+		for (const name of Reflect.ownKeys(value)) {
+			if (Array.isArray(value) && name === "length") continue
+			const property = Object.getOwnPropertyDescriptor(value, name)
+			if (property === undefined || !("value" in property)) throw new TypeError("snapshotData requires checked data")
+			Object.defineProperty(result, name, { value: visit(property.value), enumerable: property.enumerable === true })
+		}
+		Object.freeze(result)
+		onCopy?.(value, result)
+		return result
+	}
+	return visit(input)
+}
+
+export { descriptorCache, isImmutable, snapshotData }