@orkestrel/scaffold 0.0.126 → 0.0.128
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.
- package/dist/bin/main.js +5 -2
- package/dist/bin/main.js.map +1 -1
- package/dist/host/AGENTS.md +1 -1
- package/dist/host/agents/orchestration.md +3 -3
- package/dist/host/claude/AGENTS.md +2 -2
- package/dist/host/claude/agents/orkestrel.md +14 -14
- package/dist/host/claude/agents/planner.md +2 -2
- package/dist/host/claude/rules/workspace.md +7 -6
- package/dist/host/codex/agents/planner.toml +2 -2
- package/dist/host/guides/capture.md +123 -123
- package/dist/host/guides/database.md +18 -7
- package/dist/host/guides/relation.md +71 -31
- package/dist/host/guides/scaffold.md +67 -49
- package/dist/host/guides/toolbox.md +8 -1
- package/dist/host/manifest.json +14 -14
- package/dist/host/tests/config.test.ts +95 -44
- package/dist/src/core/index.cjs +128 -75
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +27 -6
- package/dist/src/core/index.d.ts +27 -6
- package/dist/src/core/index.js +128 -76
- package/dist/src/core/index.js.map +1 -1
- package/package.json +2 -2
|
@@ -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
|
|
303
|
-
| `DatabaseInterface` | interface | `{ emitter, name, status,
|
|
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
|
-
|
|
435
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
41
|
-
| ----------------------- | -------- |
|
|
42
|
-
| `createRelationManager` | function | `<T extends TableMap>(options: RelationManagerOptions<T>) => RelationManagerInterface<T>`
|
|
43
|
-
| `RelationManager` | class | `new <T extends TableMap = TableMap>(options: RelationManagerOptions<T>) => RelationManagerInterface<T>`
|
|
44
|
-
| `Model` | class | `new <T = Row>(name: string, table: TableInterface<T>, resolved: ReadonlyMap<string, ResolvedRelation>, relations: RelationMap, lookup: (model: string) => RelationContext \| undefined,
|
|
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
|
|
59
|
-
|
|
|
60
|
-
| `resolveRelation`
|
|
61
|
-
| `resolveRelationMap`
|
|
62
|
-
| `isRelationDescriptor`
|
|
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
|
|
67
|
-
| --------------- | -------- |
|
|
68
|
-
| `readColumn` | function | `(record: unknown, column: string) => unknown`
|
|
69
|
-
| `countAttached` | function | `(values: ReadonlyArray<Row \| readonly Row[] \| undefined>) => number`
|
|
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 | `{
|
|
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
|
|
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
|
|
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>`
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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`,
|
|
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
|
|
86
|
-
| ----------------------- | --------- |
|
|
87
|
-
| `AppDefinition` | interface | `{ configs, project, entry? }`
|
|
88
|
-
| `ArtifactBase` | interface | `{ path, group, ownership, environment? }`
|
|
89
|
-
| `ArtifactTemplateSet` | interface | `{ source, tests, docs, guides, orchestration }`
|
|
90
|
-
| `Audit` | interface | `{ findings, questions }`
|
|
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 }`
|
|
93
|
-
| `CompileFailure` | interface | `{ code, message }`
|
|
94
|
-
| `CompileRecord` | interface | `{ stage, input, output, failure? }`
|
|
95
|
-
| `CompilerInterface` | interface | `{ emitter, compile(), audit(), destroy() }`
|
|
96
|
-
| `CompilerOptions` | interface | `{ on?, error? }`
|
|
97
|
-
| `ConfigTemplateSet` | interface | `{ root, factories, tsconfigs, vites, browsers, commands }`
|
|
98
|
-
| `ContentArtifact` | interface | `{ origin, content, hex?, source? }`
|
|
99
|
-
| `Dependency` | interface | `{ name, range, optional? }`
|
|
100
|
-
| `DependencyPinSet` | interface | `{ runtime, development }`
|
|
101
|
-
| `FrameworkDefinition` | interface | `{ plugin, checker, suffixes, refused, dependencies }`
|
|
102
|
-
| `HostArtifact` | interface | `{ origin, ownership, source?, pointer?, hex?, content? }`
|
|
103
|
-
| `HydratedArtifact` | interface | `{ origin, ownership, source?, hex, content? }`
|
|
104
|
-
| `ManifestDependencySet` | interface | `{ runtime, development, peer }`
|
|
105
|
-
| `ManifestEdit` | interface | `{ start, end, text }`
|
|
106
|
-
| `ManifestRegionSet` | interface | `{ pins, scripts, additions?, overrides? }`
|
|
107
|
-
| `ManifestScript` | interface | `{ name, command, accepted }`
|
|
108
|
-
| `ManifestToken` | interface | `{ text, index, depth, value }`
|
|
109
|
-
| `Override` | interface | `{ path, content }`
|
|
110
|
-
| `Plan` | interface | `{ blueprint, groups, artifacts, hash? }`
|
|
111
|
-
| `PlanSummary` | interface | `{ name, src, app, groups, host, template, computed }`
|
|
112
|
-
| `Question` | interface | `{ field, message, blocking, candidates? }`
|
|
113
|
-
| `CompileResult` | interface | `{ plan?, questions, stages }`
|
|
114
|
-
| `SrcDefinition` | interface | `{ configs, project, path, formats }`
|
|
115
|
-
| `StylesExtension` | interface | `{ surface, name }`
|
|
116
|
-
| `ToolchainHold` | interface | `{ framework, range, reason }`
|
|
117
|
-
| `ViteMachinery` | interface | `{ browser, frameworks, output, showcase }`
|
|
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
|
|
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
|
|
1372
|
-
|
|
1373
|
-
|
|
1374
|
-
|
|
1375
|
-
|
|
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
|
|
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
|
-
|
|
1395
|
-
from `node_modules/@orkestrel/capture`.
|
|
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
|
|
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.
|
|
2208
|
-
|
|
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.
|
|
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
|
|