@bjornpagen/bumbledb 1.1.0 → 1.2.1

package/src/statements.ts

@@ -2,69 +2,44 @@ import {
 	type BoundsOnTarget,
 	type CapacityWeight,
 	type CapacityWindow,
-	isCapacityWeight,
-	isCapacityWindow,
+	capacityWeight,
+	capacityWindow,
 	type UnitDimensionBan,
 	unitWeight,
 	type WeightOnSource
 } from "#capacity.ts"
-import { isClosedMember, sealedFieldOf } from "#closed.ts"
+import { isClosedMember, memberDescriptor, sealedFieldOf } from "#closed.ts"
 import { AuthoringError } from "#errors.ts"
-import { type AnyFace, type FaceData, renderFace, type SameArity, type SameShapes } from "#face.ts"
-import { type AnyClosedRoster, rosterOf, rostersAgree } from "#fields.ts"
+import { type AnyFace, faceDescriptor, renderFace, type SameArity, type SameShapes } from "#face.ts"
+import { type AnyClosedRoster, assertDeclarationRecord, rosterOf, rostersAgree, signaturesAgree } from "#fields.ts"
+import { descriptorCache } from "#immutable.ts"
 import type { AnyRelation, RelationFields } from "#relation.ts"
 import { type CapacityWindowSpec, renderCapacityWindow, renderWeight, type WeightSpec } from "#spec.ts"
+import { arrayValue, recordValue } from "#values.ts"
 
