@bjornpagen/bumbledb 1.1.0 → 1.2.0

package/src/db.ts

@@ -1,14 +1,16 @@
 import type { Scope } from "effect"
 import { Effect, Option } from "effect"
-import type { ChangeSet } from "#changes.ts"
+import type { ChangeCounts, ChangeSet } from "#changes.ts"
 import { internalChanges } from "#changes.ts"
 import { drainClose, releaseOwner } from "#close.ts"
+import { membersAgree } from "#closed.ts"
 import type { CompiledSchema, SchemaId } from "#compile.ts"
-import { Schema as CoreSchema, schemaTables } from "#compile.ts"
+import { Schema as CoreSchema, declaredKey, schemaTables } from "#compile.ts"
 import type {
 	ApplyOutcomeWire,
 	DbInspectionWire,
 	ExpectedWire,
+	JudgeOutcomeWire,
 	PreparedHandle,
 	SnapshotHandle,
 	WitnessWire
@@ -28,11 +30,14 @@ import { factOfCells, keyCellsOf } from "#rows.ts"
 import type { NativeRuntime } from "#runtime.ts"
 import { nativeOperationWith, runtimeHandle } from "#runtime.ts"
 import type { CloseReport } from "#runtime-errors.ts"
-import { DbError } from "#runtime-errors.ts"
+import { argumentError, DbError } from "#runtime-errors.ts"
 import type { DirectoryHandle } from "#runtime-native.ts"
 import { runtimeNative } from "#runtime-native.ts"
 import type { AnySchema } from "#schema.ts"
+import { schemaDescriptor, schemasAgree } from "#schema.ts"
 import type { Key, QueryTemplate, Rel } from "#shape.ts"
+import type { KeyStatement } from "#statements.ts"
+import { integerValue, recordValue } from "#values.ts"
 
 /**
  * The core surface: `Db.create`/`Db.open`, scoped coherent
@@ -57,10 +62,10 @@ interface CoreWitness {
 	readonly generation: bigint
 }
 
-type ApplyExpected = { readonly kind: "any" } | { readonly kind: "exact"; readonly at: CoreWitness }
+type WriteExpected = { readonly kind: "any" } | { readonly kind: "exact"; readonly at: CoreWitness }
 
-/** Expected-state intent for an atomic apply. */
-type ApplyOptions = { readonly expected: ApplyExpected }
+/** Expected-state intent shared by judgment and application. */
+type WriteOptions = { readonly expected: WriteExpected }
 
 type ApplyOutcome =
 	| { readonly kind: "accepted"; readonly witness: CoreWitness }
@@ -68,6 +73,19 @@ type ApplyOutcome =
 	| { readonly kind: "invariant-rejected"; readonly violations: readonly Violation[] }
 	| { readonly kind: "moved"; readonly witnessed: CoreWitness; readonly current: CoreWitness }
 
+/** A judgment against the actual current base, not a promise about a later apply.
+ * A moved witness is unjudged and therefore carries no made-up change counts.
+ */
+type JudgeOutcome =
+	| { readonly kind: "admitted"; readonly base: CoreWitness; readonly changes: ChangeCounts }
+	| {
+			readonly kind: "invariant-rejected"
+			readonly base: CoreWitness
+			readonly changes: ChangeCounts
+			readonly violations: readonly Violation[]
+	  }
+	| { readonly kind: "moved"; readonly witnessed: CoreWitness; readonly current: CoreWitness }
+
 /** Storage measurements, not heap usage or mapped-page residency. */
 interface StorageInspection {
 	/** Reserved virtual address range for the LMDB mapping. */
@@ -96,7 +114,10 @@ interface DbInspection {
  * no writable authority — never a `Db`, an `apply`, or a raw transaction.
  */
 interface QueryReader<S extends AnySchema> {
-	get<R extends Rel<S>>(relation: R, key: Key<R>): Effect.Effect<Option.Option<Fact<R>>, DbError>
+	get<K extends KeyStatement<Rel<S>, readonly string[]>>(
+		key: K,
+		value: NoInfer<Key<K>>
+	): Effect.Effect<Option.Option<Fact<K["owner"]>>, DbError>
 	execute<P extends ParamsRecord, A>(
 		query: QueryTemplate<S, P, A>,
 		params: P
@@ -124,7 +145,9 @@ interface PreparedQuery<P extends ParamsRecord, A> {
 interface Db<S extends AnySchema> {
 	readonly schemaId: SchemaId
 	snapshot(): Effect.Effect<Snapshot<S>, DbError, Scope.Scope>
-	apply(changes: ChangeSet<S>, options: ApplyOptions): Effect.Effect<ApplyOutcome, DbError>
+	apply(changes: ChangeSet<S>, options: WriteOptions): Effect.Effect<ApplyOutcome, DbError>
+	/** Briefly acquires the writer, judges and aborts. Stores no facts or generation. */
+	judge(changes: ChangeSet<S>, options: WriteOptions): Effect.Effect<JudgeOutcome, DbError>
 	inspect(): Effect.Effect<DbInspection, DbError>
 	/** Clear shared query caches without invalidating live snapshots or results. */
 	clearCache(): Effect.Effect<void, DbError>
@@ -152,9 +175,60 @@ function outcomeOf(wire: ApplyOutcomeWire): ApplyOutcome {
 	}
 }
 
+function judgmentOf(wire: JudgeOutcomeWire): JudgeOutcome {
+	switch (wire.tag) {
+		case "admitted":
+			return Object.freeze({ kind: "admitted", base: witnessOf(wire.base), changes: Object.freeze(wire.changes) })
+		case "invariant-rejected":
+			return Object.freeze({
+				kind: "invariant-rejected",
+				base: witnessOf(wire.base),
+				changes: Object.freeze(wire.changes),
+				violations: wire.violations
+			})
+		case "moved":
+			return Object.freeze({ kind: "moved", witnessed: witnessOf(wire.witnessed), current: witnessOf(wire.current) })
+	}
+}
+
+function writeInputs(state: DbState, changes: object, options: WriteOptions, operation: string) {
+	return Effect.try({
+		try: () => {
+			const internal = internalChanges(changes)
+			if (internal === undefined || internal.schemaId !== state.schemaId) {
+				throw refusal(operation, "InvalidArgument")
+			}
+			const record = recordValue("write options", options, ["expected"])
+			const intent = recordValue(
+				"expected state",
+				record.expected,
+				options.expected.kind === "any" ? ["kind"] : ["kind", "at"]
+			)
+			let expected: ExpectedWire
+			if (intent.kind === "any") {
+				expected = { kind: "any" }
+			} else if (intent.kind === "exact") {
+				const at = recordValue("expected witness", intent.at, ["store", "generation"])
+				if (typeof at.store !== "string" || !/^[0-9a-f]{32}$/.test(at.store)) {
+					throw refusal(operation, "InvalidArgument")
+				}
+				expected = {
+					kind: "exact",
+					store: at.store,
+					generation: integerValue("expected generation", "u64", at.generation)
+				}
+			} else {
+				throw refusal(operation, "InvalidArgument")
+			}
+			return { handle: internal.handle, expected }
+		},
+		catch: (cause) => argumentError(operation, cause)
+	})
+}
+
 /**
- * Validates the query template's schema binding (identity, the membership
- * rule) and lowers it to IR plus wire params. Pure host preparation; the
+ * Validates the query template's ordered logical schema and lowers it to
+ * IR plus wire params. Pure host preparation; the
  * engine's IR validation remains the authority.
  */
 function preparedOf<S extends AnySchema>(
@@ -166,7 +240,7 @@ function preparedOf<S extends AnySchema>(
 	readonly wire: ReturnType<typeof wireParams>
 	readonly finds: AnyQuery["data"]["finds"]
 } {
-	if (query.schema !== theory) {
+	if (!schemasAgree(query.schema, theory)) {
 		throw refusal("QueryReader.execute", "InvalidArgument")
 	}
 	const ir = lowerQuery(query)
@@ -188,7 +262,7 @@ function executeOn<S extends AnySchema, A>(
 		Effect.gen(function* () {
 			const prepared = yield* Effect.try({
 				try: () => preparedOf(state.theory, query, params),
-				catch: (cause) => (cause instanceof DbError ? cause : refusal("QueryReader.execute", "InvalidArgument"))
+				catch: (cause) => argumentError("QueryReader.execute", cause)
 			})
 			const handle = yield* nativeOperationWith(
 				"QueryReader.execute",
@@ -220,33 +294,41 @@ function internalResultHandle(result: object) {
 	return internalResult(result)?.handle
 }
 
-function getOn<S extends AnySchema, R extends Rel<S>>(
+function getOn<S extends AnySchema, K extends KeyStatement<Rel<S>, readonly string[]>>(
 	state: SnapshotState<S>,
-	relation: R,
-	key: Key<R>
-): Effect.Effect<Option.Option<Fact<R>>, DbError> {
+	key: K,
+	value: Key<K>
+): Effect.Effect<Option.Option<Fact<K["owner"]>>, DbError> {
 	return Effect.gen(function* () {
-		if (state.theory.relations[relation.name] !== relation) {
+		const tables = schemaTables(state.theory)
+		const resolved = yield* Effect.try({
+			try: () => declaredKey(state.theory, key),
+			catch: (cause) => argumentError("QueryReader.get", cause)
+		})
+		if (resolved === undefined || key.kind !== "key") {
+			return yield* Effect.fail(refusal("QueryReader.get", "InvalidArgument"))
+		}
+		const { statementId } = resolved
+		const relation = resolved.key.owner
+		if (!membersAgree(state.theory.relations[relation.name], relation)) {
 			return yield* Effect.fail(refusal("QueryReader.get", "InvalidArgument"))
 		}
-		const tables = schemaTables(state.theory)
 		const relationId = tables.relationIds.get(relation.name)
-		const primary = tables.primaryKeys.get(relation.name)
-		if (relationId === undefined || primary === undefined) {
+		if (relationId === undefined) {
 			return yield* Effect.fail(refusal("QueryReader.get", "InvalidArgument"))
 		}
 		const cells = yield* Effect.try({
-			try: () => keyCellsOf(relation.data, primary.projection, key as Readonly<Record<string, unknown>>),
-			catch: (cause) => (cause instanceof DbError ? cause : refusal("QueryReader.get", "InvalidArgument"))
+			try: () => keyCellsOf(relation, resolved.key.projection, value),
+			catch: (cause) => argumentError("QueryReader.get", cause)
 		})
 		const row = yield* nativeOperationWith(
 			"QueryReader.get",
-			(callback) => dbNative.runtimeSnapshotGet(state.handle, relationId, primary.statementId, cells, callback),
+			(callback) => dbNative.runtimeSnapshotGet(state.handle, relationId, statementId, cells, callback),
 			dbNative.runtimeRowTake,
 			(value) => value
 		)
 		if (row === null) {
-			return Option.none<Fact<R>>()
+			return Option.none<Fact<K["owner"]>>()
 		}
 		return Option.some(factOfCells(relation, row as readonly CellValue[]))
 	})
@@ -271,7 +353,7 @@ function makePrepared<P extends ParamsRecord, A>(
 				Effect.gen(function* () {
 					const args = yield* Effect.try({
 						try: () => wireParams(definitions, params),
-						catch: () => refusal("PreparedQuery.execute", "InvalidArgument")
+						catch: (cause) => argumentError("PreparedQuery.execute", cause)
 					})
 					const result = yield* nativeOperationWith(
 						"PreparedQuery.execute",
@@ -296,12 +378,12 @@ function prepareOn<S extends AnySchema, P extends ParamsRecord, A>(
 	return Effect.gen(function* () {
 		const ir = yield* Effect.try({
 			try: () => {
-				if (query.schema !== state.theory) {
+				if (!schemasAgree(query.schema, state.theory)) {
 					throw refusal("QueryReader.prepare", "InvalidArgument")
 				}
 				return lowerQuery(query)
 			},
-			catch: () => refusal("QueryReader.prepare", "InvalidArgument")
+			catch: (cause) => argumentError("QueryReader.prepare", cause)
 		})
 		const handle = yield* Effect.acquireRelease(
 			nativeOperationWith(
@@ -321,8 +403,8 @@ function makeSnapshot<S extends AnySchema>(theory: S, handle: SnapshotHandle, wi
 	const state: SnapshotState<S> = { theory, handle }
 	const snapshot: Snapshot<S> = {
 		witness,
-		get(relation, key) {
-			return getOn(state, relation, key)
+		get(key, value) {
+			return getOn(state, key, value)
 		},
 		execute(query, params) {
 			return executeOn(state, query, params)
@@ -376,27 +458,26 @@ function makeDb<S extends AnySchema>(theory: S, state: DbState): Db<S> {
 		},
 		apply(changes, options) {
 			return Effect.gen(function* () {
-				const internal = internalChanges(changes)
-				if (internal === undefined) {
-					// A foreign object supplied dynamically refuses before
-					// any native dispatch.
-					return yield* Effect.fail(refusal("Db.apply", "InvalidArgument"))
-				}
-				if (internal.schemaId !== state.schemaId) {
-					return yield* Effect.fail(refusal("Db.apply", "InvalidArgument"))
-				}
-				const expected: ExpectedWire =
-					options.expected.kind === "any"
-						? { kind: "any" }
-						: { kind: "exact", store: options.expected.at.store, generation: options.expected.at.generation }
+				const input = yield* writeInputs(state, changes, options, "Db.apply")
 				return yield* nativeOperationWith(
 					"Db.apply",
-					(callback) => dbNative.runtimeDbApply(state.db, internal.handle, expected, callback),
+					(callback) => dbNative.runtimeDbApply(state.db, input.handle, input.expected, callback),
 					dbNative.runtimeApplyTake,
 					outcomeOf
 				)
 			})
 		},
+		judge(changes, options) {
+			return Effect.gen(function* () {
+				const input = yield* writeInputs(state, changes, options, "Db.judge")
+				return yield* nativeOperationWith(
+					"Db.judge",
+					(callback) => dbNative.runtimeDbJudge(state.db, input.handle, input.expected, callback),
+					dbNative.runtimeJudgeTake,
+					judgmentOf
+				)
+			})
+		},
 		inspect() {
 			return nativeOperationWith(
 				"Db.inspect",
@@ -446,7 +527,7 @@ function openDatabase<S extends AnySchema>(
 	return Effect.gen(function* () {
 		const runtime = yield* runtimeHandle()
 		const compiled: CompiledSchema<S> = yield* CoreSchema.compile(schema)
-		const spec = lower(schema)
+		const spec = lower(compiled.schema)
 		// Compound acquisition: register the directory owner and
 		// its finalizer BEFORE any interruptible child-open step.
 		const directory = yield* Effect.acquireRelease(
@@ -482,8 +563,8 @@ function openDatabase<S extends AnySchema>(
 					)
 					return yield* Effect.fail(refusal(operation, "InvalidArgument"))
 				}
-				const state: DbState = { theory: schema, db: outcome.db, directory, schemaId: compiled.schemaId }
-				const db = makeDb(schema, state)
+				const state: DbState = { theory: compiled.schema, db: outcome.db, directory, schemaId: compiled.schemaId }
+				const db = makeDb(compiled.schema, state)
 				dbStates.set(db, state)
 				return db
 			}),
@@ -542,10 +623,10 @@ function internalPublishedReader<S extends AnySchema>(
 	readonly execute: QueryReader<S>["execute"]
 	readonly prepare: QueryReader<S>["prepare"]
 } {
-	const state: SnapshotState<S> = { theory, handle: core as SnapshotHandle }
+	const state: SnapshotState<S> = { theory: schemaDescriptor(theory), handle: core as SnapshotHandle }
 	return Object.freeze({
-		get<R extends Rel<S>>(relation: R, key: Key<R>) {
-			return getOn(state, relation, key)
+		get<K extends KeyStatement<Rel<S>, readonly string[]>>(key: K, value: NoInfer<Key<K>>) {
+			return getOn(state, key, value)
 		},
 		execute<P extends ParamsRecord, A>(queryValue: QueryTemplate<S, P, A>, params: P) {
 			return executeOn<S, A>(state, queryValue as AnyQuery, params)
@@ -557,14 +638,15 @@ function internalPublishedReader<S extends AnySchema>(
 }
 
 export type {
-	ApplyExpected,
-	ApplyOptions,
 	ApplyOutcome,
 	CoreWitness,
 	DbInspection,
+	JudgeOutcome,
 	PreparedQuery,
 	QueryReader,
 	Snapshot,
-	StorageInspection
+	StorageInspection,
+	WriteExpected,
+	WriteOptions
 }
 export { Db, internalPublishedReader }

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 }