@orkestrel/scaffold 0.0.114 → 0.0.116

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 (108) hide show
  1. package/dist/bin/main.js +137 -15
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/orchestration.md +5 -3
  4. package/dist/host/agents/platforms/windows.md +1 -0
  5. package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +4 -4
  7. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -1
  8. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +8 -2
  9. package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +1 -0
  10. package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
  11. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
  12. package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
  13. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +9 -3
  14. package/dist/host/claude/agents/analyst.md +1 -1
  15. package/dist/host/claude/agents/astra.md +2 -2
  16. package/dist/host/claude/agents/builder.md +4 -4
  17. package/dist/host/claude/agents/opus.md +3 -3
  18. package/dist/host/claude/agents/orkestrel.md +5 -7
  19. package/dist/host/claude/agents/planner.md +8 -2
  20. package/dist/host/claude/rules/campaign.md +2 -1
  21. package/dist/host/claude/rules/documentation.md +1 -0
  22. package/dist/host/claude/rules/names.md +3 -1
  23. package/dist/host/claude/rules/tests.md +7 -4
  24. package/dist/host/claude/rules/writing.md +1 -0
  25. package/dist/host/claude/skills/enterprise-bootstrap/SKILL.md +1 -2
  26. package/dist/host/claude/skills/orkestrel-align/SKILL.md +1 -1
  27. package/dist/host/claude/skills/orkestrel-build/SKILL.md +1 -2
  28. package/dist/host/claude/skills/orkestrel-debrief/SKILL.md +1 -2
  29. package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
  30. package/dist/host/claude/skills/orkestrel-falsify/SKILL.md +1 -1
  31. package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
  32. package/dist/host/claude/skills/orkestrel-journey/SKILL.md +1 -1
  33. package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
  34. package/dist/host/claude/skills/orkestrel-polish/SKILL.md +1 -2
  35. package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -2
  36. package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
  37. package/dist/host/codex/agents/analyst.toml +8 -5
  38. package/dist/host/codex/agents/astra.toml +4 -5
  39. package/dist/host/codex/agents/builder.toml +5 -5
  40. package/dist/host/codex/agents/opus.toml +3 -4
  41. package/dist/host/codex/agents/orkestrel.toml +2 -1
  42. package/dist/host/codex/agents/planner.toml +8 -5
  43. package/dist/host/codex/agents/reviewer.toml +5 -4
  44. package/dist/host/guides/abort.md +17 -17
  45. package/dist/host/guides/agent.md +445 -445
  46. package/dist/host/guides/brief.md +143 -143
  47. package/dist/host/guides/browser.md +731 -731
  48. package/dist/host/guides/budget.md +39 -39
  49. package/dist/host/guides/capture.md +298 -298
  50. package/dist/host/guides/console.md +109 -109
  51. package/dist/host/guides/contract.md +335 -335
  52. package/dist/host/guides/csv.md +30 -30
  53. package/dist/host/guides/database.md +163 -163
  54. package/dist/host/guides/emitter.md +17 -17
  55. package/dist/host/guides/form.md +99 -99
  56. package/dist/host/guides/guide.md +361 -183
  57. package/dist/host/guides/html.md +49 -49
  58. package/dist/host/guides/indexeddb.md +40 -40
  59. package/dist/host/guides/interpret.md +139 -139
  60. package/dist/host/guides/lsp.md +114 -114
  61. package/dist/host/guides/markdown.md +68 -68
  62. package/dist/host/guides/mcp.md +3745 -3745
  63. package/dist/host/guides/middleware.md +170 -170
  64. package/dist/host/guides/msg.md +95 -95
  65. package/dist/host/guides/ndjson.md +8 -8
  66. package/dist/host/guides/ollama.md +56 -56
  67. package/dist/host/guides/pool.md +21 -21
  68. package/dist/host/guides/probe.md +82 -82
  69. package/dist/host/guides/process.md +99 -99
  70. package/dist/host/guides/program.md +98 -96
  71. package/dist/host/guides/qualifier.md +70 -70
  72. package/dist/host/guides/queue.md +37 -37
  73. package/dist/host/guides/rater.md +38 -38
  74. package/dist/host/guides/reason.md +308 -308
  75. package/dist/host/guides/relation.md +50 -50
  76. package/dist/host/guides/router.md +58 -58
  77. package/dist/host/guides/scaffold.md +554 -419
  78. package/dist/host/guides/sea.md +128 -128
  79. package/dist/host/guides/server.md +100 -100
  80. package/dist/host/guides/sqlite.md +28 -28
  81. package/dist/host/guides/sse.md +20 -20
  82. package/dist/host/guides/study.md +444 -444
  83. package/dist/host/guides/table.md +82 -82
  84. package/dist/host/guides/template.md +41 -41
  85. package/dist/host/guides/terminal.md +121 -121
  86. package/dist/host/guides/test.md +273 -273
  87. package/dist/host/guides/timeout.md +18 -18
  88. package/dist/host/guides/tool.md +27 -27
  89. package/dist/host/guides/toolbox.md +166 -166
  90. package/dist/host/guides/websocket.md +54 -54
  91. package/dist/host/guides/worker.md +24 -24
  92. package/dist/host/guides/workflow.md +187 -187
  93. package/dist/host/guides/workspace.md +55 -55
  94. package/dist/host/manifest.json +93 -93
  95. package/dist/host/tests/setupPolicy.ts +5 -3
  96. package/dist/src/core/index.cjs +89 -3
  97. package/dist/src/core/index.cjs.map +1 -1
  98. package/dist/src/core/index.d.cts +229 -144
  99. package/dist/src/core/index.d.ts +229 -144
  100. package/dist/src/core/index.js +87 -4
  101. package/dist/src/core/index.js.map +1 -1
  102. package/dist/src/server/index.cjs +292 -66
  103. package/dist/src/server/index.cjs.map +1 -1
  104. package/dist/src/server/index.d.cts +188 -6
  105. package/dist/src/server/index.d.ts +188 -6
  106. package/dist/src/server/index.js +287 -69
  107. package/dist/src/server/index.js.map +1 -1
  108. package/package.json +4 -3
@@ -73,41 +73,41 @@ produces the JSON Schema, and seeds fixtures.
73
73
 
74
74
  ### Factories
75
75
 
76
- | API | Kind | Summary |
77
- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
78
- | `createDatabase` | function | Creates a database over a driver and a declared `tables` schema. |
79
- | `createMemoryDriver` | function | Creates the in-memory reference `DriverInterface`. |
80
- | `createJSONDriver` | function | Creates a persistent JSON-file `DriverInterface` for a given path. |
81
- | `createSQLiteDriver` | function | Creates a trusted-mode, server-native SQLite `DriverInterface` for a database path, or for `:memory:` when the options bag omits one. |
82
- | `createIndexedDBDriver` | function | Creates a persistent IndexedDB `DriverInterface` for a browser database name. |
76
+ | Name | Kind | Signature | Summary |
77
+ | ----------------------- | -------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
78
+ | `createDatabase` | function | `<const T extends TableMap>(options: DatabaseOptions<T>) => DatabaseInterface<T>` | Creates a database over a driver and a declared `tables` schema. |
79
+ | `createMemoryDriver` | function | `() => DriverInterface` | Creates the in-memory reference `DriverInterface`. |
80
+ | `createJSONDriver` | function | `(path: string) => DriverInterface` | Creates a persistent JSON-file `DriverInterface` for a given path. |
81
+ | `createSQLiteDriver` | function | `(options?: SQLiteDriverOptions) => DriverInterface` | Creates a trusted-mode, server-native SQLite `DriverInterface` for a database path, or for `:memory:` when the options bag omits one. |
82
+ | `createIndexedDBDriver` | function | `(name: string) => DriverInterface` | Creates a persistent IndexedDB `DriverInterface` for a browser database name. |
83
83
 
