@orkestrel/scaffold 0.0.67 → 0.0.69

package/dist/host/guides/relation.md

@@ -0,0 +1,373 @@
+# Relation
+
+> A small, declarative ORM layer over the `@orkestrel/database` tables: a table's
+> relations named once, then records loaded or found with their related rows already
+> attached, batched so a direct relation costs one query across the whole record set and
+> a `through` relation two.
+
+The relationships (`belongs` / `many` / `one` / `through` / `morph`) cover the foreign-key shapes; nested includes recurse through the registry; `link` / `unlink` / `links` manage a many-to-many junction without hand-writing join rows. The layer stays thin above the typed store: resolution is define-time — each relation is precomputed once into a flat `ResolvedRelation`, and nothing is inferred while loading — and the loaded relation properties are deliberately loose (`Row | readonly Row[] | undefined`) rather than typed to each exact target row. The typed half is the table reached through `model.table`, and relation loading is the looser convenience on top. No write-cascades, no lazy proxies, no query builder of its own. Source: [`src/core`](../src/core). Surfaced through the `@src/core` barrel.
+
+## Surface
+
+Create a manager over a database and its relation map, then reach a typed model and load with relations attached:
+
+```ts
+import { createRelationManager, belongsTo, hasMany, hasThrough } from '@orkestrel/relation'
+
+const manager = createRelationManager({
+	database: db, // a typed DatabaseInterface from createDatabase(...)
+	relations: {
+		accounts: {
+			classification: belongsTo('classificationId', 'classifications'), // foreign key on accounts → one classification
+			contacts: hasMany('accountId'), // foreign key on contacts → many contacts back here
+			representatives: hasThrough('accountReps', 'accountId', 'repId', 'representatives'), // many-to-many through a junction
+		},
+		contacts: { account: belongsTo('accountId', 'accounts') }, // so contacts can nest-load its account
+	},
+})
+
+const accounts = manager.model('accounts') // a typed Model; only the relations you asked for are loaded
+const acme = await accounts.load('acc1', { contacts: true, classification: true })
+
+acme?.name // ✅ the base row is the table's row type
+acme?.contacts // the relation property — broad (Row | readonly Row[] | undefined); narrow at the use site
+```
+
+`model(name)` is checked against the database's declared tables, so a typo is a compile error. The model's own table (`model.table`) carries that table's row type; the attached related rows are the broad `Row` — narrow them where you read them.
+
+### Factory & manager
+
+| API                     | Kind     | Summary                                                                                                 |
+| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------- |
+| `createRelationManager` | function | Creates a `RelationManagerInterface` over a database and its relation map.                              |
+| `RelationManager`       | class    | Resolves a `RelationsShape` once at construction and vends a typed `ModelInterface` per declared table. |
+| `Model`                 | class    | Pairs a typed table with relation-aware `load` / `find` and junction management.                        |
+
+### Builders
+
+| API          | Kind     | Summary                                                                                                         |
+| ------------ | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `belongsTo`  | function | Builds a `belongs` relation — a foreign key on the owning table points at the related row (single).             |
+| `hasMany`    | function | Builds a `many` relation — a foreign key on the related table points back at the owning row (array).            |
+| `hasOne`     | function | Builds a `one` relation — like `hasMany`, but a single related row.                                             |
+| `hasThrough` | function | Builds a `through` relation — a junction table links the two sides (many-to-many).                              |
+| `hasMorph`   | function | Builds a `morph` relation — a polymorphic foreign key plus a discriminator column on the related table (array). |
+
+### Resolution
+
+| API                    | Kind     | Summary                                                                       |
+| ---------------------- | -------- | ----------------------------------------------------------------------------- |
+| `resolveRelation`      | function | Resolves one raw `Relation` value into a flat `ResolvedRelation`.             |
+| `resolveRelationMap`   | function | Resolves every entry of a `RelationMap` into a name → `ResolvedRelation` map. |
+| `isRelationDescriptor` | function | Narrows a value to a `RelationDescriptor` (the object form of a relation).    |
+
+### Row helpers
+
+| API             | Kind     | Summary                                                                |
+| --------------- | -------- | ---------------------------------------------------------------------- |
+| `readColumn`    | function | Reads one column off any record, whatever its declared type.           |
+| `countAttached` | function | Counts the related rows one relation attached across a record set.     |
+| `indexRows`     | function | Indexes rows by the string form of one column, for keyed lookups.      |
+| `groupRows`     | function | Groups rows by the string form of one column, for one-to-many lookups. |
+
+### Errors
+
+| API               | Kind     | Summary                                                                                             |
+| ----------------- | -------- | --------------------------------------------------------------------------------------------------- |
+| `RelationError`   | class    | Represents an error thrown by the relations layer, carrying a machine-readable `RelationErrorCode`. |
+| `isRelationError` | function | Narrows an unknown caught value to a `RelationError`.                                               |
+
+### Types
+
+A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. An extended interface's name comes before `plus`, with the members it adds after.
+
+| Type                       | Kind      | Shape                                                                                | Summary                                                                                                                                                                               |
+| -------------------------- | --------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Relationship`             | type      | `'belongs' \| 'many' \| 'one' \| 'through' \| 'morph'`                               | Enumerates the relationships a relation can declare.                                                                                                                                  |
+| `RelationDescriptor`       | interface | `{ relationship?, column?, key?, through?, source?, target?, tag?, label?, model? }` | Represents the object form of a relation.                                                                                                                                             |
+| `Relation`                 | type      | `string \| readonly string[] \| RelationDescriptor`                                  | Represents a single relation definition.                                                                                                                                              |
+| `RelationMap`              | type      | `Readonly<Record<string, Relation>>`                                                 | Holds a model's relations, keyed by relation name.                                                                                                                                    |
+| `RelationsShape`           | type      | `{ readonly [K in keyof T]?: RelationMap }`                                          | Holds per-table relation maps — the declarative input to `createRelationManager`.                                                                                                     |
+| `ResolvedRelation`         | type      | `ResolvedBelongs \| ResolvedMany \| ResolvedOne \| ResolvedThrough \| ResolvedMorph` | Represents a relation resolved at define-time into a flat, ready-to-load form.                                                                                                        |
+| `ResolvedBelongs`          | interface | `{ relationship, name, model, column }`                                              | Represents a `belongs` relation resolved at define-time — the foreign key sits on the owning table.                                                                                   |
+| `ResolvedMany`             | interface | `{ relationship, name, model, key }`                                                 | Represents a `many` relation resolved at define-time — the foreign key sits on the related table.                                                                                     |
+| `ResolvedOne`              | interface | `{ relationship, name, model, key }`                                                 | Represents a `one` relation resolved at define-time — `ResolvedMany`'s foreign key, one row.                                                                                          |
+| `ResolvedThrough`          | interface | `{ relationship, name, model, through, source, target }`                             | Represents a `through` relation resolved at define-time — a junction table links the two sides.                                                                                       |
+| `ResolvedMorph`            | interface | `{ relationship, name, model, key, tag, label }`                                     | Represents a `morph` relation resolved at define-time — a polymorphic foreign key and its discriminator.                                                                              |
+| `RelationErrorCode`        | type      | `'INVALID' \| 'UNKNOWN_RELATION' \| 'NOT_THROUGH'`                                   | Names a machine-readable `RelationError` code.                                                                                                                                        |
+| `Include`                  | interface | `{ [relation] }`                                                                     | Selects which relations to populate when loading — and, recursively, their own.                                                                                                       |
+| `Loaded`                   | type      | `T & Readonly<LoadedMap>`                                                            | Represents a row with its loaded relation properties attached.                                                                                                                        |
+| `LoadedMap`                | type      | `Record<string, Row \| readonly Row[] \| undefined>`                                 | Holds the relation properties attached to a `Loaded` row — each relation name mapped to its loaded related row(s), or `undefined` when a `belongs` / `one` relation misses.           |
+| `RelationContext`          | interface | `{ resolved, primary }`                                                              | Holds a related model's resolved relations and primary-key column, for nested loading.                                                                                                |
+| `FindOptions`              | interface | `OperationOptions plus { limit?, offset?, sort?, direction? }`                       | Configures pagination, ordering, and cancellation for `find`.                                                                                                                         |
+| `ModelEventMap`            | type      | `{ load, link, unlink }`                                                             | Declares the push observation surface of a `ModelInterface` — the eager-load + junction-management moments a fire-and-forget observer (logging, metrics, a sync layer) subscribes to. |
+| `ModelInterface`           | interface | `{ emitter, name, table, relations } plus load, find, link, unlink, links`           | Represents a typed table paired with relation-aware loading and junction management.                                                                                                  |
+| `RelationManagerOptions`   | interface | `{ database, relations?, model? }`                                                   | Configures `createRelationManager`.                                                                                                                                                   |
+| `RelationManagerInterface` | interface | `{ count } plus model, names, has`                                                   | Vends a typed `ModelInterface` per table.                                                                                                                                             |
+
+## Methods
+
+The public methods of each behavioral interface — one table per type, keyed by its backticked name, every call-signature member listed (its `readonly` data members, for example `emitter` / `name` / `table` / `relations` / `count`, stay in the Surface rows earlier — `Model`'s `emitter` is the typed push observation surface, see [Observing](#observing)). `Model` and `RelationManager` each implement their interface exactly, so this doubles as the per-instance method surface (`.claude/rules/documentation.md` § Parity).
+
+#### `ModelInterface`
+
+`load` / `find` batch-load (one query for a direct relation, two for `through`, regardless of result size); `link` / `unlink` / `links` manage a `through` relation's junction rows. Every method accepts the database package's optional `OperationOptions` abort signal; `find` carries the same signal in `FindOptions`.
+
+| Method   | Returns                           | Summary                                                                                                             |
+| -------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `load`   | `Promise<Loaded<T> \| undefined>` | Loads one record by key with the chosen relations populated, or a positional array of records for an array of keys. |
+| `find`   | `Promise<readonly Loaded<T>[]>`   | Finds many records, paged and sorted through `FindOptions`, with the chosen relations populated.                    |
+| `link`   | `Promise<void>`                   | Inserts a missing junction row for a `through` relation.                                                            |
+| `unlink` | `Promise<void>`                   | Removes every matching junction row for a `through` relation inside one transaction.                                |
+| `links`  | `Promise<readonly Key[]>`         | Lists the related keys reachable through a `through` relation.                                                      |
+
+#### `RelationManagerInterface`
+
+`model(name)` vends the typed model for a declared table; `names()` lists the table names that carry resolved relations, and `has(name)` reports whether a given table does.
+
+| Method  | Returns                       | Summary                                                     |
+| ------- | ----------------------------- | ----------------------------------------------------------- |
+| `model` | `ModelInterface<RowOf<T[K]>>` | Returns the typed model for a declared table.               |
+| `names` | `readonly string[]`           | Lists the names of every model carrying resolved relations. |
+| `has`   | `boolean`                     | Reports whether a model carries resolved relations.         |
+
+## Contract
+
+These invariants hold across `src/core` ↔ `relation.md`:
+
+1. **Doc ↔ source bijection.** Every `function` / `class` / `interface` / `type` row in the `## Surface` tables is a real export of the relations source tree, and every export appears as a Surface row — exhaustive, both directions (`.claude/rules/documentation.md` § Parity).
+2. **Layered on the typed database and validated at construction.** A manager is built over a `DatabaseInterface`; `model(name)` is checked against the database's declared tables and returns a model whose `table` is that table's typed `TableInterface` (a declared table with no relation entry yields a relation-less model — still fully usable for typed CRUD). Related tables are fetched by runtime name at the broad `Row` type. Every resolved target table and `through` junction must appear in `database.export()`; an undeclared table throws `RelationError('INVALID', ...)` when the manager is created, before any operation runs.
+3. **Batch loading — no N+1.** A direct included relation uses one query over the distinct foreign keys for the entire record set; a `through` relation uses two queries, one for the junction rows and one for the target rows. Related rows are grouped in memory and attached, so either query count is independent of how many parents were loaded. Nested includes recurse through the registry, and each nested level is batched again under the same rule.
+4. **Resolution is define-time.** Each raw `Relation` is resolved once at construction into a flat `ResolvedRelation` — a union discriminated on `relationship` whose every arm declares its own columns required, so a loader reads them after one narrow and never against an absent member; nothing is inferred during loading. The builders set an explicit `relationship` (so `many` and `one`, otherwise identical as `{ key }`, are unambiguous); a hand-written descriptor with no `relationship` infers one from the fields present (`through` → `through`, `tag` → `morph`, `column` → `belongs`, else `key` → `one`), and a malformed one throws `INVALID` at define-time.
+5. **Total, loose `Loaded`.** `Loaded<T>` is the base row (the table's row type) intersected with the broad relation bag `Readonly<LoadedMap>` (`Row | readonly Row[] | undefined` per relation); a missed `belongs` / `one` is `undefined`, a missed `many` / `through` / `morph` is `[]`. Through-only operations (`link` / `unlink` / `links`) throw `NOT_THROUGH` on any other relationship and `UNKNOWN_RELATION` for a relation the model never declared. `link` is idempotent for sequential calls: an existing `(key, target)` pair causes no write and no event. Concurrent `link` calls for the same pair may each insert. `unlink` removes all matching rows inside one database transaction, so a fault rolls the whole removal back. On a driver without a native transaction the database's floor snapshots the whole store, so a rollback restores every table to the scope's start.
+6. **Observation is a pure side-channel.** A `Model` owns a typed `emitter` (`ModelEventMap` — `load(name, count)` / `link(key, relation)` / `unlink(key, relation)`); `RelationManager` is event-free by design (a stateless registry has no observable lifecycle). Every event is emitted directly (the `.claude/rules/patterns.md` § Stateful emitters convention: the emitter isolates a listener throw, routing it to its own `error` handler — the `error` option, surfaced as `(error, event)`, never a domain event — itself re-entrancy-guarded) strictly after the load resolves and after the junction operation completes. `load` fires once per relation (carrying the count of rows attached across the record set — no N+1 in the events), so a buggy observer can corrupt neither the batched eager-load nor a junction write (proven by the emit-safety tests). An idempotent no-op `link` emits nothing.
+7. **Cooperative cancellation.** Every model operation accepts the database package's abort option. Query reads pass the signal to `records`. The keyed `get` read takes no options in the database package, so `load` checks the signal before it and again before each relation in the population walk; a batched `get` already in flight runs to completion. Writes pass it to their database mutation or transaction. An aborted signal surfaces unchanged as the database package's `ABORTED` error.
+8. **Doc ↔ source method bijection.** Every behavioral interface's `## Methods` table lists exactly its public methods (call-signature members) — exhaustive, both directions — and each implementing class (`Model` / `RelationManager`) exposes the same public methods, no more (`.claude/rules/documentation.md` § Parity). A renamed / added / removed method breaks the gate until the table is reconciled.
+
+Typing each loaded relation property to its exact target row (Prisma-style) is a deliberate, documented deferral — like the database guide's deferred pieces. The `Model` is **observable** — it owns a typed `emitter` (`ModelEventMap`) carrying its eager-load + junction moments (see [Observing](#observing)); `RelationManager` stays event-free by design (a stateless registry that merely vends models has no observable lifecycle of its own). Still out of scope: write-cascades; they are additive and leave the documented surface unchanged.
+
+## Patterns
+
+### Defining relations
+
+Declare every relationship with its builder, then load a record with the chosen relations
+attached:
+
+```ts
+import {
+	createRelationManager,
+	belongsTo,
+	hasMany,
+	hasOne,
+	hasThrough,
+	hasMorph,
+} from '@orkestrel/relation'
+
+const manager = createRelationManager({
+	database: db,
+	relations: {
+		accounts: {
+			classification: belongsTo('classificationId', 'classifications'), // foreign key on accounts
+			contacts: hasMany('accountId'), // foreign key on contacts → accounts
+			profile: hasOne('accountId', 'profiles'), // single, foreign key on profiles
+			representatives: hasThrough('accountReps', 'accountId', 'repId', 'representatives'), // through a junction
+			notes: hasMorph('entityId', 'entityType', 'account', 'notes'), // polymorphic
+		},
+		contacts: { account: belongsTo('accountId', 'accounts') },
+	},
+})
+
+const acme = await manager.model('accounts').load('acc1', { contacts: true, classification: true })
+```
+
+The shorthands cover the common relationships — a bare string is a `belongsTo` column, and a one-element array is a `hasMany` key (both unambiguous, so they need no `relationship`):
+
+```ts
+relations: { accounts: { classification: 'classificationId', contacts: ['accountId'] } }
+```
+
+Reach for the builders for everything else: they set an explicit `relationship`, which is what disambiguates `many` from `one` (a raw `{ key }` descriptor infers `one`).
+
+The relationships, and where each foreign key lives:
+
+| Relationship | Builder      | Foreign key location | Returns               |
+| ------------ | ------------ | -------------------- | --------------------- |
+| `belongs`    | `belongsTo`  | the owning table     | single or `undefined` |
+| `many`       | `hasMany`    | the related table    | array                 |
+| `one`        | `hasOne`     | the related table    | single or `undefined` |
+| `through`    | `hasThrough` | the junction table   | array                 |
+| `morph`      | `hasMorph`   | the related table    | array                 |
+
+### Resolving relations directly
+
+`resolveRelation` / `resolveRelationMap` / `isRelationDescriptor` are what `createRelationManager` calls internally to turn a raw `RelationMap` into one `ResolvedRelation` per entry at construction — reach for them directly when validating a relation map before wiring a manager, or when testing a descriptor's inferred `relationship`:
+
+```ts
+import { isRelationDescriptor, resolveRelation, resolveRelationMap } from '@orkestrel/relation'
+
+const resolved = resolveRelation('classification', belongsTo('classificationId', 'classifications'))
+resolved.relationship // 'belongs'
+
+const map = resolveRelationMap({ contacts: hasMany('accountId') })
+map.get('contacts')?.relationship // 'many'
+
+isRelationDescriptor(belongsTo('classificationId')) // true — the object form
+```
+
+`ResolvedRelation` is a union discriminated on `relationship`, so narrow on that member
+before reading an arm's own columns. Each arm declares its columns required —
+`ResolvedThrough` carries `through` / `source` / `target`, `ResolvedMorph` carries `key` /
+`tag` / `label` — because `resolveRelation` refuses a descriptor missing one:
+
+```ts
+import { resolveRelation, hasThrough } from '@orkestrel/relation'
+
+const resolved = resolveRelation('reps', hasThrough('accountReps', 'accountId', 'repId'))
+if (resolved.relationship === 'through') {
+	resolved.through // 'accountReps' — a required string on this arm
+	resolved.source // 'accountId'
+	resolved.target // 'repId'
+}
+```
+
+Catch a malformed relation with `isRelationError`, branching on its machine-readable `code`:
+
+```ts
+import { isRelationError } from '@orkestrel/relation'
+
+try {
+	resolveRelation('bad', {})
+} catch (error) {
+	if (isRelationError(error)) error.code // 'INVALID'
+}
+```
+
+### The registry surface
+
+Beyond `model(name)`, a `RelationManager` exposes `names()` (every table name with resolved relations) and `has(name)` (whether a given table has any):
+
+```ts
+manager.names() // for example ['accounts', 'contacts']
+manager.has('accounts') // true
+manager.has('unrelated_table') // false
+```
+
+### Loading
+
+`load` mirrors the table's keyed-read overload: a single key returns one record (or `undefined`), an array of keys returns a positional array of records (each slot `undefined` for a missing key) — and either way the relation queries are batched in one pass. `find` runs the table's query (sorted / paged) and attaches relations to the page.
+
+```ts
+const accounts = manager.model('accounts')
+
+// One record, with the chosen relations attached:
+const acme = await accounts.load('acc1', { contacts: true, classification: true })
+
+// Many records — sorted and paged — with relations attached to the page:
+const page = await accounts.find(
+	{ representatives: true },
+	{ sort: 'name', direction: 'ascending', limit: 10 },
+)
+
+// Nested includes — load a relation's own relations (recurses through the registry):
+const deep = await accounts.load('acc1', { contacts: { account: true } })
+
+// Batch by key array: an array in, an array out — and this direct-relation fetch is
+// still one query across all parents (no N+1), not one per key.
+const [a, b] = await accounts.load(['acc1', 'acc2'], { contacts: true })
+```
+
+### Typed table access
+
+For writes and plain queries, drop through to `model.table` — the full typed `TableInterface` for that model's table. This is the typed half; eager loading is the looser convenience layered on it.
+
+```ts
+const accounts = manager.model('accounts')
+await accounts.table.set({ id: 'acc4', name: 'New Corp', classificationId: 'cls1' }) // fully typed
+await accounts.table
+	.query()
+	.condition({ column: 'name', operator: 'starts', values: ['A'], connector: 'and' })
+	.collect()
+```
+
+### Through management
+
+A `through` relation's junction rows are managed by key — no need to model the junction table yourself or hand-write join rows. `link` / `unlink` / `links` resolve the relation's junction table + its source/target columns from the define-time `ResolvedRelation`, and throw `NOT_THROUGH` if pointed at a non-`through` relation.
+
+```ts
+await accounts.link('acc1', 'representatives', 'rep3') // insert a junction row (accountId=acc1, repId=rep3)
+await accounts.link('acc1', 'representatives', 'rep3') // already linked, sequential call: no write and no event
+await accounts.unlink('acc1', 'representatives', 'rep1') // remove all matches atomically
+const repIds = await accounts.links('acc1', 'representatives') // the related keys reachable through the junction
+```
+
+Pass an abort signal through the same operation option used by the database package:
+
+```ts
+const controller = new AbortController()
+const pending = accounts.load(
+	'acc1',
+	{ contacts: true, classification: true },
+	{
+		signal: controller.signal,
+	},
+)
+controller.abort('stop loading')
+await pending
+```
+
+### Observing
+
+Each `Model` exposes a typed `emitter` carrying its eager-load + junction moments for fire-and-forget observers — logging, metrics, a sync layer. Subscribe through `model.emitter.on(...)`. **Emitting is observation-only**: every event fires strictly after the load resolves and after the junction operation completes, so a listener can never change what a load does (and a throwing one can't corrupt it). The `RelationManager` is event-free by design — a stateless registry that merely vends models has no observable lifecycle of its own; observe the per-model handle instead.
+
+```ts
+const accounts = manager.model('accounts')
+accounts.emitter.on('load', (name, count) => metrics.record(`relation.${name}`, count))
+accounts.emitter.on('link', (key, relation) => sync.push(key, relation))
+```
+
+`model(name)` returns a fresh handle on every call, and each handle owns its own emitter. Retain the handle you subscribed to; a later `manager.model('accounts')` is a different observer surface. To observe every handle a manager vends, pass the listeners once as the manager's `model` option:
+
+```ts
+const manager = createRelationManager({
+	database: db,
+	relations: { accounts: { contacts: hasMany('accountId') } },
+	model: {
+		on: { load: (name, count) => metrics.record(`relation.${name}`, count) },
+		error: (error, event) => metrics.fault(event, error),
+	},
+})
+```
+
+The event vocabulary:
+
+| Entity  | Event map       | Events                                                                |
+| ------- | --------------- | --------------------------------------------------------------------- |
+| `Model` | `ModelEventMap` | `load(name, count)` · `link(key, relation)` · `unlink(key, relation)` |
+
+`load` fires once per relation an eager-load resolves (`load` / `find`, including each nested relation) — carrying the relation name and the count of related rows attached across the whole record set (the batched load has no N+1, and neither do its events — it is not one event per record); `link` / `unlink` fire after a junction row is inserted / removed, carrying the owning key + the relation name. Reads of the base rows are the table's concern (observe `model.table.emitter` for per-row `write` / `remove`).
+
+**Listener isolation.** A listener throw never escapes into the load: the emitter isolates it and routes it to its own `error` handler (the `error` option, surfaced as `(error, event)`), never to a domain event — so a buggy observer is isolated yet not silently lost. The `error` handler runs in its own try/catch, so even a throwing handler can't recurse or escape; with no handler, the throw is swallowed silently. Because every emit sits after its transition and is isolated, a buggy observer **cannot corrupt the batched eager-load or a junction write** — the load still resolves correctly and the junction row is still written — proven by the emit-safety tests. A `Model` is reached through the `RelationManager`, which threads the `model.error` option into every handle it vends, so set that option to receive a `Model` listener throw; leave it unset and the throw is swallowed silently.
+
+### Practices
+
+- **Define all related models up front** — nested includes resolve through the registry, so a relation you want to nest-load must have its own entry.
+- **Use the builders** — `belongsTo` / `hasMany` / `hasOne` / `hasThrough` / `hasMorph` set an explicit `relationship`; the string / array shorthands are unambiguous, but a raw `{ key }` resolves to `one`.
+- **Reach for typed CRUD through `model.table`** — the table is fully typed; relation loading is the looser layer on top.
+- **Request only the relations you use** — each direct relation adds one query; each `through` relation adds two.
+- **Use `link` / `unlink` / `links` for `through` joins** rather than writing junction rows by hand.
+- **Observe, don't drive** — subscribe to `model.emitter` (`load` / `link` / `unlink`) for metrics or a sync layer (see [Observing](#observing)); emitting is a pure side-channel, so a listener never changes what a load does (and a throwing one can't corrupt it).
+
+## Tests
+
+- [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` bijection (value + type exports), the `ModelInterface` / `RelationManagerInterface` ↔ `Model` / `RelationManager` method bijections, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Defining relations` fence against the `@example` block of that title (pinned so the titled pair cannot be retired silently), and the README pitch against this guide's tagline. It also runs the guide's value-claiming fences and asserts the values their comments claim.
+- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — `resolveRelation` (shorthands, builders, inference, errors, a wrong-typed descriptor member), `resolveRelationMap`, `readColumn`, `countAttached`, `indexRows`, `groupRows`.
+- [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) — `isRelationDescriptor` over the object form, the builders' output, the string / array shorthands, a member holding the wrong type, and a `relationship` outside the union.
+- [`tests/src/core/RelationManager.test.ts`](../tests/src/core/RelationManager.test.ts) — the manager-level surface: the registry (`count` / `names` / `has`), the typed `model(name)` accessor, and construction-time `INVALID` errors for undeclared relation and junction tables.
+- [`tests/src/core/Model.test.ts`](../tests/src/core/Model.test.ts) — `Model` behavior: `load` / `find` populating each relationship (batched, no N+1), nested `includes`, the loaded relation accessors, idempotent `link`, atomic `unlink`, cooperative cancellation, `links`, and the `emitter` (`ModelEventMap`): `load(name, count)` fires once per relation (the attached count, including nested relations — not one per record), `link` / `unlink` carry the owning key + relation, `on?` wiring through the manager's `model` option, and emit safety (a throwing `load` / `link` observer can't corrupt the load or junction write — the emitter isolates it and routes it to the `model.error` handler when the manager carries one).
+- [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — `createRelationManager` wires up a working, typed manager end to end.
+
+## See also
+
+- [`database.md`](database.md) — the database, tables, and query layer relations build on.
+- [`AGENTS.md`](../AGENTS.md) — the coding contract and its rule map.
+- [`README.md`](README.md) — the guides index.