@orkestrel/scaffold 0.0.135 → 0.0.136

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 (35) hide show
  1. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +167 -4
  2. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +20 -5
  3. package/dist/bin/main.js +3 -3
  4. package/dist/host/AGENTS.md +1 -1
  5. package/dist/host/agents/orchestration.md +2 -2
  6. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +201 -8
  7. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +24 -5
  8. package/dist/host/claude/agents/orkestrel.md +7 -7
  9. package/dist/host/claude/agents/reviewer.md +1 -1
  10. package/dist/host/claude/rules/documentation.md +1 -1
  11. package/dist/host/claude/rules/patterns.md +2 -2
  12. package/dist/host/claude/rules/workspace.md +9 -4
  13. package/dist/host/configs/helpers.ts +21 -6
  14. package/dist/host/guides/contract.md +198 -163
  15. package/dist/host/guides/database.md +760 -300
  16. package/dist/host/guides/indexeddb.md +80 -66
  17. package/dist/host/guides/relation.md +56 -32
  18. package/dist/host/guides/scaffold.md +8 -2
  19. package/dist/host/guides/sqlite.md +44 -23
  20. package/dist/host/guides/test.md +7 -3
  21. package/dist/host/manifest.json +19 -19
  22. package/dist/host/scripts/browsers.sh +0 -0
  23. package/dist/host/scripts/codex.sh +0 -0
  24. package/dist/host/scripts/cursor.sh +0 -0
  25. package/dist/host/scripts/deps.sh +0 -0
  26. package/dist/host/scripts/npm.sh +0 -0
  27. package/dist/host/scripts/ollama.sh +0 -0
  28. package/dist/host/tests/config.test.ts +71 -3
  29. package/dist/src/core/index.cjs +103 -26
  30. package/dist/src/core/index.cjs.map +1 -1
  31. package/dist/src/core/index.d.cts +31 -5
  32. package/dist/src/core/index.d.ts +31 -5
  33. package/dist/src/core/index.js +103 -27
  34. package/dist/src/core/index.js.map +1 -1
  35. package/package.json +3 -3
@@ -59,26 +59,38 @@ await users.index('byAge').records(rangeFromKey(18)) // adults, index-backed (O(
59
59
  context across package copies. Subclass instances pass without an exact name;
60
60
  transparent proxies, unbranded look-alikes, and plain branded objects fail.
61
61
 
