@bjornpagen/bumbledb 0.3.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
@@ -33,12 +33,15 @@ Everything below imports from the one package entry:
 import {
 	ALLEN,
 	Db,
+	type Infer,
 	abandon,
 	allen,
 	bool,
+	by,
 	bytes,
 	closed,
 	contained,
+	desc,
 	eq,
 	i64,
 	interval,
@@ -115,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))
@@ -126,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")))
@@ -134,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")))
 })
 ```
@@ -150,8 +156,8 @@ relations, glued by bidirectional conditional containments.
 
 ```ts
 // The discriminator vocabulary is a closed relation: its ground axioms are
-// axioms, and the handle constants (`Kind.Deterministic`, bare bigints) are
-// the literals on every surface.
+// axioms, and a handle is its NAME — the string literal "Deterministic" is
+// the ONE spelling, on every surface (statements, inserts, queries, rows).
 const Kind = closed("Kind", ["Deterministic", "CustomOperator"])
 const Task = relation("Task", { id: u64.fresh, kind: Kind.id })
 const DeterministicGrading = relation("DeterministicGrading", { task: u64, tolerance: i64 })
@@ -166,21 +172,28 @@ const Grading = schema("Grading", { Kind, Task, DeterministicGrading, CustomOper
 	// exists WITH that kind — composite-FK-plus-CHECK, one statement. These
 	// mirrors are also what type `task` on both arms: each lands in the
 	// "Task.id" generator class.
-	mirrors(on(Task.where({ kind: Kind.Deterministic }), "id"), on(DeterministicGrading, "task")),
-	mirrors(on(Task.where({ kind: Kind.CustomOperator }), "id"), on(CustomOperatorGrading, "task"))
+	mirrors(on(Task.where({ kind: "Deterministic" }), "id"), on(DeterministicGrading, "task")),
+	mirrors(on(Task.where({ kind: "CustomOperator" }), "id"), on(CustomOperatorGrading, "task"))
 	// Exclusivity is a theorem, not a statement: one id in two arms would
 	// force `kind` to equal two handles against the fresh key on id.
 	// The executor spends the same theorem again — recipe 22's free lunch.
 ])
 
-// Host dispatch over the discriminator is `match` — exhaustive over the
-// sealed roster by construction (a missing arm is a compile error; an
-// out-of-roster id throws, never misdispatches):
-const gradedBy = (kind: bigint) =>
-	Kind.match(kind, {
-		Deterministic: () => "tolerance",
-		CustomOperator: () => "operator"
-	})
+// Host dispatch over the discriminator is native `switch` narrowing over
+// the handle union (`Infer<typeof Kind.id>` = "Deterministic" |
+// "CustomOperator") — rows already arrive carrying the handle name, and
+// `satisfies never` makes the switch exhaustive: a missing arm is a
+// compile error.
+const gradedBy = (kind: Infer<typeof Kind.id>) => {
+	switch (kind) {
+		case "Deterministic":
+			return "tolerance"
+		case "CustomOperator":
+			return "operator"
+		default:
+			return kind satisfies never
+	}
+}
 ```
 
 ## 3. 0..1 optional attributes
@@ -207,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 }))
@@ -247,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"))
 })
 ```
@@ -284,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")
 })
 ```
@@ -301,13 +317,13 @@ declared priority handles.
 The enum idiom's replacement, first-class: a vocabulary is a **closed
 relation** — its ground axioms are declared in the schema, sealed at
 validate, frozen by the fingerprint, virtual in storage. The store holds zero
-vocabulary bytes, and handles are the literals on every surface.
+vocabulary bytes, and handle names are the string literals on every surface.
 
 ```ts
