@bjornpagen/bumbledb 1.3.1 → 2.0.0

package/COOKBOOK.md

@@ -3,7 +3,9 @@
 Worked recipes for the Effect-native surface: typed schema values,
 declared keys and laws, application-owned `Uuid` identity, one bounded
 native runtime, scoped resources, immutable final-state changes, `Option`
-reads, sealed complete results, and one-shot page streams.
+reads, sealed complete results, one-shot page streams, and durable
+`Database`s over an object store. Recipes 1 to 18 use the embedded `Db` from
+`@bjornpagen/bumbledb/engine`; recipes 19 and 20 use `Database`.
 
 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
@@ -11,7 +13,7 @@ prepended to every recipe. The examples are lazy Effect programs — nothing
 below runs a database at import time.
 
 ```ts
-import { Effect, Option, Result, Schema as EffectSchema, Stream } from "effect"
+import { Effect, Layer, Option, Result, Schema as EffectSchema, Stream } from "effect"
 import {
 	alternatives,
 	bool,
@@ -21,25 +23,25 @@ import {
 	closedId,
 	Compute,
 	contained,
-	Db,
+	Database,
 	decodeBoundaryField,
-	describeQuery,
 	duration,
 	encodeBoundaryField,
 	f64,
 	fieldSchema,
+	FsStore,
 	i64,
 	uuid,
 	Uuid,
 	interval,
 	key,
 	mirrors,
-	NativeRuntime,
+	Bumble,
 	on,
 	query,
-	queryFromDescription,
 	ref,
 	relation,
+	S3Store,
 	schema,
 	select,
 	str,
@@ -48,14 +50,16 @@ import {
 	weigh,
 	within
 } from "@bjornpagen/bumbledb"
+import { Db } from "@bjornpagen/bumbledb/engine"
 import type {
-	ApplyOutcome,
 	CompleteResult,
 	Fact,
 	FloatIntervalValue,
 	IntervalValue,
-	QueryReader
+	Migrations,
+	S3Sender
 } from "@bjornpagen/bumbledb"
+import type { ApplyOutcome, QueryReader } from "@bjornpagen/bumbledb/engine"
 
 declare const localPath: string
 ```
@@ -99,7 +103,7 @@ void [Learning, scoreIsNumber, unitsAreExact]
 
 ## 2. One runtime layer; explicit create and open
 
-`NativeRuntime.layer()` acquires the single native runtime
+`Bumble.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,
@@ -107,10 +111,8 @@ reporting. Defaults are up to four workers, 128 queued jobs, 128 cleanup reports
 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.
+Database `inspect()` reports the generation, the database's bytes on disk and
+the native operations it retains; none of these measures heap or resident RAM.
 `Db.open` never creates a missing database; `Db.create` refuses existing
 authority. Both are scoped acquisitions.
 
@@ -133,7 +135,7 @@ const createOnce = Effect.scoped(
 )
 
 // One boundary; an Effect app provides the layer in its own graph instead.
-const layer = NativeRuntime.layer()
+const layer = Bumble.layer()
 void [openExisting.pipe(Effect.provide(layer)), createOnce.pipe(Effect.provide(layer))]
 ```
 
@@ -157,15 +159,14 @@ const applyOnce = Effect.scoped(
 		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, { expected: { kind: "any" } })
-		switch (outcome.kind) {
-			case "accepted":
-			case "no-change":
-				return outcome.witness
-			case "invariant-rejected":
+		const outcome: ApplyOutcome = yield* db.apply(changes)
+		switch (outcome._tag) {
+			case "Committed":
+				return outcome.generation
+			case "Rejected":
 				// Complete statement diagnostics, typed data — never a throw.
 				return yield* Effect.fail(outcome.violations)
-			case "moved":
+			case "Moved":
 				return outcome.current
 		}
 	})