62
- | Name | Kind | Signature | Summary |
63
- | ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
64
- | `supportsIndexedDB` | function | `() => boolean` | Checks whether IndexedDB is available in this environment. |
65
- | `promisifyRequest` | function | `<T>(request: IDBRequest<T>) => Promise<T>` | Resolves an `IDBRequest` to its result, rejecting with an `IndexedDBError`. |
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<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
- | `hasKey` | function | `(source: IDBObjectStore \| IDBIndex, key: IDBValidKey) => Promise<boolean>` | Checks whether a key is present in a store or index. |
70
- | `createIndex` | function | `(store: IDBObjectStore, definition: IndexDefinition) => void` | Creates a secondary index on a store from its `IndexDefinition`. |
71
- | `wrapCall` | function | `<T>(action: () => T) => T` | Runs a synchronous native IndexedDB call, wrapping a thrown `DOMException` into a typed `IndexedDBError`. |
72
- | `rangeAboveKey` | function | `(value: IDBValidKey) => IDBKeyRange` | Builds a key range strictly above one key. |
73
- | `rangeFromKey` | function | `(value: IDBValidKey) => IDBKeyRange` | Builds a key range starting at and including one key. |
74
- | `rangeBelowKey` | function | `(value: IDBValidKey) => IDBKeyRange` | Builds a key range strictly below one key. |
75
- | `rangeToKey` | function | `(value: IDBValidKey) => IDBKeyRange` | Builds a key range ending at and including one key. |
76
- | `rangePrefix` | function | `(value: string) => IDBKeyRange` | Builds a key range containing every string with one prefix. |
77
- | `wrapDOMException` | function | `(error: DOMException \| null) => IndexedDBError` | Maps a native IndexedDB `DOMException` to a typed `IndexedDBError`. |
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
- | `isIndexedDBError` | function | `(value: unknown) => value is IndexedDBError` | Checks whether a value is an `IndexedDBError`. |
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. `wrapDOMException` is the request boundary every bridge maps a native `DOMException` through.
62
+ | Name | Kind | Signature | Summary |
63
+ | ---------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
64
+ | `supportsIndexedDB` | function | `() => boolean` | Checks whether IndexedDB is available in this environment. |
65
+ | `promisifyRequest` | function | `<T>(request: IDBRequest<T>) => Promise<T>` | Resolves an `IDBRequest` to its result, rejecting with an `IndexedDBError`. |
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<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
+ | `hasKey` | function | `(source: IDBObjectStore \| IDBIndex, key: IDBValidKey) => Promise<boolean>` | Checks whether a key is present in a store or index. |
70
+ | `createIndex` | function | `(store: IDBObjectStore, definition: IndexDefinition) => void` | Creates a secondary index on a store from its `IndexDefinition`. |
71
+ | `wrapCall` | function | `<T>(action: () => T) => T` | Runs a synchronous native IndexedDB call, wrapping a thrown `DOMException` into a typed `IndexedDBError`. |
72
+ | `rangeAboveKey` | function | `(value: IDBValidKey) => IDBKeyRange` | Builds a key range strictly above one key. |
73
+ | `rangeFromKey` | function | `(value: IDBValidKey) => IDBKeyRange` | Builds a key range starting at and including one key. |
74
+ | `rangeBelowKey` | function | `(value: IDBValidKey) => IDBKeyRange` | Builds a key range strictly below one key. |
75
+ | `rangeToKey` | function | `(value: IDBValidKey) => IDBKeyRange` | Builds a key range ending at and including one key. |
76
+ | `rangePrefix` | function | `(value: string) => IDBKeyRange` | Builds a key range containing every string with one prefix. |
77
+ | `wrapDOMException` | function | `(error: DOMException \| null) => IndexedDBError` | Maps a native IndexedDB `DOMException` to a typed `IndexedDBError`. |
78
+ | `buildRecordError` | function | `(source: IDBObjectStore \| IDBIndex, key?: IDBValidKey) => IndexedDBError` | Builds the `RECORD` error a read raises for a stored value that is no record. |
79
+ | `scanIndex` | function | `(index: IDBIndex, definition: IndexDefinition) => readonly string[]` | Scans a stored index against its declaration and returns the members that differ. |
80
+ | `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. |
81
+ | `isIndexedDBError` | function | `(value: unknown) => value is IndexedDBError` | Checks whether a value is an `IndexedDBError`. |
82
+ | `keyPathShape` | const | `import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>]>` | Declares a `KeyPath` as a contract shape: one field name, or a list of field names. |
83
+ | `indexDefinitionShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; path: import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>]>; unique: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; multiple: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; }, false>` | Declares an `IndexDefinition` as a closed contract shape. |
84
+ | `storeDefinitionShape` | const | `import("@orkestrel/contract").ObjectShape<{ path: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>]>>; increment: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; indexes: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; path: import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>]>; unique: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; multiple: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; }, false>>>; }, false>` | Declares a `StoreDefinition` as a closed contract shape. |
85
+ | `indexedDBSchemaShape` | const | `import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").ObjectShape<{ path: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>]>>; increment: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; indexes: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; path: import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>]>; unique: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; multiple: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; }, false>>>; }, false>>` | Declares an `IndexedDBSchema` as a contract shape: a record of store name to store definition. |
86
+ | `indexedDBDatabaseOptionsShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; version: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; stores: import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").ObjectShape<{ path: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>]>>; increment: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; indexes: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; path: import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>]>; unique: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; multiple: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").BooleanShape>; }, false>>>; }, false>>; upgrade: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").FunctionShape>; }, false>` | Declares the options of `createIndexedDBDatabase` as a closed contract shape. |
87
+ | `indexedDBDatabaseOptionsContract` | const | `ContractInterface<Readonly<{ name: string; stores: { readonly [k: string]: Readonly<{} & { path?: string \| readonly string[]; increment?: boolean; indexes?: readonly Readonly<{ name: string; path: string \| readonly string[]; } & { unique?: boolean; multiple?: boolean; }>[]; }>; }; } & { version?: number; upgrade?: (...args: never[]) => unknown; }>>` | Holds the compiled contract of the database options, which the database constructor admits its whole options record through. |
88
+ | `indexDefinitionContract` | const | `ContractInterface<IndexDefinition>` | Holds the compiled contract of an index definition, which `context.indexes.create` admits through. |
89
+ | `storeDefinitionContract` | const | `ContractInterface<StoreDefinition>` | Holds the compiled contract of a store definition, which `context.stores.create` admits through. |
90
+ | `indexedDBSchemaContract` | const | `ContractInterface<IndexedDBSchema>` | Holds the compiled contract of a database's store schema, the `stores` member the options contract checks. |
91
+ | `isIndexedDBErrorCode` | const | `import("@orkestrel/contract").Guard<"ABORTED" \| "CLOSED" \| "CONSTRAINT" \| "DATA" \| "INACTIVE" \| "INVALID" \| "NOT_FOUND" \| "NOT_OPEN" \| "OPEN" \| "QUOTA" \| "READONLY" \| "RECORD" \| "UNKNOWN" \| "UPGRADE">` | Checks whether a value is a code an `IndexedDBError` carries. |
92
+
93
+ `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. `buildRecordError` is the refusal `readRecord`, `readRecords`, and a cursor's `value` share for a stored value that is no record. `isIndexedDBErrorCode` is the code check `isIndexedDBError` reads, built once from the members of `IndexedDBErrorCode`. The definition shapes and their compiled contracts are the schema checks the database constructor and the upgrade verbs read, each shape bound to its declared type at compile time. A definition is a plain record whose optional members are absent: an undeclared member, an optional member present as `undefined`, and a class instance carrying the declared members are each refused. `scanIndex` is the comparison the built-in index pass and the auto-managed open both read.
82
94
 
83
95
  ### Constants
84
96
 
@@ -90,30 +102,30 @@ transparent proxies, unbranded look-alikes, and plain branded objects fail.
90
102
 
91
103
  ### Types
92
104
 
93
- | Name | Kind | Signature | Summary |
94
- | --------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
95
- | `StoreRecord` | type | `Record<string, unknown>` | Represents a record stored in, and read from, an object store. |
96
- | `KeyPath` | type | `string \| readonly string[]` | Represents a key path — one field, or several for a compound key. |
97
- | `IndexDefinition` | interface | `{ name, path, unique?, multiple? }` | Represents the declaration of a secondary index — its name, key path, and uniqueness. |
98
- | `StoreDefinition` | interface | `{ path?, increment?, indexes? }` | Represents the declaration of one object store — its key path, key generation, and secondary indexes. |
99
- | `IndexedDBSchema` | type | `Readonly<Record<string, StoreDefinition>>` | Represents a database's schema — a map of store name to its `StoreDefinition`. |
100
- | `IndexedDBUpgradeContext` | interface | `{ transaction, old, version, stores, indexes }` | Represents the escape hatch into a version-change upgrade, passed to `IndexedDBDatabaseOptions.upgrade`. |
101
- | `IndexedDBUpgradeStoreManagerInterface` | interface | `{ names, create(), drop(), store() }` | Represents the store manager of a version-change upgrade. |
102
- | `IndexedDBUpgradeIndexManagerInterface` | interface | `{ create(), drop() }` | Represents the secondary-index manager of a version-change upgrade. |
103
- | `IndexedDBDatabaseOptions` | interface | `{ name, version?, stores, upgrade? }` | Represents the options for `createIndexedDBDatabase`. |
104
- | `IndexedDBCursorOptions` | interface | `{ query?, direction? }` | Represents the options for opening a cursor. |
105
- | `IndexedDBErrorCode` | type | `'NOT_OPEN' \| 'CLOSED' \| 'NOT_FOUND' \| 'CONSTRAINT' \| 'QUOTA' \| 'ABORTED' \| 'DATA' \| 'OPEN' \| 'UPGRADE' \| 'INACTIVE' \| 'READONLY' \| 'INVALID' \| 'UNKNOWN'` | Represents a machine-readable `IndexedDBError` code. |
106
- | `IndexedDBDatabaseInterface` | interface | `{ database, name, version, stores, open, connect(), store(), read(), write(), close(), drop() }` | Represents the contract of a typed, lazily-connecting IndexedDB database. |
107
- | `IndexedDBRecordStoreInterface` | interface | `{ get(), resolve(), records(), keys(), has(), count(), set(), add(), remove(), clear(), cursor() }` | Represents the contract the object-store surfaces share — the keyed record verbs, in or out of an explicit transaction. |
108
- | `IndexedDBStoreInterface` | interface | `{ name, path, indexes, increment, index() }` | Represents the contract of an object store — the keyed record surface plus the store's own schema metadata and `index` accessor. |
109
- | `IndexedDBIndexInterface` | interface | `{ name, path, unique, multiple, get(), resolve(), records(), keys(), primary(), has(), count(), cursor() }` | Represents the contract of a secondary index — read access by an indexed key path. |
110
- | `IndexedDBCursorInterface` | interface | `{ cursor, source, key, primary, value, direction, continue(), seek(), advance(), update(), remove() }` | Represents the contract of a promisified value cursor for streaming and in-place mutation. |
111
- | `IndexedDBTransactionInterface` | interface | `{ transaction, mode, stores, active, finished, error, store(), abort(), commit() }` | Represents the contract of an explicit transaction over one or more stores. |
112
- | `IndexedDBTransactionStoreInterface` | interface | `{ store }` | Represents the contract of an object store bound to an explicit transaction. |
113
-
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.
115
-
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.
105
+ | Name | Kind | Signature | Summary |
106
+ | --------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
107
+ | `StoreRecord` | type | `Record<string, unknown>` | Represents a record stored in, and read from, an object store. |
108
+ | `KeyPath` | type | `string \| readonly string[]` | Represents a key path — one field, or several for a compound key. |
109
+ | `IndexDefinition` | interface | `{ name, path, unique?, multiple? }` | Represents the declaration of a secondary index — its name, key path, and uniqueness. |
110
+ | `StoreDefinition` | interface | `{ path?, increment?, indexes? }` | Represents the declaration of one object store — its key path, key generation, and secondary indexes. |
111
+ | `IndexedDBSchema` | type | `Readonly<Record<string, StoreDefinition>>` | Represents a database's schema — a map of store name to its `StoreDefinition`. |
112
+ | `IndexedDBUpgradeContext` | interface | `{ transaction, old, version, stores, indexes }` | Represents the escape hatch into a version-change upgrade, passed to `IndexedDBDatabaseOptions.upgrade`. |
113
+ | `IndexedDBUpgradeStoreManagerInterface` | interface | `{ names, create(), drop(), store() }` | Represents the store manager of a version-change upgrade. |
114
+ | `IndexedDBUpgradeIndexManagerInterface` | interface | `{ create(), drop() }` | Represents the secondary-index manager of a version-change upgrade. |
115
+ | `IndexedDBDatabaseOptions` | interface | `{ name, version?, stores, upgrade? }` | Represents the options for `createIndexedDBDatabase`. |
116
+ | `IndexedDBCursorOptions` | interface | `{ query?, direction? }` | Represents the options for opening a cursor. |
117
+ | `IndexedDBErrorCode` | type | `'NOT_OPEN' \| 'CLOSED' \| 'NOT_FOUND' \| 'CONSTRAINT' \| 'QUOTA' \| 'ABORTED' \| 'DATA' \| 'OPEN' \| 'UPGRADE' \| 'INACTIVE' \| 'READONLY' \| 'INVALID' \| 'RECORD' \| 'UNKNOWN'` | Represents a machine-readable `IndexedDBError` code. |
118
+ | `IndexedDBDatabaseInterface` | interface | `{ database, name, version, stores, open, connect(), store(), read(), write(), close(), drop() }` | Represents the contract of a typed, lazily-connecting IndexedDB database. |
119
+ | `IndexedDBRecordStoreInterface` | interface | `{ get(), resolve(), records(), keys(), has(), count(), set(), add(), remove(), clear(), cursor() }` | Represents the contract the object-store surfaces share — the keyed record verbs, in or out of an explicit transaction. |
120
+ | `IndexedDBStoreInterface` | interface | `{ name, path, indexes, increment, index() }` | Represents the contract of an object store — the keyed record surface plus the store's own schema metadata and `index` accessor. |
121
+ | `IndexedDBIndexInterface` | interface | `{ name, path, unique, multiple, get(), resolve(), records(), keys(), primary(), has(), count(), cursor() }` | Represents the contract of a secondary index — read access by an indexed key path. |
122
+ | `IndexedDBCursorInterface` | interface | `{ cursor, source, key, primary, value, direction, continue(), seek(), advance(), update(), remove() }` | Represents the contract of a promisified value cursor for streaming and in-place mutation. |
123
+ | `IndexedDBTransactionInterface` | interface | `{ transaction, mode, stores, active, finished, error, store(), abort(), commit() }` | Represents the contract of an explicit transaction over one or more stores. |
124
+ | `IndexedDBTransactionStoreInterface` | interface | `{ store }` | Represents the contract of an object store bound to an explicit transaction. |
125
+
126
+ Values are this package's own `StoreRecord` (a record), checked with `isRecord` (from `@orkestrel/contract`) at the read boundary — an `as`-free bridge — where a stored value that is no record raises an `IndexedDBError` of code `RECORD`. Keys are the full native `IDBValidKey`, so the wrapper speaks IndexedDB's whole key space.
127
+
128
+ 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 and declared indexes on a bump, or **omit it** for auto-managed mode, where the database opens at its current version and bumps once on its own when the stored schema lacks a declared store or a declared index, or holds a declared index whose definition differs — so adding a store or an index never needs a manual version bump. The constructor checks the whole options record through `indexedDBDatabaseOptionsContract` and refuses it with one `DATA` that names every malformed option at once, among options that are JSON data: a name that is not a non-empty string, stores outside `IndexedDBSchema` (each malformed store and member path, such as `stores.books.increment` or `stores.books.indexes.0.unique`), a version that is not an integer of at least 1, an `upgrade` that is not a function, and any undeclared option. The message is rendered by `describeFaults` from `@orkestrel/contract` with the expected shape, and `context` is `{ faults }`. The options shape declares `upgrade` with `functionShape`, so any other value is refused with `expected function`, and no such value reaches a native call that would coerce it. An omitted option is absent, never present as `undefined`: `version: undefined` and `upgrade: undefined` are each refused, as the repository's `exactOptionalPropertyTypes` setting types them, and a class instance carrying the declared members is refused because the options are a plain record. The constructor reads the caller's options once, through one top-level copy, and clones that copy, minus `upgrade`, once with `cloneJSONRecord` from `@orkestrel/contract`; `upgrade` is never cloned, and the check and the audit both run on that clone with `upgrade` rejoined, so no getter is read twice and the faults are always the refused value's. A value contract cannot clone, one that is not JSON data or one past its clone node limit of 262144 nodes, is refused with one `DATA` whose message and `context` (`{ clone }`) name that cause, with the contract error as `cause`. The clone message ends with the member's path, such as `property is not JSON data at stores.books.path`. This is a stated limit: the clone refuses before the contract checks, so one member that is not JSON data hides the faults of every other option. A getter on a nested definition is such a value: contract refuses it as not enumerable data without reading it. The handle keeps the frozen clone it admitted, so a change the caller makes to its own objects after construction reaches nothing the database creates. That open reads the index names of every declared store that declares an index, in one readonly transaction with no request.
117
129
 
118
130
  ## Methods
119
131
 
@@ -245,14 +257,14 @@ These invariants hold across `src/browser` ↔ `indexeddb.md`:
245
257
 
246
258
  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).
247
259
  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.
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`.
260
+ 3. **`StoreRecord` values, `IDBValidKey` keys.** Reads return this package's own `StoreRecord` (checked with `isRecord`, never an unchecked cast, and raising `RECORD` per invariant 7); writes take a `StoreRecord`. Keys are the native `IDBValidKey`.
249
261
  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)`).
250
262
  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`.
