@bjornpagen/bumbledb 1.0.1 → 1.2.0

package/COOKBOOK.md

@@ -8,7 +8,7 @@ reads, sealed complete results, and one-shot page streams.
 Every `ts` fence below is extracted and type-checked against the real
 package surface by `test/cookbook-doc.test.ts`; the imports fence here is
 prepended to every recipe. The examples are lazy Effect programs — nothing
-below runs a database at import time, and measured policies are inputs.
+below runs a database at import time.
 
 ```ts
 import { Effect, Option, Result, Stream } from "effect"
@@ -18,6 +18,7 @@ import {
 	closed,
 	contained,
 	Db,
+	describeQuery,
 	duration,
 	f64,
 	i64,
@@ -29,11 +30,11 @@ import {
 	NativeRuntime,
 	on,
 	query,
+	queryFromDescription,
 	ref,
 	relation,
 	Scalar,
 	schema,
-	span,
 	str,
 	u64,
 	v,
@@ -43,14 +44,12 @@ import {
 import type {
 	ApplyOutcome,
 	CompleteResult,
-	ExecutionPolicy,
 	Fact,
-	NativeRuntimeOptions,
+	FloatIntervalValue,
+	IntervalValue,
 	QueryReader
 } from "@bjornpagen/bumbledb"
 
-declare const work: ExecutionPolicy
-declare const runtimePolicy: NativeRuntimeOptions
 declare const localPath: string
 ```
 
@@ -93,8 +92,18 @@ void [Learning, scoreIsNumber, unitsAreExact]
 
 ## 2. One runtime layer; explicit create and open
 
-`NativeRuntime.layer(options)` acquires the single bounded native runtime
+`NativeRuntime.layer()` acquires the single native runtime
 with scope; reuse ONE layer value so Effect's memoization shares it.
+Optional configuration controls workers, outstanding jobs/handles, and cleanup
+reporting. Defaults are up to four workers, 128 queued jobs, 128 cleanup reports,
+64 directory owners, 1,024 native handles, and a five-second cleanup report window.
+Operations use ordinary allocation without byte/row/work quotas or execution
+deadlines. Effect interruption requests cooperative cancellation. Runtime
+inspection reports outstanding work, not memory usage.
+Database `inspect().storage` reports virtual map extent, populated file length,
+non-free LMDB pages, and allocated disk blocks (null when unavailable).
+None of these measures process heap usage or resident RAM. Log history
+inspection uses the same `StorageInspection` fields.
 `Db.open` never creates a missing database; `Db.create` refuses existing
 authority. Both are scoped acquisitions.
 
@@ -104,20 +113,20 @@ const Docs = schema("Docs", { Doc }, [key(Doc, ["id"])])
 
 const openExisting = Effect.scoped(
 	Effect.gen(function* () {
-		const db = yield* Db.open(localPath, Docs, work)
+		const db = yield* Db.open(localPath, Docs)
 		return db.schemaId
 	})
 )
 
 const createOnce = Effect.scoped(
 	Effect.gen(function* () {
-		const db = yield* Db.create(localPath, Docs, work)
+		const db = yield* Db.create(localPath, Docs)
 		return db.schemaId
 	})
 )
 
 // One boundary; an Effect app provides the layer in its own graph instead.