@@ -175,9 +176,9 @@ 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.
+writer; it does not hold a writer session open in JavaScript. A judgment
+carries the generation it judged against, and an admitted one also carries the
+net proposed fact counts. Operational errors stay in the Effect error channel.
 
 ```ts
 const judgeOnce = Effect.scoped(
@@ -186,15 +187,15 @@ const judgeOnce = Effect.scoped(
 		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" } })
+		return yield* db.judge(yield* draft.finish())
 	})
 )
 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.
+judge and apply with the same snapshot's 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
@@ -320,39 +321,6 @@ const readTwoAuthors = (reader: QueryReader<typeof Library>) =>
 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
@@ -460,9 +428,9 @@ void [okOrRefused, mintOnce]
 
 ## 10. Witnessed correction: exact expected state
 
-Read under a short scope, keep the copied witness, and apply with
-`expected: { kind: "exact", at: witness }`. An intervening net change moves
-the apply instead of silently overwriting.
+Read under a short scope, keep the snapshot's witness (an opaque value that
+outlives the snapshot), and pass it to `apply` as the expected state. An intervening net change moves the apply instead of
+silently overwriting.
 
 ```ts
 const Account = relation("Account", { id: uuid, balance: i64 })
@@ -487,7 +455,7 @@ const correct = (accountId: Uuid) =>
 			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, { expected: { kind: "exact", at: observed.at } })
+			return yield* db.apply(changes, observed.at)
 		})
 	)
 void correct
@@ -511,28 +479,25 @@ const dense: FloatIntervalValue = { start: 0.25, end: 1.5 }
 void [Windows, discrete, dense]
 ```
 
-## 12. Scoped ownership and honest close
+## 12. Scoped ownership
 
-Every native resource is scoped; early `close()` is itself an Effect
-returning the honest `CloseReport`. A scope finalizer that cannot complete
-teardown surfaces a structured `CloseFailure` DEFECT in the Cause — never a
-silently swallowed failure, never falsely reclaimed resources.
+Every native resource belongs to the scope that acquired it: the database, snapshots, prepared
+queries, results and change sets are released when their scope closes, innermost first. There is
+no `close()`; to release something early, acquire it in a smaller scope. A release that cannot
+drain cleanly is a `CloseFailure` defect in the Cause, never a swallowed failure.
 
 ```ts
 const Item = relation("Item", { id: uuid, label: str })
 const Items = schema("Items", { Item }, [key(Item, ["id"])])
 