84
84
  ### Classes
85
85
 
86
- | Class | Kind | Summary |
87
- | ------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
88
- | `Database` | class | Exposes a typed view over one shared internal lifecycle and storage context. |
89
- | `DriverIterator` | class | Forms the internal continuation boundary for a root driver async iterator. |
90
- | `MemoryDriver` | class | Implements the reference `DriverInterface` — nested maps, no I/O. |
91
- | `JSONDriver` | class | Implements a persistent `DriverInterface` backed by a single JSON file — the reference `MemoryDriver` plus file load / flush. |
92
- | `SQLiteDriver` | class | Implements the `DriverInterface` over SQLite — the server-native, trusted-mode backend built on the published `@orkestrel/sqlite` synchronous wrapper. |
93
- | `IndexedDBDriver` | class | Implements the `DriverInterface` over IndexedDB — the persistent browser backend, built on the published `@orkestrel/indexeddb` wrapper. |
94
- | `StreamPage` | class | Tracks the matching-row position of one streaming page. |
95
- | `JSONTransaction` | class | Owns the isolated memory store and schema of one JSON transaction. |
96
- | `SQLiteTransaction` | class | Owns the candidate schema and table identities of one SQLite transaction. |
86
+ | Name | Kind | Signature | Summary |
87
+ | ------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
88
+ | `Database` | class | `new <T extends TableMap = TableMap>(options: DatabaseOptions<T>) => DatabaseInterface<T>` | Exposes a typed view over one shared internal lifecycle and storage context. |
89
+ | `DriverIterator` | class | `new <T>(source: AsyncIterator<T>, guard: () => void) => AsyncIterableIterator<T>` | Forms the internal continuation boundary for a root driver async iterator. |
90
+ | `MemoryDriver` | class | `new () => DriverInterface` | Implements the reference `DriverInterface` — nested maps, no I/O. |
91
+ | `JSONDriver` | class | `new (path: string) => DriverInterface` | Implements a persistent `DriverInterface` backed by a single JSON file — the reference `MemoryDriver` plus file load / flush. |
92
+ | `SQLiteDriver` | class | `new (options?: SQLiteDriverOptions) => DriverInterface` | Implements the `DriverInterface` over SQLite — the server-native, trusted-mode backend built on the published `@orkestrel/sqlite` synchronous wrapper. |
93
+ | `IndexedDBDriver` | class | `new (name: string) => DriverInterface` | Implements the `DriverInterface` over IndexedDB — the persistent browser backend, built on the published `@orkestrel/indexeddb` wrapper. |
94
+ | `StreamPage` | class | `new (offset: number) => StreamPage` | Tracks the matching-row position of one streaming page. |
95
+ | `JSONTransaction` | class | `new (memory: MemoryDriver, schema: readonly TableSchema[], identities: ReadonlyMap<string, object>) => JSONTransaction` | Owns the isolated memory store and schema of one JSON transaction. |
96
+ | `SQLiteTransaction` | class | `new (schema: ReadonlyMap<string, TableSchema>, identities: ReadonlyMap<string, object>) => SQLiteTransaction` | Owns the candidate schema and table identities of one SQLite transaction. |
97
97
 
98
98
  ### Server
99
99
 
100
- | API | Kind | Summary |
101
- | ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
102
- | `METADATA_TABLE` | const | Names the reserved metadata table the `SQLiteDriver` creates on `open` to persist its stamped `DriverMetadata` (`version` + declared schema JSON) — the SQLite realization of the `metadata` / `stamp` driver hooks. |
103
- | `matchesConditionExactly` | function | Reports whether one `Condition` compiles to SQL that is provably identical to the core engine's `matchesCondition` for every value its column's declared type can store. |
104
- | `matchesOrderExactly` | function | Reports whether one `Order` term's column compiles to an `ORDER BY` that matches the engine's `sortRows` exactly. |
105
- | `matchesQueryExactly` | function | Reports whether a whole `QueryInput` is exact — every condition and every order term is exact. `limit` / `offset` never affect exactness (SQL `LIMIT` / `OFFSET` are always engine-identical). |
106
- | `matchesDeclaredStorage` | function | Reports whether a value's runtime type matches a column's declared exact type — the operand side of the declared-type-trust proof. |
107
- | `EXACT_COLUMN_STORAGE` | const | Lists the declared `ColumnStorage`s whose SQL equality comparisons (`equals` / `not` / `any` / `none`) and `starts` / `ends` compiles are provably engine-exact under declared-type trust — `text` / `integer` / `real` / `boolean`; a `json` or `blob` column always refines instead. |
108
- | `EXACT_RANGE_COLUMN_STORAGE` | const | Lists the declared `ColumnStorage`s whose SQL range comparisons (`above` / `below` / `from` / `to` / `between`) and `ORDER BY` compiles are provably engine-exact — `integer` / `real` / `boolean` only. `text` is excluded: see `EXACT_COLUMN_STORAGE`'s remarks for the BINARY-collation (code-point) vs. JS `<` (code-unit) divergence on supplementary-plane characters. |
109
- | `extractValues` | function | Extracts a stored row's values in a declared positional order. |
110
- | `deriveSQLiteIndexName` | function | Builds a collision-free SQL index name for a table + column-group index — shared by the compiler module's `schemaToIndexes` and `stepToSQL`, so a plan-built index name always matches one `open` would have created. |
100
+ | Name | Kind | Signature | Summary |
101
+ | ---------------------------- | -------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
102
+ | `METADATA_TABLE` | const | `"_metadata"` | Names the reserved metadata table the `SQLiteDriver` creates on `open` to persist its stamped `DriverMetadata` (`version` + declared schema JSON) — the SQLite realization of the `metadata` / `stamp` driver hooks. |
103
+ | `matchesConditionExactly` | function | `(condition: Condition, schema: TableSchema) => boolean` | Reports whether one `Condition` compiles to SQL that is provably identical to the core engine's `matchesCondition` for every value its column's declared type can store. |
104
+ | `matchesOrderExactly` | function | `(order: Order, schema: TableSchema) => boolean` | Reports whether one `Order` term's column compiles to an `ORDER BY` that matches the engine's `sortRows` exactly. |
105
+ | `matchesQueryExactly` | function | `(input: QueryInput, schema: TableSchema) => boolean` | Reports whether a whole `QueryInput` is exact — every condition and every order term is exact. `limit` / `offset` never affect exactness (SQL `LIMIT` / `OFFSET` are always engine-identical). |
106
+ | `matchesDeclaredStorage` | function | `(value: unknown, storage: ColumnStorage) => boolean` | Reports whether a value's runtime type matches a column's declared exact type — the operand side of the declared-type-trust proof. |
107
+ | `EXACT_COLUMN_STORAGE` | const | `readonly ColumnStorage[]` | Lists the declared `ColumnStorage`s whose SQL equality comparisons (`equals` / `not` / `any` / `none`) and `starts` / `ends` compiles are provably engine-exact under declared-type trust — `text` / `integer` / `real` / `boolean`; a `json` or `blob` column always refines instead. |
108
+ | `EXACT_RANGE_COLUMN_STORAGE` | const | `readonly ColumnStorage[]` | Lists the declared `ColumnStorage`s whose SQL range comparisons (`above` / `below` / `from` / `to` / `between`) and `ORDER BY` compiles are provably engine-exact — `integer` / `real` / `boolean` only. `text` is excluded: see `EXACT_COLUMN_STORAGE`'s remarks for the BINARY-collation (code-point) vs. JS `<` (code-unit) divergence on supplementary-plane characters. |
109
+ | `extractValues` | function | `(row: SQLiteRow, names: readonly string[], table: string) => readonly SQLiteValue[]` | Extracts a stored row's values in a declared positional order. |
110
+ | `deriveSQLiteIndexName` | function | `(table: string, columns: readonly string[]) => string` | Builds a collision-free SQL index name for a table + column-group index — shared by the compiler module's `schemaToIndexes` and `stepToSQL`, so a plan-built index name always matches one `open` would have created. |
111
111
 
