@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.
- package/dist/bin/main.js +13 -13
- package/dist/host/agents/orchestration.md +5 -3
- package/dist/host/claude/agents/orkestrel.md +54 -54
- package/dist/host/claude/rules/tests.md +5 -0
- package/dist/host/configs/helpers.ts +2 -2
- package/dist/host/guides/browser.md +1 -1
- package/dist/host/guides/contract.md +26 -5
- package/dist/host/guides/database.md +43 -37
- package/dist/host/guides/queue.md +3 -1
- package/dist/host/guides/scaffold.md +4 -4
- package/dist/host/guides/test.md +333 -195
- package/dist/host/guides/workflow.md +4 -2
- package/dist/host/manifest.json +14 -14
- package/dist/host/tests/config.test.ts +3 -3
- package/dist/host/tests/policy.test.ts +1 -1
- package/dist/src/core/index.cjs +13 -14
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.js +13 -14
- package/dist/src/core/index.js.map +1 -1
- package/package.json +13 -13
|
@@ -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
|
|
9
|
-
|
|
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 }) //
|
|
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
|
|
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
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
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
|
-
###
|
|
1223
|
+
### Admission through the contract
|
|
1217
1224
|
|
|
1218
|
-
|
|
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
|
|
1232
|
-
const
|
|
1233
|
-
|
|
1234
|
-
|
|
1235
|
-
|
|
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
|
-
//
|
|
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
|
|
2521
|
-
loose data (`'41'`) through `table.contract
|
|
2522
|
-
|
|
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,
|
|
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
|
|
1356
|
-
live
|
|
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.
|
|
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.
|
|
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
|