251
263
  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.
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.
264
+ 7. **A value read raises on a stored value that is no record; `count` / `has` / `keys` operate on keys.** `get`, `resolve`, `records`, and a cursor's `value` check each value with `isRecord` and raise an `IndexedDBError` of code `RECORD` for one that is no record, so no read skips a stored value: `count()` equals `records().length`, or `records()` raises. `count`, `has`, `keys`, and an index's `primary` read keys and keep reading such an entry, so a caller can find it and `remove` it. The error's `context` names the `store`, and the `index` on an index read; a store's `get` and `resolve` add the `key` they were given, and a cursor adds its `primary` key. A bulk `records` and an index's `get` and `resolve` name the primary key too. A clean read issues one request. A failing one issues a pair back to back, with no `await` between them: `getAll` and `getAllKeys` over the same range, or an index's `get` and `getKey`. It names the key at the position of the first value in that pair that is no record, so a request the caller queued after the failing read cannot run between the two reads and shift the key. When the pair holds no such value, because the caller removed or rewrote it first, the error names no key and its message says the value left before its key was read. Neither the message nor the `context` carries the stored value. The message encodes a key through `preview` from `@orkestrel/contract`, JSON-encoded and length-capped, so a long or quote-bearing key cannot balloon or fake the message; `context.key` holds the raw key. Every other message that names a caller value, a database, store, or index name, a key, or a version, writes it through the same `preview`. A stored `undefined` reads as a miss through `get`, because the native `get` returns the same `undefined` for both, and raises through `records` and a cursor's `value`.
253
265
  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).