-const layer = NativeRuntime.layer(runtimePolicy)
+const layer = NativeRuntime.layer()
 void [openExisting.pipe(Effect.provide(layer)), createOnce.pipe(Effect.provide(layer))]
 ```
 
@@ -125,7 +134,7 @@ void [openExisting.pipe(Effect.provide(layer)), createOnce.pipe(Effect.provide(l
 
 `ChangeSet.builder` acquires a scoped database-free draft. Ingestion effects
 are lazy and re-runnable while the draft is building — each execution reads
-the then-current iterable and charges work again. Within ONE change set the
+the then-current iterable. Within ONE change set the
 normalization is `(add, remove ∖ add)`: the identical fact's add wins
 independent of call order. `finish()` consumes the draft into an immutable,
 reusable `ChangeSet`.
@@ -136,12 +145,12 @@ const Tasks = schema("Tasks", { Task }, [key(Task, ["id"])])
 
 const applyOnce = Effect.scoped(
 	Effect.gen(function* () {
-		const db = yield* Db.open(localPath, Tasks, work)
+		const db = yield* Db.open(localPath, Tasks)
 		const taskId = yield* Effect.sync(() => crypto.randomUUID())
-		const draft = yield* ChangeSet.builder(Tasks, work)
+		const draft = yield* ChangeSet.builder(Tasks)
 		yield* draft.insert(Task, [{ id: taskId, title: "write the cookbook", done: 0n }])
 		const changes = yield* draft.finish()
-		const outcome: ApplyOutcome = yield* db.apply(changes, { ...work, expected: { kind: "any" } })
+		const outcome: ApplyOutcome = yield* db.apply(changes, { expected: { kind: "any" } })
 		switch (outcome.kind) {
 			case "accepted":
 			case "no-change":
@@ -157,18 +166,83 @@ const applyOnce = Effect.scoped(
 void applyOnce
 ```
 
+For a noncommitting check, `db.judge` runs the same admission procedure and
+aborts its private candidate on the native worker. It briefly takes the
+writer; it does not hold a writer session open in JavaScript. Admitted and
+rejected judgments include the actual base and net proposed fact counts.
+Operational errors stay in the Effect error channel.
+
+```ts
+const judgeOnce = Effect.scoped(
+	Effect.gen(function* () {
+		const db = yield* Db.open(localPath, Tasks)
+		const draft = yield* ChangeSet.builder(Tasks)
+		const id = yield* Effect.sync(() => crypto.randomUUID())
+		yield* draft.insert(Task, [{ id, title: "inspect a candidate", done: 0n }])
+		return yield* db.judge(yield* draft.finish(), { expected: { kind: "any" } })
+	})
+)
+void judgeOnce
+```
+
+Judgment is optional: `apply` always judges for itself. To act on a judgment,
+use its base as an exact expected witness and handle `moved`; do not assume
+another writer could not change the database between these operations.
+
+Change sets also work as inspectable values without a database. Their
+`counts` report distinct requested additions/removals, not the net change
+against any store. `records()` yields `{ relation, kind, fact }` records;
+the relation name narrows the fact type. Every traversal opens an independent
+cursor over the shared native bytes. Early termination, failure and interruption
+close it, without consuming the change set. Delivery is bounded to 256 records
+and a 64 KiB canonical-byte target per batch; a larger individual row is allowed.
+
+`toBytes()` explicitly copies the complete canonical payload. `fromBytes`
+checks its schema fingerprint, framing, scalar values, order and uniqueness;
+it refuses malformed bytes instead of silently normalizing them. Input bytes
+must remain stable until the Effect exits, and returned bytes are independently
+owned. Native byte order is canonical encoding order, not insertion order.
+
+```ts
+const inspectAndCompose = Effect.scoped(
+	Effect.gen(function* () {
+		const draft = yield* ChangeSet.builder(Tasks)
+		const id = yield* Effect.sync(() => crypto.randomUUID())
+		yield* draft.insert(Task, [{ id, title: "inspect typed changes", done: 0n }])
+		const changes = yield* draft.finish()
+		const bytes = yield* changes.toBytes()
+		const decoded = yield* ChangeSet.fromBytes(Tasks, bytes)
+		const combined = yield* changes.compose(decoded)
+		const preview = yield* Stream.runCollect(combined.records().pipe(Stream.take(10)))
+		return { counts: combined.counts, byteLength: combined.byteLength,
+			titles: preview.map((record) => record.fact.title) }
+	})
+)
+void inspectAndCompose
+```
+
+`compose` performs a native linear merge without decoding/re-encoding rows.
+It is commutative, associative and idempotent: the identical fact's add wins
+over its removal within the combined command. Two distinct rows sharing a key
+both survive composition and can still be rejected by admission. Applying two
+commands sequentially has different semantics: a later removal removes a
+previously added fact. Neither input is consumed by composition.
+
 ## 4. Keyed reads are Options
 