-// Tier 1: handles only. `closed()` mints one bare-bigint constant per handle
-// (ids = declaration order) — an emission, not a type: the engine's
-// vocabulary stays relational; the host matches on `Priority.Urgent`, or
-// dispatches exhaustively with `Priority.match` (recipe 2).
+// Tier 1: handles only. At the host surface a handle is its NAME — a string
+// literal of the roster's union ("Low" | "Normal" | "Urgent"); the engine's
+// vocabulary stays relational (ids = declaration order) and the marshal
+// owns the bijection. Dispatch is native `switch` narrowing (recipe 2).
 const Priority = closed("Priority", ["Low", "Normal", "Urgent"])
 
 const Ticket = relation("Ticket", { id: u64.fresh, priority: Priority.id, opened_at: i64 })
@@ -326,8 +342,17 @@ 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")
-	return r.match(Ticket, { id: t, priority: Priority.Urgent }).select("t")
+	const t = r.var("t")
+	return r.match(Ticket, { id: t, priority: "Urgent" }).select("t")
+})
+
+// Set membership is a plain array — the drizzle law's spelling, closed-only
+// in query match records (an ordinary u64/str field's membership is a bound
+// ∈-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.var("t")
+	return r.match(Ticket, { id: t, priority: ["Normal", "Urgent"] }).select("t")
 })
 ```
 
@@ -371,20 +396,24 @@ 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 })
 		.select("a")
 })
 
-// Host dispatch on the payload tier hands each arm its sealed axiom row:
-const label = (k: bigint) =>
-	Kind.match(k, {
-		DirectPass: (row) => `mastered, rank ${row.rank}`,
-		JudgedPass: (row) => `mastered, rank ${row.rank}`,
-		Failed: () => "not mastered"
-	})
+// Host dispatch on the payload tier is the record-table idiom — a `Record`
+// over the handle union is total by type (a missing or extra entry is a
+// compile error), and each entry reads its sealed axiom row off the typed
+// `Kind.axioms` readback:
+const labels: Record<Infer<typeof Kind.id>, string> = {
+	DirectPass: `mastered, rank ${Kind.axioms.DirectPass.rank}`,
+	JudgedPass: `mastered, rank ${Kind.axioms.JudgedPass.rank}`,
+	Failed: "not mastered"
+}
+const label = (k: Infer<typeof Kind.id>) => labels[k]
 ```
 
 Two honest boundaries. The fold has limits: payload escaping to the head and
@@ -425,13 +454,14 @@ const Oncall = schema("Oncall", { Severity, Incident, Escalation }, [
 	// The sub-vocabulary: an escalation carries a PAGING severity, by
 	// statement. ψ over the sealed extension compiles to the member set
 	// {Critical, Fatal}; the judgment is one bit test per touched fact,
-	// and an escalation at Severity.Info aborts the commit.
+	// and an escalation at "Info" aborts the commit.
 	contained(on(Escalation, "severity"), on(Severity.where({ pages: true }), "id"))
 ])
 
 // 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 })
@@ -448,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
@@ -476,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
@@ -512,8 +552,8 @@ const Ast = schema("Ast", { Kind, Node, Lit, Add, Parent }, [
 	key(Lit, ["node"]),
 	key(Add, ["node"]),
 	// Every node's arm is total, valid, and exclusive (recipe 2's theorems):
-	mirrors(on(Node.where({ kind: Kind.Lit }), "id"), on(Lit, "node")),
-	mirrors(on(Node.where({ kind: Kind.Add }), "id"), on(Add, "node")),
+	mirrors(on(Node.where({ kind: "Lit" }), "id"), on(Lit, "node")),
+	mirrors(on(Node.where({ kind: "Add" }), "id"), on(Add, "node")),
 	// Every child edge resolves — no dangling subtrees, judged at commit
 	// (these containments also put lhs/rhs in the "Node.id" class, which is
 	// exactly what lets the query below join lhs against Lit.node):
@@ -528,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 })
@@ -563,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 })
@@ -601,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 })
@@ -635,15 +681,16 @@ const Orders = schema("Orders", { State, Order, Placement, Shipment }, [
 	// The conditional target, both ways: every Shipment references an order
 	// THAT IS Shipped (validity), and every Shipped order has its Shipment
 	// (totality) — the transition and its evidence commit together.
-	mirrors(on(Shipment, "order"), on(Order.where({ state: State.Shipped }), "id"))
+	mirrors(on(Shipment, "order"), on(Order.where({ state: "Shipped" }), "id"))
 	// Transition predicates ("only Placed may ship") are host code under the
 	// generation witness — recipe 20; the schema pins the states, not the paths.
 ])
 
 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: State.Shipped })