-const explicitClose = Effect.scoped(
+const shortLived = Effect.scoped(
 	Effect.gen(function* () {
 		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
-		// counted as reclaimed.
-		return report.kind
+		const generation = yield* Effect.scoped(Effect.map(db.snapshot(), (snapshot) => snapshot.generation))
+		return generation
 	})
 )
-void explicitClose
+void shortLived
 ```
 
 ## 13. Derive slices, measure them, and round the total
@@ -575,7 +540,7 @@ const calculate = Effect.scoped(Effect.gen(function* () {
 		{ id: 1n, schedule: 1n, span: { start: 0n, end: 100n }, numerator: 1n },
 		{ id: 2n, schedule: 1n, span: { start: 100n, end: 200n }, numerator: 2n }
 	])
-	yield* db.apply(yield* change.finish(), { expected: { kind: "any" } })
+	yield* db.apply(yield* change.finish())
 	const snapshot = yield* db.snapshot()
 	return yield* (yield* snapshot.execute(amounts, {})).collect()
 }))
@@ -770,3 +735,114 @@ agree across arms and cannot share a column with a projection.
 Each expression retains its original failure boundary. Moving filters across
 an imported stage can change which arithmetic executes; a later filter cannot
 erase an upstream overflow.
+
+## 19. A durable database: idempotent submits and fresh reads
+
+A `Database` is a log in an object store read through a disposable local
+cache. Provide it once with `Database.layer` under a service key; in a Lambda,
+build the layer during init. Production opens with `onOpen: "verify"` after
+`bumbledb migrate` ran in the deploy pipeline.
+
+Mint one request id per intent and reuse it for every retry of that intent: a
+command is decided at most once. `Decided` carries the receipt (`Committed`,
+`NoChange`, `PreconditionFailed` or `InvariantRejected`). Every refusal except
+`Unknown` proves the command is not in the log; after `Unknown`, `resolve`
+answers from the log. `precondition: reader.revision` decides the command only
+if nothing committed since that read, which makes read-modify-write exact.
+
+```ts
+const Task = relation("Task", { id: uuid, title: str, done: bool })
+const Tasks = schema("Tasks", { Task }, [key(Task, ["id"])])
+const openTasks = query(Tasks).rule((r) => {
+	const { id, title } = v(Task)
+	return r.match(Task, { id, title, done: false }).find({ id, title })
+})
+
+declare const migrations: Migrations
+declare const s3: S3Sender
+
+const TasksDb = Database.tag<typeof Tasks>("app/TasksDb")
+const TasksLive = Database.layer(TasksDb, {
+	schema: Tasks,
+	migrations,
+	store: S3Store.make({
+		client: s3,
+		log: { bucket: "tasks--use1-az4--x-s3" },
+		checkpoints: { bucket: "tasks-checkpoints" },
+		prefix: "prod/"
+	}),
+	cache: { directory: "/tmp/tasks" },
+	onOpen: "verify"
+}).pipe(Layer.provide(Bumble.layer()))
+
+const completeFirst = Effect.scoped(
+	Effect.gen(function* () {
+		const db = yield* TasksDb
+		const reader = yield* db.read("latest")
+		const [first] = yield* (yield* reader.execute(openTasks, {})).collect()
+		if (first === undefined) {
+			return "nothing open"
+		}
+		const draft = yield* ChangeSet.builder(Tasks)
+		yield* draft.delete(Task, [{ ...first, done: false }])
+		yield* draft.insert(Task, [{ ...first, done: true }])
+		const requestId = Database.requestId()
+		const outcome = yield* db.submit(yield* draft.finish(), { requestId, precondition: reader.revision })
+		if (outcome._tag === "Decided") {
+			return outcome.receipt.outcome._tag
+		}
+		if (outcome.refusal._tag === "Unknown") {
+			const receipt = yield* db.resolve(requestId)
+			return Option.isSome(receipt) ? receipt.value.outcome._tag : "not decided"
+		}
+		return outcome.refusal._tag
+	})
+)
+
+void completeFirst.pipe(Effect.provide(TasksLive))
+```
+
+`read` takes `"cached"` (the cache as it is), `"latest"` (one request to find
+the log's tip) or `{ atLeast: seq }` (read-your-writes after a receipt's `seq`).
+
+## 20. One database per tenant
+
+`Database.pool` opens a database per tenant on first use and closes it after
+it has been idle for `idleTimeToLive`. Each tenant has its own log and cache;
+`FsStore` runs the same protocol on a local directory, and `MemStore` is the
+in-memory store for tests.
+
+```ts
+const Note = relation("Note", { id: uuid, text: str })
+const Notes = schema("Notes", { Note }, [key(Note, ["id"])])
+const allNotes = query(Notes).rule((r) => {
+	const { id, text } = v(Note)
+	return r.match(Note, { id, text }).find({ id, text })
+})
+
+declare const noteMigrations: Migrations
+
+const perTenant = Effect.scoped(
+	Effect.gen(function* () {
+		const pool = yield* Database.pool({
+			schema: Notes,
+			migrations: noteMigrations,
+			store: (tenant) => FsStore.make(`data/${tenant}/log`),
+			cache: (tenant) => ({ directory: `data/${tenant}/cache` }),
+			onOpen: "migrate",
+			idleTimeToLive: "10 minutes"
+		})
+		const count = (tenant: string) =>
+			Effect.scoped(
+				Effect.gen(function* () {
+					const db = yield* pool.get(tenant)
+					const reader = yield* db.read("cached")
+					return (yield* (yield* reader.execute(allNotes, {})).collect()).length
+				})
+			)
+		return yield* Effect.all([count("acme"), count("globex")])
+	})
+)
+
+void perTenant.pipe(Effect.provide(Bumble.layer()))
+```

package/README.md

@@ -8,10 +8,10 @@ the native engine.
 
 The API is **Effect-native**: every database operation constructs a lazy
 [`Effect`](https://effect.website) and every native resource is scoped.
-There is no Promise, synchronous, or disposal twin. Pure schema/query/scalar
-construction and reads of already-owned metadata stay ordinary synchronous
-expressions with no hidden native work. The package requires Effect
-`4.0.0-rc.112` exactly, as a peer dependency.
+There is no Promise, synchronous, or disposal twin. Schema, query and scalar
+construction stay ordinary synchronous expressions; a schema or query is
+validated by the engine when it is defined. The package requires Effect
+`^4.0.2` as a peer dependency.
 
 Relation declarations describe their fields, and the statements passed to
 `schema()` connect those fields into typed keys and references. Values remain
@@ -36,23 +36,29 @@ ordinary Effect Schema records for application inputs.
 The TypeScript package ships native binaries for **darwin-arm64**
 (macOS on Apple Silicon), **linux-arm64**, and **linux-x64**.
 The matching `@bjornpagen/bumbledb-<platform>` package is selected
-automatically during installation. Schema and query authoring do not load
-the addon. Attempting native database work on an unsupported platform fails
-with a diagnostic identifying the running platform and available binaries.
-Node 24 or newer is required; Edge and browser runtimes are unsupported.
+automatically during installation. Defining a schema or a query loads the
+addon and validates the definition in the engine, so an invalid definition
+throws `AuthoringError` where it is written. On an unsupported platform the
+first definition fails with a diagnostic naming the running platform and the
+available binaries. Node 26 or newer is required; Edge and browser runtimes
+are unsupported.
 Linux artifacts target Amazon Linux 2023 / glibc 2.34 or newer. Their
 correctness CI is distinct from the Apple Silicon performance measurements.
 
 ## Install
 
-This guide follows the 1.3.1 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.3.1 effect@4.0.0-rc.112
+pnpm add @bjornpagen/bumbledb effect
 ```
 
+`@aws-sdk/client-s3` is an optional peer dependency, needed only for `S3Store`.
+
+The package has two entry points and one binary. `@bjornpagen/bumbledb`
+holds authoring (relations, schemas, queries, change sets), the `Bumble`
+runtime layer and the durable `Database`. `@bjornpagen/bumbledb/engine` is
+the embedded `Db` for single-process use, tests and benchmarks. The
+`bumbledb` binary generates, checks and applies migrations.
+
 ## Quick start
 
 Declare relations, connect their fields with keys and references, build a
@@ -66,13 +72,12 @@ import {
 	capacity,
 	ChangeSet,
 	contained,
-	Db,
 	f64,
 	i64,
 	uuid,
 	interval,
 	key,
-	NativeRuntime,
+	Bumble,
 	on,
 	query,
 	ref,
@@ -84,6 +89,7 @@ import {
 	weigh,
 	within
 } from "@bjornpagen/bumbledb"
+import { Db } from "@bjornpagen/bumbledb/engine"
 
 // Relations describe stored records. Identity fields are ordinary
 // application-owned Uuid values — the database issues no identity.
@@ -135,8 +141,8 @@ const program = Effect.scoped(
 		])
 		const changes = yield* draft.finish()
 
-		const outcome = yield* db.apply(changes, { expected: { kind: "any" } })
-		if (outcome.kind !== "accepted" && outcome.kind !== "no-change") {
+		const outcome = yield* db.apply(changes)
+		if (outcome._tag !== "Committed") {
 			return outcome
 		}
 		const snapshot = yield* db.snapshot()
@@ -152,12 +158,86 @@ const program = Effect.scoped(
 
 // 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())))
+void Effect.runPromise(program.pipe(Effect.provide(Bumble.layer())))
 ```
 
 Every `ts` fence in this README is extracted and type-checked against the
 real surface by `test/readme.test.ts` — the examples cannot drift.
 
+## Durable databases
+
+`Database` keeps a database as an immutable log in an object store and reads
+it through a local cache that is only a cache. The store is `S3Store` (the log
+in an S3 Express directory bucket, checkpoints in a Standard bucket, through the
+app's `S3Client`), `FsStore` (a durable local directory) or `MemStore` (tests).
+A cold open fetches up to 32 log objects at once, and every new connection
+resolves DNS on one of libuv's 4 threads. Where lookups are slow, start Node
+with `UV_THREADPOOL_SIZE=64` or give the `S3Client` an agent that caches
+lookups.
+
+Migrations are bundled with the code. `bumbledb generate --schema
+src/schema.ts#App --name <name>` writes `migrations/NNNN_<name>/` and
+`migrations/index.ts`; add a `populate` step to a generated `migration.ts`
+when rows must be computed. Relations that keep their name and fields are
+copied unchanged. `bumbledb check --schema src/schema.ts#App` fails when the
+schema has an ungenerated change or a migration was edited.
+`onOpen: "migrate"` creates the database and runs pending migrations;
+`onOpen: "verify"` refuses to open while any is pending, so production runs
+`bumbledb migrate --config <file>` from the deploy pipeline first.
+
+```ts
+import { Effect, Option } from "effect"
+import { Bumble, ChangeSet, Database, FsStore, key, type Migrations, query, relation, schema, str, uuid, v } from "@bjornpagen/bumbledb"
+
+const Note = relation("Note", { id: uuid, text: str })
+const App = schema("App", { Note }, [key(Note, ["id"])])
+const notes = query(App).rule((r) => {
+	const { id, text } = v(Note)
+	return r.match(Note, { id, text }).find({ id, text })
+})
+
+// Generated by `bumbledb generate`: `import { migrations } from "./migrations/index.ts"`.
+declare const migrations: Migrations
+
+const program = Effect.scoped(
+	Effect.gen(function* () {
+		const db = yield* Database.make({
+			schema: App,
+			migrations,
+			store: FsStore.make("data/log"),
+			cache: { directory: "data/cache" },
+			onOpen: "migrate"
+		})
+		// One request id per intent: a retry submits the same command and is decided once.
+		const requestId = Database.requestId()
+		const draft = yield* ChangeSet.builder(App)
+		yield* draft.insert(Note, [{ id: yield* Effect.sync(() => crypto.randomUUID()), text: "hello" }])
+		const outcome = yield* db.submit(yield* draft.finish(), { requestId })
+		if (outcome._tag === "Refused" && outcome.refusal._tag === "Unknown") {
+			// The submit may or may not have been decided; its receipt says which.
+			const receipt = yield* db.resolve(requestId)
+			return Option.isSome(receipt) ? receipt.value.outcome._tag : "NotDecided"
+		}
+		const reader = yield* db.read("latest")
+		const rows = yield* (yield* reader.execute(notes, {})).collect()
+		return `${rows.length} notes at revision ${reader.revision}`
+	})
+)
+
+void Effect.runPromise(program.pipe(Effect.provide(Bumble.layer())))
+```
+
+`submit` returns `Decided` with a receipt (`Committed`, `NoChange`,
+`PreconditionFailed` or `InvariantRejected`) or `Refused` with the reason;
+every refusal but `Unknown` proves the log does not decide the command. A
+submit with `precondition: reader.revision` is decided only if nothing
+committed after that read. `read` takes `"cached"`, `"latest"` or
+`{ atLeast: seq }`.
+`Database.layer(Database.tag<typeof App>("App/Database"), options)` provides
+one database to an app graph, and `Database.pool({ ...options, store:
+(tenant) => ..., cache: (tenant) => ... })` opens one per tenant on demand and
+closes it when idle.
+
 ## Surface
 
 The SDK translates TypeScript values directly into the engine's shared schema
@@ -181,16 +261,17 @@ and query representations.
   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()` owns the shared native runtime with sensible defaults;
+- `Bumble.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, { expected })` judges one
-  immutable final-state change: `accepted`, `no-change`,
-  `invariant-rejected` (complete statement diagnostics), or `moved`.
-  `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.
+  existing authority. `db.apply(changes, expected?)` judges one immutable
+  final-state change: `Committed` (with the generation, and `changed: false`
+  when the state already held it), `Rejected` (complete statement
+  diagnostics), or `Moved` when `expected`, a snapshot's opaque `witness`, is
+  no longer current. `db.judge(changes, expected?)` uses the same admission
+  path and stores nothing: `Admitted` with net additions and removals,
+  `Rejected`, or `Moved` without judging. A 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`. It exposes `schemaId`, `counts`, and `byteLength`.
@@ -217,21 +298,6 @@ 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.
 - Operational failure is the one `DbError` tagged-reason class in the
   Effect error channel; interruption and finalizer problems stay in
   `Cause`. Resource owners are scoped and report honest `CloseReport`s;

package/dist/alternatives.d.ts

@@ -1,8 +1,8 @@
-import { type AnyClosed } from "./closed.js";
-import type { Face, SameArity, SameShapes } from "./face.js";
-import { type ClosedIdField } from "./fields.js";
-import type { RelationFields } from "./relation.js";
-import { type ContainmentStatement, type KeyStatement, type MirrorsStatement } from "./statements.js";
+import { type AnyClosed } from "./closed.ts";
+import type { Face, SameArity, SameShapes } from "./face.ts";
+import { type ClosedIdField } from "./fields.ts";
+import type { RelationFields } from "./relation.ts";
+import { type ContainmentStatement, type KeyStatement, type MirrorsStatement } from "./statements.ts";
 type KeyFace<K extends KeyStatement> = Face<K["owner"], K["projection"]>;
 type ScalarKey<K extends KeyStatement> = Extract<RelationFields<K["owner"]>[K["projection"][number]], {
     readonly kind: "interval";
@@ -16,7 +16,6 @@ type Discriminator<P extends KeyStatement, C extends AnyClosed> = {
  * Exhaustive closed alternatives, expanded into ordinary laws. Declare the
  * supplied keys in the schema once; this helper emits only the discriminator
  * containment followed by one mirrors statement per handle in roster order.
- * No new statement kind or assembled payload representation is introduced.
  */
 declare function alternatives<P extends KeyStatement, C extends AnyClosed, const Arms extends Record<C["handles"][number], KeyStatement>>(parent: P & ScalarKey<P>, discriminator: Discriminator<NoInfer<P>, NoInfer<C>>, roster: C, arms: Arms & Record<Exclude<keyof Arms, C["handles"][number]>, never> & {
     readonly [H in C["handles"][number]]: ScalarKey<Arms[H]> & SameArity<KeyFace<P>, KeyFace<Arms[H]>> & SameShapes<KeyFace<P>, KeyFace<Arms[H]>>;

package/dist/alternatives.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alternatives.d.ts","sourceRoot":"","sources":["../src/alternatives.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAA6C,MAAM,YAAY,CAAA;AAEtF,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC3D,OAAO,EAAE,KAAK,aAAa,EAAmB,MAAM,YAAY,CAAA;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,EACN,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAErB,MAAM,gBAAgB,CAAA;AAGvB,KAAK,OAAO,CAAC,CAAC,SAAS,YAAY,IAAI,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC,CAAA;AACxE,KAAK,SAAS,CAAC,CAAC,SAAS,YAAY,IACpC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,SAAS,KAAK,GACtG,OAAO,GACP;IAAE,QAAQ,CAAC,0CAA0C,EAAE,KAAK,CAAA;CAAE,CAAA;AAClE,KAAK,aAAa,CAAC,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,SAAS,IAAI;KAChE,CAAC,IAAI,MAAM,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,GAClH,CAAC,GACD,KAAK;CACR,CAAC,MAAM,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAClC,MAAM,CAAA;AAcP;;;;;GAKG;AACH,iBAAS,YAAY,CACpB,CAAC,SAAS,YAAY,EACtB,CAAC,SAAS,SAAS,EACnB,KAAK,CAAC,IAAI,SAAS,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,EAE7D,MAAM,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,EACxB,aAAa,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EACpD,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,IAAI,GACT,MAAM,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG;IAC1D,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GACvD,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GACvC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;CACzC,GACA,SAAS,CAAC,oBAAoB,GAAG,gBAAgB,CAAC,EAAE,CAmCtD;AAED,OAAO,EAAE,YAAY,EAAE,CAAA"}
+{"version":3,"file":"alternatives.d.ts","sourceRoot":"","sources":["../src/alternatives.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAA6C,MAAM,aAAa,CAAA;AAEvF,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC5D,OAAO,EAAE,KAAK,aAAa,EAAmB,MAAM,aAAa,CAAA;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,EACN,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAErB,MAAM,iBAAiB,CAAA;AAGxB,KAAK,OAAO,CAAC,CAAC,SAAS,YAAY,IAAI,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC,CAAA;AACxE,KAAK,SAAS,CAAC,CAAC,SAAS,YAAY,IACpC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,SAAS,KAAK,GACtG,OAAO,GACP;IAAE,QAAQ,CAAC,0CAA0C,EAAE,KAAK,CAAA;CAAE,CAAA;AAClE,KAAK,aAAa,CAAC,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,SAAS,IAAI;KAChE,CAAC,IAAI,MAAM,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,GAClH,CAAC,GACD,KAAK;CACR,CAAC,MAAM,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAClC,MAAM,CAAA;AAcP;;;;GAIG;AACH,iBAAS,YAAY,CACpB,CAAC,SAAS,YAAY,EACtB,CAAC,SAAS,SAAS,EACnB,KAAK,CAAC,IAAI,SAAS,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,EAE7D,MAAM,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,EACxB,aAAa,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EACpD,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,IAAI,GACT,MAAM,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG;IAC1D,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GACvD,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GACvC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;CACzC,GACA,SAAS,CAAC,oBAAoB,GAAG,gBAAgB,CAAC,EAAE,CAmCtD;AAED,OAAO,EAAE,YAAY,EAAE,CAAA"}

package/dist/alternatives.js

@@ -1,8 +1,8 @@
-import { closedDescriptor, closedId, sealedFieldOf } from "#closed.ts";
-import { AuthoringError } from "#errors.ts";
-import { signaturesAgree } from "#fields.ts";
-import { statementDescriptor } from "#statements.ts";
-import { recordValue } from "#values.ts";
+import { closedDescriptor, closedId, sealedFieldOf } from "./closed.js";
+import { AuthoringError } from "./errors.js";
+import { signaturesAgree } from "./fields.js";
+import { statementDescriptor } from "./statements.js";
+import { recordValue } from "./values.js";
 function scalarKey(input) {
     const checked = statementDescriptor(input);
     if (checked.kind !== "key")
@@ -19,7 +19,6 @@ function scalarKey(input) {
  * Exhaustive closed alternatives, expanded into ordinary laws. Declare the
  * supplied keys in the schema once; this helper emits only the discriminator
  * containment followed by one mirrors statement per handle in roster order.
- * No new statement kind or assembled payload representation is introduced.
  */
 function alternatives(parent, discriminator, roster, arms) {
     const primary = scalarKey(parent);