-`get` reads through the relation's primary declared key. A missing key is
+`get` takes the exact key descriptor used in the schema and its complete
+projected value. Every declared key is usable; there is no implicit primary key.
+A missing key is
 `Option.none` — never a fake I/O error, never a nullable row.
 
 ```ts
 const Person = relation("Person", { id: uuid, name: str })
-const People = schema("People", { Person }, [key(Person, ["id"])])
+const PersonById = key(Person, ["id"])
+const People = schema("People", { Person }, [PersonById])
 
 const lookup = (reader: QueryReader<typeof People>, personId: Uuid) =>
 	Effect.gen(function* () {
-		const found = yield* reader.get(Person, { id: personId }, work)
+		const found = yield* reader.get(PersonById, { id: personId })
 		return Option.isSome(found) ? found.value.name : "unknown"
 	})
 void lookup
@@ -203,13 +277,75 @@ const booksBy = query(Library).rule((r) => {
 const readBooks = (reader: QueryReader<typeof Library>, name: string) =>
 	Effect.scoped(
 		Effect.gen(function* () {
-			const result = yield* reader.execute(booksBy, { name }, work)
-			return yield* result.collect({ maxBytes: work.resultBytes }, work)
+			const result = yield* reader.execute(booksBy, { name })
+			return yield* result.collect()
 		})
 	)
 void readBooks
 ```
 
+For repeated calls on one snapshot, prepare once. The scoped handle keeps
+one compiled plan and reuses its execution buffers; only parameters cross
+the native boundary on subsequent calls. One-shot `execute` does not retain
+a plan. Preparations share the snapshot's pinned version but close
+independently; completed results also remain independent.
+
+Ordinary execution keeps buffers for reuse. If a prepared query will sit idle
+after a large operation, `yield* prepared.releaseMemory()` drops its
+execution buffers but keeps the compiled query and pinned snapshot. Shared
+query caches belong to the database: `yield* db.clearCache()` clears those
+separately. Neither operation invalidates live results. Both are optional;
+scope closure releases ownership as usual.
+
+```ts
+const readTwoAuthors = (reader: QueryReader<typeof Library>) =>
+	Effect.scoped(
+		Effect.gen(function* () {
+			const prepared = yield* reader.prepare(booksBy)
+			const first = yield* prepared.execute({ name: "Ursula Le Guin" })
+			const second = yield* prepared.execute({ name: "Octavia Butler" })
+			return [
+				yield* first.collect(),
+				yield* second.collect()
+			]
+		})
+	)
+void readTwoAuthors
+```
+
+Generated queries use the same checked rule, scalar, and execution machinery.
+`describeQuery` exposes the logical IR and its names as owned data. Its relation
+ordinals refer to the supplied schema's declaration order; variables are local
+to each rule. Intermediate names are local labels. The result-field record
+passed to `queryFromDescription` must match the actual derived head, including
+closed vocabularies, and determines the returned row type. Parameters supplied
+to a generated query are checked against their uses during execution.
+
+```ts
+const Event = relation("Event", { id: uuid, amount: u64 })
+const Events = schema("Events", { Event }, [key(Event, ["id"])])
+const countEvents = query(Events).rule((r) =>
+	r.match(Event, {}).find({ count: r.count() })
+)
+const description = describeQuery(countEvents)
+const totalEvents = queryFromDescription(
+	Events,
+	{ ...description, columns: ["total"] },
+	{ total: u64 }
+)
+const readTotal = (reader: QueryReader<typeof Events>) =>
+	Effect.scoped(Effect.gen(function* () {
+		const result = yield* reader.execute(totalEvents, {})
+		const rows: readonly { readonly total: bigint }[] = yield* result.collect()
+		return rows
+	}))
+void readTotal
+```
+
+Descriptions contain bigint and byte values, so they are not a JSON wire format.
+An accepted description is an authored query; native preparation still checks
+engine semantics. It carries no snapshot, prepared handle, or result rows.
+
 ## 6. Grouped exact aggregates
 
 Aggregates fold the group's distinct full bindings: keep the identity-bearing
