@orkestrel/scaffold 0.0.126 → 0.0.127

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -299,8 +299,8 @@ Pure helpers behind the query engine's pattern matching.
299
299
  | `SQLiteDriverOptions` | interface | `{ path, readonly?, timeout?, references?, pragmas? }` | Configures `createSQLiteDriver`. The `@orkestrel/database/server` entry point exports this type. |
300
300
  | `QueryPlan` | interface | `{ index?, range? }` | Represents a pushdown plan — an optional index and optional `IDBKeyRange` used to narrow a read. An omitted `index` selects the primary store; an omitted `range` performs a full scan. The plan is always a superset of the matching rows; the core engine refines it to the exact result. An empty plan (`{}`) is a primary-store full scan. The `@orkestrel/database/browser` entry point exports this type. |
301
301
  | `TableDefinition` | interface | `{ primary, columns, schema }` | Represents one table's portable definition, produced by `export` — the unit of schema / migration exchange across environments. |
302
- | `DatabaseStorageInterface` | interface | `{ table() }` | Represents a database view valid only inside one `DatabaseInterface.transaction` scope. |
303
- | `DatabaseInterface` | interface | `{ emitter, name, status, table(), import(), export(), open(), close(), transaction(), migrate() }` | Represents a database — the ergonomic entry point that owns the driver and its tables. |
302
+ | `DatabaseStorageInterface` | interface | `{ table() }` | Represents a table-only database view. |
303
+ | `DatabaseInterface` | interface | `{ emitter, name, status, import(), export(), open(), close(), transaction(), migrate() }` | Represents a database — the ergonomic entry point that owns the driver and its tables. |
304
304
  | `TableInterface` | interface | `{ emitter, name, primary, contract, get(), resolve(), has(), keys(), records(), count(), aggregate(), scan(), set(), add(), update(), remove(), clear(), query(), cursor() }` | Exposes typed keyed CRUD plus fluent query and cursor access. |
305
305
  | `QueryInterface` | interface | `{ condition(), order(), filter(), limit(), offset(), collect(), find(), count(), stream(), aggregate() }` | Builds a read through a fluent chain. |
306
306
  | `CursorInterface` | interface | `{ value, index, done, next(), update(), remove(), close() }` | Walks a table's rows forward for bulk in-place mutation. |