+		.match(Order, { id, state: "Shipped" })
 		.match(Shipment, { order: id, carrier })
 		.select("id", "carrier")
 })
@@ -701,24 +748,26 @@ const Calendar = schema("Calendar", { Rsvp, Arm, Person, Room, Event, Attendance
 	// not declared. Policy is the presence or absence of one statement.
 	// Accepting an invitation IS claiming the time (totality + validity) —
 	// and this is the statement that types Claim.source:
-	mirrors(on(Attendance.where({ rsvp: Rsvp.Accepted }), "id"), on(Claim.where({ arm: Arm.Busy }), "source")),
+	mirrors(on(Attendance.where({ rsvp: "Accepted" }), "id"), on(Claim.where({ arm: "Busy" }), "source")),
 	// Busy time lies inside working hours, pointwise — coverage rides the
 	// target's own key (disjoint + ordered is a theorem, not a request):
 	key(WorkHours, ["person", "hours"]),
-	contained(on(Claim.where({ arm: Arm.Busy }), ["person", "span"]), on(WorkHours, ["person", "hours"])),
+	contained(on(Claim.where({ arm: "Busy" }), ["person", "span"]), on(WorkHours, ["person", "hours"])),
 	contained(on(Booking, "room"), on(Room, "id")),
 	contained(on(Booking, "event"), on(Event, "id"))
 ])
 
 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")))
@@ -754,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))
@@ -762,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 })
@@ -796,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))
@@ -844,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 })
@@ -876,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
@@ -920,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"))
 })
 ```
@@ -940,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"])
@@ -953,13 +1019,14 @@ const Jobs = schema("Jobs", { State, Job, Lease }, [
 	key(Lease, ["job"]),
 	// A lease exists iff its job is Running (recipe 13's conditional target):
 	// claiming a job and leasing it commit together or not at all.
-	mirrors(on(Lease, "job"), on(Job.where({ state: State.Running }), "id"))
+	mirrors(on(Lease, "job"), on(Job.where({ state: "Running" }), "id"))
 ])
 
 // update-where's premise — "still Queued" is the witness:
 const stillQueued = query(Jobs).rule((r) => {
-	const { id, payload } = r.vars("id", "payload")
-	return r.match(Job, { id, state: State.Queued, payload }).select("id", "payload")
+	const id = r.var("id")
+	const payload = r.var("payload")
+	return r.match(Job, { id, state: "Queued", payload }).select("id", "payload")
 })
 
 const db = await Db.create("./jobs.db", Jobs)
@@ -976,8 +1043,8 @@ const outcome = db.writeWitnessed(function updateWhere(snap, tx) {
 		return abandon("nothing queued")
 	}
 	for (const row of queued) {
-		tx.delete(Job, { id: row.id, state: State.Queued, payload: row.payload })
-		tx.insert(Job, { id: row.id, state: State.Running, payload: row.payload })
+		tx.delete(Job, { id: row.id, state: "Queued", payload: row.payload })
+		tx.insert(Job, { id: row.id, state: "Running", payload: row.payload })
 		tx.insert(Lease, { job: row.id, worker: 7n, until: 60n })
 	}
 	return undefined
@@ -1007,7 +1074,7 @@ const Rollup = schema("Rollup", { Arm, Claim, BusySpan }, [
 	// Soundness, pointwise: every stored rollup point is covered by busy
 	// claims — an UNSOUND rollup (claiming busy time that isn't, or surviving
 	// its sources' deletion) cannot commit, judged on every touching commit.
-	contained(on(BusySpan, ["person", "span"]), on(Claim.where({ arm: Arm.Busy }), ["person", "span"]))
+	contained(on(BusySpan, ["person", "span"]), on(Claim.where({ arm: "Busy" }), ["person", "span"]))
 ])
 
 // Maintenance is the third witness idiom (recipe 20): re-run the deriving
@@ -1015,8 +1082,9 @@ 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")
-	return r.match(Claim, { person, span, arm: Arm.Busy }).select("person", r.pack("span"))
+	const person = r.var("person")
+	const span = r.var("span")
+	return r.match(Claim, { person, span, arm: "Busy" }).select("person", r.pack("span"))
 })
 ```
 