@@ -263,13 +399,15 @@ const labeled = query(Telemetry).rule((r) => {
 void labeled
 ```
 
-## 8. Bounded results: capped collect, one-shot page stream
+## 8. Completed results: collect or consume delivery batches
 
-`collect({ maxBytes }, work)` is database-enforced total materialization and
-leaves the result available. `pages({ pageBytes }, work)` is a ONE-SHOT consuming
+`collect()` explicitly materializes all rows into JavaScript and
+leaves the result available. `pages()` is a ONE-SHOT consuming
 stream over the completed result: the first run moves the backing into a
 private scoped cursor; a second run refuses. Every element is one owned page
-array — pages, not rows — delivered after complete evaluation.
+array of up to 256 rows — pages, not rows — delivered after complete evaluation.
+Paging bounds delivery, not query execution or total result storage. An empty
+result emits one empty page; interruption and early termination close the cursor.
 
 ```ts
 const Event = relation("Event", { id: uuid, at: i64 })
@@ -281,7 +419,7 @@ const everything = query(Feed).rule((r) => {
 })
 
 const drain = (result: CompleteResult<{ readonly id: Uuid; readonly at: bigint }>) =>
-	result.pages({ pageBytes: 65536n }, work).pipe(
+	result.pages().pipe(
 		Stream.runForEach((page) =>
 			Effect.sync(() => {
 				// One owned page array; caller mutation cannot reach native
@@ -321,27 +459,28 @@ the apply instead of silently overwriting.
 
 ```ts
 const Account = relation("Account", { id: uuid, balance: i64 })
-const Bank = schema("Bank", { Account }, [key(Account, ["id"])])
+const AccountById = key(Account, ["id"])
+const Bank = schema("Bank", { Account }, [AccountById])
 
 const correct = (accountId: Uuid) =>
 	Effect.scoped(
 		Effect.gen(function* () {
-			const db = yield* Db.open(localPath, Bank, work)
+			const db = yield* Db.open(localPath, Bank)
 			const observed = yield* Effect.scoped(
 				Effect.gen(function* () {
-					const snapshot = yield* db.snapshot(work)
-					const previous = yield* snapshot.get(Account, { id: accountId }, work)
+					const snapshot = yield* db.snapshot()
+					const previous = yield* snapshot.get(AccountById, { id: accountId })
 					if (Option.isNone(previous)) {
 						return yield* Effect.fail({ missing: accountId })
 					}
 					return { previous: previous.value, at: snapshot.witness }
 				})
 			)
-			const draft = yield* ChangeSet.builder(Bank, work)
+			const draft = yield* ChangeSet.builder(Bank)
 			yield* draft.delete(Account, [observed.previous])
 			yield* draft.insert(Account, [{ ...observed.previous, balance: observed.previous.balance + 1n }])
 			const changes = yield* draft.finish()
-			return yield* db.apply(changes, { ...work, expected: { kind: "exact", at: observed.at } })
+			return yield* db.apply(changes, { expected: { kind: "exact", at: observed.at } })
 		})
 	)
 void correct
@@ -352,16 +491,17 @@ void correct
 `f64` is a real schema scalar: NaN canonicalizes to the one quiet NaN,
 `-0` to `+0`, and the relational order is total. `interval(f64)` is the
 parameterized dense interval — half-open, NaN-free, strictly ordered.
-`span` builds checked interval values as `Result`s.
+Interval values are structural records. Their field descriptor validates
+endpoint ranges, nonemptiness and fixed width at the boundary. Integer rays
+end at the element's maximum; fixed-width intervals cannot be rays.
 
 ```ts
 const Window = relation("Window", { id: uuid, confidence: interval(f64), during: interval(i64) })
 const Windows = schema("Windows", { Window }, [key(Window, ["id"])])
 
-const discrete = span(0n, 60n)
-const dense = span(0.25, 1.5)
-const bothChecked: boolean = Result.isSuccess(discrete) && Result.isSuccess(dense)
-void [Windows, bothChecked]
+const discrete: IntervalValue = { start: 0n, end: 60n }
+const dense: FloatIntervalValue = { start: 0.25, end: 1.5 }
+void [Windows, discrete, dense]
 ```
 
 ## 12. Scoped ownership and honest close
@@ -377,7 +517,7 @@ const Items = schema("Items", { Item }, [key(Item, ["id"])])
 
 const explicitClose = Effect.scoped(
 	Effect.gen(function* () {
-		const db = yield* Db.open(localPath, Items, work)
+		const db = yield* Db.open(localPath, Items)
 		const report = yield* db.close()
 		// `closed` releases this capability's obligations; `incomplete` and
 		// `failed` retain native Closing accounting — they are never

package/README.md

@@ -19,6 +19,11 @@ ordinary `bigint`, `number` (for `f64`), `string`, boolean, byte, `Uuid`,
 and interval values; queries infer their parameter and result types from how
 those values are used.
 
+Relations, closed rosters, keys, selections, and constraints are checked
+structural descriptions. Schema construction owns copies of declarations.
+Independently constructed equivalent declarations work in queries, codecs,
+writes, and key lookups; ordered fields and enum handles must agree.
+
 ## Platform support
 
 The TypeScript package ships native binaries for **darwin-arm64**
@@ -33,8 +38,12 @@ correctness CI is distinct from the Apple Silicon performance measurements.
 
 ## Install
 
+This guide follows the 1.2.0 source API. Use the guide from the Git tag matching
+your installed package. GitHub release tarballs and npm publication are separate;
+the npm command below applies once that version is published.
+
 ```sh
-pnpm add @bjornpagen/bumbledb@1.0.1 effect@4.0.0-rc.112
+pnpm add @bjornpagen/bumbledb@1.2.0 effect@4.0.0-rc.112
 ```
 
 ## Quick start
@@ -68,7 +77,6 @@ import {
 	weigh,
 	within
 } from "@bjornpagen/bumbledb"
-import type { ExecutionPolicy, NativeRuntimeOptions } from "@bjornpagen/bumbledb"
 
 // Relations describe stored records. Identity fields are ordinary
 // application-owned Uuid values — the database issues no identity.
@@ -82,8 +90,9 @@ const Attempt = relation("Attempt", {
 })
 
 // Keys are declared statements; references and capacity are laws.
+const StudentById = key(Student, ["id"])
 const Learning = schema("Learning", { Student, Attempt }, [
-	key(Student, ["id"]),
+	StudentById,
 	key(Attempt, ["id"]),
 	contained(on(Attempt, "student"), on(Student, "id")),
 	capacity(on(Student, "id"), {
@@ -93,9 +102,6 @@ const Learning = schema("Learning", { Student, Attempt }, [
 	})
 ])
 
-// Measured policies are inputs — the library invents no limits.
-declare const runtimePolicy: NativeRuntimeOptions
-declare const work: ExecutionPolicy
 declare const localPath: string
 
 // Queries are reusable typed values: reusing a v(R) variable is the join,
@@ -111,35 +117,35 @@ const attemptsFor = query(Learning).rule((r) => {
 const program = Effect.scoped(
 	Effect.gen(function* () {
 		// First use: create explicitly. Use Db.open for an existing store.
-		const db = yield* Db.create(localPath, Learning, work)
+		const db = yield* Db.create(localPath, Learning)
 		const studentId = yield* Effect.sync(() => crypto.randomUUID())
 		const attemptId = yield* Effect.sync(() => crypto.randomUUID())
 
-		const draft = yield* ChangeSet.builder(Learning, work)
+		const draft = yield* ChangeSet.builder(Learning)
 		yield* draft.insert(Student, [{ id: studentId, name: "Ada", budget: 10n }])
 		yield* draft.insert(Attempt, [
 			{ id: attemptId, student: studentId, score: 0.9, units: 1n, active: { start: 0n, end: 60n } }
 		])
 		const changes = yield* draft.finish()
 
-		const outcome = yield* db.apply(changes, { ...work, expected: { kind: "any" } })
+		const outcome = yield* db.apply(changes, { expected: { kind: "any" } })
 		if (outcome.kind !== "accepted" && outcome.kind !== "no-change") {
 			return outcome
 		}
-		const snapshot = yield* db.snapshot(work)
-		const found = yield* snapshot.get(Student, { id: studentId }, work)
+		const snapshot = yield* db.snapshot()
+		const found = yield* snapshot.get(StudentById, { id: studentId })
 		if (Option.isNone(found)) {
 			return outcome
 		}
-		const result = yield* snapshot.execute(attemptsFor, { student: studentId }, work)
-		const rows = yield* result.collect({ maxBytes: work.resultBytes }, work)
+		const result = yield* snapshot.execute(attemptsFor, { student: studentId })
+		const rows = yield* result.collect()
 		return { outcome, rows }
 	})
 )
 
 // One boundary for this script; an Effect app supplies the layer in its
 // own application graph instead.
-void Effect.runPromise(program.pipe(Effect.provide(NativeRuntime.layer(runtimePolicy))))
+void Effect.runPromise(program.pipe(Effect.provide(NativeRuntime.layer())))
 ```
 
 Every `ts` fence in this README is extracted and type-checked against the
@@ -151,8 +157,8 @@ The SDK translates TypeScript values directly into the engine's shared schema
 and query representations.
 
 - Fields use `bool`, `bytes`, `f64`, `i64`, `uuid`, `u64`, `str`, and
-  `interval` (`interval(f64)` is the dense float interval); `span` builds
-  checked interval values. `relation()` declares stored records, while
+  `interval` (`interval(f64)` is the dense float interval). Interval values
+  are plain `{ start, end }` records checked against their field. `relation()` declares stored records, while
   `closed()` declares a fixed enum-like set whose values may carry typed
   columns. `Infer` exposes the resulting TypeScript value type. `Uuid` is
   a structural template-literal string, not a nominal brand or a cast helper.
@@ -162,24 +168,41 @@ and query representations.
 - `schema()` accepts `key`, `contained`, `mirrors`, and `capacity`
   statements. Keys are declared statements — there is no minted identity.
   `capacity(target, { from, weight?, within })` takes named options;
-  `.where` makes a reference conditional, `within` sets a count or
+  `select(relation, { field: value })` makes a reference conditional,
+  `closedId(roster)` supplies a field that accepts named enum handles,
+  `within` sets a count or
   measurement range, and `weigh` chooses a numeric field or interval
   duration. Harmless equivalent window spellings lower to one canonical
   law; genuinely different meanings still refuse.
-- `NativeRuntime.layer(options)` owns the one bounded native runtime;
+- `NativeRuntime.layer()` owns the shared native runtime with sensible defaults;
   provide it once in the app graph. `Db.create` and `Db.open` are scoped
   Effects over that runtime; `open` never creates and `create` refuses
-  existing authority. `db.apply(changes, { ...work, expected })` judges one
+  existing authority. `db.apply(changes, { expected })` judges one
   immutable final-state change: `accepted`, `no-change`,
   `invariant-rejected` (complete statement diagnostics), or `moved`.
-- `ChangeSet.builder(schema, work)` acquires a scoped database-free draft;
+  `db.judge(changes, { expected })` uses the same admission path but aborts
+  the private candidate. It returns `admitted` or `invariant-rejected` with
+  the actual base witness and net additions/removals, or `moved` without
+  judging. Both use `WriteOptions`; judgment never guarantees a later apply.
+- `ChangeSet.builder(schema)` acquires a scoped database-free draft;
   `insert`/`delete` are lazy bounded ingestion effects, `finish()` seals the
-  immutable `ChangeSet`. Snapshots satisfy the shared `QueryReader`: typed
-  `get` returns `Option`, `execute` returns a sealed `CompleteResult` whose
-  `collect({ maxBytes }, work)` is capped materialization and whose
-  `pages({ pageBytes }, work)` is a one-shot consuming `Stream` of owned page
-  arrays after complete evaluation. Delivery work is fresh: it does not
-  inherit the snapshot or execution deadline.
+  immutable `ChangeSet`. It exposes `schemaId`, `counts`, and `byteLength`.
+  `records()` is a reusable, bounded stream of relation-name-discriminated
+  facts; each traversal owns an independent scoped cursor. `toBytes()`
+  explicitly materializes canonical bytes; `ChangeSet.fromBytes(schema, bytes)`
+  checks them without normalizing malformed input. `left.compose(right)`
+  merges native records into one add-wins command without decoding rows.
+  Composition is commutative, associative, and idempotent, not sequential
+  replay. Its counts describe requested distinct actions; only `judge`
+  measures their effect against a store.
+- Snapshots satisfy the shared `QueryReader`: typed
+  `get(keyDescriptor, keyValues)` chooses an explicit declared key and returns
+  `Option`; `execute` returns a sealed `CompleteResult` whose
+  `collect()` explicitly materializes all rows and whose
+  `pages()` is a one-shot consuming `Stream` of owned page
+  arrays after complete evaluation. Each page contains up to 256 rows; this
+  bounds delivery rather than streaming execution. Effect scope closes the
+  cursor on completion, failure, or interruption.
 - `query(S).rule(...)` builds typed queries. Reusing a variable created by
   `v(R)` joins records through that value. The builder supports named result
   rows, typed parameters, negation, comparisons, boolean conditions, set
@@ -187,6 +210,21 @@ and query representations.
   `f64` are deterministic with one final rounding), named intermediate
   results, nonrecursive composition of query templates, and linear
   recursive reachability.
+- `describeQuery(q)` returns owned logical IR, result names, intermediate
+  table names, and parameter names. `queryFromDescription(S, description,
+  resultFields)` checks a generated description through the same rule builder,
+  scalar grammar, lowering, and execution paths. The result-field record is
+  checked against the derived head and infers the returned row type; it is
+  not an unchecked cast. Generated parameters are validated by their uses at
+  execution. Ordinals refer to the supplied schema's ordered declarations;
+  variable ordinals are local to each rule. Native preparation still checks
+  engine semantics. The description contains plain values, including bigint
+  and byte arrays, rather than native resources or a JSON encoding.
+  Query `data` and `schema`, and compiled-schema inspection properties,
+  return detached snapshots: editing their byte buffers cannot change the
+  query or compilation. Checked immutable branches may be shared. Structural
+  declarations with byte payloads are copied when consumed; JavaScript byte
+  buffers themselves are mutable and are never treated as immutable cache keys.
 - `Scalar.field("units")` is an unresolved source-field leaf.
   `Scalar.add(Scalar.field("units"), Scalar.u64(1n))` authors synchronously
   without native loading. Native schema binding typechecks it, including
@@ -195,6 +233,12 @@ and query representations.
   Effect error channel; interruption and finalizer problems stay in
   `Cause`. Resource owners are scoped and report honest `CloseReport`s;
   incomplete teardown surfaces as a structured `CloseFailure` defect.
+  `error.message` contains the operation and reason code for safe default
+  display. Inspect `error.reason` explicitly for engine details, or
+  `InvalidArgument.detail` for authoring text and available structured
+  diagnostics such as `MissingField`, `UnknownField`, and `InvalidValue`.
+  Those details can contain application names or values and should not be
+  copied into public logs indiscriminately.
 
 ## Cookbook