112
112
  ### SQL compilation
113
113
 
@@ -115,30 +115,30 @@ Pure, server-only functions that turn a core `QueryInput` / `TableSchema` into
115
115
  parameterized SQL text — the native-query payoff for a SQLite-backed driver.
116
116
  None of these import a SQLite package; they speak strings and values only.
117
117
 
118
- | API | Kind | Summary |
119
- | ------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
120
- | `inferValueStorage` | function | Reads the storage type a nested (`json_extract`) operand encodes as from its runtime value, never as `json`. |
121
- | `compileJSONTypeSQL` | function | Compiles a nested `FieldPath` to the `json_type(<col>, <path>)` SQL expression — the `compileFieldSQL` `json_extract` sibling used to tell a present JSON `null` apart from an absent path (both read back as SQL `NULL` through `json_extract`, but `json_type` reports `'null'` for the former and SQL `NULL` for the latter). |
122
- | `compileConditionSQL` | function | Compiles one condition to its `<column> <operator>` SQL fragment and the parameters it binds — engine-exact under SQL's three-valued NULL logic. |
123
- | `compileWhereSQL` | function | Folds the conditions into one WHERE clause, parenthesizing progressively left-to-right so the grouping matches the engine's `matchesQuery` fold. |
124
- | `compileOrderSQL` | function | Compiles the ORDER BY clause from the order terms, always ending with the primary key as the final determinant. |
125
- | `compilePageSQL` | function | Compiles the LIMIT / OFFSET clause. |
126
- | `compileQuerySQL` | function | Compiles a `QueryInput` into the SQL clause that follows a table name, with its bound parameters in clause order. |
127
- | `quoteIdentifier` | function | Quotes a SQL identifier (a table or column name) so any characters are literal. |
128
- | `compileFieldSQL` | function | Compiles a `FieldPath` to the SQL expression that reads it. |
129
- | `compileColumnSQL` | function | Maps a portable `ColumnStorage` to its SQLite column type. |
130
- | `compileAggregateSQL` | function | Compiles an `AggregateOperation` over a `FieldPath`. |
131
- | `matchesAggregateExactly` | function | Reports whether SQLite can execute an aggregate exactly like the core engine. |
132
- | `matchesSQLiteAffinity` | function | Checks a declared SQLite type against a portable storage affinity. |
133
- | `matchesAbsentPath` | function | Reports whether a caught filesystem error says that nothing is there to read. |
134
- | `encodeValue` | function | Encodes a JS value to its stored `SQLiteValue` for a declared column. |
135
- | `decodeValue` | function | Decodes a stored `SQLiteValue` back to its JS value for a declared column — the exact inverse of `encodeValue`. |
136
- | `encodeRow` | function | Encodes a whole `Row` to a `SQLiteRow` by its table's schema. |
137
- | `decodeRow` | function | Decodes a stored `SQLiteRow` back to a `Row` by its table's schema. |
138
- | `schemaToTable` | function | Projects a `TableSchema` to its `CREATE TABLE IF NOT EXISTS` statement. |
139
- | `schemaToIndexes` | function | Projects a `TableSchema` to its declared SQLite indexes. |
140
- | `stepToSQL` | function | Projects one `MigrationStep` to SQLite DDL. |
141
- | `compileBoundSQL` | function | Encodes condition operands for a SQL fragment using their declared or inferred storage. |
118
+ | Name | Kind | Signature | Summary |
119
+ | ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
120
+ | `inferValueStorage` | function | `(value: unknown) => ColumnStorage` | Reads the storage type a nested (`json_extract`) operand encodes as from its runtime value, never as `json`. |
121
+ | `compileJSONTypeSQL` | function | `(path: readonly string[]) => string` | Compiles a nested `FieldPath` to the `json_type(<col>, <path>)` SQL expression — the `compileFieldSQL` `json_extract` sibling used to tell a present JSON `null` apart from an absent path (both read back as SQL `NULL` through `json_extract`, but `json_type` reports `'null'` for the former and SQL `NULL` for the latter). |
122
+ | `compileConditionSQL` | function | `(condition: Condition, schema: TableSchema) => CompiledSQL` | Compiles one condition to its `<column> <operator>` SQL fragment and the parameters it binds — engine-exact under SQL's three-valued NULL logic. |
123
+ | `compileWhereSQL` | function | `(conditions: readonly Condition[], schema: TableSchema) => CompiledSQL` | Folds the conditions into one WHERE clause, parenthesizing progressively left-to-right so the grouping matches the engine's `matchesQuery` fold. |
124
+ | `compileOrderSQL` | function | `(order: readonly Order[] \| undefined, schema: TableSchema) => string` | Compiles the ORDER BY clause from the order terms, always ending with the primary key as the final determinant. |
125
+ | `compilePageSQL` | function | `(limit: number \| undefined, offset: number \| undefined) => CompiledSQL` | Compiles the LIMIT / OFFSET clause. |
126
+ | `compileQuerySQL` | function | `(input: QueryInput \| undefined, schema: TableSchema) => CompiledSQL` | Compiles a `QueryInput` into the SQL clause that follows a table name, with its bound parameters in clause order. |
127
+ | `quoteIdentifier` | function | `(identifier: string) => string` | Quotes a SQL identifier (a table or column name) so any characters are literal. |
128
+ | `compileFieldSQL` | function | `(path: FieldPath) => string` | Compiles a `FieldPath` to the SQL expression that reads it. |
129
+ | `compileColumnSQL` | function | `(storage: ColumnStorage) => string` | Maps a portable `ColumnStorage` to its SQLite column type. |
130
+ | `compileAggregateSQL` | function | `(operation: AggregateOperation, column: FieldPath) => string` | Compiles an `AggregateOperation` over a `FieldPath`. |
131
+ | `matchesAggregateExactly` | function | `(operation: AggregateOperation, column: FieldPath, schema: TableSchema) => boolean` | Reports whether SQLite can execute an aggregate exactly like the core engine. |
132
+ | `matchesSQLiteAffinity` | function | `(declared: unknown, storage: ColumnStorage) => boolean` | Checks a declared SQLite type against a portable storage affinity. |
133
+ | `matchesAbsentPath` | function | `(error: unknown) => boolean` | Reports whether a caught filesystem error says that nothing is there to read. |
134
+ | `encodeValue` | function | `(value: unknown, column: ColumnSchema) => SQLiteValue` | Encodes a JS value to its stored `SQLiteValue` for a declared column. |
135
+ | `decodeValue` | function | `(value: SQLiteValue, column: ColumnSchema) => unknown` | Decodes a stored `SQLiteValue` back to its JS value for a declared column — the exact inverse of `encodeValue`. |
136
+ | `encodeRow` | function | `(row: Row, schema: TableSchema) => SQLiteRow` | Encodes a whole `Row` to a `SQLiteRow` by its table's schema. |
137
+ | `decodeRow` | function | `(row: SQLiteRow, schema: TableSchema) => Row` | Decodes a stored `SQLiteRow` back to a `Row` by its table's schema. |
138
+ | `schemaToTable` | function | `(schema: TableSchema) => string` | Projects a `TableSchema` to its `CREATE TABLE IF NOT EXISTS` statement. |
139
+ | `schemaToIndexes` | function | `(schema: TableSchema) => readonly string[]` | Projects a `TableSchema` to its declared SQLite indexes. |
140
+ | `stepToSQL` | function | `(step: MigrationStep) => readonly string[]` | Projects one `MigrationStep` to SQLite DDL. |
141
+ | `compileBoundSQL` | function | `(sql: string, values: readonly unknown[], nested: boolean, declared: ColumnSchema \| undefined) => CompiledSQL` | Encodes condition operands for a SQL fragment using their declared or inferred storage. |
142
142
 
