@orkestrel/scaffold 0.0.119 → 0.0.121

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 (73) hide show
  1. package/dist/bin/main.js +19 -19
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
  4. package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
  5. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
  6. package/dist/host/claude/agents/orkestrel.md +52 -51
  7. package/dist/host/claude/rules/tests.md +2 -2
  8. package/dist/host/claude/rules/typescript.md +2 -3
  9. package/dist/host/guides/abort.md +0 -4
  10. package/dist/host/guides/agent.md +5 -5
  11. package/dist/host/guides/brief.md +7 -15
  12. package/dist/host/guides/browser.md +1 -1
  13. package/dist/host/guides/budget.md +1 -5
  14. package/dist/host/guides/capture.md +2 -2
  15. package/dist/host/guides/codec.md +18 -3
  16. package/dist/host/guides/console.md +4 -30
  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/guide.md +0 -1
  23. package/dist/host/guides/html.md +3 -7
  24. package/dist/host/guides/indexeddb.md +28 -32
  25. package/dist/host/guides/interpret.md +165 -182
  26. package/dist/host/guides/jsonrpc.md +187 -0
  27. package/dist/host/guides/lsp.md +26 -51
  28. package/dist/host/guides/markdown.md +132 -141
  29. package/dist/host/guides/mcp.md +220 -276
  30. package/dist/host/guides/middleware.md +14 -22
  31. package/dist/host/guides/msg.md +47 -63
  32. package/dist/host/guides/ndjson.md +0 -4
  33. package/dist/host/guides/ollama.md +1 -3
  34. package/dist/host/guides/pool.md +0 -4
  35. package/dist/host/guides/probe.md +71 -80
  36. package/dist/host/guides/process.md +71 -79
  37. package/dist/host/guides/program.md +26 -35
  38. package/dist/host/guides/qualifier.md +0 -6
  39. package/dist/host/guides/queue.md +0 -4
  40. package/dist/host/guides/rater.md +6 -12
  41. package/dist/host/guides/reason.md +30 -36
  42. package/dist/host/guides/relation.md +0 -2
  43. package/dist/host/guides/router.md +11 -18
  44. package/dist/host/guides/scaffold.md +148 -144
  45. package/dist/host/guides/sea.md +47 -51
  46. package/dist/host/guides/server.md +15 -19
  47. package/dist/host/guides/sqlite.md +0 -4
  48. package/dist/host/guides/sse.md +6 -10
  49. package/dist/host/guides/table.md +481 -493
  50. package/dist/host/guides/template.md +0 -4
  51. package/dist/host/guides/terminal.md +0 -26
  52. package/dist/host/guides/test.md +46 -66
  53. package/dist/host/guides/timeout.md +0 -6
  54. package/dist/host/guides/tool.md +2 -6
  55. package/dist/host/guides/toolbox.md +0 -10
  56. package/dist/host/guides/websocket.md +0 -4
  57. package/dist/host/guides/worker.md +57 -57
  58. package/dist/host/guides/workflow.md +13 -26
  59. package/dist/host/guides/workspace.md +15 -21
  60. package/dist/host/manifest.json +64 -909
  61. package/dist/src/core/index.cjs +128 -181
  62. package/dist/src/core/index.cjs.map +1 -1
  63. package/dist/src/core/index.d.cts +213 -213
  64. package/dist/src/core/index.d.ts +213 -213
  65. package/dist/src/core/index.js +117 -170
  66. package/dist/src/core/index.js.map +1 -1
  67. package/dist/src/server/index.cjs +35 -34
  68. package/dist/src/server/index.cjs.map +1 -1
  69. package/dist/src/server/index.d.cts +62 -58
  70. package/dist/src/server/index.d.ts +62 -58
  71. package/dist/src/server/index.js +36 -35
  72. package/dist/src/server/index.js.map +1 -1
  73. package/package.json +13 -13
@@ -173,7 +173,6 @@ directly.
173
173
  | `extractSignature` | function | `(code: string, source: string) => SurfaceSymbol \| undefined` | Extracts one emitted declaration's signature: the symbol its column-zero `export` head names, carrying the type text the compiler emitted for it. |
174
174
  | `extractSignatures` | function | `(declaration: string) => readonly SurfaceSymbol[]` | Extracts every signature one compiler-emitted declaration file declares: each column-zero `export` head read through `extractSignature`, an overload set's emitted heads joined in order as an intersection of parenthesized signatures. |
175
175
  | `joinHead` | function | `(lines: readonly string[], start: number) => DeclarationHead \| undefined` | Joins the declaration head starting at `start` into one space-separated line, consuming lines until the first that opens a body: one that ends with `{`, or one that closes an empty body with `{}` or `{ }`. |
176
- | `escapeRegExp` | function | `(value: string) => string` | Escapes every regex metacharacter in a literal string so it reads as text inside a larger `RegExp` source rather than as syntax. |
177
176
  | `collectDeclarations` | function | `(source: string) => ReadonlyMap<string, Declaration>` | Collects every `export class` / `export interface` declaration one file's source text declares, each keyed `${keyword} ${name}` and carrying the body lines and the base identifiers read from its own head, so a body and a heritage clause always come from the same declaration. |
178
177
  | `extractDeclaration` | function | `(source: string, keyword: DeclarationKeyword, name: string) => Declaration \| undefined` | Locates the named `export class` / `export interface` declaration in one file's source text and returns its body lines and its base identifiers read from that one head, so a body and a heritage clause always come from the same declaration, or `undefined` when the file declares no such head. |
179
178
  | `extractMemberMethods` | function | `(lines: readonly string[]) => readonly MethodEntry[]` | Selects the member lines declaring a callable member: plain, `async`, generator (`*`), and optional (`records?(`) methods all count; getters, setters, `static` members, and `#` privates never do (their keyword or `#` breaks the `name(` shape). The grammar is `collectKeys`'s, read once over `extractBodyLines`'s projection of the body, so commented method-like payload never becomes eligible and each member keys to the owner head that projection supplies. Each member carries its own doc block's description paragraph, read through `collectSummaries`; the first declaration of a name answers for it. |
@@ -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.