@bjornpagen/bumbledb 0.4.0 → 0.5.0

package/COOKBOOK.md

@@ -1,6 +1,6 @@
 # The cookbook — modeling intuition as schemas, in TypeScript
 
-The bumbledb engine's 29 cookbook recipes (`bumbledb/docs/cookbook.md`),
+The bumbledb engine's 30 cookbook recipes (`bumbledb/docs/cookbook.md`),
 translated to this SDK's structural API. **This document is illustrative,
 never normative**: where a recipe and an engine architecture chapter disagree,
 the chapter wins (`docs/architecture/README.md` rule 5) — the SDK is the same
@@ -37,9 +37,11 @@ import {
 	abandon,
 	allen,
 	bool,
+	by,
 	bytes,
 	closed,
 	contained,
+	desc,
 	eq,
 	i64,
 	interval,
@@ -116,10 +118,11 @@ const Uptime = schema("Uptime", { Service, Outage }, [
 	key(Outage, ["service", "window"])
 ])
 
-// down at instant t — `r.vars` mints the rule's whole variable scope at
-// once, and shorthand punning binds same-named columns:
+// down at instant t — `r.var` names each variable (typed by the field it
+// first binds), and shorthand punning binds same-named columns:
 const downAt = query(Uptime).rule((r) => {
-	const { service, window } = r.vars("service", "window")
+	const service = r.var("service")
+	const window = r.var("window")
 	return r
 		.match(Outage, { service, window })
 		.where(pointIn(r.param("t"), window))
@@ -127,7 +130,8 @@ const downAt = query(Uptime).rule((r) => {
 })
 // overlapping an incident window (one Allen mask, no operator zoo):
 const overlapping = query(Uptime).rule((r) => {
-	const { service, window } = r.vars("service", "window")
+	const service = r.var("service")
+	const window = r.var("window")
 	return r
 		.match(Outage, { service, window })
 		.where(allen(window, ALLEN.intersects, r.param("incident")))
@@ -135,7 +139,8 @@ const overlapping = query(Uptime).rule((r) => {
 })
 // total downtime per service (the denotation's one arithmetic):
 const downtime = query(Uptime).rule((r) => {
-	const { service, window } = r.vars("service", "window")
+	const service = r.var("service")
+	const window = r.var("window")
 	return r.match(Outage, { service, window }).select("service", r.sum(r.duration("window")))
 })
 ```
@@ -215,7 +220,7 @@ const Optionality = schema("Optionality", { Business, MailingAddress }, [
 
 // Negation is plain anti-join (no null branch exists in any operator):
 const unaddressed = query(Optionality).rule((r) => {
-	const { b } = r.vars("b")
+	const b = r.var("b")
 	return r
 		.match(Business, { id: b })
 		.where(not(MailingAddress, { business: b }))
@@ -255,7 +260,10 @@ const Money = schema("Money", { Currency, Account, Posting }, [
 // silently. Bind the fresh id: set semantics would collapse two equal
 // (account, currency, minor) postings without it.
 const totals = query(Money).rule((r) => {
-	const { id, account, currency, minor } = r.vars("id", "account", "currency", "minor")
+	const id = r.var("id")
+	const account = r.var("account")
+	const currency = r.var("currency")
+	const minor = r.var("minor")
 	return r.match(Posting, { id, account, currency, minor }).select("account", "currency", r.sum("minor"))
 })
 ```
@@ -292,7 +300,7 @@ const Content = schema("Content", { Region, Document, Replica }, [
 
 // a bytes param self-encodes (Uint8Array by inference):
 const byDigest = query(Content).rule((r) => {
-	const { id } = r.vars("id")
+	const id = r.var("id")
 	return r.match(Document, { id, payload: r.param("digest") }).select("id")
 })
 ```
@@ -334,7 +342,7 @@ const Tickets = schema("Tickets", { Priority, Ticket }, [
 // that drifts without a rebuild is an ordinary relation — a vocabulary is
 // never written, only declared.
 const urgent = query(Tickets).rule((r) => {
-	const { t } = r.vars("t")
+	const t = r.var("t")
 	return r.match(Ticket, { id: t, priority: "Urgent" }).select("t")
 })
 
@@ -343,7 +351,7 @@ const urgent = query(Tickets).rule((r) => {
 // ∈-set param, `r.inSet`); the array folds to the same wire set the param
 // spelling crosses. In `.where()` selections arrays work at EVERY field kind.
 const actionable = query(Tickets).rule((r) => {
-	const { t } = r.vars("t")
+	const t = r.var("t")
 	return r.match(Ticket, { id: t, priority: ["Normal", "Urgent"] }).select("t")
 })
 ```
@@ -388,7 +396,8 @@ const Review = schema("Review", { Kind, Attempt, Certificate }, [
 // exactly like an ordinary one, and the atom folds at prepare into a
 // plan-constant handle set on its sibling.
 const masteredAttempts = query(Review).rule((r) => {
-	const { a, k } = r.vars("a", "k")
+	const a = r.var("a")
+	const k = r.var("k")
 	return r
 		.match(Attempt, { id: a, kind: k })
 		.match(Kind, { id: k, mastered: true })
@@ -451,7 +460,8 @@ const Oncall = schema("Oncall", { Severity, Incident, Escalation }, [
 
 // who is being paged — the same ψ, on the read side:
 const paged = query(Oncall).rule((r) => {
-	const { i, s } = r.vars("i", "s")
+	const i = r.var("i")
+	const s = r.var("s")
 	return r
 		.match(Escalation, { incident: i, severity: s })
 		.match(Severity, { id: s, pages: true })
@@ -468,7 +478,8 @@ plus pointwise keys realizes exact partition
 (`lean/Bumbledb/Dependencies.lean: exact_partition_iff`), and the mixed-width
 interval positions type by element domain
 (`lean/Bumbledb/Schema.lean: Value.points_one_tag_u64`); ordering the result
-remains a host presentation step.
+remains a host presentation step — the SDK ships the comparator (`by`/`desc`,
+keys as data); the engine never orders.
 
 The linked-list verdict: successor pointers are control flow smuggled into
 data. Order is a value. The idiomatic ordered collection is an interval
@@ -496,12 +507,21 @@ const Playlists = schema("Playlists", { Playlist, Extent, Slot }, [
 
 // Positional access is membership — "what plays at position ?pos":
 const playingAt = query(Playlists).rule((r) => {
-	const { slot, track } = r.vars("slot", "track")
+	const slot = r.var("slot")
+	const track = r.var("track")
 	return r
 		.match(Slot, { playlist: r.param("list"), slot, track })
 		.where(pointIn(r.param("pos"), slot))
 		.select("track")
 })
+
+// Answers are SETS — the host sorts them, and the SDK ships the comparator:
+// sort keys as data, a bare name ascending, `desc(...)` the flip; intervals
+// order by (start, end). Limit is the language's own `.slice(0, n)`.
+const inPlayOrder = [
+	{ slot: { start: 1n, end: 2n }, track: "b" },
+	{ slot: { start: 0n, end: 1n }, track: "a" }
+].sort(by("slot", "track"))
 ```
 
 Middle insert is honest about its cost: making room at position `k` shifts
@@ -548,7 +568,8 @@ const Ast = schema("Ast", { Kind, Node, Lit, Add, Parent }, [
 ])
 
 const lhsLiteral = query(Ast).rule((r) => {
-	const { l, v } = r.vars("l", "v")
+	const l = r.var("l")
+	const v = r.var("v")
 	return r
 		.match(Add, { node: r.param("n"), lhs: l })
 		.match(Lit, { node: l, value: v })
@@ -583,7 +604,8 @@ const Graph = schema("Graph", { Person, Repo, Follows, Maintains }, [
 // live in the "Person.id" class, so the reuse is lawful); `lt` keeps each
 // pair once:
 const mutual = query(Graph).rule((r) => {
-	const { a, b } = r.vars("a", "b")
+	const a = r.var("a")
+	const b = r.var("b")
 	return r
 		.match(Follows, { follower: a, followee: b })
 		.match(Follows, { follower: b, followee: a })
@@ -621,7 +643,11 @@ const Ecs = schema("Ecs", { Entity, Transform, Velocity, Renderable }, [
 
 // The physics join is the component intersection:
 const physics = query(Ecs).rule((r) => {
-	const { entity, x, y, dx, dy } = r.vars("entity", "x", "y", "dx", "dy")
+	const entity = r.var("entity")
+	const x = r.var("x")
+	const y = r.var("y")
+	const dx = r.var("dx")
+	const dy = r.var("dy")
 	return r
 		.match(Transform, { entity, x, y })
 		.match(Velocity, { entity, dx, dy })
@@ -661,7 +687,8 @@ const Orders = schema("Orders", { State, Order, Placement, Shipment }, [
 ])
 
 const shipped = query(Orders).rule((r) => {
-	const { id, carrier } = r.vars("id", "carrier")
+	const id = r.var("id")
+	const carrier = r.var("carrier")
 	return r
 		.match(Order, { id, state: "Shipped" })
 		.match(Shipment, { order: id, carrier })
@@ -731,14 +758,16 @@ const Calendar = schema("Calendar", { Rsvp, Arm, Person, Room, Event, Attendance
 ])
 
 const roomConflicts = query(Calendar).rule((r) => {
-	const { room, span } = r.vars("room", "span")
+	const room = r.var("room")
+	const span = r.var("span")
 	return r
 		.match(Booking, { room, span })
 		.where(allen(span, ALLEN.intersects, r.param("want")))
 		.select("room", "span")
 })
 const personLoad = query(Calendar).rule((r) => {
-	const { person, span } = r.vars("person", "span")
+	const person = r.var("person")
+	const span = r.var("span")
 	return r
 		.match(Claim, { person, span })
 		.where(allen(span, ALLEN.intersects, r.param("window")))
@@ -774,7 +803,8 @@ const Pricing = schema("Pricing", { Policy, Version }, [
 
 // in force on date t — one membership probe:
 const inForce = query(Pricing).rule((r) => {
-	const { rate_bps, valid } = r.vars("rate_bps", "valid")
+	const rate_bps = r.var("rate_bps")
+	const valid = r.var("valid")
 	return r
 		.match(Version, { policy: r.param("p"), rate_bps, valid })
 		.where(pointIn(r.param("t"), valid))
@@ -782,7 +812,9 @@ const inForce = query(Pricing).rule((r) => {
 })
 // clean successions (half-open makes MEETS exact, no ±1 fudge):
 const successions = query(Pricing).rule((r) => {
-	const { p, a, b } = r.vars("p", "a", "b")
+	const p = r.var("p")
+	const a = r.var("a")
+	const b = r.var("b")
 	return r
 		.match(Version, { policy: p, valid: a })
 		.match(Version, { policy: p, valid: b })
@@ -816,7 +848,8 @@ const Payroll = schema("Payroll", { FiscalYear, PayPeriod }, [
 
 // the period holding date t:
 const holding = query(Payroll).rule((r) => {
-	const { seq, span } = r.vars("seq", "span")
+	const seq = r.var("seq")
+	const span = r.var("span")
 	return r
 		.match(PayPeriod, { year: r.param("y"), seq, span })
 		.where(pointIn(r.param("t"), span))
@@ -864,7 +897,9 @@ const Tax = schema("Tax", { Status, Regime, Bracket, Residency, Earned }, [
 // owed is host arithmetic over the bracket walk — arithmetic beyond the
 // measure is refused (the ledger).
 const marginal = query(Tax).rule((r) => {
-	const { reg, b, rate_bps } = r.vars("reg", "b", "rate_bps")
+	const reg = r.var("reg")
+	const b = r.var("b")
+	const rate_bps = r.var("rate_bps")
 	return r
 		.match(Regime, { id: reg, year: r.param("y"), status: r.param("s") })
 		.match(Bracket, { regime: reg, income: b, rate_bps })
@@ -896,17 +931,21 @@ const FreeTime = schema("FreeTime", { Person, Claim }, [
 
 // busy time, coalesced (adjacent segments merge — the half-open law):
 const busy = query(FreeTime).rule((r) => {
-	const { person, span } = r.vars("person", "span")
+	const person = r.var("person")
+	const span = r.var("span")
 	return r.match(Claim, { person, span }).select("person", r.pack("span"))
 })
 // raw claimed time (overlaps double-count — often the wrong question):
 const claimed = query(FreeTime).rule((r) => {
-	const { person, span } = r.vars("person", "span")
+	const person = r.var("person")
+	const span = r.var("span")
 	return r.match(Claim, { person, span }).select("person", r.sum(r.duration("span")))
 })
 // Coalesced totals = the two-query composition (pack, then a host fold) —
 // aggregates never nest; free time (gaps) is the two-line host walk over
-// sorted packed answers — both refusals recorded in the ledger.
+// sorted packed answers (`rows.sort(by("person", "span"))` — the
+// keys-as-data comparator; limit is the language's own `.slice`) — both
+// refusals recorded in the ledger.
 ```
 
 ## The write side
@@ -940,12 +979,16 @@ const Ledger = schema("Ledger", { Account, JournalEntry, Posting }, [
 
 // balances (bind the fresh id — set semantics collapses duplicates):
 const balances = query(Ledger).rule((r) => {
-	const { id, account, minor } = r.vars("id", "account", "minor")
+	const id = r.var("id")
+	const account = r.var("account")
+	const minor = r.var("minor")
 	return r.match(Posting, { id, account, minor }).select("account", r.sum("minor"))
 })
 // double-entry audit (host asserts every total is 0 — discipline, not schema):
 const doubleEntry = query(Ledger).rule((r) => {
-	const { id, entry, minor } = r.vars("id", "entry", "minor")
+	const id = r.var("id")
+	const entry = r.var("entry")
+	const minor = r.var("minor")
 	return r.match(Posting, { id, entry, minor }).select("entry", r.sum("minor"))
 })
 ```
@@ -960,8 +1003,11 @@ final-state point reads need no earlier witness.
 The generation witness: read the model, propose a delta, commit iff the model
 you read is still the model. In the SDK the whole loop is `db.writeWitnessed`
 — retry on movement is built in (every generation move is self-inflicted by
-the host's own interleaved writes), and `abandon(payload)` declines to commit
-without issuing anything.
+the host's own interleaved writes), capped at 64 attempts: a callback that
+itself issues a plain `db.write` each try re-moves the generation it is about
+to witness, and past the cap that interleave hazard throws the typed
+`ErrWitnessedLivelock` instead of spinning forever. `abandon(payload)`
+declines to commit without issuing anything.
 
 ```ts
 const State = closed("State", ["Queued", "Running", "Done"])
@@ -978,7 +1024,8 @@ const Jobs = schema("Jobs", { State, Job, Lease }, [
 
 // update-where's premise — "still Queued" is the witness:
 const stillQueued = query(Jobs).rule((r) => {
-	const { id, payload } = r.vars("id", "payload")
+	const id = r.var("id")
+	const payload = r.var("payload")
 	return r.match(Job, { id, state: "Queued", payload }).select("id", "payload")
 })
 
@@ -1035,7 +1082,8 @@ const Rollup = schema("Rollup", { Arm, Claim, BusySpan }, [
 // against sources it didn't actually read. The deriving query (pack IS the
 // coalesce):
 const deriving = query(Rollup).rule((r) => {
-	const { person, span } = r.vars("person", "span")
+	const person = r.var("person")
+	const span = r.var("span")
 	return r.match(Claim, { person, span, arm: "Busy" }).select("person", r.pack("span"))
 })
 ```
@@ -1069,14 +1117,16 @@ const Payments = schema("Payments", { Kind, Payment, Card, Ach }, [
 // provably disjoint, so the executor elides cross-rule dedup — the free lunch.
 const wholeDu = query(Payments)
 	.rule((r) => {
-		const { id, n } = r.vars("id", "n")
+		const id = r.var("id")
+		const n = r.var("n")
 		return r
 			.match(Payment, { id, kind: "Card" })
 			.match(Card, { payment: id, last4: n })
 			.select("id", "n")
 	})
 	.rule((r) => {
-		const { id, n } = r.vars("id", "n")
+		const id = r.var("id")
+		const n = r.var("n")
 		return r
 			.match(Payment, { id, kind: "Ach" })
 			.match(Ach, { payment: id, routing: n })
@@ -1148,7 +1198,7 @@ const Closure = schema("Closure", { Node, Parent }, [
 
 // The loop's one query — the frontier's children, one ∈-set probe:
 const step = query(Closure).rule((r) => {
-	const { c } = r.vars("c")
+	const c = r.var("c")
 	return r.match(Parent, { child: c, parent: r.inSet("frontier") }).select("c")
 })
 ```
@@ -1192,21 +1242,22 @@ const reach = program(Closure, (p) => {
 	const rec = p.rec("reach")
 	const seeded = rec
 		.rule((r) => {
-			const { c } = r.vars("c")
+			const c = r.var("c")
 			return r
 				.match(Node, { id: c })
 				.where(eq(c, r.param("root")))
 				.select("c")
 		})
 		.rule((r) => {
-			const { c, parent } = r.vars("c", "parent")
+			const c = r.var("c")
+			const parent = r.var("parent")
 			return r
 				.match(Parent, { child: c, parent })
 				.idb(rec, parent)
 				.select("c")
 		})
 	return p.output((r) => {
-		const { c } = r.vars("c")
+		const c = r.var("c")
 		return r.match(Node, { id: c }).idb(seeded, c).select("c")
 	})
 })
@@ -1249,13 +1300,14 @@ const Accounts = schema("Accounts", { Account, AccountParent, Posting }, [
 // The two queries the host rollup composes:
 //   the frontier step (recipe 24's loop, verbatim):
 const frontierStep = query(Accounts).rule((r) => {
-	const { c } = r.vars("c")
+	const c = r.var("c")
 	return r.match(AccountParent, { child: c, parent: r.inSet("frontier") }).select("c")
 })
 //   the rollup over the accumulated subtree (bind the fresh id — recipe
 //   19's discipline, spent again; equal postings to one account both count):
 const subtreeRollup = query(Accounts).rule((r) => {
-	const { id, minor } = r.vars("id", "minor")
+	const id = r.var("id")
+	const minor = r.var("minor")
 	return r.match(Posting, { id, account: r.inSet("subtree"), minor }).select(r.sum("minor"))
 })
 // The engine-native form: the closure stratum converges first, then the
@@ -1264,21 +1316,24 @@ const nativeRollup = program(Accounts, (p) => {
 	const sub = p.rec("sub")
 	const seeded = sub
 		.rule((r) => {
-			const { a } = r.vars("a")
+			const a = r.var("a")
 			return r
 				.match(Account, { id: a })
 				.where(eq(a, r.param("root")))
 				.select("a")
 		})
 		.rule((r) => {
-			const { a, parent } = r.vars("a", "parent")
+			const a = r.var("a")
+			const parent = r.var("parent")
 			return r
 				.match(AccountParent, { child: a, parent })
 				.idb(sub, parent)
 				.select("a")
 		})
 	return p.output((r) => {
-		const { id, a, minor } = r.vars("id", "a", "minor")
+		const id = r.var("id")
+		const a = r.var("a")
+		const minor = r.var("minor")
 		return r
 			.match(Posting, { id, account: a, minor })
 			.idb(seeded, a)
@@ -1348,7 +1403,9 @@ const MaintainedRollup = schema("MaintainedRollup", { Arm, Claim, BusySpan }, [
 
 // Derive the desired rollup on the maintenance snapshot:
 const deriving = query(MaintainedRollup).rule((r) => {
-	const { source, person, span } = r.vars("source", "person", "span")
+	const source = r.var("source")
+	const person = r.var("person")
+	const span = r.var("span")
 	return r.match(Claim, { source, person, arm: "Busy", span }).select("person", r.pack("span"))
 })
 ```
@@ -1402,7 +1459,10 @@ const Payroll = schema("Payroll", { Employee, Salary }, [
 
 // The post-migration read — salaries in force at an instant:
 const inForceAt = query(Payroll).rule((r) => {
-	const { e, name, amount, w } = r.vars("e", "name", "amount", "w")
+	const e = r.var("e")
+	const name = r.var("name")
+	const amount = r.var("amount")
+	const w = r.var("w")
 	return r
 		.match(Employee, { id: e, name })
 		.match(Salary, { employee: e, amount, applies: w })
@@ -1468,3 +1528,77 @@ unit slots `[4,5)`, `[5,6)` satisfies both directions, because nothing forces
 the witness rows to mirror the sidecar's segmentation — only its points. If
 per-row correspondence matters, the host writes zones at slot granularity;
 the schema proves disjointness and coverage either way.
+
+## Point reads
+
+## 30. The keyed read
+
+Guarantee: validator/runtime premises — a declared key FD admits at most one
+fact per determinant tuple (the key phase of the commit judgment), and every
+keyed point read answers exactly that fact or nothing, on every scope
+(`ts/test/keyed-get.test.ts`; the engine half is
+`crates/bumbledb/tests/keyed_get.rs`).
+
+The key is a **law**, and the read surface is that law made callable. The
+schema says `key(Program, ["grp"])` — one program per group — so "the
+program of a group" is a well-posed question with at most one answer, and
+the store already enforces that on every commit. Hold the statement VALUE:
+it is the read's selector below (statement identity is the membership rule).
+
+```ts
+const Grp = relation("Grp", { id: u64.fresh, label: str })
+const Program = relation("Program", { id: u64.fresh, grp: u64, title: str })
+// The law: one program per group — the callable key.
+const programGrpKey = key(Program, ["grp"])
+
+const KeyedRead = schema("KeyedRead", { Grp, Program }, [
+	contained(on(Program, "grp"), on(Grp, "id")),
+	programGrpKey
+])
+```
+
+The point read is the statement handed back to `get` — one spelling on
+every scope (the symmetry rule): `db.get` standalone, `snap.get` inside a
+read scope, `tx.get` inside a write transaction, where the transaction side
+answers the FINAL state (base plus pending delta: read-your-writes, a
+pending delete answers `undefined`). The key object is typed by the
+statement's own projection — a wrong field name is a compile error, never a
+runtime shape check. The primary 2-arg form needs no statement: the fresh
+field IS the primary key.
+
+```ts
+const db = await Db.create("./programs.db", KeyedRead)
+
+const minted: { grp?: bigint } = {}
+db.write((tx) => {
+	const g = tx.insert(Grp, { label: "algebra" })
+	tx.insert(Program, { grp: g.id, title: "linear equations" })
+	minted.grp = g.id
+})
+const grp = minted.grp ?? 0n
+
+// db.get — the standalone keyed read through the declared law:
+const byGroup = db.get(Program, programGrpKey, { grp })
+
+// snap.get — the same spelling inside a read scope:
+const viaSnap = db.read((snap) => snap.get(Program, programGrpKey, { grp }))
+
+// tx.get — key-shaped read-modify-write, final-state (recipe 20's third
+// idiom): per-fact premises need no earlier snapshot witness.
+db.write((tx) => {
+	const current = tx.get(Program, programGrpKey, { grp })
+	if (current !== undefined) {
+		tx.delete(Program, current)
+		tx.insert(Program, { id: current.id, grp: current.grp, title: "linear equations II" })
+	}
+})
+
+// The primary 2-arg form — the fresh field is the primary key:
+const byId = byGroup === undefined ? undefined : db.get(Program, { id: byGroup.id })
+```
+
+The anti-pattern this recipe retires: a scan-and-find where a key law
+exists — `snap.scan(Program).find((row) => row.grp === grp)` — re-derives
+in the host what the store already enforces. The uniqueness the fold
+quietly assumes IS the declared key statement; spell the law and the point
+read comes with it.

package/README.md

@@ -79,7 +79,9 @@ if (!result.ok) {
 // first binding; params are typed by use; rows are typed from the select.
 // `gt` is one of the free comparison exports.
 const certifiedAbove = query(Review).rule((r) => {
-	const { a, k, rank } = r.vars("a", "k", "rank")
+	const a = r.var("a")
+	const k = r.var("k")
+	const rank = r.var("rank")
 	return r
 		.match(Certificate, { attempt: a, kind: k })
 		.match(Kind, { id: k, mastered: true, rank }) // ψ on the read side too
@@ -118,7 +120,7 @@ The drizzle law governs this surface: the SDK's job at the host boundary is tran
 - The structural type kernel — fields as pure structure (`bool`, `bytes`, `i64`, `u64`, `str`, `interval`, `span`), `relation()`, and `closed()` sealed rosters with typed axiom payloads. A closed reference's value type IS the handle union (`Infer` speaks it); dispatch is native `switch` narrowing with `satisfies never` exhaustiveness. Domains are never declared: `schema()` computes every field's class from the statement list.
 - The statement algebra — `schema()`, `key`, `contained`, `mirrors`, `window`; faces via `on` (set membership is a plain array in `.where`); counts via `exactly`, `atLeast`, `atMost`, `between`, `none`; ψ-selection via `.where` on relations and closed rosters.
 - The `Db` runtime — `Db.create`/`Db.open`, path-cached stores, transactions, typed violations, scoped snapshot reads, the witnessed write loop with `abandon`.
-- The query surface — Datalog as values, `query(S).rule(r => ...)`: named vars, params typed by use, negation, aggregates, and the free comparison/connective exports (`eq`, `ne`, `lt`, `le`, `gt`, `ge`, `and`, `or`, `not`, `allen`/`ALLEN`, `pointIn`, `covers`); set membership at a closed field is a plain array in the match record (`r.match(Ticket, { priority: ["Normal", "Urgent"] })` — closed-only there: an ordinary field's membership is a bound `r.inSet` param); stratified recursion via `program()`; `db.prepare` as a plain value.
+- The query surface — Datalog as values, `query(S).rule(r => ...)`: named vars, params typed by use, negation, aggregates, and the free comparison/connective exports (`eq`, `ne`, `lt`, `le`, `gt`, `ge`, `and`, `or`, `not`, `allen`/`ALLEN`, `pointIn`); set membership at a closed field is a plain array in the match record (`r.match(Ticket, { priority: ["Normal", "Urgent"] })` — closed-only there: an ordinary field's membership is a bound `r.inSet` param); stratified recursion via `program()`; `db.prepare` as a plain value.
 - The exhume surface — `Db.exhume`, the schema-independent read path: a store's self-described shapes and raw facts by name, with typed refusals (`ErrExhumeNoDescriptor`, `ErrExhumeFormatMismatch`, `ErrExhumeCorruption`).
 
 ## Cookbook

package/dist/closed.d.ts

@@ -30,6 +30,7 @@
  * shape.
  */
 import { type AnyField, type ClosedIdField, type Infer } from "#fields.ts";
+import type { AnyRelation, RelationField } from "#relation.ts";
 import { type SelectionBinding, type SelectionInput } from "#relation.ts";
 import type { LiteralSpec } from "#spec.ts";
 /**
@@ -44,7 +45,7 @@ type PayloadField = Exclude<AnyField, {
  * unspellable — the sealed shape mints the synthetic `id` itself (ordinal
  * 0 of the matchable fields), so a declared column named `id` would be
  * shadowed by the synthetic slot everywhere the shape resolves by name
- * (`matchFieldsOf`, the projected face, `spec.rs`'s resolver). The wall is
+ * (`sealedFieldsOf`, the projected face, `spec.rs`'s resolver). The wall is
  * typed here and judged again at construction in {@link mintClosed} — the
  * runtime twin for untyped callers, warmer and earlier than the engine's
  * `DuplicateFieldName` at `Db.create`.
@@ -173,6 +174,33 @@ interface AnyClosed {
     readonly axioms: Readonly<Record<string, object>>;
     readonly columns: Readonly<Record<string, PayloadField>>;
 }
+/**
+ * THE relation-kind discriminant — the ONE spelling of "is this schema
+ * member closed?" (the type tier's twin is the `AnyClosed` conditional
+ * arms). A closed relation's runtime description carries its handle
+ * roster; an ordinary relation's never does. Every runtime closed/ordinary
+ * fork in the SDK judges through this predicate — never a re-spelled
+ * structural probe.
+ */
+declare function isClosedMember(member: AnyRelation | AnyClosed): member is AnyClosed;
+/**
+ * The SEALED field list of a schema member — THE one reader of "what
+ * fields does this owner expose": an ordinary relation's declared fields;
+ * a closed relation's sealed shape — the synthetic `id` (the value's own
+ * roster-carrying descriptor, by identity) at ordinal 0, then the declared
+ * payload columns at declared index + 1 (the sealed shift, mirroring the
+ * engine's `SchemaDescriptor::sealed_fields`). A `ClosedColumn` is
+ * structurally a `RelationField`, so both kinds read uniformly.
+ */
+declare function sealedFieldsOf(member: AnyRelation | AnyClosed): readonly RelationField[];
+/**
+ * One sealed field by name — derived from {@link sealedFieldsOf}, so the
+ * closed synthetic `id` resolves everywhere a name is looked up (no reader
+ * can silently lack the `id` arm). `undefined` when the name is foreign
+ * (the type tiers make that unwritable; the engine re-judges at
+ * `Db.create`).
+ */
+declare function sealedFieldOf(member: AnyRelation | AnyClosed, fieldName: string): AnyField | undefined;
 /** Bare tier: `closed("Kind", ["Checking", "Savings"])` — handles only. */
 declare function closed<const Name extends string, const Handles extends readonly [string, ...string[]]>(name: Name, handles: Handles): Closed<Name, Handles[number], Record<never, never>>;
 /**
@@ -189,5 +217,5 @@ declare function closed<const Name extends string, const Handles extends readonl
  */
 declare function closed<const Name extends string, const Cols extends PayloadColumns, Handles extends string>(name: Name, columns: Cols, axioms: Axioms<Handles, Cols>): Closed<Name, Handles, Cols>;
 export type { AnyClosed, AnySelectedClosed, AxiomRow, Axioms, Closed, ClosedColumn, ClosedCore, ClosedData, ClosedRow, ClosedSelectable, ClosedSelectionInput, PayloadField, SelectedClosed };
-export { closed };
+export { closed, isClosedMember, sealedFieldOf, sealedFieldsOf };
 //# sourceMappingURL=closed.d.ts.map

package/dist/closed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"closed.d.ts","sourceRoot":"","sources":["../src/closed.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"closed.d.ts","sourceRoot":"","sources":["../src/closed.ts"],"names":[],"mappings":"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"}