143
143
  ### Browser
144
144
 
@@ -146,23 +146,23 @@ Pure functions behind the IndexedDB driver's key-range pushdown planner — a
146
146
  candidate superset the core engine then refines to the exact result, never
147
147
  lossy.
148
148
 
149
- | API | Kind | Summary |
150
- | -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
151
- | `selectPlan` | function | Plans an IndexedDB read for a `QueryInput` — picks the index (or the primary store) and `IDBKeyRange` to narrow by, falling back to a full scan. |
152
- | `conditionToRange` | function | Translates one `Condition` to the `IDBKeyRange` it maps to, when its operator is one of the exact key comparisons over scalar operands; otherwise returns `undefined`. |
153
- | `INDEXABLE_STORAGE` | const | Lists the declared `ColumnStorage`s that are valid, orderable IndexedDB keys. |
154
- | `METADATA_STORE` | const | Names the reserved out-of-line store `__metadata__` the `IndexedDBDriver` stamps its `DriverMetadata` into. |
155
- | `mapIndexedDBError` | function | Maps a backend `IndexedDBError` to the portable `DatabaseError` taxonomy — the default mapping used everywhere except inside `migrate()`. |
156
- | `mapMigrationError` | function | Maps a backend `IndexedDBError` to the portable `DatabaseError` taxonomy for use inside `migrate()` — the one context where `UPGRADE` means the migration itself failed, not a generic driver fault. |
157
- | `deriveIndexedDBIndexName` | function | Derives an IndexedDB index name for a declared column group — a bare column name for a single-column index, a deterministic collision-free encoding for a compound one. |
158
- | `schemaToStore` | function | Projects a table schema into the IndexedDB wrapper's store definition. |
149
+ | Name | Kind | Signature | Summary |
150
+ | -------------------------- | -------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
151
+ | `selectPlan` | function | `(input: QueryInput \| undefined, schema: TableSchema, available: readonly string[]) => QueryPlan` | Plans an IndexedDB read for a `QueryInput` — picks the index (or the primary store) and `IDBKeyRange` to narrow by, falling back to a full scan. |
152
+ | `conditionToRange` | function | `(condition: Condition) => IDBKeyRange \| undefined` | Translates one `Condition` to the `IDBKeyRange` it maps to, when its operator is one of the exact key comparisons over scalar operands; otherwise returns `undefined`. |
153
+ | `INDEXABLE_STORAGE` | const | `readonly ColumnStorage[]` | Lists the declared `ColumnStorage`s that are valid, orderable IndexedDB keys. |
154
+ | `METADATA_STORE` | const | `"__metadata__"` | Names the reserved out-of-line store `__metadata__` the `IndexedDBDriver` stamps its `DriverMetadata` into. |
155
+ | `mapIndexedDBError` | function | `(error: IndexedDBError) => DatabaseError` | Maps a backend `IndexedDBError` to the portable `DatabaseError` taxonomy — the default mapping used everywhere except inside `migrate()`. |
156
+ | `mapMigrationError` | function | `(error: IndexedDBError) => DatabaseError` | Maps a backend `IndexedDBError` to the portable `DatabaseError` taxonomy for use inside `migrate()` — the one context where `UPGRADE` means the migration itself failed, not a generic driver fault. |
157
+ | `deriveIndexedDBIndexName` | function | `(columns: readonly string[]) => string` | Derives an IndexedDB index name for a declared column group — a bare column name for a single-column index, a deterministic collision-free encoding for a compound one. |
158
+ | `schemaToStore` | function | `(schema: TableSchema) => StoreDefinition` | Projects a table schema into the IndexedDB wrapper's store definition. |
159
159
 
160
160
  ### Errors
161
161
 
162
- | API | Kind | Summary |
163
- | ----------------- | -------- | ----------------------------------------------------- |
164
- | `DatabaseError` | class | Represents an error thrown by the database layer. |
165
- | `isDatabaseError` | function | Narrows an unknown caught value to a `DatabaseError`. |
162
+ | Name | Kind | Signature | Summary |
163
+ | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
164
+ | `DatabaseError` | class | `new (code: DatabaseErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => DatabaseError` | Represents an error thrown by the database layer. |
165
+ | `isDatabaseError` | function | `(value: unknown) => value is DatabaseError` | Narrows an unknown caught value to a `DatabaseError`. |
166
166
 
167
167
  The constructor installs an own, non-enumerable, non-writable
168
168
  `Symbol.for('@orkestrel/database.DatabaseError')` property whose value is the
@@ -176,24 +176,24 @@ and plain objects carrying only the brand.
176
176
  The portable semantics every backend shares — pure, total functions the
177
177
  driver never re-implements.
178
178
 