254
266
 
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.
267
+ 9. **One atomic upgrade boundary.** The built-in create-missing-stores pass, the custom `upgrade` callback, and the built-in index pass run in that order inside the same versionchange transaction and failure boundary. The index pass creates each declared index an existing declared store lacks, finds a declared index the callback already created, and checks each declared index's key path, `unique`, and `multiple` against the stored index; a difference rejects `connect()` with `UPGRADE` carrying `context` `{ store, index }`, whose `cause` is an `UPGRADE` error with the same `context`; every `UPGRADE` rejection copies a typed cause's `context` up the same way. A custom callback that aborts the versionchange transaction itself, through `context.transaction.abort()`, rejects `connect()` with `UPGRADE` whose `cause` is an `ABORTED` error over the native `AbortError` (`UPGRADE` → `ABORTED` → native `AbortError`), whether it aborts synchronously or after awaiting a request. The abort reverts the connection to its prior version at once, so the built-in index pass reads that version and does not run, and the stored version stays where it was. Nothing in the wrapper drops a store or an index, so an undeclared index a callback created survives every later bump. `context.stores.create` and `context.indexes.create` admit a definition through `storeDefinitionContract` and `indexDefinitionContract` before any native call, and refuse one outside its type with `DATA`, a fault in the caller's own argument, naming each offending member; `connect()` rejects with `UPGRADE` over that cause, carrying its `{ store, faults }` context. A pinned open that triggers no upgrade runs neither pass and checks no index. 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.
256
268
  10. **Blocking is progress; close wins lifecycle races.** Native `blocked` notifications from open/delete requests are not terminal failures, so `connect()` / `drop()` stay pending until the blocker closes and IndexedDB reports success or error. Repeated `connect()` calls share that pending Promise. `close()` permanently retires the handle even while an open is pending: every native database returned later is closed before the pending `connect()` rejects with `CLOSED`, including the second open of an auto-managed missing-store bump. Connection events carry their exact database identity, so a stale close/versionchange event cannot clear a different live connection.
