@orkestrel/scaffold 0.0.118 → 0.0.120

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.
Files changed (55) hide show
  1. package/dist/bin/main.js +15 -15
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/platforms/windows.md +2 -1
  4. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
  5. package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
  7. package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
  8. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +2 -1
  9. package/dist/host/claude/agents/orkestrel.md +27 -26
  10. package/dist/host/claude/rules/names.md +3 -2
  11. package/dist/host/claude/rules/tests.md +4 -2
  12. package/dist/host/claude/rules/typescript.md +2 -3
  13. package/dist/host/claude/rules/workspace.md +2 -1
  14. package/dist/host/guides/abort.md +0 -4
  15. package/dist/host/guides/budget.md +1 -5
  16. package/dist/host/guides/codec.md +18 -3
  17. package/dist/host/guides/contract.md +23 -44
  18. package/dist/host/guides/csv.md +86 -93
  19. package/dist/host/guides/database.md +0 -4
  20. package/dist/host/guides/emitter.md +0 -2
  21. package/dist/host/guides/form.md +26 -47
  22. package/dist/host/guides/html.md +3 -7
  23. package/dist/host/guides/indexeddb.md +28 -32
  24. package/dist/host/guides/jsonrpc.md +187 -0
  25. package/dist/host/guides/markdown.md +132 -141
  26. package/dist/host/guides/msg.md +47 -63
  27. package/dist/host/guides/ndjson.md +0 -4
  28. package/dist/host/guides/pool.md +0 -4
  29. package/dist/host/guides/process.md +71 -79
  30. package/dist/host/guides/reason.md +30 -36
  31. package/dist/host/guides/router.md +11 -18
  32. package/dist/host/guides/scaffold.md +147 -137
  33. package/dist/host/guides/sqlite.md +0 -4
  34. package/dist/host/guides/sse.md +6 -10
  35. package/dist/host/guides/table.md +481 -493
  36. package/dist/host/guides/template.md +0 -4
  37. package/dist/host/guides/test.md +46 -66
  38. package/dist/host/guides/timeout.md +0 -6
  39. package/dist/host/guides/tool.md +2 -6
  40. package/dist/host/guides/websocket.md +0 -4
  41. package/dist/host/manifest.json +100 -428
  42. package/dist/host/tests/setupPolicy.ts +18 -6
  43. package/dist/src/core/index.cjs +171 -122
  44. package/dist/src/core/index.cjs.map +1 -1
  45. package/dist/src/core/index.d.cts +236 -213
  46. package/dist/src/core/index.d.ts +236 -213
  47. package/dist/src/core/index.js +159 -111
  48. package/dist/src/core/index.js.map +1 -1
  49. package/dist/src/server/index.cjs +62 -39
  50. package/dist/src/server/index.cjs.map +1 -1
  51. package/dist/src/server/index.d.cts +59 -54
  52. package/dist/src/server/index.d.ts +59 -54
  53. package/dist/src/server/index.js +63 -40
  54. package/dist/src/server/index.js.map +1 -1
  55. package/package.json +9 -9
@@ -13,7 +13,7 @@ That totality statement governs document parsing. `parseStartTag` is the separat
13
13
 
14
14
  ### Types
15
15
 
16
- The full node shape and handle contract, from [`types.ts`](../src/core/types.ts). `category` is the discriminant every node carries; absence is always `undefined`, never a sentinel. A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. A member's type never appears in a cell, because the declaration carries it and the row's name reaches it. A generic declaration carries its parameter binding beside its literal, so a `TNode` or a `T` in a cell is that declaration's own parameter. The node categories are worked through in § [The AST model](#the-ast-model), and the option interfaces in § [The sanitize floor](#the-sanitize-floor) and § [The distill pass](#the-distill-pass).
16
+ The full node shape and handle contract, from [`types.ts`](../src/core/types.ts). `category` is the discriminant every node carries; absence is always `undefined`, never a sentinel. A member's type never appears in a cell, because the declaration carries it and the row's name reaches it. A generic declaration carries its parameter binding beside its literal, so a `TNode` or a `T` in a cell is that declaration's own parameter. The node categories are worked through in § [The AST model](#the-ast-model), and the option interfaces in § [The sanitize floor](#the-sanitize-floor) and § [The distill pass](#the-distill-pass).
17
17
 
18
18
  | Name | Kind | Signature | Summary |
19
19
  | --------------------- | --------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -45,7 +45,7 @@ The full node shape and handle contract, from [`types.ts`](../src/core/types.ts)
45
45
 
46
46
  ### Constants
47
47
 