179
- | Helper | Kind | Summary |
180
- | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
181
- | `compareValues` | function | Compares two arbitrary values under one total order — the comparator behind sorting and the range operators. |
182
- | `matchesCondition` | function | Evaluates one `Condition` against a row — the per-operator predicate. |
183
- | `matchesQuery` | function | Folds a row through a list of conditions, joining each by its connector. |
184
- | `sortRows` | function | Sorts rows by an ordering specification, leaving the input untouched. |
185
- | `applyQuery` | function | Applies a `QueryInput` to rows — filter, then sort, then page. |
186
- | `validatePage` | function | Validates the paging fields of a portable query. |
187
- | `computeAggregate` | function | Computes an aggregate over a column across rows. |
188
- | `extractKey` | function | Reads a row's primary key from a column, when it is a usable `Key`. |
189
- | `bindRowKey` | function | Returns a fresh row whose primary column is authoritatively bound to its storage key. |
190
- | `shapeToColumnSchema` | function | Projects one contract shape into a portable column schema. |
191
- | `findColumn` | function | Reads one flat column's declaration out of a table schema. |
192
- | `resolvePrimary` | function | Resolves the primary-key column one table keys its rows by. |
193
- | `requireColumns` | function | Requires one declared table's columns out of a table map. |
194
- | `shapeToColumnStorage` | function | Maps a column's `ContractShape` to its portable `ColumnStorage` — the value a `TableSchema` carries so a native backend can declare a real column. |
195
- | `filterRows` | function | Filters rows by a list of conditions — the shared basis for a table's count and aggregate paths (no sort/page, unlike `applyQuery`). |
196
- | `equalsValue` | function | Compares two values structurally by SameValueZero leaves — the comparator behind conformance checks and any test/fixture that needs "same data", not "same reference". |
179
+ | Name | Kind | Signature | Summary |
180
+ | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
181
+ | `compareValues` | function | `(left: unknown, right: unknown) => number` | Compares two arbitrary values under one total order — the comparator behind sorting and the range operators. |
182
+ | `matchesCondition` | function | `(row: Row, condition: Condition) => boolean` | Evaluates one `Condition` against a row — the per-operator predicate. |
183
+ | `matchesQuery` | function | `(row: Row, conditions: readonly Condition[]) => boolean` | Folds a row through a list of conditions, joining each by its connector. |
184
+ | `sortRows` | function | `(rows: readonly Row[], order: readonly Order[]) => readonly Row[]` | Sorts rows by an ordering specification, leaving the input untouched. |
185
+ | `applyQuery` | function | `(rows: readonly Row[], input?: QueryInput) => readonly Row[]` | Applies a `QueryInput` to rows — filter, then sort, then page. |
186
+ | `validatePage` | function | `(input?: QueryInput) => void` | Validates the paging fields of a portable query. |
187
+ | `computeAggregate` | function | `(rows: readonly unknown[], operation: AggregateOperation, column: FieldPath) => number \| undefined` | Computes an aggregate over a column across rows. |
188
+ | `extractKey` | function | `(row: Row, column: string) => Key \| undefined` | Reads a row's primary key from a column, when it is a usable `Key`. |
189
+ | `bindRowKey` | function | `(row: Row, primary: string, key: Key) => Row` | Returns a fresh row whose primary column is authoritatively bound to its storage key. |
190
+ | `shapeToColumnSchema` | function | `(name: string, shape: ContractShape) => ColumnSchema` | Projects one contract shape into a portable column schema. |
191
+ | `findColumn` | function | `(name: string, schema: TableSchema) => ColumnSchema \| undefined` | Reads one flat column's declaration out of a table schema. |
192
+ | `resolvePrimary` | function | `(primary: PrimaryMap, name: string) => string` | Resolves the primary-key column one table keys its rows by. |
193
+ | `requireColumns` | function | `(<T extends TableMap, K extends keyof T & string>(tables: T, name: K) => T[K]) & ((tables: TableMap, name: string) => ColumnMap)` | Requires one declared table's columns out of a table map. |
194
+ | `shapeToColumnStorage` | function | `(shape: ContractShape) => ColumnStorage` | Maps a column's `ContractShape` to its portable `ColumnStorage` — the value a `TableSchema` carries so a native backend can declare a real column. |
195
+ | `filterRows` | function | `(rows: readonly Row[], conditions: readonly Condition[]) => readonly Row[]` | Filters rows by a list of conditions — the shared basis for a table's count and aggregate paths (no sort/page, unlike `applyQuery`). |
196
+ | `equalsValue` | function | `(left: unknown, right: unknown) => boolean` | Compares two values structurally by SameValueZero leaves — the comparator behind conformance checks and any test/fixture that needs "same data", not "same reference". |
197
197
 
198
198
  For `minimum` and `maximum`, `computeAggregate` compares each numeric value
199
199
  with a scalar `Math.min` or `Math.max` call. The helper never passes a
@@ -201,9 +201,9 @@ row-sized argument list.
201
201
 
202
202
  ### Abort
203
203
 
204
- | API | Kind | Summary |
205
- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------- |
206
- | `checkAbort` | function | Throws when an `AbortSignal` has fired — the shared abort gate checked at operation boundaries and between streamed rows. |
204
+ | Name | Kind | Signature | Summary |
205
+ | ------------ | -------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
206
+ | `checkAbort` | function | `(signal: AbortSignal \| undefined) => void` | Throws when an `AbortSignal` has fired — the shared abort gate checked at operation boundaries and between streamed rows. |
207
207
 
208
208
  ### Migrations
209
209
 
@@ -211,52 +211,52 @@ Caller-driven schema migration — a pure structural diff plus a pure row
211
211
  transform. Versioning drivers persist reconciliation metadata through the paired
212
212
  `metadata` / `stamp` hooks.
213
213
 
214
- | API | Kind | Summary |
215
- | ------------------------ | -------- | ------------------------------------------------------------------------------- |
216
- | `planMigration` | function | Diffs a deployed and a declared table set structurally into a `Migration` plan. |
217
- | `migrateRows` | function | Applies one table's `MigrationStep`s to its rows — a pure row transform. |
218
- | `projectMigrationSchema` | function | Projects migration steps sequentially over a canonical validated owned schema. |
219
- | `normalizeDriverSchema` | function | Canonicalizes an unknown driver schema into a distinct deeply frozen snapshot. |
214
+ | Name | Kind | Signature | Summary |
215
+ | ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
216
+ | `planMigration` | function | `(deployed: readonly TableSchema[], declared: readonly TableSchema[], from?: number, to?: number) => Migration` | Diffs a deployed and a declared table set structurally into a `Migration` plan. |
217
+ | `migrateRows` | function | `(rows: readonly Row[], steps: readonly MigrationStep[]) => readonly Row[]` | Applies one table's `MigrationStep`s to its rows — a pure row transform. |
218
+ | `projectMigrationSchema` | function | `(schema: readonly TableSchema[], steps: readonly MigrationStep[]) => readonly TableSchema[]` | Projects migration steps sequentially over a canonical validated owned schema. |
219
+ | `normalizeDriverSchema` | function | `(value: unknown) => readonly TableSchema[]` | Canonicalizes an unknown driver schema into a distinct deeply frozen snapshot. |
220
220
 
221
221
  ### Conformance
222
222
 
223
- | API | Kind | Summary |
224
- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
225
- | `conformDriver` | function | Runs the driver-conformance battery, throwing on the first violated invariant — the fail-fast entry point most callers (test setup, CI smoke checks) want. |
226
- | `scanDriver` | function | Walks the driver-conformance battery against a fresh `DriverInterface` per phase, yielding one `ConformanceFinding` per violated invariant — the shared invariant suite every backend (in-memory, SQLite, IndexedDB) must uphold to be a drop-in `DriverInterface`. |
227
- | `auditDriver` | function | Runs the full driver-conformance battery and collects every violation — the audit entry point for a driver author who wants a complete report rather than a single fail-fast throw. |
223
+ | Name | Kind | Signature | Summary |
224
+ | --------------- | -------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
225
+ | `conformDriver` | function | `(factory: () => DriverInterface) => Promise<void>` | Runs the driver-conformance battery, throwing on the first violated invariant — the fail-fast entry point most callers (test setup, CI smoke checks) want. |
226
+ | `scanDriver` | function | `(factory: () => DriverInterface) => AsyncIterable<ConformanceFinding>` | Walks the driver-conformance battery against a fresh `DriverInterface` per phase, yielding one `ConformanceFinding` per violated invariant — the shared invariant suite every backend (in-memory, SQLite, IndexedDB) must uphold to be a drop-in `DriverInterface`. |
227
+ | `auditDriver` | function | `(factory: () => DriverInterface) => Promise<readonly ConformanceFinding[]>` | Runs the full driver-conformance battery and collects every violation — the audit entry point for a driver author who wants a complete report rather than a single fail-fast throw. |
228
228
 
229
229
  ### Helpers & guards
230
230
 
231
231
  Pure helpers behind the query engine's pattern matching.
232
232
 
