@bjornpagen/bumbledb 0.4.0 → 0.6.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,
@@ -54,7 +56,8 @@ import {
 	relation,
 	schema,
 	str,
-	u64
+	u64,
+	v
 } from "@bjornpagen/bumbledb"
 ```
 
@@ -116,27 +119,27 @@ 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 — v(Outage) mints a fresh variable per column (typed by
+// that column's law-class); destructure what you bind, reuse to join:
 const downAt = query(Uptime).rule((r) => {
-	const { service, window } = r.vars("service", "window")
+	const { service, window } = v(Outage)
 	return r
 		.match(Outage, { service, window })
 		.where(pointIn(r.param("t"), window))
-		.select("service")
+		.find({ service })
 })
 // 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, window } = v(Outage)
 	return r
 		.match(Outage, { service, window })
 		.where(allen(window, ALLEN.intersects, r.param("incident")))
-		.select("service", "window")
+		.find({ service, window })
 })
 // total downtime per service (the denotation's one arithmetic):
 const downtime = query(Uptime).rule((r) => {
-	const { service, window } = r.vars("service", "window")
-	return r.match(Outage, { service, window }).select("service", r.sum(r.duration("window")))
+	const { service, window } = v(Outage)
+	return r.match(Outage, { service, window }).find({ service, downtime: r.sum(r.duration(window)) })
 })
 ```
 
@@ -215,11 +218,11 @@ 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 { id: b } = v(Business)
 	return r
 		.match(Business, { id: b })
 		.where(not(MailingAddress, { business: b }))
-		.select("b")
+		.find({ b })
 })
 ```
 
@@ -255,8 +258,8 @@ 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")
-	return r.match(Posting, { id, account, currency, minor }).select("account", "currency", r.sum("minor"))
+	const { id, account, currency, minor } = v(Posting)
+	return r.match(Posting, { id, account, currency, minor }).find({ account, currency, total: r.sum(minor) })
 })
 ```
 
@@ -292,8 +295,8 @@ 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")
-	return r.match(Document, { id, payload: r.param("digest") }).select("id")
+	const { id } = v(Document)
+	return r.match(Document, { id, payload: r.param("digest") }).find({ id })
 })
 ```
 
@@ -334,8 +337,8 @@ 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: "Urgent" }).select("t")
+	const { id: t } = v(Ticket)
+	return r.match(Ticket, { id: t, priority: "Urgent" }).find({ t })
 })
 
 // Set membership is a plain array — the drizzle law's spelling, closed-only
@@ -343,8 +346,8 @@ 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")
-	return r.match(Ticket, { id: t, priority: ["Normal", "Urgent"] }).select("t")
+	const { id: t } = v(Ticket)
+	return r.match(Ticket, { id: t, priority: ["Normal", "Urgent"] }).find({ t })
 })
 ```
 
@@ -388,11 +391,11 @@ 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 { id: a, kind: k } = v(Attempt)
 	return r
 		.match(Attempt, { id: a, kind: k })
 		.match(Kind, { id: k, mastered: true })
-		.select("a")
+		.find({ a })
 })
 
 // Host dispatch on the payload tier is the record-table idiom — a `Record`
@@ -451,11 +454,11 @@ 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 { incident: i, severity: s } = v(Escalation)
 	return r
 		.match(Escalation, { incident: i, severity: s })
 		.match(Severity, { id: s, pages: true })
-		.select("i")
+		.find({ i })
 })
 ```
 
@@ -468,7 +471,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 +500,20 @@ 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, track } = v(Slot)
 	return r
 		.match(Slot, { playlist: r.param("list"), slot, track })
 		.where(pointIn(r.param("pos"), slot))
-		.select("track")
+		.find({ 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,11 +560,12 @@ const Ast = schema("Ast", { Kind, Node, Lit, Add, Parent }, [
 ])
 
 const lhsLiteral = query(Ast).rule((r) => {
-	const { l, v } = r.vars("l", "v")
+	const { lhs: l } = v(Add)
+	const { value } = v(Lit)
 	return r
 		.match(Add, { node: r.param("n"), lhs: l })
-		.match(Lit, { node: l, value: v })
-		.select("v")
+		.match(Lit, { node: l, value })
+		.find({ value })
 })
 ```
 
@@ -583,12 +596,12 @@ 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 { follower: a, followee: b } = v(Follows)
 	return r
 		.match(Follows, { follower: a, followee: b })
 		.match(Follows, { follower: b, followee: a })
 		.where(lt(a, b))
-		.select("a", "b")
+		.find({ a, b })
 })
 ```
 
@@ -621,11 +634,12 @@ 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, x, y } = v(Transform)
+	const { dx, dy } = v(Velocity)
 	return r
 		.match(Transform, { entity, x, y })
 		.match(Velocity, { entity, dx, dy })
-		.select("entity", "x", "y", "dx", "dy")
+		.find({ entity, x, y, dx, dy })
 })
 ```
 