48
- The element vocabularies, allowlists, entity table, and depth bound every engine reads, from [`constants.ts`](../src/core/constants.ts). Every collection is a frozen array, or — for the keyed tables — a frozen record read through `Object.hasOwn`, so nothing a consumer can reach changes what an engine sees (§ [The sanitize floor](#the-sanitize-floor)). A `Shape` cell holds the constant's declared type. The depth bound's degrade behavior is § [Depth degrade semantics](#depth-degrade-semantics).
48
+ The element vocabularies, allowlists, entity table, and depth bound every engine reads, from [`constants.ts`](../src/core/constants.ts). Every collection is a frozen array, or — for the keyed tables — a frozen record read through `Object.hasOwn`, so nothing a consumer can reach changes what an engine sees (§ [The sanitize floor](#the-sanitize-floor)). The depth bound's degrade behavior is § [Depth degrade semantics](#depth-degrade-semantics).
49
49
 
50
50
  | Name | Kind | Signature | Summary |
51
51
  | ---------------------- | ----- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -73,8 +73,6 @@ The element vocabularies, allowlists, entity table, and depth bound every engine
73
73
 
74
74
  The from-unknown guards, from [`validators.ts`](../src/core/validators.ts). A guard validates an entire untrusted value from scratch — a deserialized AST, a value crossing a process boundary — and is total: a cycle, a hostile prototype, a revoked proxy, or 10,000 levels of nesting returns `false` rather than throwing. The name, element, and URL predicates the engines consult narrow nothing, so they are not guards: they sit with the other pure leaves in [`helpers.ts`](../src/core/helpers.ts) (§ [Helpers](#helpers)).
75
75
 
76
- In a guard table a `Shape` cell holds the type the guard narrows to.
77
-
78
76
  | Name | Kind | Signature | Summary |
79
77
  | ----------------- | -------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80
78
  | `isHTMLAttribute` | const | `Guard<HTMLAttribute>` | Determines whether an arbitrary value is a structurally valid HTML attribute - exactly a string name, optionally a string value, and nothing else. |
@@ -163,12 +161,10 @@ resolveDerivations([[node, node]]).get(node) // node
163
161
 
164
162
  Declarative `ContractShape` values (from `@orkestrel/contract`) in [`shapers.ts`](../src/core/shapers.ts) — `createContract` compiles one shape into a JSON Schema, a guard, a coercing parser, and a seeded generator that can never drift apart. A shape tree has no lazy or self-referential node, so only the leaves of this AST shape here; `ElementNode` and `HTMLDocument` recurse into `HTMLNode` and therefore stay hand-written, cycle- and depth-capped guards in `validators.ts`.
165
163
 
166
- A `Shape` cell holds the constant's declared type.
167
-
168
164
  | Name | Kind | Signature | Summary |
169
165
  | ---------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
170
166
  | `attributeShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; value: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; }, false>` | Describes the shape of an `HTMLAttribute` - an element attribute's name and, when the source wrote one, its value. `value` is optional: its absence is what distinguishes `<input disabled>` from `<input disabled="">`. |
171
- | `textShape` | const | `import("@orkestrel/contract").ObjectShape<{ category: import("@orkestrel/contract").LiteralShape<readonly ["text"]>; value: import("@orkestrel/contract").StringShape; }, false>` | Describes the shape of a `TextNode` - the decoded character-data leaf. |
167
+ | `textNodeShape` | const | `import("@orkestrel/contract").ObjectShape<{ category: import("@orkestrel/contract").LiteralShape<readonly ["text"]>; value: import("@orkestrel/contract").StringShape; }, false>` | Describes the shape of a `TextNode` - the decoded character-data leaf. |
172
168
  | `commentShape` | const | `import("@orkestrel/contract").ObjectShape<{ category: import("@orkestrel/contract").LiteralShape<readonly ["comment"]>; value: import("@orkestrel/contract").StringShape; }, false>` | Describes the shape of a `CommentNode` - the verbatim, never-decoded comment leaf a bogus comment also recovers to. |
173
169
  | `doctypeShape` | const | `import("@orkestrel/contract").ObjectShape<{ category: import("@orkestrel/contract").LiteralShape<readonly ["doctype"]>; name: import("@orkestrel/contract").StringShape; public: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; system: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; }, false>` | Describes the shape of a `DoctypeNode` - the declared root name plus the optional public and system identifiers of a legacy declaration. |
174
170
 
@@ -64,8 +64,8 @@ transparent proxies, unbranded look-alikes, and plain branded objects fail.
64
64
  | `supportsIndexedDB` | function | `() => boolean` | Checks whether IndexedDB is available in this environment. |
65
65
  | `promisifyRequest` | function | `<T>(request: IDBRequest<T>) => Promise<T>` | Resolves an `IDBRequest` to its result, rejecting with an `IndexedDBError`. |
66
66
  | `promisifyTransaction` | function | `(transaction: IDBTransaction) => Promise<void>` | Resolves after an `IDBTransaction` commits, rejecting if it errors or aborts. |
67
- | `readRecord` | function | `(source: IDBObjectStore \| IDBIndex, key: IDBValidKey) => Promise<Row \| undefined>` | Reads one record by key from a store or index, narrowing it to a `Row`. |
68
- | `readRecords` | function | `(source: IDBObjectStore \| IDBIndex, query?: IDBKeyRange \| IDBValidKey, count?: number) => Promise<readonly Row[]>` | Reads many records from a store or index over an optional key range, narrowing each to a `Row`. |
67
+ | `readRecord` | function | `(source: IDBObjectStore \| IDBIndex, key: IDBValidKey) => Promise<StoreRecord \| undefined>` | Reads one record by key from a store or index, narrowing it to a `StoreRecord`. |
68
+ | `readRecords` | function | `(source: IDBObjectStore \| IDBIndex, query?: IDBKeyRange \| IDBValidKey, count?: number) => Promise<readonly StoreRecord[]>` | Reads many records from a store or index over an optional key range, narrowing each to a `StoreRecord`. |
69
69
  | `hasKey` | function | `(source: IDBObjectStore \| IDBIndex, key: IDBValidKey) => Promise<boolean>` | Checks whether a key is present in a store or index. |
70
70
  | `createIndex` | function | `(store: IDBObjectStore, definition: IndexDefinition) => void` | Creates a secondary index on a store from its `IndexDefinition`. |
71
71
  | `wrapCall` | function | `<T>(action: () => T) => T` | Runs a synchronous native IndexedDB call, wrapping a thrown `DOMException` into a typed `IndexedDBError`. |
@@ -74,29 +74,25 @@ transparent proxies, unbranded look-alikes, and plain branded objects fail.
74
74
  | `rangeBelowKey` | function | `(value: IDBValidKey) => IDBKeyRange` | Builds a key range strictly below one key. |
75
75
  | `rangeToKey` | function | `(value: IDBValidKey) => IDBKeyRange` | Builds a key range ending at and including one key. |
76
76
  | `rangePrefix` | function | `(value: string) => IDBKeyRange` | Builds a key range containing every string with one prefix. |
77
- | `wrapError` | function | `(error: DOMException \| null) => IndexedDBError` | Maps a native IndexedDB `DOMException` to a typed `IndexedDBError`. |
77
+ | `wrapDOMException` | function | `(error: DOMException \| null) => IndexedDBError` | Maps a native IndexedDB `DOMException` to a typed `IndexedDBError`. |
78
78
  | `IndexedDBError` | class | `new (code: IndexedDBErrorCode, message: string, cause?: unknown, context?: Readonly<Record<string, unknown>>) => IndexedDBError` | Represents an error thrown by the IndexedDB wrapper, carrying a machine-readable `code` and an optional `context` beside the native cause. |
79
79
  | `isIndexedDBError` | function | `(value: unknown) => value is IndexedDBError` | Checks whether a value is an `IndexedDBError`. |
80
80
 
81
- `supportsIndexedDB` reads `globalThis.indexedDB`, and `hasKey` is a native `count` greater than 0. `createIndex` is the shared index-DDL leaf both the built-in schema pass and `context.indexes.create` run. `wrapError` is the request boundary every bridge maps a native `DOMException` through.
81
+ `supportsIndexedDB` reads `globalThis.indexedDB`, and `hasKey` is a native `count` greater than 0. `createIndex` is the shared index-DDL leaf both the built-in schema pass and `context.indexes.create` run. `wrapDOMException` is the request boundary every bridge maps a native `DOMException` through.
82
82
 
83
83
  ### Constants
84
84
 
85
- A `Shape` cell holds the constant's declared type.
86
-
87
85
  | Name | Kind | Signature | Summary |
88
86
  | ------------- | ----- | ---------------------------------------------- | --------------------------------------------------------------------- |
89
87
  | `ERROR_CODES` | const | `Readonly<Record<string, IndexedDBErrorCode>>` | Maps native `DOMException.name` → the wrapper's `IndexedDBErrorCode`. |
90
88
 
91
- `wrapError` reads this frozen map at the request boundary, falling back to `UNKNOWN` for a native name it does not carry.
89
+ `wrapDOMException` reads this frozen map at the request boundary, falling back to `UNKNOWN` for a native name it does not carry.
92
90
 
93
91
  ### Types
94
92
 
95
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. An extended interface's name comes before `plus`, with the members it adds after.
96
-
97
93
  | Name | Kind | Signature | Summary |
98
94
  | --------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
99
- | `Row` | type | `Record<string, unknown>` | Represents a record stored in, and read from, an object store. |
95
+ | `StoreRecord` | type | `Record<string, unknown>` | Represents a record stored in, and read from, an object store. |
100
96
  | `KeyPath` | type | `string \| readonly string[]` | Represents a key path — one field, or several for a compound key. |
101
97
  | `IndexDefinition` | interface | `{ name, path, unique?, multiple? }` | Represents the declaration of a secondary index — its name, key path, and uniqueness. |
102
98
  | `StoreDefinition` | interface | `{ path?, increment?, indexes? }` | Represents the declaration of one object store — its key path, key generation, and secondary indexes. |
@@ -115,13 +111,13 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
115
111
  | `IndexedDBTransactionInterface` | interface | `{ transaction, mode, stores, active, finished, error, store(), abort(), commit() }` | Represents the contract of an explicit transaction over one or more stores. |
116
112
  | `IndexedDBTransactionStoreInterface` | interface | `{ store }` | Represents the contract of an object store bound to an explicit transaction. |
117
113
 
118
- Values are this package's own `Row` (a record), narrowed from IndexedDB's structured clone with `isRecord` (from `@orkestrel/contract`) at the read boundary — an `as`-free bridge. Keys are the full native `IDBValidKey`, so the wrapper speaks IndexedDB's whole key space.
114
+ Values are this package's own `StoreRecord` (a record), narrowed from IndexedDB's structured clone with `isRecord` (from `@orkestrel/contract`) at the read boundary — an `as`-free bridge. Keys are the full native `IDBValidKey`, so the wrapper speaks IndexedDB's whole key space.
119
115
 
120
116
  A database connects **lazily**: the first store operation (or an explicit `connect`) opens it; you never wire up `onsuccess` yourself. `version` controls schema creation: pin an explicit number to create any missing stores on a bump, or **omit it** for auto-managed mode, where the database opens at its current version and bumps once on its own to create any declared store the stored schema lacks — so adding a store never needs a manual version bump.
121
117
 
122
118
  ## Methods
123
119
 
124
- The public methods of each behavioral interface — one table per type, keyed by its backticked name, every call-signature member listed. Each interface's `readonly` data members are named in the `Shape` column of the [Types](#types) table, earlier. Each class implements its interface exactly, so this doubles as the per-instance method surface (`AGENTS.md` § Documentation contract).
120
+ The public methods of each behavioral interface — one table per type, keyed by its backticked name, every call-signature member listed. Each interface's `readonly` data members are named in the `Signature` column of the [Types](#types) table, earlier. Each class implements its interface exactly, so this doubles as the per-instance method surface (`AGENTS.md` § Documentation contract).
125
121
 
126
122
  `IndexedDBUpgradeContext` carries only readonly data, so no Methods table follows for it. Its managers carry the upgrade's schema verbs: `context.stores` is the store manager, while `IndexedDBDatabaseInterface.stores` is the plain name list.
127
123
 
@@ -142,9 +138,9 @@ The keyed record surface `IndexedDBStoreInterface` and `IndexedDBTransactionStor
142
138
 
143
139
  | Method | Returns | Summary |
144
140
  | --------- | ------------------------------------------- | ---------------------------------------------------------------------- |
145
- | `get` | `Promise<Row \| undefined>` | Reads the record at a primary key, or `undefined` on a miss. |
146
- | `resolve` | `Promise<Row>` | Reads the record at a primary key, throwing `NOT_FOUND` on a miss. |
147
- | `records` | `Promise<readonly Row[]>` | Reads the stored records over an optional key range. |
141
+ | `get` | `Promise<StoreRecord \| undefined>` | Reads the record at a primary key, or `undefined` on a miss. |
142
+ | `resolve` | `Promise<StoreRecord>` | Reads the record at a primary key, throwing `NOT_FOUND` on a miss. |
143
+ | `records` | `Promise<readonly StoreRecord[]>` | Reads the stored records over an optional key range. |
148
144
  | `keys` | `Promise<readonly IDBValidKey[]>` | Lists the stored primary keys over an optional key range. |
149
145
  | `has` | `Promise<boolean>` | Checks whether a primary key is present. |
150
146
  | `count` | `Promise<number>` | Counts the stored records within an optional key range. |
@@ -160,9 +156,9 @@ The keyed record surface `IndexedDBStoreInterface` and `IndexedDBTransactionStor
160
156
 
161
157
  | Method | Returns | Summary |
162
158
  | --------- | ------------------------------------------- | ---------------------------------------------------------------------------- |
163
- | `get` | `Promise<Row \| undefined>` | Reads the record at a primary key, or `undefined` on a miss. |
164
- | `resolve` | `Promise<Row>` | Reads the record at a primary key, throwing `NOT_FOUND` on a miss. |
165
- | `records` | `Promise<readonly Row[]>` | Reads the stored records over an optional key range. |
159
+ | `get` | `Promise<StoreRecord \| undefined>` | Reads the record at a primary key, or `undefined` on a miss. |
160
+ | `resolve` | `Promise<StoreRecord>` | Reads the record at a primary key, throwing `NOT_FOUND` on a miss. |
161
+ | `records` | `Promise<readonly StoreRecord[]>` | Reads the stored records over an optional key range. |
166
162
  | `keys` | `Promise<readonly IDBValidKey[]>` | Lists the stored primary keys over an optional key range. |
167
163
  | `has` | `Promise<boolean>` | Checks whether a primary key is present. |
168
164
  | `count` | `Promise<number>` | Counts the stored records within an optional key range. |
@@ -177,9 +173,9 @@ The keyed record surface `IndexedDBStoreInterface` and `IndexedDBTransactionStor
177
173
 
178
174
  | Method | Returns | Summary |
179
175
  | --------- | ------------------------------------------- | -------------------------------------------------------------------------------- |
180
- | `get` | `Promise<Row \| undefined>` | Reads the first record for an index key, or `undefined` on a miss. |
181
- | `resolve` | `Promise<Row>` | Reads the first record for an index key, throwing `NOT_FOUND` on a miss. |
182
- | `records` | `Promise<readonly Row[]>` | Reads the matching records over an optional index-key range. |
176
+ | `get` | `Promise<StoreRecord \| undefined>` | Reads the first record for an index key, or `undefined` on a miss. |
177
+ | `resolve` | `Promise<StoreRecord>` | Reads the first record for an index key, throwing `NOT_FOUND` on a miss. |
178
+ | `records` | `Promise<readonly StoreRecord[]>` | Reads the matching records over an optional index-key range. |
183
179
  | `keys` | `Promise<readonly IDBValidKey[]>` | Lists the primary keys of the matching records over an optional index-key range. |
184
180
  | `primary` | `Promise<IDBValidKey \| undefined>` | Reads the primary key an index key maps to, or `undefined` on a miss. |
185
181
  | `has` | `Promise<boolean>` | Checks whether an index key is present. |
@@ -212,9 +208,9 @@ Each readonly data member is a snapshot of the position the cursor stopped on, b
212
208
 
213
209
  | Method | Returns | Summary |
214
210
  | --------- | ------------------------------------------- | ---------------------------------------------------------------------- |
215
- | `get` | `Promise<Row \| undefined>` | Reads the record at a primary key, or `undefined` on a miss. |
216
- | `resolve` | `Promise<Row>` | Reads the record at a primary key, throwing `NOT_FOUND` on a miss. |
217
- | `records` | `Promise<readonly Row[]>` | Reads the stored records over an optional key range. |
211
+ | `get` | `Promise<StoreRecord \| undefined>` | Reads the record at a primary key, or `undefined` on a miss. |
212
+ | `resolve` | `Promise<StoreRecord>` | Reads the record at a primary key, throwing `NOT_FOUND` on a miss. |
213
+ | `records` | `Promise<readonly StoreRecord[]>` | Reads the stored records over an optional key range. |
218
214
  | `keys` | `Promise<readonly IDBValidKey[]>` | Lists the stored primary keys over an optional key range. |
219
215
  | `has` | `Promise<boolean>` | Checks whether a primary key is present. |
220
216
  | `count` | `Promise<number>` | Counts the stored records within an optional key range. |
@@ -249,11 +245,11 @@ These invariants hold across `src/browser` ↔ `indexeddb.md`:
249
245
 
250
246
  1. **DOC ↔ SOURCE bijection.** Every row in the `## Surface` tables is a real export of the wrapper, and every export appears as a Surface row — exhaustive, both directions (`AGENTS.md` § Documentation contract).
251
247
  2. **Native, not a query engine.** The wrapper exposes only what raw IndexedDB offers natively — object stores, secondary indexes, key-range helpers, cursors, and multi-store transactions. It has **no** `where` / `filter` / `order` / aggregate builder; that stays out of scope entirely, deliberately, so the wrapper never grows into a second query DSL.
252
- 3. **`Row` values, `IDBValidKey` keys.** Reads return this package's own `Row` (narrowed with `isRecord`, never an unchecked cast); writes take a `Row`. Keys are the native `IDBValidKey`.
253
- 4. **In-line or out-of-line keys.** A store with a `path` keys rows by that field; a store with no `path` is out-of-line and takes an explicit key on `set` / `add` (`set(row, key)`).
248
+ 3. **`StoreRecord` values, `IDBValidKey` keys.** Reads return this package's own `StoreRecord` (narrowed with `isRecord`, never an unchecked cast); writes take a `StoreRecord`. Keys are the native `IDBValidKey`.
249
+ 4. **In-line or out-of-line keys.** A store with a `path` keys records by that field; a store with no `path` is out-of-line and takes an explicit key on `set` / `add` (`set(record, key)`).
254
250
  5. **Batch by the array overload, array-first.** `get` / `resolve` / `has` / `remove` / `set` / `add` take one value for one result or an array for an array of results (`.claude/rules/patterns.md` § Managers § Batch operations). The array overload is declared first because an array is itself both a record and a compound `IDBValidKey`; to act on a single compound key, pass `IDBKeyRange.only([…])` to `records` / `count`.
255
251
  6. **Each standalone call is its own transaction; `read` / `write` are atomic.** A store method opens and commits its own implicit transaction; `db.read` / `db.write` run a scope across stores that commits on resolve and rolls back on a throw. The completion listener is attached BEFORE the scope runs (not after it resolves), so a scope whose last step is a non-IDB `await` — letting the native transaction auto-commit while the scope is still on the stack — still settles `read` / `write` instead of hanging: `complete` can otherwise fire before a listener attached only after the scope returns would ever be wired.
256
- 7. **`get` / `records` narrow to records; `count` / `has` / `keys` operate on keys.** A store or index counts, tests presence, and lists keys over every stored value regardless of shape, but `get` / `resolve` / `records` narrow each value with `isRecord` — so a store holding a non-record value shows `count` greater than `records().length`, and `has` reads `true` for a key `get` reads back as `undefined` (a miss and a non-record value both read as `undefined` from `get`). A cursor reports the same boundary the same way: `cursor.value` is `Row | undefined` and reads `undefined` for a non-record stored value — see Cursor streaming and in-place mutation, later in this guide.
252
+ 7. **`get` / `records` narrow to records; `count` / `has` / `keys` operate on keys.** A store or index counts, tests presence, and lists keys over every stored value regardless of shape, but `get` / `resolve` / `records` narrow each value with `isRecord` — so a store holding a non-record value shows `count` greater than `records().length`, and `has` reads `true` for a key `get` reads back as `undefined` (a miss and a non-record value both read as `undefined` from `get`). A cursor reports the same boundary the same way: `cursor.value` is `StoreRecord | undefined` and reads `undefined` for a non-record stored value — see Cursor streaming and in-place mutation, later in this guide.
257
253
  8. **DOC ↔ SOURCE method bijection.** Every method in a `## Methods` table is a real call-signature member of that interface in source, and every public method of each behavioral interface is documented — exhaustive, both directions; and each implementing class exposes exactly its interface's public methods, no more (`AGENTS.md` § Documentation contract).
258
254
 
259
255
  9. **One atomic upgrade boundary.** The built-in create-missing-stores pass and the custom `upgrade` callback run inside the same versionchange transaction and failure boundary. A synchronous built-in/custom fault, or a custom rejection captured while that transaction remains active, aborts the whole upgrade and rejects `connect()` with `UPGRADE`; no partially created store, index, or migration survives. Its `cause` preserves the initiating value even when that value is `undefined`, and a native schema failure retains the nested typed chain (`UPGRADE` → `CONSTRAINT` → native `ConstraintError`). A failed open clears only its attempt-local state, so the same handle can retry. If auto-commit already occurred but the browser reports success after a failure was recorded, the wrapper closes that result before rejecting, preventing an orphan connection; closing cannot undo the already-committed schema.
@@ -319,7 +315,7 @@ while (cursor) {
319
315
  }
320
316
  ```
321
317
 
322
- A `store` cursor runs in a `readwrite` transaction, so `update` / `remove` work; an `index` cursor is read-only and rejects them with a typed `IndexedDBError` (`code: 'READONLY'`, native `ReadOnlyError`). Iterate promptly — an unrelated `await` between `continue` steps lets the transaction auto-commit and ends the loop. `cursor.value` is `Row | undefined`: it narrows the stored value with `isRecord` exactly as `get` does, so a non-record stored value reads `undefined` while the cursor still stops on that position and still exposes its `key` and `primary`. Test `value` before you dereference it.
318
+ A `store` cursor runs in a `readwrite` transaction, so `update` / `remove` work; an `index` cursor is read-only and rejects them with a typed `IndexedDBError` (`code: 'READONLY'`, native `ReadOnlyError`). Iterate promptly — an unrelated `await` between `continue` steps lets the transaction auto-commit and ends the loop. `cursor.value` is `StoreRecord | undefined`: it narrows the stored value with `isRecord` exactly as `get` does, so a non-record stored value reads `undefined` while the cursor still stops on that position and still exposes its `key` and `primary`. Test `value` before you dereference it.
323
319
 
324
320
  ### Seeking an index cursor to one primary key
325
321
 
@@ -391,18 +387,18 @@ import {
391
387
  readRecord,
392
388
  readRecords,
393
389
  wrapCall,
394
- wrapError,
390
+ wrapDOMException,
395
391
  } from '@orkestrel/indexeddb'
396
392
 
397
393
  await db.read('users', async (transaction) => {
398
394
  const native = transaction.store('users').store
399
395
  await promisifyRequest(wrapCall(() => native.get('u1'))) // sync throw → IndexedDBError too
400
- await readRecord(native, 'u1') // narrowed to Row (or undefined) with isRecord
396
+ await readRecord(native, 'u1') // narrowed to StoreRecord (or undefined) with isRecord
401
397
  await readRecords(native) // every record, narrowed the same way
402
398
  await hasKey(native, 'u1') // a native count() > 0
403
399
  await promisifyTransaction(native.transaction) // resolves after the transaction commits
404
400
  })
405
- wrapError(null) // the same DOMException → IndexedDBError mapping every bridge uses
401
+ wrapDOMException(null) // the same DOMException → IndexedDBError mapping every bridge uses
406
402
 
407
403
  // createIndex is the leaf `context.indexes.create` delegates to inside
408
404
  // onupgradeneeded — call it directly only if you are hand-rolling a raw
@@ -493,7 +489,7 @@ await db.connect()
493
489
  ## Tests
494
490
 
495
491
  - [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/browser` bijection, the `## Methods` ↔ interface bijection, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Feature-detecting before opening a database` fence against the `@example` block of that title (pinned so the titled pair cannot be retired silently), and the README pitch against this guide's tagline.
496
- - [`tests/src/browser/helpers.test.ts`](../tests/src/browser/helpers.test.ts) — the `supportsIndexedDB` probe, the key-range helpers asserted on the bounds they return, the shared read primitives (`readRecord` / `readRecords` / `hasKey`) over a real store / index (including the non-record `isRecord` boundary), `createIndex` translating an `IndexDefinition` into a native `createIndex` call inside a real `onupgradeneeded` (honouring `unique` / `multiple`), the `promisifyRequest` / `promisifyTransaction` bridges (success + `IndexedDBError` rejection), `wrapCall` over each of its three paths (a returned value passing through, a thrown `DOMException` surfacing as the mapped `IndexedDBError` with the native error as `cause`, and a non-`DOMException` throw rethrown by identity), the `context` an `IndexedDBError` carries beside its `code`, `wrapError` (including `INACTIVE` / `INVALID`), and `isIndexedDBError`.
492
+ - [`tests/src/browser/helpers.test.ts`](../tests/src/browser/helpers.test.ts) — the `supportsIndexedDB` probe, the key-range helpers asserted on the bounds they return, the shared read primitives (`readRecord` / `readRecords` / `hasKey`) over a real store / index (including the non-record `isRecord` boundary), `createIndex` translating an `IndexDefinition` into a native `createIndex` call inside a real `onupgradeneeded` (honouring `unique` / `multiple`), the `promisifyRequest` / `promisifyTransaction` bridges (success + `IndexedDBError` rejection), `wrapCall` over each of its three paths (a returned value passing through, a thrown `DOMException` surfacing as the mapped `IndexedDBError` with the native error as `cause`, and a non-`DOMException` throw rethrown by identity), the `context` an `IndexedDBError` carries beside its `code`, `wrapDOMException` (including `INACTIVE` / `INVALID`), and `isIndexedDBError`.
497
493
  - [`tests/src/browser/IndexedDBDatabase.test.ts`](../tests/src/browser/IndexedDBDatabase.test.ts) — the database handle in real Chromium: lazy connect and state, the `store` accessor, atomic `read` / `write` scopes (including settling when the scope ends on a trailing non-IDB `await`, the auto-commit race), `close` / `drop`, the auto-managed schema path, persistence across reopen, the `upgrade` hook (dropping a store, indexing an existing store and a same-upgrade `context.stores.create`d store through `context.indexes.create` — honouring `unique` / `multiple` — removing an index through `context.indexes.drop`, data migration through `context.stores.store`, `context.stores.create`, `old` / `version` / `stores.names`, an async `upgrade` rejection cleanly failing `connect()` with `UPGRADE`, and a synchronous `wrapCall` fault from `context.stores.drop` / `context.indexes.drop` targeting a missing store/index likewise failing `connect()` with `UPGRADE`), built-in auto-managed missing-store creation containing duplicate index names as `UPGRADE` → `CONSTRAINT` → native `ConstraintError` on two distinct same-handle `connect()` retries while suppressing the custom callback, atomic rollback of the version, sentinel data, and failed store, deletion without an orphan connection, synchronous `throw undefined` and asynchronous `Promise.reject(undefined)` failures retaining a present `cause` property, raw blockers proving a versioned open and deletion remain pending until release, repeated blocked connects share one Promise and produce one upgrade/owned connection, `close()` during blocked explicit or auto-managed second opens rejecting `CLOSED` after release without orphaning the native result, and `drop()` directly retiring a pending blocked open before deletion completes without leaving an orphan, a live connection yielding to a second connection's `versionchange`, that yielded handle lazily reconnecting at the new version on its next operation, and an ABNORMAL (non-self-initiated) `onclose` likewise leaving the handle able to lazily reconnect instead of staying invalid forever.
498
494
  - [`tests/src/browser/IndexedDBStore.test.ts`](../tests/src/browser/IndexedDBStore.test.ts) — the store reached through `db.store(name)`: metadata getters, the keyed CRUD surface with array-first batch overloads, key-range reads, `index` / `cursor` access, and the `NOT_FOUND` / `CONSTRAINT` / `DATA` (a non-cloneable value) faults.
499
495
  - [`tests/src/browser/IndexedDBIndex.test.ts`](../tests/src/browser/IndexedDBIndex.test.ts) — the index reached through `store.index(name)`: metadata getters, the read surface (`get` / `resolve` / `records` / `keys` / `primary` / `has` / `count` / `cursor`), the unique-index lookup + constraint, and the `multiple` (multiEntry) array index.
@@ -0,0 +1,187 @@
1
+ # JSON-RPC 2.0
2
+
3
+ > The JSON-RPC 2.0 wire contract the Orkestrel protocol packages share: the message types, total
4
+ > structural guards that place every parsed JSON value in at most one message arm, the reserved
5
+ > error codes, and the response builders.
6
+
7
+ Source: [`src/core`](../src/core). Published through `@orkestrel/jsonrpc`.
8
+
9
+ ## Messages
10
+
11
+ A JSON-RPC 2.0 message is an invocation or a response. An invocation is a `JSONRPCRequest`, which
12
+ carries an `id` and requires a response, or a `JSONRPCNotification`, which carries no `id` member
13
+ and permits none. A response is a `JSONRPCResultResponse`, which echoes the request's `id` beside a
14
+ `result`, or a `JSONRPCErrorResponse`, which carries a `JSONRPCError` under `error`.
15
+ `JSONRPCInvocation`, `JSONRPCResponse`, and `JSONRPCMessage` name the unions.
16
+
17
+ A `JSONRPCId` is a string or a finite integer, and never `null`. An error response always carries an
18
+ `id` member, and the member holds `null` when the request's id could not be read. A request and a
19
+ result response always carry an id.
20
+
21
+ The package carries parameters by name only: a present `params` member is a record, and the guards
22
+ refuse a by-position array.
23
+
24
+ The guards partition every value whose presence checks and member reads agree. An invocation guard
25
+ refuses a value carrying a `result` or `error` member, a response guard refuses a value carrying a
26
+ `method` member, the notification guard refuses any `id` member, the result-response guard refuses
27
+ an `error` member, and the error-response guard refuses a `result` member. A value carrying both an
28
+ invocation's and a response's members is no message. A `Proxy` whose `has` and `get` traps
29
+ disagree can satisfy several arms: a `has` trap that denies every member lets one value pass as a
30
+ notification and as an error response.
31
+
32
+ ### Classify a message
33
+
34
+ Pass any parsed value to a guard. Each guard answers for one arm, and `isJSONRPCMessage` answers
35
+ for all of them:
36
+
37
+ ```ts
38
+ import { isJSONRPCInvocation, isJSONRPCMessage, isJSONRPCResponse } from '@orkestrel/jsonrpc'
39
+
40
+ const hybrid: unknown = JSON.parse('{"jsonrpc":"2.0","id":1,"method":"ping","result":null}')
41
+
42
+ isJSONRPCMessage(hybrid) // false
43
+ isJSONRPCInvocation({ jsonrpc: '2.0', method: 'initialized' }) // true
44
+ isJSONRPCResponse({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }) // true
45
+ ```
46
+
47
+ ## Responses
48
+
49
+ `buildJSONRPCResult` echoes a request's id beside a result. The id must be an integer or a string
50
+ and the result a JSON value, and the builder checks neither. `buildJSONRPCError` writes the
51
+ id it is given, `null` included, and omits `data` from the error object when the argument is
52
+ absent. The five `JSONRPC_*` constants are the codes JSON-RPC 2.0 reserves for a parse failure, an
53
+ invalid request, an unknown method, invalid parameters, and an internal failure. The package throws
54
+ no error of its own.
55
+
56
+ ### Answer a request
57
+
58
+ Parse the payload, answer an unreadable or invalid request with `id: null`, and echo the id of every
59
+ request the guard accepts:
60
+
61
+ ```ts
62
+ import type { JSONRPCResponse } from '@orkestrel/jsonrpc'
63
+ import {
64
+ buildJSONRPCError,
65
+ buildJSONRPCResult,
66
+ isJSONRPCRequest,
67
+ JSONRPC_INVALID_REQUEST,
68
+ JSONRPC_METHOD_NOT_FOUND,
69
+ JSONRPC_PARSE_ERROR,
70
+ } from '@orkestrel/jsonrpc'
71
+
72
+ function answer(text: string): JSONRPCResponse {
73
+ let value: unknown
74
+ try {
75
+ value = JSON.parse(text)
76
+ } catch {
77
+ return buildJSONRPCError(null, JSONRPC_PARSE_ERROR, 'Parse error')
78
+ }
79
+ if (!isJSONRPCRequest(value)) {
80
+ return buildJSONRPCError(null, JSONRPC_INVALID_REQUEST, 'Invalid Request')
81
+ }
82
+ if (value.method !== 'ping') {
83
+ return buildJSONRPCError(value.id, JSONRPC_METHOD_NOT_FOUND, 'Method not found')
84
+ }
85
+ return buildJSONRPCResult(value.id, 'pong')
86
+ }
87
+
88
+ answer('{') // { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }
89
+ answer('{"jsonrpc":"2.0","id":7,"method":"ping"}') // { jsonrpc: '2.0', id: 7, result: 'pong' }
90
+ ```
91
+
92
+ ## Validation
93
+
94
+ Every guard takes `unknown` and never throws. `isJSONRPCId` accepts a string or a finite integer,
95
+ and every other guard returns `false` for a value that is not a plain record. A guard reads members
96
+ through property access, so an accessor or a `Proxy` with no traps passes when the members it
97
+ yields pass. A member that throws on read fails the value, except a `data` member and a member the
98
+ contract does not name: no guard reads either, so a throwing accessor there passes. A guard accepts
99
+ members the contract does not name.
100
+
101
+ - `isJSONRPCId` accepts a string, the empty string included, and a finite integer.
102
+ - `isJSONRPCError` requires an integer `code` and a string `message`, and accepts any `data`.
103
+ - `isJSONRPCRequest` requires `jsonrpc: '2.0'`, an id, and a string `method`.
104
+ - `isJSONRPCNotification` requires `jsonrpc: '2.0'` and a string `method`, and refuses an `id`
105
+ member whatever it holds, `undefined` and `null` included.
106
+ - `isJSONRPCResultResponse` requires `jsonrpc: '2.0'`, an id, and a `result` member holding any
107
+ value but `undefined`, which JSON cannot carry.
108
+ - `isJSONRPCErrorResponse` requires `jsonrpc: '2.0'`, an `id` member holding an id or `null`, and
109
+ an `error` that `isJSONRPCError` accepts.
110
+ - `isJSONRPCInvocation`, `isJSONRPCResponse`, and `isJSONRPCMessage` accept what their arms accept.
111
+
112
+ The following calls show each boundary:
113
+
114
+ ```ts
115
+ import {
116
+ isJSONRPCError,
117
+ isJSONRPCErrorResponse,
118
+ isJSONRPCId,
119
+ isJSONRPCNotification,
120
+ isJSONRPCResultResponse,
121
+ } from '@orkestrel/jsonrpc'
122
+
123
+ isJSONRPCId(1.5) // false
124
+ isJSONRPCError({ code: -32601, message: 'Method not found', data: { method: 'ping' } }) // true
125
+ isJSONRPCNotification({ jsonrpc: '2.0', method: 'log', id: undefined }) // false
126
+ isJSONRPCResultResponse({ jsonrpc: '2.0', id: 1, result: null }) // true
127
+ isJSONRPCErrorResponse({ jsonrpc: '2.0', error: { code: -32700, message: 'Parse error' } }) // false
128
+ ```
129
+
130
+ ## Surface
131
+
132
+ ### Message types
133
+
134
+ The package provides these message contracts.
135
+
136
+ | Name | Kind | Signature | Summary |
137
+ | ----------------------- | --------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
138
+ | `JSONRPCId` | type | `string \| number` | Identifies a JSON-RPC 2.0 request and the response that answers it. |
139
+ | `JSONRPCRequest` | interface | `{ jsonrpc, id, method, params? }` | Describes a JSON-RPC 2.0 method call that requires a response. |
140
+ | `JSONRPCNotification` | interface | `{ jsonrpc, method, id?, params? }` | Describes a JSON-RPC 2.0 method call that permits no response. |
141
+ | `JSONRPCInvocation` | type | `JSONRPCRequest \| JSONRPCNotification` | Describes one inbound JSON-RPC 2.0 call, a request or a notification. |
142
+ | `JSONRPCError` | interface | `{ code, message, data? }` | Describes the error object a JSON-RPC 2.0 error response carries. |
143
+ | `JSONRPCResultResponse` | interface | `{ jsonrpc, id, result, error? }` | Describes a successful JSON-RPC 2.0 response. |
144
+ | `JSONRPCErrorResponse` | interface | `{ jsonrpc, id, error, result? }` | Describes a failed JSON-RPC 2.0 response, with `id` set to `null` when the request's id could not be read. |
145
+ | `JSONRPCResponse` | type | `JSONRPCResultResponse \| JSONRPCErrorResponse` | Describes either outcome of a JSON-RPC 2.0 request. |
146
+ | `JSONRPCMessage` | type | `JSONRPCInvocation \| JSONRPCResponse` | Describes one complete JSON-RPC 2.0 wire message. |
147
+
148
+ ### Error codes
149
+
150
+ The package provides these reserved error codes.
151
+
152
+ | Name | Kind | Signature | Summary |
153
+ | -------------------------- | ----- | --------- | ------------------------------------------------------------------------ |
154
+ | `JSONRPC_PARSE_ERROR` | const | `-32700` | Identifies a payload that is not valid JSON, `-32700`. |
155
+ | `JSONRPC_INVALID_REQUEST` | const | `-32600` | Identifies a payload that is not a valid JSON-RPC 2.0 request, `-32600`. |
156
+ | `JSONRPC_METHOD_NOT_FOUND` | const | `-32601` | Identifies a method the receiver does not provide, `-32601`. |
157
+ | `JSONRPC_INVALID_PARAMS` | const | `-32602` | Identifies invalid method parameters, `-32602`. |
158
+ | `JSONRPC_INTERNAL_ERROR` | const | `-32603` | Identifies an internal receiver failure, `-32603`. |
159
+
160
+ ### Guards
161
+
162
+ The package provides these guards.
163
+
164
+ | Name | Kind | Signature | Summary |
165
+ | ------------------------- | -------- | ---------------------------------------------------- | -------------------------------------------------------------------------- |
166
+ | `isJSONRPCId` | function | `(value: unknown) => value is JSONRPCId` | Checks whether a value is a JSON-RPC 2.0 id, a string or a finite integer. |
167
+ | `isJSONRPCError` | function | `(value: unknown) => value is JSONRPCError` | Checks whether a value is a JSON-RPC 2.0 error object. |
168
+ | `isJSONRPCRequest` | function | `(value: unknown) => value is JSONRPCRequest` | Checks whether a value is a JSON-RPC 2.0 request. |
169
+ | `isJSONRPCNotification` | function | `(value: unknown) => value is JSONRPCNotification` | Checks whether a value is a JSON-RPC 2.0 notification. |
170
+ | `isJSONRPCInvocation` | function | `(value: unknown) => value is JSONRPCInvocation` | Checks whether a value is a JSON-RPC 2.0 request or notification. |
171
+ | `isJSONRPCResultResponse` | function | `(value: unknown) => value is JSONRPCResultResponse` | Checks whether a value is a successful JSON-RPC 2.0 response. |
172
+ | `isJSONRPCErrorResponse` | function | `(value: unknown) => value is JSONRPCErrorResponse` | Checks whether a value is a failed JSON-RPC 2.0 response. |
173
+ | `isJSONRPCResponse` | function | `(value: unknown) => value is JSONRPCResponse` | Checks whether a value is a JSON-RPC 2.0 response. |
174
+ | `isJSONRPCMessage` | function | `(value: unknown) => value is JSONRPCMessage` | Checks whether a value is a JSON-RPC 2.0 message. |
175
+
176
+ ### Builders
177
+
178
+ The package provides these response builders.
179
+
180
+ | Name | Kind | Signature | Summary |
181
+ | -------------------- | -------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
182
+ | `buildJSONRPCResult` | function | `(id: JSONRPCId, result: unknown) => JSONRPCResultResponse` | Builds a successful JSON-RPC 2.0 response that echoes the request's id. |
183
+ | `buildJSONRPCError` | function | `(id: JSONRPCId \| null, code: number, message: string, data?: unknown) => JSONRPCErrorResponse` | Builds a failed JSON-RPC 2.0 response, omitting `data` when it is absent. |
184
+
185
+ ## Tests
186
+
187
+ [`tests/src/core`](../tests/src/core) proves the guards, the builders, and the barrel.