@bjornpagen/bumbledb 1.1.0 → 1.2.0

package/src/rows.ts

@@ -17,9 +17,9 @@ import { AuthoringError, SdkInvariantError } from "#errors.ts"
  * scans and byte copies.
  */
 import type { AnyClosedRoster, AnyField } from "#fields.ts"
-import { isFloatIntervalValue, isIntervalValue, literalShapeError, rosterOf } from "#fields.ts"
-import type { AnyRelation, Fact, RelationData } from "#relation.ts"
-import { Uuid } from "#uuid.ts"
+import { literalShapeError, rosterOf } from "#fields.ts"
+import { type AnyRelation, type Fact, relationFields } from "#relation.ts"
+import { fieldValue, recordValue } from "#values.ts"
 
 /**
  * One owned cell at the private bridge boundary. The declared sealed field
@@ -44,20 +44,12 @@ interface FlatRows {
 }
 
 function recordOf(fact: object): Readonly<Record<string, unknown>> {
-	if (typeof fact !== "object" && typeof fact !== "function") {
-		throw new AuthoringError({ message: "fact object is not string-indexable" })
+	if (typeof fact !== "object" || fact === null) {
+		throw new AuthoringError({ message: "expected a fact record" })
 	}
 	return fact as Readonly<Record<string, unknown>>
 }
 
-function refuseShared(context: string, value: Uint8Array): void {
-	if (!(value.buffer instanceof ArrayBuffer)) {
-		throw new AuthoringError({
-			message: `${context}: SharedArrayBuffer-backed views are refused — make a synchronized stable copy into ordinary unshared input first`
-		})
-	}
-}
-
 /**
  * Approximate payload size for host batching, not a memory allowance.
  * Strings use two bytes per UTF-16 code unit, not their UTF-8 wire size.
@@ -81,26 +73,11 @@ function hostCellCharge(value: unknown): bigint {
 	return 0n
 }
 
-/**
- * The write half of the closed bijection: one handle NAME to its u64 row
- * id (declaration order = row ids). An unknown name is a pointed refusal
- * naming the vocabulary and its roster.
- */
-function closedCellOf(context: string, closed: AnyClosedRoster, name: string): CellValue {
-	const id = closed.handles.indexOf(name)
-	if (id === -1) {
-		throw new AuthoringError({
-			message: `${context}: "${name}" is not a handle of ${closed.name} — the roster is ${closed.handles.join(", ")}`
-		})
-	}
-	return BigInt(id)
-}
-
 function handleOf(context: string, closed: AnyClosedRoster, cell: unknown): string {
 	if (typeof cell !== "bigint") {
 		throw literalShapeError(context, `a ${closed.name} handle id (bigint)`, cell)
 	}
-	const handle = closed.handles[Number(cell)]
+	const handle = cell < 0n || cell >= BigInt(closed.handles.length) ? undefined : closed.handles[Number(cell)]
 	if (handle === undefined) {
 		throw new AuthoringError({
 			message: `${context}: id ${cell} is outside the ${closed.name} roster (${closed.handles.join(", ")})`
@@ -110,86 +87,21 @@ function handleOf(context: string, closed: AnyClosedRoster, cell: unknown): stri
 }
 
 function cellOf(context: string, field: AnyField, value: unknown): CellValue {
-	const roster = rosterOf(field)
-	if (roster !== undefined) {
-		if (typeof value !== "string") {
-			throw literalShapeError(context, `a ${roster.name} handle name (string)`, value)
-		}
-		return closedCellOf(context, roster, value)
-	}
-	switch (field.kind) {
-		case "bool": {
-			if (typeof value !== "boolean") {
-				throw literalShapeError(context, "boolean", value)
-			}
-			return value
-		}
-		case "u64":
-		case "i64": {
-			if (typeof value !== "bigint") {
-				throw literalShapeError(context, "bigint", value)
-			}
-			return value
-		}
-		case "str": {
-			if (typeof value !== "string") {
-				throw literalShapeError(context, "string", value)
-			}
-			if (!value.isWellFormed()) {
-				throw literalShapeError(context, "well-formed string", value)
-			}
-			return value
-		}
-		case "f64": {
-			if (typeof value !== "number") {
-				throw literalShapeError(context, "number", value)
-			}
-			return value
-		}
-		case "uuid": {
-			if (!Uuid.isUuid(value)) {
-				throw literalShapeError(context, "a UUID (canonical UUID text)", value)
-			}
-			// UUIDs cross as canonical hyphenated text, not raw bytes.
-			return value
-		}
-		case "bytes": {
-			if (!(value instanceof Uint8Array)) {
-				throw literalShapeError(context, "Uint8Array", value)
-			}
-			refuseShared(context, value)
-			if (value.byteLength !== field.width) {
-				throw new AuthoringError({
-					message: `${context}: bytes<${field.width}> takes exactly ${field.width} bytes (got ${value.byteLength})`
-				})
-			}
-			// Owned copy at the ownership boundary: later caller mutation
-			// cannot change an accepted cell.
-			return Uint8Array.from(value)
-		}
-		case "interval": {
-			if (field.element === "f64") {
-				if (!isFloatIntervalValue(value)) {
-					throw literalShapeError(context, "float interval ({ start, end } numbers)", value)
-				}
-				if (Number.isNaN(value.start) || Number.isNaN(value.end)) {
-					throw new AuthoringError({ message: `${context}: a float interval endpoint cannot be NaN` })
-				}
-				const start = Object.is(value.start, -0) ? 0 : value.start
-				const end = Object.is(value.end, -0) ? 0 : value.end
-				if (!(start < end)) {
-					throw new AuthoringError({
-						message: `${context}: a float interval is half-open and nonempty (start < end strictly)`
-					})
-				}
-				return { start, end }
-			}
-			if (!isIntervalValue(value)) {
-				throw literalShapeError(context, "interval ({ start, end } bigints)", value)
-			}
-			return { start: value.start, end: value.end }
-		}
+	if ("closed" in field) {
+		return BigInt(field.closed.handles.indexOf(fieldValue(context, field, value)))
 	}
+	return fieldValue(context, field, value)
+}
+
+function factCellsOf(data: AnyRelation, fact: unknown): CellValue[] {
+	const record = recordValue(
+		`relation ${data.name}`,
+		fact,
+		relationFields(data).map((declared) => declared.name)
+	)
+	return relationFields(data).map((declared) =>
+		cellOf(`relation ${data.name} field ${declared.name}`, declared.field, record[declared.name])
+	)
 }
 
 /**
@@ -198,115 +110,39 @@ function cellOf(context: string, field: AnyField, value: unknown): CellValue {
  * Missing-field refusal and per-cell judgment are
  * {@link cellOf}'s, byte for byte.
  */
-function flatRowsOf(data: RelationData, facts: Iterable<object>): FlatRows {
+function flatRowsOf(data: AnyRelation, facts: Iterable<object>): FlatRows {
 	const cells: CellValue[] = []
 	let rows = 0n
 	for (const fact of facts) {
+		for (const cell of factCellsOf(data, fact)) cells.push(cell)
 		rows += 1n
-		const record = recordOf(fact)
-		for (const declared of data.fields) {
-			const value = record[declared.name]
-			if (value === undefined) {
-				throw new AuthoringError({ message: `relation ${data.name}: fact is missing field ${declared.name}` })
-			}
-			const cell = cellOf(`relation ${data.name} field ${declared.name}`, declared.field, value)
-			cells.push(cell)
-		}
 	}
 	return { rows, cells }
 }
 
 function keyCellsOf(
-	data: RelationData,
+	data: AnyRelation,
 	projection: readonly string[],
-	key: Readonly<Record<string, unknown>>
+	input: Readonly<Record<string, unknown>>
 ): CellValue[] {
-	for (const supplied of Object.keys(key)) {
-		if (key[supplied] !== undefined && !projection.includes(supplied)) {
-			throw new AuthoringError({
-				message: `relation ${data.name}: key object carries field ${supplied} outside the primary key projection (${projection.join(", ")})`
-			})
-		}
-	}
+	const key = recordValue(`relation ${data.name} key`, input, projection)
 	return projection.map(function marshalKeyCell(fieldName) {
-		const declared = data.fields.find(function byName(candidate) {
-			return candidate.name === fieldName
-		})
+		const declared = relationFields(data).find((candidate) => candidate.name === fieldName)
 		if (declared === undefined) {
-			throw new AuthoringError({
-				message: `relation ${data.name}: key projection cites unknown field ${fieldName}`
-			})
+			throw new AuthoringError({ message: `relation ${data.name}: key projection cites unknown field ${fieldName}` })
 		}
-		const value = key[fieldName]
-		if (value === undefined) {
-			throw new AuthoringError({
-				message: `relation ${data.name}: key object is missing field ${fieldName} — get reads through the primary (first-declared) key, whose projection is (${projection.join(", ")})`
-			})
-		}
-		return cellOf(`relation ${data.name} key field ${fieldName}`, declared.field, value)
+		return cellOf(`relation ${data.name} key field ${fieldName}`, declared.field, key[fieldName])
 	})
 }
 
 function decodeCell(context: string, field: AnyField, cell: unknown): unknown {
 	const roster = rosterOf(field)
-	if (roster !== undefined) {
-		return handleOf(context, roster, cell)
-	}
-	switch (field.kind) {
-		case "bool": {
-			if (typeof cell !== "boolean") {
-				throw new SdkInvariantError({ message: `${context}: expected boolean cell` })
-			}
-			return cell
-		}
-		case "u64":
-		case "i64": {
-			if (typeof cell !== "bigint") {
-				throw new SdkInvariantError({ message: `${context}: expected bigint cell` })
-			}
-			return cell
-		}
-		case "f64": {
-			if (typeof cell !== "number") {
-				throw new SdkInvariantError({ message: `${context}: expected number cell` })
-			}
-			return cell
-		}
-		case "str": {
-			if (typeof cell !== "string") {
-				throw new SdkInvariantError({ message: `${context}: expected string cell` })
-			}
-			return cell
-		}
-		case "uuid": {
-			// The native renderer spells uuid as the canonical
-			// canonical hyphenated UUID string (marshal.rs `uuid_hex`); the read
-			// side revalidates the spelling and keeps the string value.
-			if (!Uuid.isUuid(cell)) {
-				throw new SdkInvariantError({
-					message: `${context}: expected an uuid cell (canonical UUID text)`
-				})
-			}
-			return cell
-		}
-		case "bytes": {
-			if (!(cell instanceof Uint8Array)) {
-				throw new SdkInvariantError({ message: `${context}: expected owned bytes` })
-			}
-			return cell
-		}
-		case "interval": {
-			if (field.element === "f64") {
-				if (!isFloatIntervalValue(cell)) {
-					throw new SdkInvariantError({ message: `${context}: expected a float interval cell` })
-				}
-				return Object.freeze({ start: cell.start, end: cell.end })
-			}
-			if (!isIntervalValue(cell)) {
-				throw new SdkInvariantError({ message: `${context}: expected an integer interval cell` })
-			}
-			return Object.freeze({ start: cell.start, end: cell.end })
-		}
+	if (roster !== undefined) return handleOf(context, roster, cell)
+	try {
+		return fieldValue(context, field, cell)
+	} catch (cause) {
+		if (cause instanceof AuthoringError) throw new SdkInvariantError({ message: cause.message })
+		throw cause
 	}
 }
 
@@ -314,7 +150,7 @@ function isCompleteFact<R extends AnyRelation>(
 	relation: R,
 	decoded: Readonly<Record<string, unknown>>
 ): decoded is Readonly<Record<string, unknown>> & Fact<R> {
-	return relation.data.fields.every(function present(declared) {
+	return relationFields(relation).every(function present(declared) {
 		return decoded[declared.name] !== undefined
 	})
 }
@@ -324,21 +160,22 @@ function isCompleteFact<R extends AnyRelation>(
  * declared field order: stable field names and shapes, no Proxy or per-cell closures.
  */
 function factOfCells<R extends AnyRelation>(relation: R, row: readonly unknown[]): Fact<R> {
-	const data = relation.data
-	if (row.length !== data.fields.length) {
+	const data = relation
+	if (row.length !== relationFields(data).length) {
 		throw new SdkInvariantError({
-			message: `relation ${data.name}: row arity ${row.length} does not match the ${data.fields.length} declared fields`
+			message: `relation ${data.name}: row arity ${row.length} does not match the ${relationFields(data).length} declared fields`
 		})
 	}
 	const decoded: Record<string, unknown> = {}
-	data.fields.forEach(function decodeOne(declared, ordinal) {
+	relationFields(data).forEach(function decodeOne(declared, ordinal) {
 		const cell = row[ordinal]
 		if (cell === undefined) {
 			throw new SdkInvariantError({
 				message: `relation ${data.name}: row cell ${ordinal} (${declared.name}) is absent`
 			})
 		}
-		decoded[declared.name] = decodeCell(`relation ${data.name} field ${declared.name}`, declared.field, cell)
+		const value = decodeCell(`relation ${data.name} field ${declared.name}`, declared.field, cell)
+		setOwnField(decoded, declared.name, value)
 	})
 	Object.freeze(decoded)
 	if (!isCompleteFact(relation, decoded)) {
@@ -347,5 +184,25 @@ function factOfCells<R extends AnyRelation>(relation: R, row: readonly unknown[]
 	return decoded
 }
 
+/** Preserve every declared name as data, including JavaScript's prototype setter. */
+function setOwnField(record: Record<string, unknown>, name: string, value: unknown): void {
+	if (name === "__proto__") {
+		Object.defineProperty(record, name, { value, enumerable: true, writable: true, configurable: true })
+	} else {
+		record[name] = value
+	}
+}
+
 export type { CellValue, FlatRows }
-export { cellOf, decodeCell, factOfCells, flatRowsOf, handleOf, hostCellCharge, keyCellsOf, recordOf }
+export {
+	cellOf,
+	decodeCell,
+	factCellsOf,
+	factOfCells,
+	flatRowsOf,
+	handleOf,
+	hostCellCharge,
+	keyCellsOf,
+	recordOf,
+	setOwnField
+}

package/src/runtime-errors.ts

@@ -1,4 +1,5 @@
 import { Schema } from "effect"
+import { AuthoringDiagnostic, AuthoringError } from "#errors.ts"
 import { runtimeErrorCodes } from "#runtime-codes.ts"
 
 export { runtimeErrorCodes } from "#runtime-codes.ts"
@@ -12,7 +13,18 @@ const ResourceLimit = Schema.Struct({
 })
 const PlainReason = Schema.Struct({
 	_tag: Schema.Literals(
-		runtimeErrorCodes.filter((code) => code !== "ResourceLimit" && code !== "Io" && code !== "Engine")
+		runtimeErrorCodes.filter(
+			(code) => code !== "ResourceLimit" && code !== "Io" && code !== "Engine" && code !== "InvalidArgument"
+		)
+	)
+})
+const InvalidArgument = Schema.Struct({
+	_tag: Schema.Literal("InvalidArgument"),
+	detail: Schema.optional(
+		Schema.Struct({
+			message: Schema.String,
+			diagnostic: Schema.optional(AuthoringDiagnostic)
+		})
 	)
 })
 const Io = Schema.Struct({
@@ -26,7 +38,7 @@ const Engine = Schema.Struct({
 	kind: Schema.String,
 	message: Schema.String
 })
-export const DbReason = Schema.Union([ResourceLimit, Io, Engine, PlainReason])
+export const DbReason = Schema.Union([ResourceLimit, Io, Engine, InvalidArgument, PlainReason])
 export class DbError extends Schema.TaggedError<DbError>()("DbError", {
 	operation: Schema.String,
 	reason: DbReason
@@ -34,12 +46,44 @@ export class DbError extends Schema.TaggedError<DbError>()("DbError", {
 	get code() {
 		return this.reason._tag
 	}
+	/** Safe default display; callers explicitly inspect structured detail. */
+	override get message(): string {
+		return `${this.operation}: ${this.code}`
+	}
 }
 
 const decodeReason = Schema.decodeUnknownOption(DbReason)
 export function dbError(operation: string, cause: unknown): DbError {
+	if (cause instanceof DbError) return cause
+	if (cause instanceof AuthoringError) return argumentError(operation, cause)
 	const decoded = decodeReason(cause)
-	return new DbError({ operation, reason: decoded._tag === "Some" ? decoded.value : { _tag: "Internal" } })
+	if (decoded._tag === "Some") return new DbError({ operation, reason: decoded.value })
+	// Synchronous native schema/marshalling refusals precede the executor's
+	// tagged error wire. Preserve their engine family instead of losing it.
+	if (
+		typeof cause === "object" &&
+		cause !== null &&
+		"kind" in cause &&
+		typeof cause.kind === "string" &&
+		"message" in cause &&
+		typeof cause.message === "string"
+	) {
+		return new DbError({ operation, reason: { _tag: "Engine", kind: cause.kind, message: cause.message } })
+	}
+	return new DbError({ operation, reason: { _tag: "Internal" } })
+}
+
+/** Host input failures retain authoring details without displaying values. */
+export function argumentError(operation: string, cause: unknown): DbError {
+	if (cause instanceof DbError) return cause
+	if (cause instanceof AuthoringError) {
+		const detail =
+			cause.diagnostic === undefined
+				? { message: cause.message }
+				: { message: cause.message, diagnostic: cause.diagnostic }
+		return new DbError({ operation, reason: { _tag: "InvalidArgument", detail } })
+	}
+	return new DbError({ operation, reason: { _tag: "InvalidArgument" } })
 }
 
 const Outstanding = Schema.Struct({

package/src/schema.ts

@@ -1,3 +1,4 @@
+import { isDeepStrictEqual } from "node:util"
 import { AuthoringError, SdkInvariantError } from "#errors.ts"
 /**
  * `schema` — assembles relations and statements into a theory value (the
@@ -17,13 +18,15 @@ import { AuthoringError, SdkInvariantError } from "#errors.ts"
  */
 
 import type { AnyClosed } from "#closed.ts"
-import { isClosedMember, sealedFieldOf } from "#closed.ts"
-import type { FaceData } from "#face.ts"
+import { isClosedMember, memberDescriptor, membersAgree, sealedFieldOf } from "#closed.ts"
+import type { AnyFace } from "#face.ts"
 import { assertDeclarationOrderKey, assertDeclarationRecord, rosterOf } from "#fields.ts"
+import { descriptorCache, isImmutable } from "#immutable.ts"
 import { type ClassesOf, classesComplete, computeClasses, type LawfulStatements, type SchemaClasses } from "#law.ts"
 import type { AnyRelation } from "#relation.ts"
 import type { LiteralSetSpec, LiteralSpec } from "#spec.ts"
-import { isStatement, renderStatement, type Statement } from "#statements.ts"
+import { renderStatement, type Statement, statementDescriptor } from "#statements.ts"
+import { arrayValue, recordValue } from "#values.ts"
 
 interface ImpliedKeys {
 	readonly rendered: ReadonlySet<string>
@@ -54,7 +57,7 @@ function collectImplied(name: string, relations: SchemaRelations): ImpliedKeys {
 }
 
 function statementOwners(statement: Statement): readonly SchemaRelation[] {
-	const data = statement.data
+	const data = statement
 	if (data.kind === "key") {
 		return [data.owner]
 	}
@@ -69,9 +72,9 @@ function verifyMembership(name: string, relations: SchemaRelations, statement: S
 				message: `schema ${name}: relation ${owner.name} is not declared in this schema — ${rendered}`
 			})
 		}
-		if (member !== owner) {
+		if (!membersAgree(member, owner)) {
 			throw new AuthoringError({
-				message: `schema ${name}: statement references a different relation value named ${owner.name} than the one this schema declares — ${rendered}`
+				message: `schema ${name}: statement references a different relation declaration named ${owner.name} than the one this schema declares — ${rendered}`
 			})
 		}
 	}
@@ -86,7 +89,7 @@ function bindingLiterals(set: LiteralSetSpec): readonly LiteralSpec[] {
 
 function verifyBindingHandles(
 	name: string,
-	face: FaceData,
+	face: AnyFace,
 	binding: { readonly field: string; readonly set: LiteralSetSpec },
 	rendered: string
 ): void {
@@ -109,7 +112,7 @@ function verifyBindingHandles(
 }
 
 function verifyHandles(name: string, statement: Statement, rendered: string): void {
-	const data = statement.data
+	const data = statement
 	if (data.kind === "key") {
 		return
 	}
@@ -122,11 +125,11 @@ function verifyHandles(name: string, statement: Statement, rendered: string): vo
 
 function closedTargetOf(statements: readonly Statement[], owner: string, field: string): string | undefined {
 	for (const statement of statements) {
-		const data = statement.data
+		const data = statement
 		if (data.kind !== "containment" && data.kind !== "mirrors") {
 			continue
 		}
-		const pairs: Array<readonly [FaceData, FaceData]> = [[data.source, data.target]]
+		const pairs: Array<readonly [AnyFace, AnyFace]> = [[data.source, data.target]]
 		if (data.kind === "mirrors") {
 			pairs.push([data.target, data.source])
 		}
@@ -148,7 +151,7 @@ function closedTargetOf(statements: readonly Statement[], owner: string, field:
 
 function verifyClosedReferences(name: string, statements: readonly Statement[]): void {
 	for (const statement of statements) {
-		const data = statement.data
+		const data = statement
 		if (data.kind === "key") {
 			continue
 		}
@@ -164,7 +167,7 @@ function verifyClosedReferences(name: string, statements: readonly Statement[]):
 function verifyClosedReferenceBinding(
 	name: string,
 	statements: readonly Statement[],
-	face: FaceData,
+	face: AnyFace,
 	binding: { readonly field: string; readonly set: LiteralSetSpec },
 	rendered: string
 ): void {
@@ -213,7 +216,7 @@ function verifyTargetKeys(
 ): void {
 	const declared = new Map<string, Array<readonly string[]>>()
 	for (const statement of statements) {
-		const data = statement.data
+		const data = statement
 		if (data.kind !== "key") {
 			continue
 		}
@@ -225,7 +228,7 @@ function verifyTargetKeys(
 		}
 	}
 	for (const statement of statements) {
-		const data = statement.data
+		const data = statement
 		if (data.kind === "key") {
 			continue
 		}
@@ -251,7 +254,7 @@ function verifyTargetKeys(
  */
 function verifyTargetKeyFace(
 	name: string,
-	face: FaceData,
+	face: AnyFace,
 	implied: ReadonlyMap<string, ReadonlyArray<readonly string[]>>,
 	declared: ReadonlyMap<string, ReadonlyArray<readonly string[]>>,
 	rendered: string
@@ -310,25 +313,92 @@ interface Schema<Rels extends SchemaRelations, Classes extends SchemaClasses = S
 
 type AnySchema = Schema<SchemaRelations>
 
+/**
+ * Logical schema equivalence, including the ordered native ordinals and
+ * host decoding domains. Schema display names do not change the theory.
+ * A database/snapshot still has its own resource identity and lifetime.
+ */
+function schemasAgree(leftInput: AnySchema, rightInput: AnySchema): boolean {
+	const left = schemaDescriptor(leftInput)
+	const right = schemaDescriptor(rightInput)
+	if (left === right) return true
+	const cacheable = isImmutable(left) && isImmutable(right)
+	const cached = schemaComparisons.get(left)?.get(right)
+	if (cacheable && cached !== undefined) return cached
+	const names = Object.keys(left.relations)
+	const otherNames = Object.keys(right.relations)
+	const equal =
+		names.length === otherNames.length &&
+		names.every((name, index) => {
+			const member = right.relations[name]
+			return name === otherNames[index] && member !== undefined && membersAgree(left.relations[name], member)
+		}) &&
+		isDeepStrictEqual(left.statements, right.statements) &&
+		isDeepStrictEqual(left.classes, right.classes)
+	if (cacheable) {
+		let comparisons = schemaComparisons.get(left)
+		if (comparisons === undefined) {
+			comparisons = new WeakMap()
+			schemaComparisons.set(left, comparisons)
+		}
+		comparisons.set(right, equal)
+	}
+	return equal
+}
+
+const schemaComparisons = new WeakMap<AnySchema, WeakMap<AnySchema, boolean>>()
+
+function schemaDescriptor<S extends AnySchema>(input: S): S
+function schemaDescriptor(input: unknown): AnySchema
+function schemaDescriptor(input: unknown): AnySchema {
+	return checkedSchema(input)
+}
+
+const checkedSchema = descriptorCache((input): AnySchema => {
+	const raw = recordValue("schema", input, ["name", "relations", "statements", "classes"])
+	if (typeof raw.name !== "string") throw new AuthoringError({ message: "schema: expected a name" })
+	const relations = ownRelations(raw.name, raw.relations)
+	const statements = arrayValue("schema statements", raw.statements, (_, statement) => statementDescriptor(statement))
+	const result = schema(raw.name, relations, statements)
+	const classes = recordValue("schema classes", raw.classes, Object.keys(result.classes))
+	for (const [name, fields] of Object.entries(result.classes)) {
+		const supplied = recordValue(`schema classes.${name}`, classes[name], Object.keys(fields))
+		for (const [field, value] of Object.entries(fields)) {
+			if (supplied[field] !== value)
+				throw new AuthoringError({ message: `schema classes.${name}.${field}: incorrect class` })
+		}
+	}
+	return result
+})
+
 type EvaluatedClasses<C extends SchemaClasses> = C extends SchemaClasses
 	? { readonly [N in keyof C]: { readonly [F in keyof C[N]]: C[N][F] } }
 	: never
 
+function ownRelations<R extends SchemaRelations>(name: string, input: R): R
+function ownRelations(name: string, input: unknown): SchemaRelations
+function ownRelations(name: string, input: unknown): SchemaRelations {
+	if (typeof input !== "object" || input === null)
+		throw new AuthoringError({ message: `schema ${name}: expected relations` })
+	assertDeclarationRecord(`schema ${name} relations`, input)
+	return Object.freeze(
+		Object.fromEntries(Object.entries(input).map(([name, member]) => [name, memberDescriptor(member)]))
+	)
+}
+
 function schema<const Rels extends SchemaRelations, const Stmts extends readonly Statement[]>(
 	name: string,
 	relations: Rels,
 	statements: Stmts & LawfulStatements<Rels, Stmts>
 ): Schema<Rels, EvaluatedClasses<ClassesOf<Rels, Stmts>>> {
-	const implied = collectImplied(name, relations)
+	assertDeclarationOrderKey("schema", name)
+	const ownedRelations = ownRelations(name, relations)
+	const ownedStatements = arrayValue("schema statements", statements, (_, statement) => statementDescriptor(statement))
+	const implied = collectImplied(name, ownedRelations)
 	const seen = new Set<string>()
-	for (const statement of statements) {
-		if (!isStatement(statement)) {
-			throw new AuthoringError({
-				message: `schema ${name}: a statement is minted only by key/contained/mirrors/capacity — a structural literal skips the construction-time arity and roster walls`
-			})
-		}
+	for (const statement of ownedStatements) {
 		const rendered = renderStatement(statement)
-		verifyMembership(name, relations, statement, rendered)
+		verifyMembership(name, ownedRelations, statement, rendered)
 		if (implied.rendered.has(rendered)) {
 			throw new AuthoringError({
 				message: `schema ${name}: ${rendered} is redundant here (closedness already implies it) — and rejected as a duplicate`
@@ -340,14 +410,14 @@ function schema<const Rels extends SchemaRelations, const Stmts extends readonly
 		seen.add(rendered)
 		verifyHandles(name, statement, rendered)
 	}
-	verifyClosedReferences(name, statements)
-	verifyTargetKeys(name, statements, implied.roster)
-	const classes = computeClasses(name, relations, statements)
-	if (!classesComplete<EvaluatedClasses<ClassesOf<Rels, Stmts>>>(classes, relations)) {
+	verifyClosedReferences(name, ownedStatements)
+	verifyTargetKeys(name, ownedStatements, implied.roster)
+	const classes = computeClasses(name, ownedRelations, ownedStatements)
+	if (!classesComplete<EvaluatedClasses<ClassesOf<Rels, Stmts>>>(classes, ownedRelations)) {
 		throw new SdkInvariantError({ message: `schema ${name}: class-map construction incomplete` })
 	}
-	return Object.freeze({ name, relations, statements: Object.freeze([...statements]), classes })
+	return Object.freeze({ name, relations: ownedRelations, statements: Object.freeze(ownedStatements), classes })
 }
 
 export type { AnySchema, Schema, SchemaRelation, SchemaRelations }
-export { schema }
+export { schema, schemaDescriptor, schemasAgree }