@@ -661,11 +675,12 @@ const Orders = schema("Orders", { State, Order, Placement, Shipment }, [
 ])
 
 const shipped = query(Orders).rule((r) => {
-	const { id, carrier } = r.vars("id", "carrier")
+	const { id } = v(Order)
+	const { carrier } = v(Shipment)
 	return r
 		.match(Order, { id, state: "Shipped" })
 		.match(Shipment, { order: id, carrier })
-		.select("id", "carrier")
+		.find({ id, carrier })
 })
 ```
 
@@ -731,18 +746,18 @@ 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, span } = v(Booking)
 	return r
 		.match(Booking, { room, span })
 		.where(allen(span, ALLEN.intersects, r.param("want")))
-		.select("room", "span")
+		.find({ room, span })
 })
 const personLoad = query(Calendar).rule((r) => {
-	const { person, span } = r.vars("person", "span")
+	const { person, span } = v(Claim)
 	return r
 		.match(Claim, { person, span })
 		.where(allen(span, ALLEN.intersects, r.param("window")))
-		.select("person", "span")
+		.find({ person, span })
 })
 ```
 
@@ -774,20 +789,21 @@ 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, valid } = v(Version)
 	return r
 		.match(Version, { policy: r.param("p"), rate_bps, valid })
 		.where(pointIn(r.param("t"), valid))
-		.select("rate_bps")
+		.find({ rate_bps })
 })
 // 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 { policy: p, valid: a } = v(Version)
+	const { valid: b } = v(Version)
 	return r
 		.match(Version, { policy: p, valid: a })
 		.match(Version, { policy: p, valid: b })
 		.where(allen(a, ALLEN.meets, b))
-		.select("a", "b")
+		.find({ a, b })
 })
 ```
 
@@ -816,11 +832,11 @@ 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, span } = v(PayPeriod)
 	return r
 		.match(PayPeriod, { year: r.param("y"), seq, span })
 		.where(pointIn(r.param("t"), span))
-		.select("seq")
+		.find({ seq })
 })
 ```
 
@@ -864,12 +880,13 @@ 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 { id: reg } = v(Regime)
+	const { income: b, rate_bps } = v(Bracket)
 	return r
 		.match(Regime, { id: reg, year: r.param("y"), status: r.param("s") })
 		.match(Bracket, { regime: reg, income: b, rate_bps })
 		.where(pointIn(r.param("taxable"), b))
-		.select("rate_bps")
+		.find({ rate_bps })
 })
 ```
 
@@ -896,17 +913,19 @@ 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")
-	return r.match(Claim, { person, span }).select("person", r.pack("span"))
+	const { person, span } = v(Claim)
+	return r.match(Claim, { person, span }).find({ person, packed: 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")
-	return r.match(Claim, { person, span }).select("person", r.sum(r.duration("span")))
+	const { person, span } = v(Claim)
+	return r.match(Claim, { person, span }).find({ person, claimed: 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,13 +959,13 @@ 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")
-	return r.match(Posting, { id, account, minor }).select("account", r.sum("minor"))
+	const { id, account, minor } = v(Posting)
+	return r.match(Posting, { id, account, minor }).find({ account, balance: 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")
-	return r.match(Posting, { id, entry, minor }).select("entry", r.sum("minor"))
+	const { id, entry, minor } = v(Posting)
+	return r.match(Posting, { id, entry, minor }).find({ entry, balance: r.sum(minor) })
 })
 ```
 
@@ -960,8 +979,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,8 +1000,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")
-	return r.match(Job, { id, state: "Queued", payload }).select("id", "payload")
+	const { id, payload } = v(Job)
+	return r.match(Job, { id, state: "Queued", payload }).find({ id, payload })
 })
 
 const db = await Db.create("./jobs.db", Jobs)
@@ -1035,8 +1057,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")
-	return r.match(Claim, { person, span, arm: "Busy" }).select("person", r.pack("span"))
+	const { person, span } = v(Claim)
+	return r.match(Claim, { person, span, arm: "Busy" }).find({ person, packed: r.pack(span) })
 })
 ```
 
@@ -1069,18 +1091,20 @@ 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 } = v(Payment)
+		const { last4: n } = v(Card)
 		return r
 			.match(Payment, { id, kind: "Card" })
 			.match(Card, { payment: id, last4: n })
-			.select("id", "n")
+			.find({ id, n })
 	})
 	.rule((r) => {
-		const { id, n } = r.vars("id", "n")
+		const { id } = v(Payment)
+		const { routing: n } = v(Ach)
 		return r
 			.match(Payment, { id, kind: "Ach" })
 			.match(Ach, { payment: id, routing: n })
-			.select("id", "n")
+			.find({ id, n })
 	})
 ```
 