-interface KeyData<R extends AnyRelation, Projection extends readonly string[]> {
+interface KeyStatement<R extends AnyRelation = AnyRelation, Projection extends readonly string[] = readonly string[]> {
 	readonly kind: "key"
 	readonly owner: R
 	readonly projection: Projection
 }
-
-interface ContainmentData<Src extends FaceData = FaceData, Tgt extends FaceData = FaceData> {
+interface ContainmentStatement<Src extends AnyFace = AnyFace, Tgt extends AnyFace = AnyFace> {
 	readonly kind: "containment"
 	readonly source: Src
 	readonly target: Tgt
 }
-
-interface MirrorsData<Src extends FaceData = FaceData, Tgt extends FaceData = FaceData> {
+interface MirrorsStatement<Src extends AnyFace = AnyFace, Tgt extends AnyFace = AnyFace> {
 	readonly kind: "mirrors"
 	readonly source: Src
 	readonly target: Tgt
 }
-
-interface CapacityData<Tgt extends FaceData = FaceData, Src extends FaceData = FaceData> {
+interface CapacityStatement<Tgt extends AnyFace = AnyFace, Src extends AnyFace = AnyFace> {
 	readonly kind: "capacity"
 	readonly target: Tgt
-	readonly weight: WeightSpec
-	readonly window: CapacityWindowSpec
+	readonly weight: CapacityWeight
+	readonly window: CapacityWindow
 	readonly source: Src
 }
-
-type StatementData = KeyData<AnyRelation, readonly string[]> | ContainmentData | MirrorsData | CapacityData
-
-const admitted: unique symbol = Symbol("bumbledb.statement.admitted")
-
-interface Statement {
-	readonly data: StatementData
-	readonly [admitted]: true
-}
-
-function isStatement(value: unknown): value is Statement {
-	return typeof value === "object" && value !== null && admitted in value
-}
-
-interface ContainedStatement<Src extends FaceData, Tgt extends FaceData> extends Statement {
-	readonly data: ContainmentData<Src, Tgt> | MirrorsData<Src, Tgt>
-}
-
-interface CapacityStatement<Tgt extends FaceData, Src extends FaceData> extends Statement {
-	readonly data: CapacityData<Tgt, Src>
-}
-
-interface KeyStatement<R extends AnyRelation, Projection extends readonly string[]> extends Statement {
-	readonly data: KeyData<R, Projection>
-}
+type Statement = KeyStatement | ContainmentStatement | MirrorsStatement | CapacityStatement
 
 function renderRosterSide(roster: AnyClosedRoster | undefined): string {
 	return roster === undefined ? "a bare column" : `a ${roster.name} reference`
@@ -79,7 +54,7 @@ function renderRosterSide(roster: AnyClosedRoster | undefined): string {
  * `Db.create`'s colder engine refusal. The error carries the two faces'
  * own facts: names, arities, and the rendered statement.
  */
-function assertArityAgreement(source: FaceData, target: FaceData, statement: Statement): void {
+function assertArityAgreement(source: AnyFace, target: AnyFace, statement: Statement): void {
 	if (source.projection.length !== target.projection.length) {
 		throw new AuthoringError({
 			message: `${source.owner.name}(${source.projection.join(", ")}) and ${target.owner.name}(${target.projection.join(", ")}) project ${source.projection.length} vs ${target.projection.length} fields — positional pairing requires both faces to project equally many — ${renderStatement(statement)}`
@@ -87,7 +62,7 @@ function assertArityAgreement(source: FaceData, target: FaceData, statement: Sta
 	}
 }
 
-function assertRosterAgreement(source: FaceData, target: FaceData, statement: Statement): void {
+function assertRosterAgreement(source: AnyFace, target: AnyFace, statement: Statement): void {
 	source.projection.forEach(function agreeAt(fieldName, position) {
 		const targetField = target.projection[position]
 		if (targetField === undefined) {
@@ -103,79 +78,7 @@ function assertRosterAgreement(source: FaceData, target: FaceData, statement: St
 	})
 }
 
-/**
- * `R(X) -> R` — the FD key form, composite keys as tuples. No selection
- * parameter exists (the FD-with-selection shape is unrepresentable, as in
- * the grammar), and only ordinary relations are accepted: a closed
- * relation's key `R(id) -> R` is materialized by the engine, so an
- * explicit one would only ever be a duplicate. Every projected name is
- * checked against `R`'s field block in the type, and the tuple is carried
- * in the returned value's type ({@link KeyStatement}) — keyed point reads
- * through THIS statement are typed field-for-field, descriptors resolvable
- * through the owner's schema type. A DUPLICATE field in the projection is
- * refused here, at the mint (the engine's `FieldSet` refuses the same
- * duplicate at `Db.create`; canonical utterance says the twice-spelled
- * field is the once-spelled projection respelled) — without this wall a
- * `new Set`-collapsed duplicate could set-match a shorter target
- * projection the engine refuses.
- */
-function key<
-	R extends AnyRelation,
-	const Projection extends readonly [keyof RelationFields<R> & string, ...(keyof RelationFields<R> & string)[]]
->(relation: R, fields: Projection): KeyStatement<R, Projection> {
-	if (isClosedMember(relation)) {
-		throw new AuthoringError({
-			message: `key(${relation.name}, ...): closedness already materializes ${relation.name}(id) -> ${relation.name} — an explicit key on a closed relation is rejected as a duplicate`
-		})
-	}
-	const seen = new Set<string>()
-	for (const fieldName of fields) {
-		if (seen.has(fieldName)) {
-			throw new AuthoringError({
-				message: `key(${relation.name}, ...): the projection spells ${fieldName} twice — write it once (the canonical-utterance law: one meaning, one spelling)`
-			})
-		}
-		seen.add(fieldName)
-	}
-	const data: KeyData<R, Projection> = Object.freeze({
-		kind: "key",
-		owner: relation,
-		projection: Object.freeze(fields)
-	})
-	return Object.freeze({ data, [admitted]: true as const })
-}
-
-function contained<A extends AnyFace, B extends AnyFace>(
-	source: A,
-	target: B & SameArity<A, B> & SameShapes<A, B>
-): ContainedStatement<A["data"], B["data"]> {
-	const data: ContainmentData<A["data"], B["data"]> = Object.freeze({
-		kind: "containment",
-		source: source.data,
-		target: target.data
-	})
-	const statement = Object.freeze({ data, [admitted]: true as const })
-	assertArityAgreement(data.source, data.target, statement)
-	assertRosterAgreement(data.source, data.target, statement)
-	return statement
-}
-
-function mirrors<A extends AnyFace, B extends AnyFace>(
-	source: A,
-	target: B & SameArity<A, B> & SameShapes<A, B>
-): ContainedStatement<A["data"], B["data"]> {
-	const data: MirrorsData<A["data"], B["data"]> = Object.freeze({
-		kind: "mirrors",
-		source: source.data,
-		target: target.data
-	})
-	const statement = Object.freeze({ data, [admitted]: true as const })
-	assertArityAgreement(data.source, data.target, statement)
-	assertRosterAgreement(data.source, data.target, statement)
-	return statement
-}
-
-function assertWeightOnSource(weight: WeightSpec, source: FaceData, statement: Statement): void {
+function assertWeightOnSource(weight: WeightSpec, source: AnyFace, statement: Statement): void {
 	if (weight.kind === "unit") {
 		return
 	}
@@ -197,7 +100,7 @@ function assertWeightOnSource(weight: WeightSpec, source: FaceData, statement: S
 	}
 }
 
-function assertBoundsOnTarget(window: CapacityWindowSpec, target: FaceData, statement: Statement): void {
+function assertBoundsOnTarget(window: CapacityWindowSpec, target: AnyFace, statement: Statement): void {
 	const bounds = window.kind === "range" ? [window.lo, window.hi] : [window.kind === "exact" ? window.n : window.lo]
 	for (const bound of bounds) {
 		if (bound.kind === "lit") {
@@ -222,19 +125,112 @@ function assertBoundsOnTarget(window: CapacityWindowSpec, target: FaceData, stat
 	}
 }
 
-/**
- * The chapter 34 NAMED-OPTIONS capacity call — it replaces the old four
- * positional arguments: `capacity(target, { from, weight?, within })`.
- * Unit weight is the default; `weigh(...)`/`within(...)` remain the only
- * mints for the weight/window values.
- */
+function assertShapes(source: AnyFace, target: AnyFace): void {
+	for (let i = 0; i < source.projection.length; i++) {
+		const a = sealedFieldOf(source.owner, source.projection[i] ?? "")
+		const b = sealedFieldOf(target.owner, target.projection[i] ?? "")
+		if (a === undefined || b === undefined) throw new AuthoringError({ message: "statement: unknown projected field" })
+		const left = a.kind === "interval" ? { ...a, width: undefined } : a
+		const right = b.kind === "interval" ? { ...b, width: undefined } : b
+		if (!signaturesAgree(left, right))
+			throw new AuthoringError({ message: "statement: projected field shapes do not agree" })
+	}
+}
+
+/** Every authoring path checks and owns the same plain descriptor. */
+function statementDescriptor<S extends Statement>(input: S): S
+function statementDescriptor(input: unknown): Statement
+function statementDescriptor(input: unknown): Statement {
+	return checkedStatement(input)
+}
+
+const checkedStatement = descriptorCache((raw): Statement => {
+	const input = recordValue("statement", raw, typeof raw === "object" && raw !== null ? Object.keys(raw) : [])
+	assertDeclarationRecord("statement", input)
+	if (input?.kind === "key") {
+		recordValue("key", input, ["kind", "owner", "projection"])
+		const owner = memberDescriptor(input.owner as unknown)
+		if (isClosedMember(owner))
+			throw new AuthoringError({
+				message: `key(${owner.name}, ...): closedness already materializes its key; explicit keys on closed relations are duplicates`
+			})
+		const projection = arrayValue("key projection", input.projection, (_, value) => {
+			if (typeof value !== "string") throw new AuthoringError({ message: "key: expected a field name" })
+			return value
+		})
+		if (projection.length === 0) throw new AuthoringError({ message: "key: expected a nonempty field projection" })
+		const seen = new Set<string>()
+		for (const field of projection) {
+			if (typeof field !== "string" || sealedFieldOf(owner, field) === undefined)
+				throw new AuthoringError({ message: `key(${owner.name}, ...): unknown field ${String(field)}` })
+			if (seen.has(field))
+				throw new AuthoringError({ message: `key(${owner.name}, ...): the projection spells ${field} twice` })
+			seen.add(field)
+		}
+		return Object.freeze({ kind: "key", owner, projection })
+	}
+	if (input?.kind !== "containment" && input?.kind !== "mirrors" && input?.kind !== "capacity") {
+		throw new AuthoringError({ message: "statement: unknown kind" })
+	}
+	recordValue(
+		"statement",
+		input,
+		input.kind === "capacity" ? ["kind", "target", "weight", "window", "source"] : ["kind", "source", "target"]
+	)
+	const source = faceDescriptor(input.source)
+	const target = faceDescriptor(input.target)
+	const statement =
+		input.kind === "capacity"
+			? Object.freeze({
+					kind: input.kind,
+					source,
+					target,
+					weight: capacityWeight(input.weight),
+					window: capacityWindow(input.window)
+				})
+			: Object.freeze({ kind: input.kind, source, target })
+	assertArityAgreement(source, target, statement)
+	assertRosterAgreement(source, target, statement)
+	assertShapes(source, target)
+	if (statement.kind === "capacity") {
+		const { weight, window } = statement
+		if (weight.kind === "unit" && window.kind === "range" && window.hi.kind === "durationField") {
+			throw new AuthoringError({ message: "a unit (count) window against a duration bound mixes dimensions (C18)" })
+		}
+		assertWeightOnSource(weight, source, statement)
+		assertBoundsOnTarget(window, target, statement)
+	}
+	return statement
+})
+
+function key<
+	R extends AnyRelation,
+	const Projection extends readonly [keyof RelationFields<R> & string, ...(keyof RelationFields<R> & string)[]]
+>(relation: R, fields: Projection): KeyStatement<R, Projection> {
+	return statementDescriptor({ kind: "key", owner: relation, projection: fields })
+}
+
+function contained<A extends AnyFace, B extends AnyFace>(
+	source: A,
+	target: B & SameArity<A, B> & SameShapes<A, B>
+): ContainmentStatement<A, B> {
+	return statementDescriptor({ kind: "containment", source, target })
+}
+
+function mirrors<A extends AnyFace, B extends AnyFace>(
+	source: A,
+	target: B & SameArity<A, B> & SameShapes<A, B>
+): MirrorsStatement<A, B> {
+	return statementDescriptor({ kind: "mirrors", source, target })
+}
+
 function capacity<B extends AnyFace, W extends CapacityWindow, A extends AnyFace>(
 	target: B,
 	options: {
 		readonly from: A & SameArity<B, A> & SameShapes<B, A>
 		readonly within: W & UnitDimensionBan<W> & BoundsOnTarget<W, B>
 	}
-): CapacityStatement<B["data"], A["data"]>
+): CapacityStatement<B, A>
 function capacity<B extends AnyFace, M extends CapacityWeight, W extends CapacityWindow, A extends AnyFace>(
 	target: B,
 	options: {
@@ -242,84 +238,37 @@ function capacity<B extends AnyFace, M extends CapacityWeight, W extends Capacit
 		readonly weight: M & WeightOnSource<M, A>
 		readonly within: W & BoundsOnTarget<W, B>
 	}
-): CapacityStatement<B["data"], A["data"]>
+): CapacityStatement<B, A>
 function capacity(
 	target: AnyFace,
-	options: {
-		readonly from: AnyFace
-		readonly weight?: unknown
-		readonly within: unknown
-	}
-): CapacityStatement<FaceData, FaceData> {
-	if (typeof options !== "object" || options === null || !("from" in options) || !("within" in options)) {
-		throw new AuthoringError({
-			message:
-				"capacity takes named options — capacity(target, { from, weight?, within }) (chapter 34's one spelling; the positional arguments are deleted)"
-		})
-	}
-	const windowValue = options.within
-	const source = options.from
-	if (!isCapacityWindow(windowValue)) {
-		throw new AuthoringError({
-			message:
-				"a capacity window is minted only by within() — a structural literal skips the ban table (the canonical-utterance law)"
-		})
-	}
-	let weight: WeightSpec = unitWeight
-	if (options.weight !== undefined) {
-		if (!isCapacityWeight(options.weight)) {
-			throw new AuthoringError({
-				message: "a capacity weight is minted only by weigh() — a structural literal skips the row-local weight wall"
-			})
-		}
-		weight = options.weight.weight
-	}
-	const window = windowValue.window
-	// The unit-floor and vacuous-window ban tables are deleted:
-	// `{1..*}`, `{N..*}` and `{0..*}` are accepted canonical laws now.
-	// CapacityDimensionMixing remains — genuinely different semantics.
-	if (weight.kind === "unit" && window.kind === "range" && window.hi.kind === "durationField") {
-		throw new AuthoringError({
-			message: `a unit (count) window against the duration() bound on ${window.hi.field} mixes dimensions (C18) — weigh the source with weigh(duration(field)), or bound by a u64 field or literal`
-		})
-	}
-	const data: CapacityData = Object.freeze({
+	options: { readonly from: AnyFace; readonly weight?: unknown; readonly within: unknown }
+): CapacityStatement {
+	recordValue(
+		"capacity options",
+		options,
+		Object.hasOwn(options, "weight") ? ["from", "weight", "within"] : ["from", "within"]
+	)
+	return statementDescriptor({
 		kind: "capacity",
-		target: target.data,
-		weight,
-		window,
-		source: source.data
+		target,
+		source: options.from,
+		weight: options.weight === undefined ? unitWeight : capacityWeight(options.weight),
+		window: capacityWindow(options.within)
 	})
-	const statement = Object.freeze({ data, [admitted]: true as const })
-	assertArityAgreement(data.source, data.target, statement)
-	assertRosterAgreement(data.source, data.target, statement)
-	assertWeightOnSource(weight, data.source, statement)
-	assertBoundsOnTarget(window, data.target, statement)
-	return statement
 }
 
 function renderStatement(statement: Statement): string {
-	const data = statement.data
-	switch (data.kind) {
+	switch (statement.kind) {
 		case "key":
-			return `${data.owner.name}(${data.projection.join(", ")}) -> ${data.owner.name}`
+			return `${statement.owner.name}(${statement.projection.join(", ")}) -> ${statement.owner.name}`
 		case "containment":
-			return `${renderFace(data.source)} <= ${renderFace(data.target)}`
+			return `${renderFace(statement.source)} <= ${renderFace(statement.target)}`
 		case "mirrors":
-			return `${renderFace(data.source)} == ${renderFace(data.target)}`
+			return `${renderFace(statement.source)} == ${renderFace(statement.target)}`
 		case "capacity":
-			return `${renderFace(data.target)} <=${renderWeight(data.weight)}${renderCapacityWindow(data.window)} ${renderFace(data.source)}`
+			return `${renderFace(statement.target)} <=${renderWeight(statement.weight)}${renderCapacityWindow(statement.window)} ${renderFace(statement.source)}`
 	}
 }
 
-export type {
-	CapacityData,
-	CapacityStatement,
-	ContainedStatement,
-	ContainmentData,
-	KeyData,
-	KeyStatement,
-	Statement,
-	StatementData
-}
-export { capacity, contained, isStatement, key, mirrors, renderStatement }
+export type { CapacityStatement, ContainmentStatement, KeyStatement, MirrorsStatement, Statement }
+export { capacity, contained, key, mirrors, renderStatement, statementDescriptor }

package/src/values.ts

@@ -0,0 +1,223 @@
+import { type AuthoringDiagnostic, AuthoringError } from "#errors.ts"
+import type { AnyField, Infer } from "#fields.ts"
+import type { ValueSpec } from "#spec.ts"
+import { Uuid } from "#uuid.ts"
+
+const U64_MAX = 0xffffffffffffffffn
+const I64_MIN = -0x8000000000000000n
+const I64_MAX = 0x7fffffffffffffffn
+
+function invalid(context: string, expected: string, code: AuthoringDiagnostic["code"] = "InvalidValue"): never {
+	throw new AuthoringError({ message: `${context}: expected ${expected}`, diagnostic: { code, context, expected } })
+}
+
+/** Validate the complete record shape without reading any field getter. */
+function recordValue(context: string, input: unknown, fields: readonly string[]): Readonly<Record<string, unknown>> {
+	if (typeof input !== "object" || input === null) {
+		return invalid(context, "a plain record", "InvalidRecord")
+	}
+	const prototype = Object.getPrototypeOf(input)
+	if (prototype !== Object.prototype && prototype !== null) {
+		return invalid(context, "a plain record", "InvalidRecord")
+	}
+	for (const name of Reflect.ownKeys(input)) {
+		if (typeof name !== "string" || !fields.includes(name)) {
+			return invalid(`${context}.${String(name)}`, "only the declared fields", "UnknownField")
+		}
+		const property = Object.getOwnPropertyDescriptor(input, name)
+		if (property?.enumerable !== true || !("value" in property)) {
+			return invalid(`${context}.${name}`, "enumerable own data fields", "InvalidRecord")
+		}
+	}
+	for (const name of fields) {
+		if (!Object.hasOwn(input, name)) {
+			return invalid(`${context}.${name}`, "a required own field", "MissingField")
+		}
+	}
+	return input as Readonly<Record<string, unknown>>
+}
+
+/** Own a dense data array without invoking caller element accessors or methods. */
+function arrayValue<A>(context: string, input: unknown, parse: (context: string, input: unknown) => A): readonly A[] {
+	if (!Array.isArray(input)) return invalid(context, "an array", "InvalidRecord")
+	for (const name of Reflect.ownKeys(input)) {
+		if (name === "length") continue
+		if (typeof name !== "string" || !/^(0|[1-9][0-9]*)$/.test(name) || Number(name) >= input.length)
+			return invalid(context, "only array elements", "InvalidRecord")
+		const property = Object.getOwnPropertyDescriptor(input, name)
+		if (property?.enumerable !== true || !("value" in property))
+			return invalid(context, "own data elements", "InvalidRecord")
+	}
+	const result: A[] = []
+	for (let index = 0; index < input.length; index++) {
+		if (!Object.hasOwn(input, index)) return invalid(`${context}[${index}]`, "a present element", "MissingField")
+		result.push(parse(`${context}[${index}]`, input[index]))
+	}
+	return Object.freeze(result)
+}
+
+function integerValue(context: string, kind: "u64" | "i64", input: unknown): bigint {
+	if (typeof input !== "bigint") return invalid(context, `${kind} bigint`)
+	const minimum = kind === "u64" ? 0n : I64_MIN
+	const maximum = kind === "u64" ? U64_MAX : I64_MAX
+	if (input < minimum || input > maximum) return invalid(context, `${kind} bigint in range`)
+	return input
+}
+
+function floatValue(context: string, input: unknown): number {
+	if (typeof input !== "number") return invalid(context, "number")
+	if (Number.isNaN(input)) return Number.NaN
+	return Object.is(input, -0) ? 0 : input
+}
+
+/** Read typed-array internal slots through the intrinsic getters, never a
+ * caller's shadowed buffer/length properties or custom iterator. */
+function bytesValue(context: string, input: unknown): Uint8Array {
+	if (!(input instanceof Uint8Array)) return invalid(context, "Uint8Array")
+	const prototype = Object.getPrototypeOf(Uint8Array.prototype)
+	const buffer = Reflect.get(prototype, "buffer", input)
+	if (!(buffer instanceof ArrayBuffer))
+		throw new AuthoringError({
+			message: `${context}: SharedArrayBuffer-backed views are refused`,
+			diagnostic: { code: "InvalidValue", context, expected: "ArrayBuffer-backed bytes" }
+		})
+	const offset = Reflect.get(prototype, "byteOffset", input)
+	const length = Reflect.get(prototype, "byteLength", input)
+	try {
+		return new Uint8Array(new Uint8Array(buffer, offset, length))
+	} catch {
+		return invalid(context, "non-detached bytes")
+	}
+}
+
+/**
+ * The host interpreter of a field descriptor. All ingress paths use the
+ * same range, width, ownership and canonicalization rules. Native admission
+ * remains authoritative; this interpreter mirrors its value domain.
+ */
+function fieldValue<F extends AnyField>(context: string, field: F, input: unknown): Infer<F>
+function fieldValue(context: string, field: AnyField, input: unknown): Infer<AnyField> {
+	if ("closed" in field) {
+		if (typeof input !== "string" || !field.closed.handles.includes(input)) {
+			return invalid(context, `a ${field.closed.name} handle`)
+		}
+		return input
+	}
+	switch (field.kind) {
+		case "bool":
+			return typeof input === "boolean" ? input : invalid(context, "boolean")
+		case "str":
+			return typeof input === "string" && input.isWellFormed() ? input : invalid(context, "well-formed string")
+		case "u64":
+		case "i64":
+			return integerValue(context, field.kind, input)
+		case "f64":
+			return floatValue(context, input)
+		case "uuid":
+			return Uuid.isUuid(input) ? input : invalid(context, "canonical UUID text")
+		case "bytes": {
+			const owned = bytesValue(context, input)
+			if (owned.byteLength !== field.width) return invalid(context, `bytes<${field.width}>`)
+			return owned
+		}
+		case "interval": {
+			const record = recordValue(context, input, ["start", "end"])
+			if (field.element === "f64") {
+				const start = floatValue(`${context}.start`, record.start)
+				const end = floatValue(`${context}.end`, record.end)
+				if (!(start < end)) return invalid(context, "a nonempty float interval with non-NaN endpoints")
+				return Object.freeze({ start, end })
+			}
+			const start = integerValue(`${context}.start`, field.element, record.start)
+			const end = integerValue(`${context}.end`, field.element, record.end)
+			if (start >= end) return invalid(context, "a nonempty interval (start < end)")
+			const maximumEnd = field.element === "u64" ? U64_MAX : I64_MAX
+			if (field.width !== undefined && (end === maximumEnd || end - start !== field.width)) {
+				return invalid(context, `a finite interval of width ${field.width}`)
+			}
+			return Object.freeze({ start, end })
+		}
+	}
+}
+
+/** One checked host value to the native logical scalar description. */
+function taggedValueOf(context: string, field: AnyField, input: unknown): ValueSpec {
+	if ("closed" in field) {
+		const handle = fieldValue(context, field, input)
+		return { kind: "u64", value: BigInt(field.closed.handles.indexOf(handle)) }
+	}
+	switch (field.kind) {
+		case "bool":
+			return { kind: "bool", value: fieldValue(context, field, input) }
+		case "str":
+			return { kind: "string", value: fieldValue(context, field, input) }
+		case "u64":
+			return { kind: "u64", value: fieldValue(context, field, input) }
+		case "i64":
+			return { kind: "i64", value: fieldValue(context, field, input) }
+		case "f64":
+			return { kind: "f64", value: fieldValue(context, field, input) }
+		case "uuid":
+			return { kind: "uuid", value: fieldValue(context, field, input) }
+		case "bytes":
+			return { kind: "fixedBytes", value: fieldValue(context, field, input) }
+		case "interval": {
+			if (field.element === "f64") {
+				const value = fieldValue(context, { ...field, element: "f64" }, input)
+				return { kind: "intervalF64", ...value }
+			}
+			const value = fieldValue(context, { ...field, element: field.element }, input)
+			return { kind: field.element === "u64" ? "intervalU64" : "intervalI64", ...value }
+		}
+	}
+}
+
+/** Check a generated logical value through the same field interpreter. */
+function valueDescriptor(context: string, input: unknown): ValueSpec {
+	if (typeof input !== "object" || input === null) return invalid(context, "a tagged value", "InvalidRecord")
+	const tag = recordValue(context, input, Object.keys(input)).kind
+	const intervalElement = { intervalU64: "u64", intervalI64: "i64", intervalF64: "f64" } as const
+	if (tag === "intervalU64" || tag === "intervalI64" || tag === "intervalF64") {
+		const raw = recordValue(context, input, ["kind", "start", "end"])
+		return Object.freeze(
+			taggedValueOf(
+				context,
+				{ kind: "interval", element: intervalElement[tag], width: undefined },
+				{ start: raw.start, end: raw.end }
+			)
+		)
+	}
+	const raw = recordValue(context, input, ["kind", "value"])
+	if (tag === "fixedBytes") {
+		const bytes = bytesValue(context, raw.value)
+		if (bytes.byteLength < 1 || bytes.byteLength > 64) return invalid(context, "bytes with width 1 through 64")
+		return Object.freeze({ kind: "fixedBytes", value: bytes })
+	}
+	if (tag === "string") return Object.freeze(taggedValueOf(context, { kind: "str" }, raw.value))
+	switch (tag) {
+		case "bool":
+			return Object.freeze(taggedValueOf(context, { kind: tag }, raw.value))
+		case "u64":
+			return Object.freeze(taggedValueOf(context, { kind: tag }, raw.value))
+		case "i64":
+			return Object.freeze(taggedValueOf(context, { kind: tag }, raw.value))
+		case "f64":
+			return Object.freeze(taggedValueOf(context, { kind: tag }, raw.value))
+		case "uuid":
+			return Object.freeze(taggedValueOf(context, { kind: tag }, raw.value))
+	}
+	return invalid(context, "a supported value tag", "InvalidDeclaration")
+}
+
+export {
+	arrayValue,
+	bytesValue,
+	fieldValue,
+	I64_MAX,
+	I64_MIN,
+	integerValue,
+	recordValue,
+	taggedValueOf,
+	U64_MAX,
+	valueDescriptor
+}