233
- | API | Kind | Summary |
234
- | ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
235
- | `cloneDriverMetadata` | function | Clones unknown driver metadata into a distinct deeply frozen snapshot. |
236
- | `matchesWildcardPattern` | function | Matches a value against a wildcard pattern in linear time — the shared, ReDoS-safe engine behind `matchesLikePattern` and `matchesGlobPattern`. |
237
- | `matchesWildcardSegment` | function | Checks whether a fixed-length wildcard segment matches a value at an offset. |
238
- | `matchesLikePattern` | function | Matches a value against a SQL `LIKE` pattern, folding case. |
239
- | `matchesGlobPattern` | function | Matches a value against a `GLOB` pattern, preserving case. |
240
- | `isDriverMetadata` | function | Checks whether a value is persisted driver metadata. |
241
- | `isDriverSchema` | function | Checks whether a value is a complete portable driver schema. |
242
- | `isColumnSchema` | function | Checks whether a value is a portable column schema. |
243
- | `isTableSchema` | function | Checks whether a value is a portable table schema. |
244
- | `isMigrationStep` | function | Checks whether a value is one ordered migration step. |
245
- | `isMigration` | function | Checks whether a value is an ordered migration plan. |
246
- | `isMigrationInput` | function | Checks whether a value is one atomic migration request. |
247
- | `isKey` | function | Checks whether a value is a usable database key. |
248
- | `cloneDriverSchema` | function | Clones unknown driver schema into a distinct deeply frozen snapshot. |
249
- | `cloneMigrationInput` | function | Clones unknown migration input into a distinct deeply frozen snapshot. |
250
- | `captureFailure` | function | Captures the exact rejection or synchronous throw from a driver conformance operation. |
233
+ | Name | Kind | Signature | Summary |
234
+ | ------------------------ | -------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
235
+ | `cloneDriverMetadata` | function | `(value: unknown) => DriverMetadata` | Clones unknown driver metadata into a distinct deeply frozen snapshot. |
236
+ | `matchesWildcardPattern` | function | `(value: string, pattern: string, any: string, single: string, fold: boolean) => boolean` | Matches a value against a wildcard pattern in linear time — the shared, ReDoS-safe engine behind `matchesLikePattern` and `matchesGlobPattern`. |
237
+ | `matchesWildcardSegment` | function | `(value: string, segment: string, at: number, single: string) => boolean` | Checks whether a fixed-length wildcard segment matches a value at an offset. |
238
+ | `matchesLikePattern` | function | `(value: string, pattern: string) => boolean` | Matches a value against a SQL `LIKE` pattern, folding case. |
239
+ | `matchesGlobPattern` | function | `(value: string, pattern: string) => boolean` | Matches a value against a `GLOB` pattern, preserving case. |
240
+ | `isDriverMetadata` | function | `(value: unknown) => value is DriverMetadata` | Checks whether a value is persisted driver metadata. |
241
+ | `isDriverSchema` | function | `(value: unknown) => value is readonly TableSchema[]` | Checks whether a value is a complete portable driver schema. |
242
+ | `isColumnSchema` | function | `(value: unknown) => value is ColumnSchema` | Checks whether a value is a portable column schema. |
243
+ | `isTableSchema` | function | `(value: unknown) => value is TableSchema` | Checks whether a value is a portable table schema. |
244
+ | `isMigrationStep` | function | `(value: unknown) => value is MigrationStep` | Checks whether a value is one ordered migration step. |
245
+ | `isMigration` | function | `(value: unknown) => value is Migration` | Checks whether a value is an ordered migration plan. |
246
+ | `isMigrationInput` | function | `(value: unknown) => value is MigrationInput` | Checks whether a value is one atomic migration request. |
247
+ | `isKey` | function | `(value: unknown) => value is Key` | Checks whether a value is a usable database key. |
248
+ | `cloneDriverSchema` | function | `(value: unknown) => readonly TableSchema[]` | Clones unknown driver schema into a distinct deeply frozen snapshot. |
249
+ | `cloneMigrationInput` | function | `(value: unknown) => MigrationInput` | Clones unknown migration input into a distinct deeply frozen snapshot. |
250
+ | `captureFailure` | function | `(operation: () => Promise<unknown>) => Promise<unknown>` | Captures the exact rejection or synchronous throw from a driver conformance operation. |
251
251
 
252
252
  ### Constants
253
253
 
254
254
  A `Shape` cell holds the constant's declared type.
255
255
 
256
- | Constant | Kind | Shape | Summary |
256
+ | Name | Kind | Signature | Summary |
257
257
  | -------------------------- | ----- | ------------------------ | ------------------------------------------------------------------------------------------------------------- |
258
- | `DEFAULT_PRIMARY` | const | `string` | Supplies the primary-key column, `'id'`, assumed when `PrimaryMap` does not name one. |
259
- | `MAX_PATTERN_LENGTH` | const | `number` | Sets the longest `LIKE` / `GLOB` pattern the wildcard matcher accepts, 1024 characters, before rejecting it. |
258
+ | `DEFAULT_PRIMARY` | const | `"id"` | Supplies the primary-key column, `'id'`, assumed when `PrimaryMap` does not name one. |
259
+ | `MAX_PATTERN_LENGTH` | const | `1024` | Sets the longest `LIKE` / `GLOB` pattern the wildcard matcher accepts, 1024 characters, before rejecting it. |
260
260
  | `CONFORMANCE_USERS_SCHEMA` | const | `TableSchema` | Describes the `users` table the driver-conformance battery opens — keyed by the default `id` primary column. |
261
261
  | `CONFORMANCE_POSTS_SCHEMA` | const | `TableSchema` | Describes the `posts` table the driver-conformance battery opens — keyed by a non-`id` `slug` primary column. |
262
262
  | `CONFORMANCE_SCHEMA` | const | `readonly TableSchema[]` | Holds the fixed `users` and `posts` schema every driver-conformance phase opens. |
@@ -265,49 +265,49 @@ A `Shape` cell holds the constant's declared type.
265
265
 
266
266
  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.
267
267
 