257
269
 
258
270
  ## Patterns
@@ -301,7 +313,7 @@ await users.index('byEmail').get('ada@x.io') // unique-index point lookup
301
313
  await users.records(rangePrefix('user:')) // primary-key prefix scan
302
314
  ```
303
315
 
304
- The single-boundary builders each fix a native boolean argument that reads as nothing at the call site, and `rangePrefix` caps the range at U+FFFF. Pass a native `IDBKeyRange` wherever the native call is already readable — `IDBKeyRange.only` for one key, `IDBKeyRange.bound` for a lower and an upper boundary.
316
+ The single-boundary builders each fix a native boolean argument that reads as nothing at the call site. `rangePrefix` closes the range at the prefix's successor, excluded: the prefix with its trailing U+FFFF code units dropped and its final code unit incremented, so `rangePrefix('user:')` ends before `'user;'` and still holds a key that continues past U+FFFF after the prefix. An empty prefix, or one of U+FFFF alone, has no successor and closes at an empty binary key, excluded (`IDBKeyRange.bound(value, new ArrayBuffer(0), false, true)`): IndexedDB orders every string below every binary and array key, so no key that is not a string enters a prefix range. Pass a native `IDBKeyRange` wherever the native call is already readable — `IDBKeyRange.only` for one key, `IDBKeyRange.bound` for a lower and an upper boundary.
305
317
 
306
318
  ### Cursor streaming and in-place mutation
307
319
 
@@ -310,12 +322,12 @@ Streams a store's records with a cursor, removing a record in place as the loop
310
322
  ```ts
311
323
  let cursor = await db.store('users').cursor()
312
324
  while (cursor) {
313
- if (cursor.value?.active === false) await cursor.remove()
325
+ if (cursor.value.active === false) await cursor.remove()
314
326
  cursor = await cursor.continue()
315
327
  }
316
328
  ```
317
329
 
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.
330
+ 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 a `StoreRecord`, checked with `isRecord` when you read it: a stored value that is no record raises `RECORD` at that read, naming the store, the index on an index cursor, and the `primary` key. No other member reads the value, so the cursor still stops on that position, still exposes its `key` and `primary`, and a store cursor's `remove` deletes the entry.
319
331
 
320
332
  ### Seeking an index cursor to one primary key
321
333
 
@@ -410,19 +422,19 @@ wrapDOMException(null) // the same DOMException → IndexedDBError mapping every
410
422
  Branches on a typed `IndexedDBError` code, falling back to an upsert when an insert collides on a duplicate key.
411
423
 
412
424
  ```ts
413
- import { IndexedDBError } from '@orkestrel/indexeddb'
425
+ import { isIndexedDBError } from '@orkestrel/indexeddb'
414
426
 
415
427
  // Insert if new, fall back to upsert on a duplicate-key collision.
