@orkestrel/scaffold 0.0.131 → 0.0.133

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.
@@ -5,8 +5,8 @@
5
5
  > file, SQLite, or IndexedDB.
6
6
 
7
7
  A table is a contract. Declare a `tables` map of
8
- [`ContractShape`](contract.md)s once, and the row type, write-time coercion and
9
- validation, JSON-Schema introspection, and seed data all flow from that one
8
+ [`ContractShape`](contract.md)s once, and the row type, write-time admission,
9
+ JSON-Schema introspection, and seed data all flow from that one
10
10
  declaration — no separate schema, no annotations, no `as`.
11
11
 
12
12
  The design stance is one engine, thin drivers. A backend implements only an
@@ -53,7 +53,7 @@ const db = createDatabase({
53
53
 
54
54
  const users = db.table('users') // hold the handle; TableInterface<{ id; name; age }>
55
55
 
56
- await users.set({ id: 'u1', name: 'Ada', age: 36 }) // coerced + validated through the contract
56
+ await users.set({ id: 'u1', name: 'Ada', age: 36 }) // admitted whole through the contract
57
57
  await users.get('u1') // typed { id; name; age } | undefined — narrowed, never `as`
58
58
  await users
59
59
  .query()
@@ -68,7 +68,7 @@ never write `objectShape` at the table level. The row type is `Infer` of
68
68
  those columns, so `db.table('users')` is checked against the schema (a
69
69
  typo'd column name or a wrong-typed write fails at compile time) and returns
70
70
  a `TableInterface` typed by that row. That one declaration is the single
71
- source of truth: it types the table, drives write coercion + validation,
71
+ source of truth: it types the table, drives write admission,
72
72
  produces the JSON Schema, and seeds fixtures.
73
73
 
74
74
  ### Factories
@@ -169,7 +169,9 @@ The constructor installs an own, non-enumerable, non-writable
169
169
  error itself. `isDatabaseError` accepts branded subclasses across package copies
170
170
  and ESM/CJS entries without requiring an exact `name`. It validates the declared
171
171
  code and optional context, and refuses unbranded look-alikes, transparent proxies,
172
- and plain objects carrying only the brand.
172
+ and plain objects carrying only the brand. When the context carries a `faults`
173
+ member, as a `VALIDATION` refusal from `Table` does, the guard requires a list
174
+ whose every entry passes Contract's `isAuditFault` function.
173
175
 
174
176
  ### Query engine
175
177
 
@@ -525,19 +527,24 @@ These invariants hold across the core database source tree ↔ this guide:
525
527
  both directions (see `.claude/rules/documentation.md` § Parity). Exported
526
528
  implementation declarations outside
527
529
  an entry barrel remain internal.
528
- 2. **A table is a contract.** Every write is coerced **and** validated
529
- through the table's compiled contract — `set` / `add` / `update` run the
530
- row through the installed Contract 0.0.9 `contract.parse`, one step that
531
- both coerces and enforces constraints such as `min` / `pattern`. Every
532
- parsed result already satisfies `contract.is`, so `Table` does not run a
533
- second guard after parsing; a row that fails throws `VALIDATION`. Reads are
534
- narrowed back to the table's row type through the guard — never an `as`
535
- (see `AGENTS.md` § Non-negotiable rules). The
536
- row type is the shape's `Infer`, so a `tables` map types every table from
537
- one declaration. A contract rejection reports only the table plus the first
538
- bounded contract fault (`field` and `reason` when one exists); the rejected
539
- row, received value, and parser cause never enter the message, context,
540
- serialized error, or table events.
530
+ 2. **A table is a contract.** Every write is admitted whole through the
531
+ table's compiled contract — `set` / `add` / `update` run the row through
532
+ Contract's `admitValue`, which admits a lossless repair such as `'36'` to
533
+ `36` for a number column and enforces constraints such as `min` /
534
+ `pattern`. A row that carries an undeclared top-level column, omits a
535
+ required column, or needs a lossy repair such as `'036'` to `36` throws
536
+ `VALIDATION`; the table never removes a column to admit the rest. A
537
+ `rawShape` column admits any defined value, so the nested keys of a JSON
538
+ column never refuse. Reads are narrowed back to the table's row type
539
+ through the guard — never an `as` (see `AGENTS.md` § Non-negotiable
540
+ rules). The row type is the shape's `Infer`, so a `tables` map types every
541
+ table from one declaration. A refusal's context carries `table` and
542
+ `faults`, the `AuditFault` list `admitValue` returned, and its message
543
+ names the table and the first fault through Contract's `describeFaultLine`
544
+ function. A fault's `received` member and the message carry Contract's
545
+ JSON-encoded, length-capped rendering of the received value; the rejected
546
+ row and the parser cause never enter the message, context, serialized
547
+ error, or table events.
541
548
  3. **Thin driver, one engine, native overrides.** The required
542
549
  `DriverInterface` surface is the irreducible storage primitive — keyed
543
550
  read/write/atomic-insert/delete, an ordered `scan`, key listing, and `snapshot`. `open`
@@ -1213,13 +1220,13 @@ await users.remove(['u1', 'u2']) // → readonly boolean[]
1213
1220
  A batch runs as independent sequential operations; wrap it in `transaction`
1214
1221
  when it must be atomic.
1215
1222
 
1216
- ### Coercion through the contract
1223
+ ### Admission through the contract
1217
1224
 
1218
- Parses a numeric string against the table's contract, stores the coerced number, and reads it back:
1225
+ Admits a numeric string against the table's contract, stores the repaired number, and refuses an undeclared column:
1219
1226
 
1220
1227
  ```ts
1221
- import { createDatabase, createMemoryDriver } from '@orkestrel/database'
1222
- import { integerShape, stringShape } from '@orkestrel/contract'
1228
+ import { createDatabase, createMemoryDriver, isDatabaseError } from '@orkestrel/database'
1229
+ import { admitValue, integerShape, stringShape } from '@orkestrel/contract'
1223
1230
 
1224
1231
  const users = createDatabase({
1225
1232
  driver: createMemoryDriver(),
@@ -1228,18 +1235,16 @@ const users = createDatabase({
1228
1235
  },
1229
1236
  }).table('users')
1230
1237
 
1231
- // A numeric column accepts a numeric string and stores the coerced number.
1232
- const normalized = users.contract.parse({
1233
- id: 'u2',
1234
- name: 'Bo',
1235
- age: '41',
1236
- role: 'member',
1237
- })
1238
- if (normalized === undefined) throw new Error('Expected the row to parse')
1239
- await users.set(normalized)
1240
- ;(await users.get('u2'))?.age // 41 (a number) — the contract parsed it
1238
+ // A numeric string is a lossless repair, so admitValue admits it as the number.
1239
+ const admitted = admitValue(users.contract, { id: 'u2', name: 'Bo', age: '41', role: 'member' })
1240
+ if (!admitted.success) throw new Error('Expected the row to admit')
1241
+ await users.set(admitted.value.value)
1242
+ ;(await users.get('u2'))?.age // 41 (a number)
1241
1243
 
1242
- // A row that cannot satisfy the shape throws DatabaseError('VALIDATION').
1244
+ // An undeclared column refuses with DatabaseError('VALIDATION') and the contract's faults.
1245
+ const imported = { id: 'u3', name: 'Cy', age: 29, role: 'member', nickname: 'Cy' }
1246
+ const refused = await users.set(imported).catch((error: unknown) => error)
1247
+ if (isDatabaseError(refused)) refused.context?.faults // [{ reason: 'extra', path: ['nickname'] }]
1243
1248
  ```
1244
1249
 
1245
1250
  ### Fluent queries
@@ -2517,9 +2522,10 @@ mapMigrationError(fault) // → the same, but an UPGRADE fault becomes 'MIGRATIO
2517
2522
 
2518
2523
  - **Declare tables in `createDatabase({ tables })` and hold the handles** —
2519
2524
  `const users = db.table('users')`; reuse them rather than re-resolving.
2520
- - **Writes coerce, reads narrow.** At an unknown-input boundary, normalize
2521
- loose data (`'41'`) through `table.contract.parse` before a typed write;
2522
- trust `get` / `records` to return the row type.
2525
+ - **Writes admit whole, reads narrow.** At an unknown-input boundary, admit
2526
+ loose data (`'41'`) through `admitValue(table.contract, input)` and write
2527
+ its value; a refusal carries the faults to report. Trust `get` / `records`
2528
+ to return the row type.
2523
2529
  - **Use `resolve` when absence is an error**, `get` when it is expected —
2524
2530
  `resolve` throws `NOT_FOUND`, `get` returns `undefined`.
2525
2531
  - **Reach for `query()` over `records()`** — the builder compiles a portable
@@ -2549,7 +2555,7 @@ mapMigrationError(fault) // → the same, but an UPGRADE fault becomes 'MIGRATIO
2549
2555
  - [`tests/src/core/Database.test.ts`](../tests/src/core/Database.test.ts) — declared tables, lazy connect, typed CRUD, custom keys, indexes, import/export, and callback transactions: whole accepted-operation drain, synchronous-throw and asynchronous-rejection reason identity, caught-operation rejection still rolling back, callback-over-drain error precedence, root/import/lifecycle/nesting barriers, stale scoped table/query/cursor/stream invalidation, and truthful successful-rollback-only events. It also covers explicit migration and versioned open: deployed-schema-first reconciliation, fresh stamp, same-version no-op, atomic upgrade input, higher-version rejection, paired-hook enforcement (metadata-only and stamp-only are inert), and migrate-event behavior.
2550
2556
  - [`tests/src/core/ScopedIterator.test.ts`](../tests/src/core/ScopedIterator.test.ts) — direct internal continuation-lifetime coverage: tracked `next` / `return` / `throw`, the readiness thunk running before every advance and its failure preempting the source, synchronous source throws, missing methods, concurrent accepted continuations, idle iterators, late conflicts, and exactly-once rejected cleanup.
2551
2557
  - [`tests/src/core/DriverIterator.test.ts`](../tests/src/core/DriverIterator.test.ts) — direct root-driver continuation coverage: pre/post-read guards, produced-row discard, terminalization, return races, missing methods, throw delegation, and exactly-once cleanup.
2552
- - [`tests/src/core/Table.test.ts`](../tests/src/core/Table.test.ts) — `Table`'s keyed CRUD + batch overloads, payload-safe bounded contract diagnostics, strict paging at every read boundary, coercion and error paths, `add` dispatch through atomic `insert` (including concurrent duplicate claims), sequential partial-batch abort semantics, and the emitter's post-commit and no-aborted-event behavior.
2558
+ - [`tests/src/core/Table.test.ts`](../tests/src/core/Table.test.ts) — `Table`'s keyed CRUD + batch overloads, payload-safe bounded contract diagnostics, strict paging at every read boundary, whole-row admission with its lossless repairs, its undeclared, missing, and lossy refusals, and the raw-column nested-key admission, `add` dispatch through atomic `insert` (including concurrent duplicate claims), sequential partial-batch abort semantics, and the emitter's post-commit and no-aborted-event behavior.
2553
2559
  - [`tests/src/core/Query.test.ts`](../tests/src/core/Query.test.ts) — `Query`'s where / and / or dispatch, ordering, synchronous strict page builders with no failed mutation, legal zero, `filter`, and aggregates.
2554
2560
  - [`tests/src/core/Cursor.test.ts`](../tests/src/core/Cursor.test.ts) — cursor behavior over a key snapshot: `value` / `index` / `done`, serialized overlapping `next` / `update` / `remove`, rejection recovery, synchronous runner admission, terminal close before queued work and during dispatched reads/mutations, plus transaction-ledger regressions for deleted-key skipping, unawaited normalized updates, validation rollback, and retained closed/active conflicts.
2555
2561
  - [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — `createDatabase` / `createMemoryDriver` each return a working instance of their interface (a round-trip end to end).
@@ -18,7 +18,9 @@ store and a crash leaves exactly the unfinished rows. Pass a `store` to `createQ
18
18
  after a restart a fresh queue over the same store `restore()`s precisely that unfinished work.
19
19
  `DatabaseQueueStore` is the durable engine over the `@orkestrel/database` layer (a queue's
20
20
  durable state is a table), driver-pluggable across memory / JSON / SQLite; `MemoryQueueStore`
21
- is the zero-plumbing in-process default.
21
+ is the zero-plumbing in-process default. The table admits each entry whole against the input
22
+ shape, so through `DatabaseQueueStore` an `enqueue` input that carries an undeclared member
23
+ rejects with a `QueueError` of code `store`, whose cause is the `DatabaseError` of code `VALIDATION` that carries the faults, before the handler runs.
22
24
 
23
25
  `Queue` is **observable**: it exposes a typed `emitter` (`.claude/rules/patterns.md` §
24
26
  Stateful emitters) carrying its lifecycle moments for fire-and-forget observers — logging,
@@ -1352,8 +1352,8 @@ The project loads `tests/setup.ts` alone. The tests import
1352
1352
  `tests/setupStudy.ts`, a harness module the package owns, so scaffold plans no such file and no
1353
1353
  project loads it as a setup file. In publishing and `private: true` workspaces, run the project on
1354
1354
  demand with `npm run test:studies` alone; no gate or chain runs it.
1355
- Its longer timeouts and disabled file parallelism match the
1356
- live-service project. The root `studies/` directory holds the adapters and declarations the study
1355
+ Its longer timeouts match the live-service project, and its files run in parallel, because its
1356
+ proofs drive seeded, replayed, or scripted runs rather than a live service. The root `studies/` directory holds the adapters and declarations the study
1357
1357
  tests run, and it selects nothing. A chain that carries a study step fails the configuration proof
1358
1358
  until the workspace removes that step during scaffold adoption.
1359
1359
 
@@ -2209,7 +2209,7 @@ extras pass through unchanged except for the selected showcase pair. Extras foll
2209
2209
  `ORKESTREL_RANGE_PATTERN`; foreign peers follow `FLOOR_RANGE_PATTERN`.
2210
2210
 
2211
2211
  A browser application with `showcase: true`, including its Vue face, selects exact
2212
- `vite-plugin-singlefile: 2.3.3`, Vite `^8.3.7` from scaffold's manifest, and the npm override
2212
+ `vite-plugin-singlefile: 2.3.3`, Vite `^8.3.8` from scaffold's manifest, and the npm override
2213
2213
  `"vite-plugin-singlefile@2.3.3": { "micromatch": "npm:picomatch@2.3.2" }`. This policy applies
2214
2214
  after extras. Online resolution excludes this pair from ordinary foreign-major updates; other
2215
2215
  dependencies retain their usual resolution. Repair preserves each package's runtime or development
@@ -2287,7 +2287,7 @@ The dependency tables select these floors:
2287
2287
  | `oxfmt` | `^0.78.0` | Every workspace |
2288
2288
  | `@microsoft/api-extractor` | `^7.60.1` | Declaration builds; uses its bundled TypeScript 6.0.3 engine |
2289
2289
  | `playwright` | `^1.64.1` | Browser tooling |
2290
- | Vite | `^8.3.7` | Every workspace |
2290
+ | Vite | `^8.3.8` | Every workspace |
2291
2291
  | `@types/node` | `^24.19.2` | Every workspace; generated workspaces support Node `>=22.18.0` |
2292
2292
 
2293
2293
  Node 26 types admit APIs that the supported runtime lacks. Inside the declared major the verbs