268
- | Type | Kind | Shape | Summary |
269
- | -------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
270
- | `Key` | type | `string \| number` | Represents a primary key — the value identifying a row within its table. |
271
- | `KeyFunction` | type | `() => Key` | Represents a key-generating function. |
272
- | `Row` | type | `Record<string, unknown>` | Represents a table row — a plain record of column values keyed by column name. |
273
- | `ConditionOperator` | type | `'equals' \| 'not' \| 'above' \| 'below' \| 'from' \| 'to' \| 'between' \| 'like' \| 'glob' \| 'starts' \| 'ends' \| 'any' \| 'none' \| 'absent' \| 'present'` | Represents a WHERE operator — the comparison a single `Condition` applies. |
274
- | `ConditionConnector` | type | `'and' \| 'or'` | Names how a `Condition` joins to the running result of the conditions before it. |
275
- | `Condition` | interface | `{ column, operator, values, connector }` | Represents one compiled WHERE condition. |
276
- | `OrderDirection` | type | `'ascending' \| 'descending'` | Names a sort direction. |
277
- | `Order` | interface | `{ column, direction }` | Represents one ordering term — a column (`FieldPath`, flat or nested) and its direction. |
278
- | `QueryInput` | interface | `{ conditions?, order?, limit?, offset? }` | Represents a serializable read specification — everything a backend needs to compile one read, free of JS callbacks so any backend can honor it. |
279
- | `AggregateOperation` | type | `'count' \| 'sum' \| 'average' \| 'minimum' \| 'maximum'` | Names an aggregate computed over a numeric column. |
280
- | `OperationOptions` | interface | `{ signal? }` | Options for an abortable operation. |
281
- | `DatabaseStatus` | type | `'idle' \| 'open' \| 'closed'` | Names the lifecycle state of a `DatabaseInterface`. |
282
- | `AdmissionInterface` | interface | `{ accepting } plus track` | Represents the admission boundary a scoped operation enters before it runs. |
283
- | `DatabaseErrorCode` | type | `'CLOSED' \| 'NOT_FOUND' \| 'CONFLICT' \| 'VALIDATION' \| 'ABORTED' \| 'MIGRATION' \| 'CONFORMANCE' \| 'DRIVER'` | Names a machine-readable `DatabaseError` code. |
284
- | `ConformanceFinding` | interface | `{ check, message, context }` | Represents one violated invariant from the driver-conformance battery. |
285
- | `DatabaseEventMap` | type | `{ open, close, transaction, commit, rollback, migrate }` | Describes the push observation surface of a `DatabaseInterface` — the connection + transaction lifecycle a fire-and-forget observer (logging, metrics, tracing, cache invalidation) subscribes to. |
286
- | `TableEventMap` | type | `{ write, remove, clear }` | Describes the push observation surface of a `TableInterface` — the per-row mutation moments a fire-and-forget observer (cache invalidation, sync, an audit log) subscribes to, alongside the database-level `DatabaseEventMap`. |
287
- | `ColumnMap` | type | `Readonly<Record<string, ContractShape>>` | Represents one table's columns — a map of column name to its value `ContractShape`. |
288
- | `TableMap` | type | `Readonly<Record<string, ColumnMap>>` | Represents a database's table schema — a map of table name to its `ColumnMap`. |
289
- | `RowOf` | type | `Infer<{ category: 'object'; properties: C }>` | Represents the row type a table's `ColumnMap` describe — `Infer` of the `objectShape` the database wraps them in. |
290
- | `PrimaryMap` | type | `Readonly<Record<string, string>>` | Holds per-table primary-key column overrides — `{ [table]: column }`. |
291
- | `IndexMap` | type | `Readonly<Record<string, ReadonlyArray<readonly string[]>>>` | Holds per-table secondary indexes — `{ [table]: groups }`, each group one (possibly compound) index of column names. |
292
- | `ColumnStorage` | type | `'text' \| 'integer' \| 'real' \| 'boolean' \| 'json' \| 'blob'` | Names a portable storage type for a column — the backend maps it to its native type (SQLite affinity, an IndexedDB value). Derived from a column's `ContractShape` by `shapeToColumnStorage`; `json` covers object/array/union/raw values a backend stores as JSON text and can `json_extract` for nested-field queries. |
293
- | `ColumnSchema` | interface | `{ name, storage, optional, nullable }` | Represents one column of a `TableSchema` — its name, portable `ColumnStorage`, and whether it independently accepts absence (`optional`) and explicit `null` (`nullable`). |
294
- | `TableSchema` | interface | `{ name, primary, columns, indexes }` | Represents a backend-agnostic description of one table — what `open` hands each driver so a native backend can create real tables and indexes. |
295
- | `MigrationStep` | type | `{ operation: 'table.add', table } \| { operation: 'table.remove', table } \| { operation: 'column.add', table, column } \| { operation: 'column.remove', table, column } \| { operation: 'index.add', table, index } \| { operation: 'index.remove', table, index }` | Represents one step of a `Migration` plan — a single schema change applied to one table. |
296
- | `Migration` | interface | `{ from, to, steps }` | Represents a schema migration plan — an ordered set of `MigrationStep`s moving a database from one schema version to another. |
297
- | `MigrationInput` | interface | `{ plan, metadata? }` | Represents one atomic migration request. |
298
- | `StorageInterface` | interface | `{} plus read, write, insert, delete, keys, scan, clear, records?, aggregate?, stream?, migrate?, metadata?, stamp?` | Declares the storage operations available only inside a driver's transaction scope. |
299
- | `DriverMetadata` | interface | `{ version, schema }` | Represents persisted schema metadata a versioning driver owns as an immutable snapshot. |
300
- | `DriverInterface` | interface | `StorageInterface plus {} plus open, close, snapshot, transaction?` | Declares the storage primitive every backend implements — the whole of the bridge. |
301
- | `DatabaseOptions` | interface | `{ on?, error?, driver, tables, primary?, indexes?, name?, generator?, version? }` | Options for `createDatabase`. |
302
- | `CompiledSQL` | interface | `{ sql, parameters }` | Represents a parameterized SQL fragment or statement plus its bind values. The `@orkestrel/database/server` entry point exports this type. |
303
- | `SQLiteDriverOptions` | interface | `{ path?, readonly?, timeout?, references?, pragmas? }` | Configures `createSQLiteDriver`. The `@orkestrel/database/server` entry point exports this type. |
304
- | `QueryPlan` | interface | `{ index?, range? }` | Represents a pushdown plan — an optional index and optional `IDBKeyRange` used to narrow a read. An omitted `index` selects the primary store; an omitted `range` performs a full scan. The plan is always a superset of the matching rows; the core engine refines it to the exact result. An empty plan (`{}`) is a primary-store full scan. The `@orkestrel/database/browser` entry point exports this type. |
305
- | `TableDefinition` | interface | `{ primary, columns, schema }` | Represents one table's portable definition, produced by `export` — the unit of schema / migration exchange across environments. |
306
- | `DatabaseStorageInterface` | interface | `{} plus table` | Represents a database view valid only inside one `DatabaseInterface.transaction` scope. |
307
- | `DatabaseInterface` | interface | `{ emitter, name, status } plus table, import, export, open, close, transaction, migrate` | Represents a database — the ergonomic entry point that owns the driver and its tables. |
308
- | `TableInterface` | interface | `{ emitter, name, primary, contract } plus get, resolve, has, keys, records, count, aggregate, scan, set, add, update, remove, clear, query, cursor` | Exposes typed keyed CRUD plus fluent query and cursor access. |
309
- | `QueryInterface` | interface | `{} plus condition, order, filter, limit, offset, collect, find, count, stream, aggregate` | Builds a read through a fluent chain. |
310
- | `CursorInterface` | interface | `{ value, index, done } plus next, update, remove, close` | Walks a table's rows forward for bulk in-place mutation. |
268
+ | Name | Kind | Signature | Summary |
269
+ | -------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
270
+ | `Key` | type | `string \| number` | Represents a primary key — the value identifying a row within its table. |
271
+ | `KeyFunction` | type | `() => Key` | Represents a key-generating function. |
272
+ | `Row` | type | `Record<string, unknown>` | Represents a table row — a plain record of column values keyed by column name. |
273
+ | `ConditionOperator` | type | `'equals' \| 'not' \| 'above' \| 'below' \| 'from' \| 'to' \| 'between' \| 'like' \| 'glob' \| 'starts' \| 'ends' \| 'any' \| 'none' \| 'absent' \| 'present'` | Represents a WHERE operator — the comparison a single `Condition` applies. |
274
+ | `ConditionConnector` | type | `'and' \| 'or'` | Names how a `Condition` joins to the running result of the conditions before it. |
275
+ | `Condition` | interface | `{ column, operator, values, connector }` | Represents one compiled WHERE condition. |
276
+ | `OrderDirection` | type | `'ascending' \| 'descending'` | Names a sort direction. |
277
+ | `Order` | interface | `{ column, direction }` | Represents one ordering term — a column (`FieldPath`, flat or nested) and its direction. |
278
+ | `QueryInput` | interface | `{ conditions?, order?, limit?, offset? }` | Represents a serializable read specification — everything a backend needs to compile one read, free of JS callbacks so any backend can honor it. |
279
+ | `AggregateOperation` | type | `'count' \| 'sum' \| 'average' \| 'minimum' \| 'maximum'` | Names an aggregate computed over a numeric column. |
280
+ | `OperationOptions` | interface | `{ signal? }` | Options for an abortable operation. |
281
+ | `DatabaseStatus` | type | `'idle' \| 'open' \| 'closed'` | Names the lifecycle state of a `DatabaseInterface`. |
282
+ | `AdmissionInterface` | interface | `{ accepting, track() }` | Represents the admission boundary a scoped operation enters before it runs. |
283
+ | `DatabaseErrorCode` | type | `'CLOSED' \| 'NOT_FOUND' \| 'CONFLICT' \| 'VALIDATION' \| 'ABORTED' \| 'MIGRATION' \| 'CONFORMANCE' \| 'DRIVER'` | Names a machine-readable `DatabaseError` code. |
284
+ | `ConformanceFinding` | interface | `{ check, message, context }` | Represents one violated invariant from the driver-conformance battery. |
285
+ | `DatabaseEventMap` | type | `{ readonly open: readonly []; readonly close: readonly []; readonly transaction: readonly []; readonly commit: readonly []; readonly rollback: readonly [error: unknown]; readonly migrate: readonly [migration: Migration]; }` | Describes the push observation surface of a `DatabaseInterface` — the connection + transaction lifecycle a fire-and-forget observer (logging, metrics, tracing, cache invalidation) subscribes to. |
286
+ | `TableEventMap` | type | `{ readonly write: readonly [key: Key]; readonly remove: readonly [key: Key]; readonly clear: readonly []; }` | Describes the push observation surface of a `TableInterface` — the per-row mutation moments a fire-and-forget observer (cache invalidation, sync, an audit log) subscribes to, alongside the database-level `DatabaseEventMap`. |
287
+ | `ColumnMap` | type | `Readonly<Record<string, ContractShape>>` | Represents one table's columns — a map of column name to its value `ContractShape`. |
288
+ | `TableMap` | type | `Readonly<Record<string, ColumnMap>>` | Represents a database's table schema — a map of table name to its `ColumnMap`. |
289
+ | `RowOf` | type | `Infer<{ readonly category: 'object'; readonly properties: C; }>` | Represents the row type a table's `ColumnMap` describe — `Infer` of the `objectShape` the database wraps them in. |
290
+ | `PrimaryMap` | type | `Readonly<Record<string, string>>` | Holds per-table primary-key column overrides — `{ [table]: column }`. |
291
+ | `IndexMap` | type | `Readonly<Record<string, ReadonlyArray<readonly string[]>>>` | Holds per-table secondary indexes — `{ [table]: groups }`, each group one (possibly compound) index of column names. |
292
+ | `ColumnStorage` | type | `'text' \| 'integer' \| 'real' \| 'boolean' \| 'json' \| 'blob'` | Names a portable storage type for a column — the backend maps it to its native type (SQLite affinity, an IndexedDB value). Derived from a column's `ContractShape` by `shapeToColumnStorage`; `json` covers object/array/union/raw values a backend stores as JSON text and can `json_extract` for nested-field queries. |
293
+ | `ColumnSchema` | interface | `{ name, storage, optional, nullable }` | Represents one column of a `TableSchema` — its name, portable `ColumnStorage`, and whether it independently accepts absence (`optional`) and explicit `null` (`nullable`). |
294
+ | `TableSchema` | interface | `{ name, primary, columns, indexes }` | Represents a backend-agnostic description of one table — what `open` hands each driver so a native backend can create real tables and indexes. |
295
+ | `MigrationStep` | type | `{ readonly operation: 'table.add'; readonly table: TableSchema; } \| { readonly operation: 'table.remove'; readonly table: string; } \| { readonly operation: 'column.add'; readonly table: string; readonly column: ColumnSchema; } \| { readonly operation: 'column.remove'; readonly table: string; readonly column: string; } \| { readonly operation: 'index.add'; readonly table: string; readonly index: readonly string[]; } \| { readonly operation: 'index.remove'; readonly table: string; readonly index: readonly string[]; }` | Represents one step of a `Migration` plan — a single schema change applied to one table. |
296
+ | `Migration` | interface | `{ from, to, steps }` | Represents a schema migration plan — an ordered set of `MigrationStep`s moving a database from one schema version to another. |
297
+ | `MigrationInput` | interface | `{ plan, metadata? }` | Represents one atomic migration request. |
298
+ | `StorageInterface` | interface | `{ read(), write(), insert(), delete(), keys(), scan(), clear(), records?(), aggregate?(), stream?(), migrate?(), metadata?(), stamp?() }` | Declares the storage operations available only inside a driver's transaction scope. |
299
+ | `DriverMetadata` | interface | `{ version, schema }` | Represents persisted schema metadata a versioning driver owns as an immutable snapshot. |
300
+ | `DriverInterface` | interface | `{ open(), close(), snapshot(), transaction?() }` | Declares the storage primitive every backend implements — the whole of the bridge. |
301
+ | `DatabaseOptions` | interface | `{ on?, error?, driver, tables, primary?, indexes?, name?, generator?, version? }` | Options for `createDatabase`. |
302
+ | `CompiledSQL` | interface | `{ sql, parameters }` | Represents a parameterized SQL fragment or statement plus its bind values. The `@orkestrel/database/server` entry point exports this type. |
303
+ | `SQLiteDriverOptions` | interface | `{ path?, readonly?, timeout?, references?, pragmas? }` | Configures `createSQLiteDriver`. The `@orkestrel/database/server` entry point exports this type. |
304
+ | `QueryPlan` | interface | `{ index?, range? }` | Represents a pushdown plan — an optional index and optional `IDBKeyRange` used to narrow a read. An omitted `index` selects the primary store; an omitted `range` performs a full scan. The plan is always a superset of the matching rows; the core engine refines it to the exact result. An empty plan (`{}`) is a primary-store full scan. The `@orkestrel/database/browser` entry point exports this type. |
305
+ | `TableDefinition` | interface | `{ primary, columns, schema }` | Represents one table's portable definition, produced by `export` — the unit of schema / migration exchange across environments. |
306
+ | `DatabaseStorageInterface` | interface | `{ table() }` | Represents a database view valid only inside one `DatabaseInterface.transaction` scope. |
307
+ | `DatabaseInterface` | interface | `{ emitter, name, status, table(), import(), export(), open(), close(), transaction(), migrate() }` | Represents a database — the ergonomic entry point that owns the driver and its tables. |
308
+ | `TableInterface` | interface | `{ emitter, name, primary, contract, get(), resolve(), has(), keys(), records(), count(), aggregate(), scan(), set(), add(), update(), remove(), clear(), query(), cursor() }` | Exposes typed keyed CRUD plus fluent query and cursor access. |
309
+ | `QueryInterface` | interface | `{ condition(), order(), filter(), limit(), offset(), collect(), find(), count(), stream(), aggregate() }` | Builds a read through a fluent chain. |
310
+ | `CursorInterface` | interface | `{ value, index, done, next(), update(), remove(), close() }` | Walks a table's rows forward for bulk in-place mutation. |
311
311
 
312
312
  ### Operation state
313
313