@@ -416,6 +416,9 @@ on the snapshot floor (see [Native transactions](#native-transactions)).
416
416
 
417
417
  #### `DatabaseInterface`
418
418
 
419
+ `DatabaseInterface` extends `DatabaseStorageInterface` and inherits its `table` method.
420
+ The database is accepted wherever table-only storage is accepted.
421
+
419
422
  `transaction` and `migrate` each take an optional `OperationOptions`, whose
420
423
  `signal` is checked once, at entry.
421
424
 
@@ -431,12 +434,14 @@ on the snapshot floor (see [Native transactions](#native-transactions)).
431
434
 
432
435
  #### `DatabaseStorageInterface`
433
436
 
434
- The scoped view and every table taken from it throw `CONFLICT` for work started
435
- after the transaction settles.
437
+ A root database presents this table-only view for its lifetime. A transaction
438
+ scope presents a view that cannot open, close, import, migrate, or nest a
439
+ transaction. The scoped view and every table taken from it throw `CONFLICT`
440
+ for work started after the transaction settles.
436
441
 
437
- | Method | Returns | Summary |
438
- | ------- | ----------------------------- | ------------------------------------------------------ |
439
- | `table` | `TableInterface<RowOf<T[K]>>` | Returns a table bound to the active transaction scope. |
442
+ | Method | Returns | Summary |
443
+ | ------- | ----------------------------- | ---------------------------------------------- |
444
+ | `table` | `TableInterface<RowOf<T[K]>>` | Returns the typed handle for a declared table. |
440
445
 
441
446
  #### `AdmissionInterface`
442
447
 
@@ -1481,6 +1486,12 @@ publish cursor state or restore `value` after close.
1481
1486
 
1482
1487
  ### Transactions
1483
1488
 
1489
+ `DatabaseInterface` extends `DatabaseStorageInterface`, so a root database and
1490
+ a transaction callback's storage both satisfy the table-only contract. The root
1491
+ presents that view for its lifetime. The transaction supplies a scoped view
1492
+ that cannot open, close, import, migrate, or nest a transaction; the view and
1493
+ every table captured from it throw `CONFLICT` after the scope settles.
1494
+
1484
1495
  Runs a scoped callback across two tables that commits on success and rolls every table back when the scope throws:
1485
1496
 
1486
1497
  ```ts
@@ -9,13 +9,13 @@ The relationships (`belongs` / `many` / `one` / `through` / `morph`) cover the f
9
9
 
10
10
  ## Surface
11
11
 
12
- Create a manager over a database and its relation map, then reach a typed model and load with relations attached:
12
+ Create a manager over storage and its relation map, then reach a typed model and load with relations attached. In root examples, `TABLES` names the table map passed to `createDatabase`, and `db` is its returned `DatabaseInterface<typeof TABLES>`:
13
13
 
14
14
  ```ts
15
15
  import { createRelationManager, belongsTo, hasMany, hasThrough } from '@orkestrel/relation'
16
16
 
17
- const manager = createRelationManager({
18
- database: db, // a typed DatabaseInterface from createDatabase(...)
17
+ const manager = createRelationManager<typeof TABLES>({
18
+ storage: db, // the DatabaseInterface<typeof TABLES> returned by createDatabase(...)
19
19
  relations: {
20
20
  accounts: {
21
21
  classification: belongsTo('classificationId', 'classifications'), // foreign key on accounts → one classification
@@ -37,11 +37,11 @@ acme?.contacts // the relation property — broad (Row | readonly Row[] | undefi
37
37
 
38
38
  ### Factory & manager
39
39
 
40
- | Name | Kind | Signature | Summary |
41
- | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
42
- | `createRelationManager` | function | `<T extends TableMap>(options: RelationManagerOptions<T>) => RelationManagerInterface<T>` | Creates a `RelationManagerInterface` over a database and its relation map. |
43
- | `RelationManager` | class | `new <T extends TableMap = TableMap>(options: RelationManagerOptions<T>) => RelationManagerInterface<T>` | Resolves a `RelationsShape` once at construction and vends a typed `ModelInterface` per declared table. |
44
- | `Model` | class | `new <T = Row>(name: string, table: TableInterface<T>, resolved: ReadonlyMap<string, ResolvedRelation>, relations: RelationMap, lookup: (model: string) => RelationContext \| undefined, database: DatabaseInterface, on?: EmitterHooks<ModelEventMap>, error?: EmitterErrorHandler) => ModelInterface<T>` | Pairs a typed table with relation-aware `load` / `find` and junction management. |
40
+ | Name | Kind | Signature | Summary |
41
+ | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
42
+ | `createRelationManager` | function | `<T extends TableMap>(options: RelationManagerOptions<T>) => RelationManagerInterface<T>` | Creates a `RelationManagerInterface` over storage and its relation map. |
43
+ | `RelationManager` | class | `new <T extends TableMap = TableMap>(options: RelationManagerOptions<T>) => RelationManagerInterface<T>` | Resolves a `RelationsShape` once at construction and vends a typed `ModelInterface` per declared table. |
44
+ | `Model` | class | `new <T = Row>(name: string, table: TableInterface<T>, resolved: ReadonlyMap<string, ResolvedRelation>, relations: RelationMap, lookup: (model: string) => RelationContext \| undefined, storage: DatabaseStorageInterface, on?: EmitterHooks<ModelEventMap>, error?: EmitterErrorHandler) => ModelInterface<T>` | Pairs a typed table with relation-aware `load` / `find` and junction management. |
45
45
 
46
46
  ### Builders
47
47
 
@@ -55,20 +55,21 @@ acme?.contacts // the relation property — broad (Row | readonly Row[] | undefi
55
55
 
56
56
  ### Resolution
57
57
 
58
- | Name | Kind | Signature | Summary |
59
- | ---------------------- | -------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
60
- | `resolveRelation` | function | `(name: string, value: Relation) => ResolvedRelation` | Resolves one raw `Relation` value into a flat `ResolvedRelation`. |
61
- | `resolveRelationMap` | function | `(relations: RelationMap) => ReadonlyMap<string, ResolvedRelation>` | Resolves every entry of a `RelationMap` into a name → `ResolvedRelation` map. |
62
- | `isRelationDescriptor` | function | `(value: unknown) => value is RelationDescriptor` | Narrows a value to a `RelationDescriptor` (the object form of a relation). |
58
+ | Name | Kind | Signature | Summary |
59
+ | ----------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
60
+ | `resolveRelation` | function | `(name: string, value: Relation) => ResolvedRelation` | Resolves one raw `Relation` value into a flat `ResolvedRelation`. |
61
+ | `resolveRelationMap` | function | `(relations: RelationMap) => ReadonlyMap<string, ResolvedRelation>` | Resolves every entry of a `RelationMap` into a name → `ResolvedRelation` map. |
62
+ | `isRelationDescriptor` | function | `(value: unknown) => value is RelationDescriptor` | Narrows a value to a `RelationDescriptor` (the object form of a relation). |
63
+ | `validateRelationTable` | function | `(storage: DatabaseStorageInterface, model: string, relation: string, table: string, junction?: boolean) => void` | Validates a relation table through its bound storage, translating only an undeclared table. |
63
64
 
64
65
  ### Row helpers
65
66
 
66
- | Name | Kind | Signature | Summary |
67
- | --------------- | -------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
68
- | `readColumn` | function | `(record: unknown, column: string) => unknown` | Reads one column off any record, whatever its declared type. |
69
- | `countAttached` | function | `(values: ReadonlyArray<Row \| readonly Row[] \| undefined>) => number` | Counts the related rows one relation attached across a record set. |
70
- | `indexRows` | function | `(rows: readonly Row[], column: string) => ReadonlyMap<string, Row>` | Indexes rows by the string form of one column, for keyed lookups. |
71
- | `groupRows` | function | `(rows: readonly Row[], column: string) => ReadonlyMap<string, readonly Row[]>` | Groups rows by the string form of one column, for one-to-many lookups. |
67
+ | Name | Kind | Signature | Summary |
68
+ | --------------- | -------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
69
+ | `readColumn` | function | `(record: unknown, column: string) => unknown` | Reads one column off any record, whatever its declared type. |
70
+ | `countAttached` | function | `(values: ReadonlyArray<Row \| readonly Row[] \| undefined>) => number` | Counts the related rows one relation attached across a record set. |
71
+ | `indexRows` | function | `(rows: readonly Row[], column: string, values?: readonly Row[]) => ReadonlyMap<string, Row>` | Indexes rows by the string form of one column, for keyed lookups. |
72
+ | `groupRows` | function | `(rows: readonly Row[], column: string, values?: readonly Row[]) => ReadonlyMap<string, readonly Row[]>` | Groups rows by the string form of one column, for one-to-many lookups. |
72
73
 
73
74
  ### Errors
74
75
 
@@ -104,7 +105,7 @@ transparent proxies, unbranded look-alikes, and plain branded objects.
104
105
  | `FindOptions` | interface | `{ limit?, offset?, sort?, direction? }` | Configures pagination, ordering, and cancellation for `find`. |
105
106
  | `ModelEventMap` | type | `{ readonly load: readonly [name: string, count: number]; readonly link: readonly [key: Key, relation: string]; readonly unlink: readonly [key: Key, relation: string]; }` | 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. |
106
107
  | `ModelInterface` | interface | `{ emitter, name, table, relations, load(), find(), link(), unlink(), links() }` | Represents a typed table paired with relation-aware loading and junction management. |
107
- | `RelationManagerOptions` | interface | `{ database, relations?, model? }` | Configures `createRelationManager`. |
108
+ | `RelationManagerOptions` | interface | `{ storage, relations?, model? }` | Configures `createRelationManager`. |
108
109
  | `RelationManagerInterface` | interface | `{ count, model(), names(), has() }` | Vends a typed `ModelInterface` per table. |
109
110
 
110
111
  ## Methods
@@ -120,7 +121,7 @@ The public methods of each behavioral interface — one table per type, keyed by
120
121
  | `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. |
121
122
  | `find` | `Promise<readonly Loaded<T>[]>` | Finds many records, paged and sorted through `FindOptions`, with the chosen relations populated. |
122
123
  | `link` | `Promise<void>` | Inserts a missing junction row for a `through` relation. |
123
- | `unlink` | `Promise<void>` | Removes every matching junction row for a `through` relation inside one transaction. |
124
+ | `unlink` | `Promise<void>` | Removes every matching junction row for a `through` relation through the bound storage. |
124
125
  | `links` | `Promise<readonly Key[]>` | Lists the related keys reachable through a `through` relation. |
125
126
 
126
127
  #### `RelationManagerInterface`
@@ -138,16 +139,18 @@ The public methods of each behavioral interface — one table per type, keyed by
138
139
  These invariants hold across `src/core` ↔ `relation.md`:
139
140
 
140
141
  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).
141
- 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.
142
+ 2. **Layered on typed storage and validated at construction.** A manager binds to `DatabaseStorageInterface<T> & DatabaseStorageInterface`: the `DatabaseInterface<T>` returned by `createDatabase`, or transaction storage. At a typed root, pass the table map as the type argument; a transaction scope infers it. A `Database<T>` class expression is outside this option contract. `model(name)` preserves the declared table row type. Related tables are resolved by runtime name at the broad `Row` type. Construction resolves every target and junction through `storage.table(name)`. An undeclared target or junction throws `INVALID` with `{ model, relation, table }`; other database errors propagate unchanged, including `CLOSED` when construction resolves a relation on a closed root and `CONFLICT` for settled transaction storage.
142
143
  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.
143
144
  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.
144
- 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.
145
- 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.
146
- 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.
145
+ 5. **Total, loose `Loaded`.** `Loaded<T>` intersects the base row with `Readonly<LoadedMap>` (`Row | readonly Row[] | undefined` per relation). A missed `belongs` / `one` is `undefined`; a missed `many` / `through` / `morph` is `[]`. Through-only operations throw `NOT_THROUGH` for another relationship and `UNKNOWN_RELATION` for an undeclared relation. Sequential `link` calls are idempotent; an existing pair writes and emits nothing. Concurrent calls may each insert. `unlink` removes every matching junction row through its bound storage and shares the fate of that scope. Enclose the call in `database.transaction()` for all-or-nothing removal. Outside a transaction, a fault propagates unchanged and leaves earlier removals committed. A failed removal emits no `unlink` event.
146
+ 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. `link` and `unlink` report completion within the bound scope, before any outer commit; an event can therefore precede an outer rollback.
147
+ 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 bound storage mutation. An aborted signal surfaces unchanged as the database package's `ABORTED` error.
147
148
  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.
148
149
 
149
150
  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.
150
151
 
152
+ Loaded relation properties replace same-named columns in returned rows. Grouping and indexing read the raw columns, so attachments survive that shadowing. Read an original column through `model.table` when a relation replaces it.
153
+
151
154
  ## Patterns
152
155
 
153
156
  ### Defining relations
@@ -165,8 +168,8 @@ import {
165
168
  hasMorph,
166
169
  } from '@orkestrel/relation'
167
170
 
168
- const manager = createRelationManager({
169
- database: db,
171
+ const manager = createRelationManager<typeof TABLES>({
172
+ storage: db,
170
173
  relations: {
171
174
  accounts: {
172
175
  classification: belongsTo('classificationId', 'classifications'), // foreign key on accounts
@@ -244,6 +247,14 @@ try {
244
247
  }
245
248
  ```
246
249
 
250
+ Validate a target through a bound storage view; an undeclared target throws `INVALID` with its model, relation, and table context:
251
+
252
+ ```ts
253
+ import { validateRelationTable } from '@orkestrel/relation'
254
+
255
+ validateRelationTable(storage, 'accounts', 'contacts', 'contacts')
256
+ ```
257
+
247
258
  ### The registry surface
248
259
 
249
260
  Beyond `model(name)`, a `RelationManager` exposes `names()` (every table name with resolved relations) and `has(name)` (whether a given table has any):
@@ -298,7 +309,7 @@ A `through` relation's junction rows are managed by key — no need to model the
298
309
  ```ts
299
310
  await accounts.link('acc1', 'representatives', 'rep3') // insert a junction row (accountId=acc1, repId=rep3)
300
311
  await accounts.link('acc1', 'representatives', 'rep3') // already linked, sequential call: no write and no event
301
- await accounts.unlink('acc1', 'representatives', 'rep1') // remove all matches atomically
312
+ await accounts.unlink('acc1', 'representatives', 'rep1') // remove every match through the bound storage
302
313
  const repIds = await accounts.links('acc1', 'representatives') // the related keys reachable through the junction
303
314
  ```
304
315
 
@@ -317,6 +328,35 @@ controller.abort('stop loading')
317
328
  await pending
318
329
  ```
319
330
 
331
+ ### Transactions
332
+
333
+ Construct the manager inside the transaction callback so its tables and relation operations share that scope. Retain the manager only within the callback; models and tables reject work after settlement with `CONFLICT`. This example reads the contact written in its scope and asserts its count:
334
+
335
+ ```ts
336
+ import { createDatabase, createMemoryDriver } from '@orkestrel/database'
337
+ import { isArray, stringShape } from '@orkestrel/contract'
338
+ import { createRelationManager, hasMany } from '@orkestrel/relation'
339
+
340
+ const TABLES = {
341
+ accounts: { id: stringShape(), name: stringShape() },
342
+ contacts: { id: stringShape(), accountId: stringShape() },
343
+ }
344
+ const database = createDatabase({ driver: createMemoryDriver(), tables: TABLES })
345
+ const count = await database.transaction(async (storage) => {
346
+ const manager = createRelationManager({
347
+ storage,
348
+ relations: { accounts: { contacts: hasMany('accountId') } },
349
+ })
350
+ await manager.model('accounts').table.set({ id: 'a1', name: 'Acme' })
351
+ await storage.table('contacts').set({ id: 'c1', accountId: 'a1' })
352
+ const account = await manager.model('accounts').load('a1', { contacts: true })
353
+ return isArray(account?.contacts) ? account.contacts.length : 0
354
+ })
355
+ if (count !== 1) throw new Error('Expected one related contact')
356
+ ```
357
+
358
+ An uncaught scope failure rolls its writes back. Model `link` and `unlink` events fire after their junction operation completes in scope and before the outer commit. Publish effects that require committed data after `database.transaction()` resolves.
359
+
320
360
  ### Observing
321
361
 
322
362
  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.
@@ -330,8 +370,8 @@ accounts.emitter.on('link', (key, relation) => sync.push(key, relation))
330
370
  `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:
331
371
 
332
372
  ```ts
333
- const manager = createRelationManager({
334
- database: db,
373
+ const manager = createRelationManager<typeof TABLES>({
374
+ storage: db,
335
375
  relations: { accounts: { contacts: hasMany('accountId') } },
336
376
  model: {
337
377
  on: { load: (name, count) => metrics.record(`relation.${name}`, count) },
@@ -365,7 +405,7 @@ The event vocabulary:
365
405
  - [`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`.
366
406
  - [`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.
367
407
  - [`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.
368
- - [`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).
408
+ - [`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`, scope-bound `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).
369
409
  - [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — `createRelationManager` wires up a working, typed manager end to end.
370
410
 
371
411
  ## See also
@@ -82,39 +82,39 @@ Exported from `@orkestrel/scaffold`, and reachable from
82
82
 
83
83
  #### Interfaces
84
84
 
85
- | Name | Kind | Signature | Summary |
86
- | ----------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
87
- | `AppDefinition` | interface | `{ configs, project, entry? }` | Describes the configuration and runtime-entry settings one private `app` environment contributes. |
88
- | `ArtifactBase` | interface | `{ path, group, ownership, environment? }` | Describes the fields every planned file carries. |
89
- | `ArtifactTemplateSet` | interface | `{ source, tests, docs, guides, orchestration }` | Represents the source, test, document, guide, and service template text. |
90
- | `Audit` | interface | `{ findings, questions }` | Represents the whole comparison of a plan against a target's current content. |
91
- | `Blueprint` | interface | `{ name, description?, keywords, src, app, extensions, styles, themes, dependencies, peers, extras, version, engines, overrides, bin, setup, guides, integration, conformance, tree, service, vendors, studies, global, showcase, journey, skills }` | Represents the closed, JSON-serializable workspace specification. |
92
- | `BrowserExtension` | interface | `{ surface, name, axes }` | Represents a browser framework and its physically occupied axes. |
93
- | `CompileFailure` | interface | `{ code, message }` | Represents the coded reason one compile stage failed. |
94
- | `CompileRecord` | interface | `{ stage, input, output, failure? }` | Holds the input and output snapshot of one compile stage. |
95
- | `CompilerInterface` | interface | `{ emitter, compile(), audit(), destroy() }` | Describes the compilation contract: pure, synchronous, and host-independent. |
96
- | `CompilerOptions` | interface | `{ on?, error? }` | Represents the options for the compiler. |
97
- | `ConfigTemplateSet` | interface | `{ root, factories, tsconfigs, vites, browsers, commands }` | Represents the configuration template text, grouped by the artifact each template builds. |
98
- | `ContentArtifact` | interface | `{ origin, content, hex?, source? }` | Represents a text file produced by the template or computed compilation path. |
99
- | `Dependency` | interface | `{ name, range, optional? }` | Represents one runtime `@orkestrel/*` dependency of a generated workspace. |
100
- | `DependencyPinSet` | interface | `{ runtime, development }` | Describes the runtime and development sections a range-writing operation may change. |
101
- | `FrameworkDefinition` | interface | `{ plugin, checker, suffixes, refused, dependencies }` | Describes the tooling and package boundaries a browser framework contributes. |
102
- | `HostArtifact` | interface | `{ origin, ownership, source?, pointer?, hex?, content? }` | Represents a file byte-copied from the vendored data root, planned before its bytes are read. |
103
- | `HydratedArtifact` | interface | `{ origin, ownership, source?, hex, content? }` | Represents a vendored file whose exact bytes have been read, so its content can be compared. |
104
- | `ManifestDependencySet` | interface | `{ runtime, development, peer }` | Describes the runtime, development, and peer sections read from an existing package manifest. |
105
- | `ManifestEdit` | interface | `{ start, end, text }` | Represents one in-place replacement of manifest text. |
106
- | `ManifestRegionSet` | interface | `{ pins, scripts, additions?, overrides? }` | Describes the manifest regions a writing operation may change. |
107
- | `ManifestScript` | interface | `{ name, command, accepted }` | Represents one manifest script a region-writing operation may replace. |
108
- | `ManifestToken` | interface | `{ text, index, depth, value }` | Represents one string or object brace found in manifest text. |
109
- | `Override` | interface | `{ path, content }` | Represents one artifact override. |
110
- | `Plan` | interface | `{ blueprint, groups, artifacts, hash? }` | Holds the compiled, ordered artifact list and the selection it covers. |
111
- | `PlanSummary` | interface | `{ name, src, app, groups, host, template, computed }` | Represents the tally of one plan by artifact origin. |
112
- | `Question` | interface | `{ field, message, blocking, candidates? }` | Represents one validation issue raised against a blueprint or a plan. |
113
- | `CompileResult` | interface | `{ plan?, questions, stages }` | Represents the replayable outcome of one compile. |
114
- | `SrcDefinition` | interface | `{ configs, project, path, formats }` | Describes the build and export settings one published `src` environment contributes. |
115
- | `StylesExtension` | interface | `{ surface, name }` | Represents a named sheet face under `src/<name>`. |
116
- | `ToolchainHold` | interface | `{ framework, range, reason }` | Represents one foreign tool range required by a browser framework. |
117
- | `ViteMachinery` | interface | `{ browser, frameworks, output, showcase }` | Names which host-specific pipelines a generated root Vite configuration carries. |
85
+ | Name | Kind | Signature | Summary |
86
+ | ----------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
87
+ | `AppDefinition` | interface | `{ configs, project, entry? }` | Describes the configuration and runtime-entry settings one private `app` environment contributes. |
88
+ | `ArtifactBase` | interface | `{ path, group, ownership, environment? }` | Describes the fields every planned file carries. |
89
+ | `ArtifactTemplateSet` | interface | `{ source, tests, docs, guides, orchestration }` | Represents the source, test, document, guide, and service template text. |
90
+ | `Audit` | interface | `{ findings, questions }` | Represents the whole comparison of a plan against a target's current content. |
91
+ | `Blueprint` | interface | `{ name, description?, keywords, src, app, extensions, styles, themes, dependencies, peers, extras, version, engines, overrides, bin, setup, guides, integration, conformance, tree, service, vendors, studies, global, showcase, journey, base, skills }` | Represents the closed, JSON-serializable workspace specification. |
92
+ | `BrowserExtension` | interface | `{ surface, name, axes }` | Represents a browser framework and its physically occupied axes. |
93
+ | `CompileFailure` | interface | `{ code, message }` | Represents the coded reason one compile stage failed. |
94
+ | `CompileRecord` | interface | `{ stage, input, output, failure? }` | Holds the input and output snapshot of one compile stage. |
95
+ | `CompilerInterface` | interface | `{ emitter, compile(), audit(), destroy() }` | Describes the compilation contract: pure, synchronous, and host-independent. |
96
+ | `CompilerOptions` | interface | `{ on?, error? }` | Represents the options for the compiler. |
97
+ | `ConfigTemplateSet` | interface | `{ root, factories, tsconfigs, vites, browsers, commands }` | Represents the configuration template text, grouped by the artifact each template builds. |
98
+ | `ContentArtifact` | interface | `{ origin, content, hex?, source? }` | Represents a text file produced by the template or computed compilation path. |
99
+ | `Dependency` | interface | `{ name, range, optional? }` | Represents one runtime `@orkestrel/*` dependency of a generated workspace. |
100
+ | `DependencyPinSet` | interface | `{ runtime, development }` | Describes the runtime and development sections a range-writing operation may change. |
101
+ | `FrameworkDefinition` | interface | `{ plugin, checker, suffixes, refused, dependencies }` | Describes the tooling and package boundaries a browser framework contributes. |
102
+ | `HostArtifact` | interface | `{ origin, ownership, source?, pointer?, hex?, content? }` | Represents a file byte-copied from the vendored data root, planned before its bytes are read. |
103
+ | `HydratedArtifact` | interface | `{ origin, ownership, source?, hex, content? }` | Represents a vendored file whose exact bytes have been read, so its content can be compared. |
104
+ | `ManifestDependencySet` | interface | `{ runtime, development, peer }` | Describes the runtime, development, and peer sections read from an existing package manifest. |
105
+ | `ManifestEdit` | interface | `{ start, end, text }` | Represents one in-place replacement of manifest text. |
106
+ | `ManifestRegionSet` | interface | `{ pins, scripts, additions?, overrides? }` | Describes the manifest regions a writing operation may change. |
107
+ | `ManifestScript` | interface | `{ name, command, accepted }` | Represents one manifest script a region-writing operation may replace. |
108
+ | `ManifestToken` | interface | `{ text, index, depth, value }` | Represents one string or object brace found in manifest text. |
109
+ | `Override` | interface | `{ path, content }` | Represents one artifact override. |
110
+ | `Plan` | interface | `{ blueprint, groups, artifacts, hash? }` | Holds the compiled, ordered artifact list and the selection it covers. |
111
+ | `PlanSummary` | interface | `{ name, src, app, groups, host, template, computed }` | Represents the tally of one plan by artifact origin. |
112
+ | `Question` | interface | `{ field, message, blocking, candidates? }` | Represents one validation issue raised against a blueprint or a plan. |
113
+ | `CompileResult` | interface | `{ plan?, questions, stages }` | Represents the replayable outcome of one compile. |
114
+ | `SrcDefinition` | interface | `{ configs, project, path, formats }` | Describes the build and export settings one published `src` environment contributes. |
115
+ | `StylesExtension` | interface | `{ surface, name }` | Represents a named sheet face under `src/<name>`. |
116
+ | `ToolchainHold` | interface | `{ framework, range, reason }` | Represents one foreign tool range required by a browser framework. |
117
+ | `ViteMachinery` | interface | `{ browser, frameworks, output, showcase }` | Names which host-specific pipelines a generated root Vite configuration carries. |
118
118
 
119
119
  | Name | Kind | Signature | Summary |
120
120
  | ------------------- | --------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- |
@@ -146,6 +146,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
146
146
  | `BROWSE_DEV_DEPENDENCIES` | const | `Readonly<Record<string, string>>` | Names the development dependency a browser or styles surface adds. |
147
147
  | `BROWSE_UPSTREAM` | const | `readonly string[]` | Lists the packages `@orkestrel/browser` depends on at runtime, directly or transitively, frozen. |
148
148
  | `CAPTURE_DEV_DEPENDENCIES` | const | `Readonly<Record<string, string>>` | Names the development dependency a browser application's journey axis adds. |
149
+ | `BROWSER_ENTRIES` | const | `readonly string[]` | Lists the Orkestrel packages that publish a `/browser` entry, frozen. |
149
150
  | `CAPTURE_UPSTREAM` | const | `readonly string[]` | Lists the capture package and its fleet runtime dependency closure, frozen. |
150
151
  | `CANON_PATHS` | const | `readonly string[]` | Lists the instruction-canon paths staged for reading rather than for a target, frozen. |
151
152
  | `CATALOG_AGENT_PATH` | const | `".claude/agents/orkestrel.md"` | Names the agent file whose marker-bounded package table the catalog verb alone owns. |
@@ -1016,9 +1017,9 @@ section. A name carrying no colon has no family, and a family the section declar
1016
1017
  nothing to follow, so each of those is appended after the last declared script instead. `catalog`
1017
1018
  writes no script region; it names the ranges alone.
1018
1019
 
1019
- The browser application's journey axis adds `journey` and `capture`. Their generated commands,
1020
+ The base browser application's journey axis adds `journey` and `capture`, and each app-side browser face adds `journey:<name>` and `capture:<name>`. Their generated commands,
1020
1021
  `capture journey` and `capture frames`, have no predecessor forms in the accepted set. Missing
1021
- commands append; generated values remain writable; `replaceManifestScripts` preserves customized
1022
+ commands append, each face's `journey:<name>` and `capture:<name>` among them; generated values remain writable; `replaceManifestScripts` preserves customized
1022
1023
  values while repairing siblings independently, so a selected or wrapped `journey` command survives
1023
1024
  repair. Neither scoped command replaces `test:journey` in a private workspace's gate chain.
1024
1025
  Publishing workspaces keep application and journey suites outside release gates and chains.
@@ -1266,7 +1267,7 @@ because the shape is chosen once and read afterwards: `new` refuses the advisory
1266
1267
  caller creating a workspace holds the same refusal, and the Compile section states it.
1267
1268
 
1268
1269
  `bin`, `setup`, `guides`, `integration`, `conformance`, `tree`, `service`, `vendors`, `studies`,
1269
- `global`, `styles`, `themes`, `showcase`, `journey`, and `skills` are structural facts, and `extensions` lists the
1270
+ `global`, `styles`, `themes`, `showcase`, `journey`, `base`, and `skills` are structural facts, and `extensions` lists the
1270
1271
  extension faces. Reading verbs set each fact and list each extension only when the workspace
1271
1272
  physically ships the directory or exact-case file that defines it, never because of the workspace's
1272
1273
  name and never because a sibling fact is set.
@@ -1296,6 +1297,9 @@ can import and render the extension's components. A browser application without
1296
1297
  extension keeps the non-Vue pipeline, and a `src/browser` selection adds no Vue plugin or
1297
1298
  dependency.
1298
1299
 
1300
+ Every browser project also pre-bundles each declared `@orkestrel` package's `/browser` entry when
1301
+ that package publishes one. Node projects keep no `optimizeDeps` setting.
1302
+
1299
1303
  A structural fact is read when a verb runs, not when the file appears. Writing
1300
1304
  `tests/integration.test.ts` into a workspace sets the fact, but the root configuration on disk was
1301
1305
  generated before that file existed and still registers no `integration` project, so `test:config`
@@ -1368,11 +1372,19 @@ no artifact, configuration, script, or dependency, and the gate reports a non-bl
1368
1372
  that field so the caller who set it learns it emitted nothing.
1369
1373
 
1370
1374
  The library's `journey` flag defaults to `false`; `new` sets it when its `app` selection includes
1371
- `browser`. Reading verbs infer it from the wrapper's presence. The flag requires a browser application. Without that
1372
- application, it emits no journey configuration or script and raises a non-blocking `journey`
1373
- question. With that application, the content-owned root configuration defines the `appJourney`
1374
- factory and excludes `tests/app/browser/integration.test.ts` from the ordinary `app:browser`
1375
- project. Surfaces and extensions states the journey of each further application mode.
1375
+ `browser`. Reading verbs infer it from the wrapper's presence. The `base` fact selects the exact-case
1376
+ `app/browser/main.ts` entry. `new` sets `base` when the browser environment is selected, while a
1377
+ target without that entry, including one with only `app/browser/Main.ts`, has `base: false`. A
1378
+ face-only workspace retains the browser environment and its `appBrowser` project without planning
1379
+ the base entry, scripts, application record member, or arrival journey. When the browser environment
1380
+ has no base entry or app-side browser face, the plan raises one non-blocking question on `base`.
1381
+
1382
+ With a journey and a declared browser application, the content-owned root configuration defines
1383
+ the `appJourney` factory. It selects the suite for the exact Vite mode and refuses a mode the generated `applications`
1384
+ record omits. The base record member follows `base`, which follows the exact-case `app/browser/main.ts`
1385
+ entry, and a face's member follows its extension, which the reader sets from the `app/<name>` directory. The ordinary `app:browser` project
1386
+ excludes the base arrival suite only when `base` is true. Surfaces and extensions states the journey
1387
+ of each further application mode.
1376
1388
 
1377
1389
  Edit the variant list in `configs/app/vite.journey.config.ts`. This wrapper is birth-owned:
1378
1390
  scaffold creates it when absent and preserves your edits during `repair`. It imports
@@ -1380,7 +1392,9 @@ scaffold creates it when absent and preserves your edits during `repair`. It imp
1380
1392
  at 1280 × 800 and `compact` at 390 × 844 without a theme. Rename and extend those variants for
1381
1393
  your application; apply themes through the application's interface in your tests.
1382
1394
 
1383
- The wrapper registers `journey:<name>` for each variant through the root factory. Each project
1395
+ The wrapper registers `journey:<name>` for each variant through the root factory. Each app-side
1396
+ browser face also receives `journey:<name>` as `capture journey --mode <name>` and `capture:<name>`
1397
+ as `capture frames --mode <name>`. Each project
1384
1398
  collects the integration suite of the application the Vite mode selects, sets the variant
1385
1399
  viewport, and provides `variant`
1386
1400
  as its name, `variants` as the declared list, and `capture` as a boolean. The root configuration
@@ -1391,8 +1405,9 @@ workspace, application and journey suites run on demand outside release gates an
1391
1405
  With the journey axis off, the ordinary
1392
1406
  browser project retains its integration suite.
1393
1407
 
1394
- The same axis adds `journey: capture journey` and `capture: capture frames`, using the executable
1395
- from `node_modules/@orkestrel/capture`. Run `npm run journey -- <selector>` for behavior with
1408
+ With `base`, the same axis adds `journey: capture journey` and `capture: capture frames`, using the
1409
+ executable from `node_modules/@orkestrel/capture`. Each app-side browser face adds
1410
+ `journey:<name>` and `capture:<name>`, the same commands with `--mode <name>`. Run `npm run journey -- <selector>` for behavior with
1396
1411
  capture off and `npm run capture -- <selector>` for frames with `CAPTURE=1`. A selector is `all`
1397
1412
  or a colon-delimited owner path declared by the wrapper. Narrow with `--variant <name>` and
1398
1413
  `--case <exact-full-name>`; frames also accept `--state <name>`. Replace the selector with
@@ -1495,6 +1510,7 @@ no selection is stored anywhere. Each fact and each extension has its own marker
1495
1510
  | `themes` | The exact-case `THEMES_BARREL_PATH` and `THEMES_ENTRY_PATH` files under `src/styles/themes` |
1496
1511
  | `showcase` | The exact-case `configs/app/vite.showcase.config.ts` wrapper, or a `showcase` directory |
1497
1512
  | `journey` | The exact-case `configs/app/vite.journey.config.ts` wrapper |
1513
+ | `base` | The exact-case `app/browser/main.ts` entry |
1498
1514
  | `vue` | A `src/vue` or `app/vue` directory, and `axes` lists each one present |
1499
1515
  | A styles extension | A direct `src/<name>` directory holding the exact-case `index.scss` and `sheet.ts` files |
1500
1516
 
@@ -1609,7 +1625,7 @@ leaves every sibling page in place. It stamps the final inlined page through `st
1609
1625
  the page `showcase/<application>.html`. The manifest declares `showcase` and `build:showcase` for
1610
1626
  the base mode and `showcase:<framework>` and `build:showcase:<framework>` for each extension mode,
1611
1627
  and a publishing workspace rebuilds every page from `prepublishOnly` after `npm run build` and
1612
- before `npm test`. The vendored `.prettierignore` lists `showcase/`, so formatting never rewrites a
1628
+ before `npm test`, the base page only when `base` is set. The vendored `.prettierignore` lists `showcase/`, so formatting never rewrites a
1613
1629
  committed page.
1614
1630
 
1615
1631
  `stampPage` writes one `<meta name="build-id" content="DIGEST" />` line before the line that closes
@@ -1628,7 +1644,8 @@ include and exclude replacement, viewport, commands, and plugin rules. The manif
1628
1644
  application and `test:journey:<framework>`, the same command with `--mode <framework>`, for each
1629
1645
  app-side browser extension. A private workspace runs them after `npm run test:app` in `test`.
1630
1646
  A publishing workspace keeps those scripts available on demand and invokes neither application
1631
- nor journey suites from its release gates and chains.
1647
+ nor journey suites from its release gates and chains. With `base` unset, the plan omits `test:journey`
1648
+ and its `npm run test:journey` chain entry, and the base arrival journey below.
1632
1649
 
1633
1650
  Scaffold seeds one birth-owned arrival journey per application at
1634
1651
  `tests/app/<application>/integration.test.ts`. The base journey imports `app/browser/main.ts`, and
@@ -2204,8 +2221,9 @@ row entering or leaving the manifest moves a test rather than passing unnoticed.
2204
2221
  of `STYLES_DEV_DEPENDENCIES`, is a seed as well: it carries the `^1.105.1` range the
2205
2222
  `@orkestrel/veneer` checkout declared on 2026-09-30, and that test names it in the seeded set.
2206
2223
 
2207
- `CAPTURE_DEV_DEPENDENCIES` seeds `@orkestrel/capture` at `^0.0.1` only when the blueprint's
2208
- `journey` axis is enabled and its `app` includes `browser`. `CAPTURE_UPSTREAM` withholds that
2224
+ `CAPTURE_DEV_DEPENDENCIES` seeds `@orkestrel/capture` at `^0.0.5`, the first release whose commands
2225
+ take `--mode`, only when the blueprint plans a journey: the `journey` axis with the base entry or
2226
+ an app-side browser face. `CAPTURE_UPSTREAM` withholds that
2209
2227
  seed from capture itself and its fleet runtime closure: `@orkestrel/contract`,
2210
2228
  `@orkestrel/emitter`, `@orkestrel/process`, and `@orkestrel/timeout`. The frozen, sorted list
2211
2229
  follows dependencies and peers from capture's installed manifests and moves with the capture
@@ -2244,7 +2262,7 @@ The dependency tables select these floors:
2244
2262
  | Vitest | `^5.1.0` | Every workspace |
2245
2263
  | `@vitest/browser-playwright` | `^5.1.0` | Browser tooling |
2246
2264
  | `oxlint` | `^1.93.0` | Every workspace |
2247
- | `oxfmt` | `^0.77.0` | Every workspace |
2265
+ | `oxfmt` | `^0.78.0` | Every workspace |
2248
2266
  | `@microsoft/api-extractor` | `^7.60.1` | Declaration builds; uses its bundled TypeScript 6.0.3 engine |
2249
2267
  | `playwright` | `^1.64.1` | Browser tooling |
2250
2268
  | Vite | `^8.3.7` | Every workspace |
@@ -847,12 +847,19 @@ restored?.id // 'audit'
847
847
 
848
848
  Register a live relation manager and load a row with a nested dot-path `include` list:
849
849
 
850
+ The tool opens no transaction. `unlink` removes every matching junction row through the manager's
851
+ bound storage, one row at a time. Outside a transaction, a failed removal leaves earlier removals
852
+ committed and the pair linked; `links` still lists the target. Repeat `unlink` to complete removal.
853
+ For all-or-nothing removal, build the manager with `createRelationManager({ storage, relations })`
854
+ inside the host's `database.transaction(async (storage) => ...)` callback and use its tool only
855
+ within that scope. Let the failure propagate out of the callback so the transaction rolls back.
856
+
850
857
  ```ts
851
858
  import { createRelationTool } from '@orkestrel/toolbox'
852
859
  import { createToolManager } from '@orkestrel/tool'
853
860
  import type { RelationManagerInterface } from '@orkestrel/relation'
854
861
 
855
- declare const manager: RelationManagerInterface // built with createRelationManager({ database, relations: { ... } })
862
+ declare const manager: RelationManagerInterface // built with createRelationManager({ storage: database, relations: { ... } })
856
863
 
857
864
  const tool = createRelationTool({ managers: { shop: manager } }) // omit "manager" in a call when only one is registered
858
865