@@ -1040,8 +1108,8 @@ const Payments = schema("Payments", { Kind, Payment, Card, Ach }, [
 	contained(on(Payment, "kind"), on(Kind, "id")),
 	key(Card, ["payment"]),
 	key(Ach, ["payment"]),
-	mirrors(on(Payment.where({ kind: Kind.Card }), "id"), on(Card, "payment")),
-	mirrors(on(Payment.where({ kind: Kind.Ach }), "id"), on(Ach, "payment"))
+	mirrors(on(Payment.where({ kind: "Card" }), "id"), on(Card, "payment")),
+	mirrors(on(Payment.where({ kind: "Ach" }), "id"), on(Ach, "payment"))
 ])
 
 // One query, two rules (set union). The exclusivity theorem (recipe 2) is
@@ -1049,16 +1117,18 @@ 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: Kind.Card })
+			.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: Kind.Ach })
+			.match(Payment, { id, kind: "Ach" })
 			.match(Ach, { payment: id, routing: n })
 			.select("id", "n")
 	})
@@ -1128,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")
 })
 ```
@@ -1172,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")
 	})
 })
@@ -1229,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
@@ -1244,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)
@@ -1323,13 +1398,15 @@ const MaintainedRollup = schema("MaintainedRollup", { Arm, Claim, BusySpan }, [
 	key(Claim, ["source"]),
 	key(Claim, ["person", "span"]),
 	key(BusySpan, ["person", "span"]),
-	contained(on(BusySpan, ["person", "span"]), on(Claim.where({ arm: Arm.Busy }), ["person", "span"]))
+	contained(on(BusySpan, ["person", "span"]), on(Claim.where({ arm: "Busy" }), ["person", "span"]))
 ])
 
 // Derive the desired rollup on the maintenance snapshot:
 const deriving = query(MaintainedRollup).rule((r) => {
-	const { source, person, span } = r.vars("source", "person", "span")
-	return r.match(Claim, { source, person, arm: Arm.Busy, span }).select("person", r.pack("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"))
 })
 ```
 
@@ -1382,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 })
@@ -1437,8 +1517,8 @@ const ZoneLedger = schema("ZoneLedger", { Kind, Ledger, Zone, UnitSlot, PairSlot
 	key(PairSlot, ["ledger", "at"]),
 	// Each kind's zones carry exactly its sidecar's points — mixed widths,
 	// one element domain:
-	mirrors(on(Zone.where({ kind: Kind.Unit }), ["ledger", "at"]), on(UnitSlot, ["ledger", "at"])),
-	mirrors(on(Zone.where({ kind: Kind.Pair }), ["ledger", "at"]), on(PairSlot, ["ledger", "at"]))
+	mirrors(on(Zone.where({ kind: "Unit" }), ["ledger", "at"]), on(UnitSlot, ["ledger", "at"])),
+	mirrors(on(Zone.where({ kind: "Pair" }), ["ledger", "at"]), on(PairSlot, ["ledger", "at"]))
 ])
 ```
 
@@ -1448,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.