416
428
  try {
417
429
  await db.store('users').add({ id: 'u1', name: 'Ada' })
418
430
  } catch (error) {
419
- if (error instanceof IndexedDBError && error.code === 'CONSTRAINT') {
431
+ if (isIndexedDBError(error) && error.code === 'CONSTRAINT') {
420
432
  await db.store('users').set({ id: 'u1', name: 'Ada' })
421
433
  } else throw error
422
434
  }
423
435
  ```
424
436
 
425
- Every terminal native `DOMException` crosses the request boundary as an `IndexedDBError` carrying a machine-readable `code` (`CONSTRAINT`, `NOT_FOUND`, `QUOTA`, `ABORTED`, `READONLY`, `DATA`, …), so a `catch` branches on `error.code` rather than parsing a message string. A native `blocked` notification is not a terminal exception and has no error code; the operation remains pending. `ReadOnlyError` (a write attempted on a `readonly` transaction — for example mutating through a cursor opened by `index(...).cursor()`, which always runs read-only) maps to `READONLY`; both `DataError` (an invalid key) and `DataCloneError` (a value IndexedDB's structured clone cannot serialize, for example a function) map to `DATA`.
437
+ Every terminal native `DOMException` crosses the request boundary as an `IndexedDBError` carrying a machine-readable `code` (`CONSTRAINT`, `NOT_FOUND`, `QUOTA`, `ABORTED`, `READONLY`, `DATA`, …), so a `catch` branches on `error.code` rather than parsing a message string. A native `blocked` notification is not a terminal exception and has no error code; the operation remains pending. `ReadOnlyError` (a write attempted on a `readonly` transaction — for example mutating through a cursor opened by `index(...).cursor()`, which always runs read-only) maps to `READONLY`; `DATA` names a malformed caller argument and has two origins. Native `DataError` (an invalid key) and `DataCloneError` (a value IndexedDB's structured clone cannot serialize, for example a function) map to it, with the native error as `cause`. The wrapper raises it itself when it refuses a malformed argument, with `context` and no native cause: a database constructor refusal carries `{ faults }` for every malformed option at once among options that are JSON data, or `{ clone }` with the contract clone error as `cause` when any option is not JSON data contract can clone, which hides the faults of every other option, and `context.stores.create` and `context.indexes.create` carry `{ store, faults }`. `OPEN` stays for an open that fails. `RECORD` is the wrapper's own code for a fault in the stored data: a read found a value that is no record, and the remedy is to rewrite or remove that entry (see invariant 7).
426
438
 
427
439
  ### Narrowing a caught value with `isIndexedDBError`
428
440
 
@@ -442,7 +454,7 @@ try {
442
454
 
443
455
  ### Versioned upgrades: dropping a store, indexing an existing store, migrating data
444
456
 
445
- > **The auto-commit rule.** A transaction — including the versionchange transaction `upgrade` runs in — commits the moment control returns to the event loop with no pending IndexedDB request. Every step inside `upgrade` (and inside any `read` / `write` scope) must be an awaited IndexedDB request; a non-IDB `await` (a `fetch`, a `setTimeout`, an unrelated Promise) lets the transaction auto-commit out from under you, so any later `IndexedDBTransactionStoreInterface` call on it fails `INACTIVE` — every request-issuing call wraps its synchronous native invocation so this (and a closed-connection `INVALID`) surfaces as a typed `IndexedDBError`, the same as an asynchronous fault. This is also why there is no returnable, held-open transaction handle on this wrapper — IndexedDB itself auto-commits any transaction that isn't driven promptly, so a handle you could stash and use later would be broken by design; `read` / `write` and `upgrade` exist specifically to keep the whole scope on the stack instead. The built-in create-missing pass and the custom callback share one capture boundary, and every schema verb on the upgrade's managers — `context.stores.create` / `context.stores.drop` / `context.stores.store` / `context.indexes.create` / `context.indexes.drop` — goes through `wrapCall`, so synchronous schema faults are retained as the `UPGRADE` error's typed cause rather than escaping as raw `DOMException`s. A custom rejection captured while the versionchange transaction remains active aborts that same transaction and rolls the whole upgrade back. If auto-commit wins first but the rejection is recorded before the open success event, `connect()` still closes that connection and rejects, but the committed schema cannot be reversed. The wrapper cannot retroactively turn an already-resolved `connect()` into a rejection: if the open request succeeded before the custom Promise rejected, that late rejection is outside the recoverable boundary.
457
+ > **The auto-commit rule.** A transaction — including the versionchange transaction `upgrade` runs in — commits the moment control returns to the event loop with no pending IndexedDB request. Every step inside `upgrade` (and inside any `read` / `write` scope) must be an awaited IndexedDB request; a non-IDB `await` (a `fetch`, a `setTimeout`, an unrelated Promise) lets the transaction auto-commit out from under you, so any later `IndexedDBTransactionStoreInterface` call on it fails `INACTIVE` — every request-issuing call wraps its synchronous native invocation so this (and a closed-connection `INVALID`) surfaces as a typed `IndexedDBError`, the same as an asynchronous fault. This is also why there is no returnable, held-open transaction handle on this wrapper — IndexedDB itself auto-commits any transaction that isn't driven promptly, so a handle you could stash and use later would be broken by design; `read` / `write` and `upgrade` exist specifically to keep the whole scope on the stack instead. The built-in create-missing pass, the custom callback, and the built-in index pass after it share one capture boundary, and every schema verb on the upgrade's managers — `context.stores.create` / `context.stores.drop` / `context.stores.store` / `context.indexes.create` / `context.indexes.drop` — goes through `wrapCall`, so synchronous schema faults are retained as the `UPGRADE` error's typed cause rather than escaping as raw `DOMException`s. A custom rejection captured while the versionchange transaction remains active aborts that same transaction and rolls the whole upgrade back. If auto-commit wins first but the rejection is recorded before the open success event, `connect()` still closes that connection and rejects, but the committed schema cannot be reversed. The wrapper cannot retroactively turn an already-resolved `connect()` into a rejection: if the open request succeeded before the custom Promise rejected, that late rejection is outside the recoverable boundary.
446
458
  >
447
459
  > `upgrade` may return `void` or a `Promise<void>` — an async `upgrade` can `await` the IDB requests it issues through `context.stores.store(...)`, subject to the same rule. A rejection captured while the transaction is active aborts it and rejects the pending `connect()` with a typed `IndexedDBError` (code `UPGRADE`) rather than an unhandled rejection. The initiating value is preserved as `cause`, including an explicitly rejected `undefined`; a failure does not poison the handle, so a later `connect()` starts a fresh attempt.
448
460
 
@@ -459,9 +471,9 @@ const db = createIndexedDBDatabase({
459
471
  // Create a store the built-in create-missing pass doesn't cover because it
460
472
  // isn't declared in `stores` — app-internal bookkeeping, for example.
461
473
  context.stores.create('meta', { path: 'key' })
462
- // The built-in pass only creates missing stores, so an index on an
463
- // already-existing store goes through the index manager; `drop` is its
464
- // inverse, over an index a prior version left behind.
474
+ // A declared index the store lacks is created by the built-in index pass
475
+ // after this callback, which finds `byName` present when the callback
476
+ // creates it first; `drop` removes an index a prior version left behind.
465
477
  context.indexes.create('users', { name: 'byName', path: 'name' })
466
478
  context.indexes.drop('users', 'byRetired')
467
479
  // Migrate data in place, awaiting only the IDB requests `store()` issues.
@@ -484,20 +496,22 @@ await db.connect()
484
496
  - **Reach for the key-range helpers** instead of reading everything and filtering in JS; an index plus a key range is the wrapper's whole point.
485
497
  - **A live connection yields to another tab's upgrade, and recovers from an abnormal close.** The database wires the native `onversionchange` event to close itself, so a second tab (or a second `IndexedDBDatabaseInterface` in the same page) opening at a higher version is never blocked indefinitely. Because that `close()` is self-initiated, the native `close` event does NOT fire for it — so the `onversionchange` handler also clears its own latches directly. The native `onclose` event — fired for an ABNORMAL, browser-initiated close (a crashed connection, storage eviction) that this handle did not request — clears the SAME latches, so either path leaves the handle able to lazily reconnect on its next operation rather than failing `NOT_OPEN` (or a stale, dead connection) forever. Without this, two open tabs over the same database can hang forever, and an abnormal close would permanently wedge the handle.
486
498
  - **Storage persistence is app policy, not this wrapper's job.** Whether the browser is allowed to evict a database under storage pressure (`navigator.storage.persist()`) is a call the consuming application makes — this wrapper does not surface a `durability` option or any persistence API; it stays strictly on the raw IndexedDB CRUD/schema surface.
487
- - **Safari quirks — untested here, Chromium-only CI.** This package's test suite runs against real Chromium only. Safari has historically shipped `getAll` bugs and first-transaction-after-upgrade quirks on some versions; if you must support Safari, verify your exact schema and upgrade path there directly rather than assuming Chromium parity.
499
+ - **The suite runs on Chromium alone.** Every browser proof in this package runs against real Chromium through Playwright. Firefox and WebKit, Safari's engine included, are unproven until a consumer ships to one; before you ship to either, run your own schema, upgrade path, and reads there rather than assuming Chromium parity.
488
500
 
489
501
  ## Tests
490
502
 
491
503
  - [`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.
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`.
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.
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.
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.
496
- - [`tests/src/browser/IndexedDBCursor.test.ts`](../tests/src/browser/IndexedDBCursor.test.ts) — the store/index cursor: the position snapshot (`key` / `primary` / `value` / `direction`), the moves (`continue` / `seek` / `advance`), `seek` on a store cursor rejecting with `UNKNOWN`, in-place `update` / `remove`, an index cursor's `update` / `remove` rejecting with `READONLY`, and a non-record stored value reading `undefined` from `value`.
497
- - [`tests/src/browser/IndexedDBTransaction.test.ts`](../tests/src/browser/IndexedDBTransaction.test.ts) — the transaction from a `read` / `write` scope: metadata getters, scoped `store` access with its out-of-scope guard, and `abort` / `commit` with their already-finished `INACTIVE` faults.
498
- - [`tests/src/browser/IndexedDBTransactionStore.test.ts`](../tests/src/browser/IndexedDBTransactionStore.test.ts) — the scoped store reached through `transaction.store(name)`: the same keyed CRUD surface as a standalone store but bound to the owning transaction (so a sequence of reads and writes is atomic), without `index`, and a real `INACTIVE` fault after the owning transaction auto-commits out from under a captured store.
504
+ - [`tests/src/browser/helpers.test.ts`](../tests/src/browser/helpers.test.ts) — the `supportsIndexedDB` probe (and its `false` while `indexedDB` reads `null`), the key-range helpers asserted on the bounds they return, the shared read primitives (`readRecord` / `readRecords` / `hasKey`) over a real store / index (including the `RECORD` raise for a stored value that is no record, with the `context` each read names, and the index point read pair naming its primary key while the caller removes the entry), `scanIndex` over a matching index and each differing member, the exact `RECORD` message naming a quote-bearing store and index name and one past 64 characters, `rangePrefix` closing at the exact successor, and at an empty binary key where no successor exists, `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`.
505
+ - [`tests/src/browser/validators.test.ts`](../tests/src/browser/validators.test.ts) — `isIndexedDBErrorCode` bound to `IndexedDBErrorCode` at compile time, admitting each declared code and every code `ERROR_CODES` produces, and refusing adjacent strings and every non-string.
506
+ - [`tests/src/browser/contracts.test.ts`](../tests/src/browser/contracts.test.ts) — each definition shape bound to its declared type at compile time, and each contract admitting the declared forms and refusing a member of the wrong type, a missing member, an undeclared member, a class instance, and an optional member present as `undefined` (an index optional, and a store `increment` or `path`), admitting an empty list as a key path, with the audit naming the offending member path; the options shape bound to `IndexedDBDatabaseOptions` apart from `upgrade`, which it reads as the `"function"` literal; and the options contract auditing every malformed option in one pass.
507
+ - [`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; and the declared index reconcile: an auto-managed reopen creating a declared index with the rows unchanged and an identical reopen moving no version, a pinned bump creating one with no callback, a differing stored index rejecting `connect()` with `UPGRADE` naming the store and index on a pinned and on an auto-managed open, an undeclared index a callback created surviving a later bump, a pinned open at the stored version leaving a missing declared index absent, the mismatch rejection carrying `{ store, index }` on itself and on its cause, and a callback that aborts the versionchange transaction itself, synchronously or after an awaited request, rejecting `connect()` with `UPGRADE` over `ABORTED` over the native `AbortError` with the version kept; a lower pinned version rejecting `OPEN` over the native `VersionError`, not `UPGRADE`; construction refusing with `DATA` every option the types forbid, a class instance and a store optional present as `undefined` included, with three malformed options named in one refusal and each refusal's exact `context.faults`, the string `'function'`, `null`, a number, an object whose `toString` returns `'function'`, a version or an upgrade present as `undefined`, and a class instance as options each refused, a bound function and an async function admitted as `upgrade`, and a caller's change to its own `stores`, `name`, `version`, or `upgrade` after construction reaching nothing the database creates, each options getter read once on admission and on refusal with the refusal naming the fault of that one read, a getter on a store definition refused at the clone without being read, an empty key path and an empty index list admitted, and a schema past the clone node limit and a version that is not finite refused naming their clone cause, naming every malformed store and member and carrying the faults in `context`; `context.stores.create` and `context.indexes.create` refusing a definition outside its type with `DATA`, a class instance and an optional member present as `undefined` included, at the store level as at the index level; and the exact message of each refusal that names a caller value, driven with a quote-bearing name and one past the 64 characters a preview keeps.
508
+ - [`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, the prefix read of a key that continues past U+FFFF and of a prefix with no successor beside an array key and a binary key, the `NOT_FOUND` / `CONSTRAINT` / `DATA` (a non-cloneable value, an invalid key) faults, `RECORD` from `get` / `resolve` / `records` while `count` / `has` / `keys` still read the entry, one request for a clean bulk read beside three for a failing one, one request for a clean point read on a store and on an index, a message that encodes a 1 MB key or a quote-bearing key through a capped preview while `context.key` keeps the raw key, and an undeclared index name written through the same preview.
509
+ - [`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, a `resolve` miss whose message writes a 1 MB key or a quote-bearing key through a capped preview while `context.key` keeps the raw key, the `multiple` (multiEntry) array index, the primary key a failing read names among rows sharing an index key, and `RECORD` from `get` / `resolve` / `records` while `count` / `has` / `keys` / `primary` still read the entry.
510
+ - [`tests/src/browser/IndexedDBCursor.test.ts`](../tests/src/browser/IndexedDBCursor.test.ts) — the store/index cursor: the position snapshot (`key` / `primary` / `value` / `direction`), the moves (`continue` / `seek` / `advance`), `seek` on a store cursor rejecting with `UNKNOWN`, in-place `update` / `remove`, an index cursor's `update` / `remove` rejecting with `READONLY`, and `RECORD` raised at the `value` read of a stored value that is no record, on a store cursor and on an index cursor, with `key` / `primary` / `remove` still working at that position.
511
+ - [`tests/src/browser/IndexedDBTransaction.test.ts`](../tests/src/browser/IndexedDBTransaction.test.ts) — the transaction from a `read` / `write` scope: metadata getters, scoped `store` access with its out-of-scope guard, `abort` / `commit` with their already-finished `INACTIVE` faults, and the exact out-of-scope and no-longer-active messages with a quote-bearing store name and one past 64 characters.
512
+ - [`tests/src/browser/IndexedDBTransactionStore.test.ts`](../tests/src/browser/IndexedDBTransactionStore.test.ts) — the scoped store reached through `transaction.store(name)`: the same keyed CRUD surface as a standalone store but bound to the owning transaction (so a sequence of reads and writes is atomic), without `index`, a real `INACTIVE` fault after the owning transaction auto-commits out from under a captured store, a `resolve` miss whose message writes a 1 MB key or a quote-bearing key through a capped preview, `RECORD` from `get` / `resolve` / `records` inside a scope, and the key a failing bulk read names beside the caller's own removal: none when the removal runs first, `k02` when the number sits there, and the key the pair read when the removal follows a read queued behind, with the late key-list form as the control that names a valid record.
499
513
  - [`tests/src/browser/factories.test.ts`](../tests/src/browser/factories.test.ts) — `createIndexedDBDatabase` returns a working `IndexedDBDatabaseInterface` that connects lazily, creates its declared stores and indexes, and round-trips real data.
500
- - [`tests/src/browser/integration.test.ts`](../tests/src/browser/integration.test.ts) — this guide's flagship fences, transcribed and executed against real Chromium storage: each case runs one fence over a uniquely-named database and asserts the value that fence's comments claim, so a comment the code contradicts fails here. `tests/guides.test.ts` carries the presence guard beside each transcription, proving the transcribed lines are still the documented ones.
514
+ - [`tests/src/browser/integration.test.ts`](../tests/src/browser/integration.test.ts) — this guide's flagship fences, transcribed and executed against real Chromium storage: each case runs one fence over a uniquely-named database and asserts the value that fence's comments claim, so a comment the code contradicts fails here. It also executes invariant 7 through `readRecordClaim`: `count` 3, `has` true, keys `a` `b` `c`, and `RECORD` with `{ store: 'books', key: 'b' }` from `get`, `resolve`, `records`, and a cursor's `value`, with no stored value in any message. `tests/guides.test.ts` carries the presence guard beside each transcription, proving the transcribed lines are still the documented ones.
501
515
 
502
516
  ## See also
503
517