@@ -1148,8 +1172,8 @@ 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")
-	return r.match(Parent, { child: c, parent: r.inSet("frontier") }).select("c")
+	const { child: c } = v(Parent)
+	return r.match(Parent, { child: c, parent: r.inSet("frontier") }).find({ c })
 })
 ```
 
@@ -1192,22 +1216,22 @@ const reach = program(Closure, (p) => {
 	const rec = p.rec("reach")
 	const seeded = rec
 		.rule((r) => {
-			const { c } = r.vars("c")
+			const { id: c } = v(Node)
 			return r
 				.match(Node, { id: c })
 				.where(eq(c, r.param("root")))
-				.select("c")
+				.find({ c })
 		})
 		.rule((r) => {
-			const { c, parent } = r.vars("c", "parent")
+			const { child: c, parent } = v(Parent)
 			return r
 				.match(Parent, { child: c, parent })
-				.idb(rec, parent)
-				.select("c")
+				.idb(rec, { c: parent })
+				.find({ c })
 		})
 	return p.output((r) => {
-		const { c } = r.vars("c")
-		return r.match(Node, { id: c }).idb(seeded, c).select("c")
+		const { id: c } = v(Node)
+		return r.match(Node, { id: c }).idb(seeded, { c }).find({ c })
 	})
 })
 const reachPrepared = db.prepare(reach)
@@ -1249,14 +1273,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")
-	return r.match(AccountParent, { child: c, parent: r.inSet("frontier") }).select("c")
+	const { child: c } = v(AccountParent)
+	return r.match(AccountParent, { child: c, parent: r.inSet("frontier") }).find({ 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")
-	return r.match(Posting, { id, account: r.inSet("subtree"), minor }).select(r.sum("minor"))
+	const { id, minor } = v(Posting)
+	return r.match(Posting, { id, account: r.inSet("subtree"), minor }).find({ total: r.sum(minor) })
 })
 // The engine-native form: the closure stratum converges first, then the
 // output's fold runs once over the finished subtree.
@@ -1264,25 +1288,25 @@ const nativeRollup = program(Accounts, (p) => {
 	const sub = p.rec("sub")
 	const seeded = sub
 		.rule((r) => {
-			const { a } = r.vars("a")
+			const { id: a } = v(Account)
 			return r
 				.match(Account, { id: a })
 				.where(eq(a, r.param("root")))
-				.select("a")
+				.find({ a })
 		})
 		.rule((r) => {
-			const { a, parent } = r.vars("a", "parent")
+			const { child: a, parent } = v(AccountParent)
 			return r
 				.match(AccountParent, { child: a, parent })
-				.idb(sub, parent)
-				.select("a")
+				.idb(sub, { a: parent })
+				.find({ a })
 		})
 	return p.output((r) => {
-		const { id, a, minor } = r.vars("id", "a", "minor")
+		const { id, account: a, minor } = v(Posting)
 		return r
 			.match(Posting, { id, account: a, minor })
-			.idb(seeded, a)
-			.select(r.sum("minor"))
+			.idb(seeded, { a })
+			.find({ total: r.sum(minor) })
 	})
 })
 ```
@@ -1348,8 +1372,8 @@ 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")
-	return r.match(Claim, { source, person, arm: "Busy", span }).select("person", r.pack("span"))
+	const { source, person, span } = v(Claim)
+	return r.match(Claim, { source, person, arm: "Busy", span }).find({ person, packed: r.pack(span) })
 })
 ```
 
@@ -1402,12 +1426,13 @@ 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 { id: e, name } = v(Employee)
+	const { amount, applies: w } = v(Salary)
 	return r
 		.match(Employee, { id: e, name })
 		.match(Salary, { employee: e, amount, applies: w })
 		.where(pointIn(r.param("at"), w))
-		.select("name", "amount")
+		.find({ name, amount })
 })
 ```
 
@@ -1468,3 +1493,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

@@ -27,7 +27,7 @@ classes, inferred query rows, and rejections that arrive as data rather than
 exceptions.
 
 ```ts
-import { bool, closed, contained, Db, gt, type Infer, key, on, query, relation, schema, u64 } from "@bjornpagen/bumbledb"
+import { bool, closed, contained, Db, gt, type Infer, key, on, query, relation, schema, u64, v } from "@bjornpagen/bumbledb"
 
 // A closed relation: a sealed roster of axioms with typed payload columns.
 // At the host surface a handle is its NAME — the string literal "DirectPass"
@@ -75,16 +75,18 @@ if (!result.ok) {
 	}
 }
 
-// Query: Datalog as values. Vars are named and typed by the class of their
-// first binding; params are typed by use; rows are typed from the select.
+// Query: Datalog as values. v(R) mints a fresh variable per column, typed by
+// the column's law-class; reusing one by object reference IS the join, and
+// rows are typed from the find keys. Params are typed by use.
 // `gt` is one of the free comparison exports.
 const certifiedAbove = query(Review).rule((r) => {
-	const { a, k, rank } = r.vars("a", "k", "rank")
+	const { attempt: a, kind: k } = v(Certificate)
+	const { rank } = v(Kind)
 	return r
 		.match(Certificate, { attempt: a, kind: k })
-		.match(Kind, { id: k, mastered: true, rank }) // ψ on the read side too
+		.match(Kind, { id: k, mastered: true, rank }) // k reused at Kind.id — that reuse is the join; ψ on the read side too
 		.where(gt(rank, r.param("floor")))
-		.select("a", "rank")
+		.find({ a, rank })
 })
 
 const prepared = db.prepare(certifiedAbove)
@@ -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 => ...)`: `v(R)`-minted vars (identity is the object reference — reusing one across binding positions IS the join), `find({...})` named result heads (renames are real), params typed by use unchanged, 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