@orkestrel/scaffold 0.0.131 → 0.0.132

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 CHANGED
@@ -10,7 +10,7 @@ import { readdirSync } from "node:fs";
10
10
  import { parseArgs } from "node:util";
11
11
  var package_default = {
12
12
  name: "@orkestrel/scaffold",
13
- version: "0.0.131",
13
+ version: "0.0.132",
14
14
  description: "Scaffold workspaces with commands: new, audit, surface, repair, catalog, and overwrite.",
15
15
  keywords: [
16
16
  "audit",
@@ -102,27 +102,27 @@ var package_default = {
102
102
  "prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test && npm run test:templates && npm run test:distribution -- --mode release"
103
103
  },
104
104
  dependencies: {
105
- "@orkestrel/console": "^0.0.19",
106
- "@orkestrel/contract": "^0.0.22",
107
- "@orkestrel/emitter": "^0.0.15",
108
- "@orkestrel/markdown": "^0.0.20",
109
- "@orkestrel/process": "^0.0.18",
110
- "@orkestrel/template": "^0.0.13"
105
+ "@orkestrel/console": "^0.0.20",
106
+ "@orkestrel/contract": "^0.0.23",
107
+ "@orkestrel/emitter": "^0.0.16",
108
+ "@orkestrel/markdown": "^0.0.21",
109
+ "@orkestrel/process": "^0.0.19",
110
+ "@orkestrel/template": "^0.0.14"
111
111
  },
112
112
  devDependencies: {
113
113
  "@microsoft/api-extractor": "^7.60.1",
114
114
  "@orkestrel/browser": "^0.0.32",
115
115
  "@orkestrel/guide": "^0.0.30",
116
- "@orkestrel/html": "^0.0.15",
116
+ "@orkestrel/html": "^0.0.16",
117
117
  "@orkestrel/probe": "^0.0.29",
118
- "@orkestrel/test": "^0.0.33",
118
+ "@orkestrel/test": "^0.0.34",
119
119
  "@types/node": "^24.19.2",
120
120
  "@vitest/browser-playwright": "^5.1.0",
121
121
  "oxfmt": "^0.78.0",
122
122
  "oxlint": "^1.93.0",
123
123
  "playwright": "^1.64.1",
124
124
  "typescript": "^7.0.2",
125
- "vite": "^8.3.7",
125
+ "vite": "^8.3.8",
126
126
  "vitest": "^5.1.0"
127
127
  },
128
128
  engines: { "node": ">=22.18.0" }
@@ -91,18 +91,18 @@ The harness's own engine orchestrates: Claude Fable 5.2 or Claude Opus 5.5 in Cl
91
91
  - When no acceptance check reads a run's result anymore, stop the run.
92
92
  - When a verifier lane fails in its harness rather than in the gate, run the gate once yourself and read its exit code; write no comparator, snapshot, or retry chain to obtain evidence.
93
93
  - Keep valid receipts. Re-run a check only when a change to its inputs, configuration, environment, or claim could alter what it proved, and then run the narrowest check that covers the change. Never repeat a passing check to collect another receipt or to have every suite pass in one command; name the receipt that covers each check a brief does not rerun.
94
- - Ask the user only for a decision that is theirs: scope, the spend ceiling and stop line § Hold the plan names, a conflicting ruling, a credential, publication, or a commit or push the law reserves. Decide routine matters yourself, such as time and lane allowances, retries, and order, and report them, with time in whole minutes.
94
+ - Ask the user only for a decision that is theirs: scope, a product decision, a conflicting ruling, a credential, publication, or a commit or push the law reserves. Never ask the user to agree an estimate, a spend ceiling, a stop line, or a time allowance. Decide those yourself, with time and lane allowances, retries, and order, and report them in status, with time in whole minutes.
95
95
  - Never end a turn with work pending and nothing that will wake the session: run the work as a tracked background command or a child whose completion notifies, or schedule a wake. While a lane runs, continue independent work.
96
96
  - When nobody is awake to answer and a session waits on a child, arm a keep-alive and a limit on the wait, and name a peer session as the watchdog.
97
97
 
98
98
  ## Hold the plan
99
99
 
100
- - Open with the goal and acceptance criteria per `AGENTS.md` § Work loop, then estimate the scope: the units, the review and evidence each needs, and what stays out. When the estimate is large, agree with the user the estimate, the spend ceiling, and the stop line: how much lane time the work can take, and the point at which work stops and reports. Derive an estimate or a process cap from a measurement of the same command, execution shape, and toolchain, and state that measurement beside the figure, or state that none exists.
100
+ - Open with the goal and acceptance criteria per `AGENTS.md` § Work loop, then estimate the scope: the units, the review and evidence each needs, and what stays out. When the estimate is large, set the spend ceiling and the stop line yourself, sized to what the work's quality and performance need: how much lane time the work can take, and the point at which work stops and reports. Report all three in status. Derive an estimate or a process cap from a measurement of the same command, execution shape, and toolchain, and state that measurement beside the figure, or state that none exists.
101
101
  - When a measurement has more than one arm, price each arm in lane hours before ruling it in, and put that table first in the report that asks for the ruling.
102
102
  - Before each unit, name the plan step it serves. Cut a unit no step needs; set an unplanned idea aside in the plan and return to the step.
103
103
  - Add a tracked file only where the request, the plan, or a rule names it.
104
104
  - After every unit return, unexpected result, or user message, compare the work with the plan: mark what is done, restate the next step, and set aside what no longer serves the goal.
105
- - When the work outgrows its estimate, stop, re-estimate, and bring the user the choice to cut, defer, or extend before continuing.
105
+ - When the work outgrows its estimate, re-estimate, then cut, defer, or extend by what the goal's quality and performance need, and report the choice in status.
106
106
  - When the user questions the plan, test it against the evidence in hand: reopen it where the evidence disagrees and report what changed; where the evidence holds, answer with that evidence.
107
107
  - Answer a status question before dispatching more work, and close every report the same way: the goal, what is done against it, what is measured, what remains, and the next step.
108
108
 
@@ -110,6 +110,7 @@ The harness's own engine orchestrates: Claude Fable 5.2 or Claude Opus 5.5 in Cl
110
110
 
111
111
  - Size the effort to the task before spending: a lookup takes one lane, routed per § Routing, and only open-ended work with independent, high-value parts fans out, per § Parallelism.
112
112
  - Locate the evidence with short broad probes before any deep pass: a run of the shipped command, a census, a search. Go deep only on a defect or gap a run has shown, in one lane, with the narrowest instrument that answers it: a counting probe or a mutation.
113
+ - When work is experimental or its viability is open, settle viability first with throwaway probes and a thin end-to-end prototype under `tmp/probes/`, breadth-first, before any design's deep phase, any long measured run, or any build. Write each probe and prototype so its cases and assertions carry into the test, study, or journey it would become. A probe takes whatever leeway its question needs. When a unit adopts one, keep its cases and assertions and rewrite everything else to the rules, never copying it: names, placement, kind files, shared fixtures, and the test, study, or journey conventions. Review judges promoted code as it judges any other. A probe that answers no opens a design question before anything builds on it.
113
114
  - When a defect class can recur across packages, census the class across every package before a review of any one: a script lists the whole population, `scout` marks each listed row against the brief's explicit criteria, and `analyst` or the Orchestrator rules each marked row once and fixes it at its cause. A list made by hand is no population.
114
115
  - Define a class in a census by what the code does, never by how it spells it. Where a baseline build exists, run a seeded differential against it over the repair's input domain, and report a search's hits as a floor, never as the class.
115
116
  - Set every stop with what reopens it, and record both in the plan. At a re-examination, hold the stop unless a proposal names the condition it meets; a stop that names no condition passes only on the user's ruling. Before a continuation, record whether its unit repairs an admitted row or reopens the stopped seam.
@@ -43,55 +43,55 @@ Treat generated package identifiers, versions, layers, and dependency ranges as
43
43
 
44
44
  | Package | Version | Layer | Runtime dependencies | Peer dependencies |
45
45
  | ----------------------- | --------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
46
- | `@orkestrel/abort` | `0.0.16` | L1 | `@orkestrel/contract` `^0.0.22` | |
46
+ | `@orkestrel/abort` | `0.0.17` | L1 | `@orkestrel/contract` `^0.0.23` | |
47
47
  | `@orkestrel/agent` | `0.0.40` | L5 | `@orkestrel/tool` `^0.0.22`, `@orkestrel/abort` `^0.0.16`, `@orkestrel/queue` `^0.0.21`, `@orkestrel/budget` `^0.0.17`, `@orkestrel/ndjson` `^0.0.16`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/database` `^0.0.22`, `@orkestrel/workflow` `^0.0.27`, `@orkestrel/workspace` `^0.0.16` | |
48
48
  | `@orkestrel/brief` | `0.0.17` | L4 | `@orkestrel/reason` `^0.0.17`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/interpret` `^0.0.22` | |
49
49
  | `@orkestrel/browser` | `0.0.32` | L5 | `@orkestrel/mcp` `^0.0.42`, `@orkestrel/html` `^0.0.15`, `@orkestrel/pool` `^0.0.20`, `@orkestrel/tool` `^0.0.22`, `@orkestrel/codec` `^0.0.9`, `@orkestrel/router` `^0.0.20`, `@orkestrel/server` `^0.0.26`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/markdown` `^0.0.20`, `@orkestrel/websocket` `^0.0.18` | |
50
- | `@orkestrel/budget` | `0.0.17` | L1 | `@orkestrel/contract` `^0.0.22` | |
50
+ | `@orkestrel/budget` | `0.0.18` | L1 | `@orkestrel/contract` `^0.0.23` | |
51
51
  | `@orkestrel/capture` | `0.0.6` | L3 | `@orkestrel/process` `^0.0.18`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22` | `vite` `^8.3.7`, `vitest` `^4.1.12 \|\| ^5.1.0`, `playwright` `^1.61.0`, `@vitest/browser-playwright` `^4.1.12 \|\| ^5.0.5` |
52
- | `@orkestrel/codec` | `0.0.9` | L1 | `@orkestrel/contract` `^0.0.22` | |
53
- | `@orkestrel/console` | `0.0.19` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
54
- | `@orkestrel/contract` | `0.0.22` | L0 | | |
55
- | `@orkestrel/csv` | `0.0.13` | L2 | `@orkestrel/codec` `^0.0.9`, `@orkestrel/contract` `^0.0.22` | |
56
- | `@orkestrel/database` | `0.0.22` | L2 | `@orkestrel/sqlite` `^0.0.17`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/indexeddb` `^0.0.17` | |
57
- | `@orkestrel/emitter` | `0.0.15` | L1 | `@orkestrel/contract` `^0.0.22` | |
58
- | `@orkestrel/form` | `0.0.16` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
52
+ | `@orkestrel/codec` | `0.0.10` | L1 | `@orkestrel/contract` `^0.0.23` | |
53
+ | `@orkestrel/console` | `0.0.20` | L2 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
54
+ | `@orkestrel/contract` | `0.0.23` | L0 | | |
55
+ | `@orkestrel/csv` | `0.0.14` | L2 | `@orkestrel/codec` `^0.0.10`, `@orkestrel/contract` `^0.0.23` | |
56
+ | `@orkestrel/database` | `0.0.23` | L2 | `@orkestrel/sqlite` `^0.0.18`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23`, `@orkestrel/indexeddb` `^0.0.18` | |
57
+ | `@orkestrel/emitter` | `0.0.16` | L1 | `@orkestrel/contract` `^0.0.23` | |
58
+ | `@orkestrel/form` | `0.0.17` | L2 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
59
59
  | `@orkestrel/guide` | `0.0.30` | L3 | `@orkestrel/contract` `^0.0.22`, `@orkestrel/markdown` `^0.0.20` | |
60
- | `@orkestrel/html` | `0.0.15` | L1 | `@orkestrel/contract` `^0.0.22` | |
61
- | `@orkestrel/indexeddb` | `0.0.17` | L1 | `@orkestrel/contract` `^0.0.22` | |
60
+ | `@orkestrel/html` | `0.0.16` | L1 | `@orkestrel/contract` `^0.0.23` | |
61
+ | `@orkestrel/indexeddb` | `0.0.18` | L1 | `@orkestrel/contract` `^0.0.23` | |
62
62
  | `@orkestrel/interpret` | `0.0.22` | L3 | `@orkestrel/reason` `^0.0.17`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/template` `^0.0.13` | |
63
- | `@orkestrel/jsonrpc` | `0.0.2` | L1 | `@orkestrel/contract` `^0.0.22` | |
63
+ | `@orkestrel/jsonrpc` | `0.0.3` | L1 | `@orkestrel/contract` `^0.0.23` | |
64
64
  | `@orkestrel/lsp` | `0.0.14` | L3 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/jsonrpc` `^0.0.2`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22` | |
65
- | `@orkestrel/markdown` | `0.0.20` | L2 | `@orkestrel/html` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
65
+ | `@orkestrel/markdown` | `0.0.21` | L2 | `@orkestrel/html` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
66
66
  | `@orkestrel/mcp` | `0.0.42` | L4 | `@orkestrel/sse` `^0.0.13`, `@orkestrel/tool` `^0.0.22`, `@orkestrel/codec` `^0.0.9`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/jsonrpc` `^0.0.2`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/websocket` `^0.0.18` | `@orkestrel/router` `^0.0.20`, `@orkestrel/server` `^0.0.26` |
67
67
  | `@orkestrel/middleware` | `0.0.30` | L4 | `@orkestrel/abort` `^0.0.16`, `@orkestrel/budget` `^0.0.17`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22` | `@orkestrel/server` `^0.0.26`, `@orkestrel/database` `^0.0.22` |
68
- | `@orkestrel/msg` | `0.0.16` | L2 | `@orkestrel/codec` `^0.0.9`, `@orkestrel/contract` `^0.0.22` | |
69
- | `@orkestrel/ndjson` | `0.0.16` | L1 | `@orkestrel/contract` `^0.0.22` | |
68
+ | `@orkestrel/msg` | `0.0.17` | L2 | `@orkestrel/codec` `^0.0.10`, `@orkestrel/contract` `^0.0.23` | |
69
+ | `@orkestrel/ndjson` | `0.0.17` | L1 | `@orkestrel/contract` `^0.0.23` | |
70
70
  | `@orkestrel/ollama` | `0.0.34` | L6 | `@orkestrel/tool` `^0.0.22`, `@orkestrel/agent` `^0.0.40`, `@orkestrel/budget` `^0.0.17`, `@orkestrel/ndjson` `^0.0.16`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22` | |
71
- | `@orkestrel/pool` | `0.0.20` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
71
+ | `@orkestrel/pool` | `0.0.21` | L2 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
72
72
  | `@orkestrel/probe` | `0.0.29` | L5 | `@orkestrel/lsp` `^0.0.14`, `@orkestrel/mcp` `^0.0.42`, `@orkestrel/pool` `^0.0.20`, `@orkestrel/tool` `^0.0.22`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/process` `^0.0.18`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22` | `vitest` `^4.1.12 \|\| ^5.1.0`, `typescript` `^6.0.3 \|\| ^7.0.2` |
73
- | `@orkestrel/process` | `0.0.18` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
73
+ | `@orkestrel/process` | `0.0.19` | L2 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
74
74
  | `@orkestrel/program` | `0.0.20` | L4 | `@orkestrel/rater` `^0.0.21`, `@orkestrel/reason` `^0.0.17`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/qualifier` `^0.0.21` | |
75
75
  | `@orkestrel/qualifier` | `0.0.21` | L3 | `@orkestrel/reason` `^0.0.17`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
76
76
  | `@orkestrel/queue` | `0.0.21` | L3 | `@orkestrel/abort` `^0.0.16`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/database` `^0.0.22` | |
77
77
  | `@orkestrel/rater` | `0.0.21` | L3 | `@orkestrel/reason` `^0.0.17`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
78
- | `@orkestrel/reason` | `0.0.17` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
78
+ | `@orkestrel/reason` | `0.0.18` | L2 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
79
79
  | `@orkestrel/relation` | `0.0.20` | L3 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/database` `^0.0.22` | |
80
- | `@orkestrel/router` | `0.0.20` | L2 | `@orkestrel/abort` `^0.0.16`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
81
- | `@orkestrel/scaffold` | `0.0.130` | L3 | `@orkestrel/console` `^0.0.19`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/markdown` `^0.0.20`, `@orkestrel/template` `^0.0.13` | |
80
+ | `@orkestrel/router` | `0.0.21` | L2 | `@orkestrel/abort` `^0.0.17`, `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
81
+ | `@orkestrel/scaffold` | `0.0.131` | L3 | `@orkestrel/console` `^0.0.19`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/markdown` `^0.0.20`, `@orkestrel/template` `^0.0.13` | |
82
82
  | `@orkestrel/sea` | `0.0.22` | L3 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/process` `^0.0.18`, `@orkestrel/contract` `^0.0.22` | |
83
83
  | `@orkestrel/server` | `0.0.26` | L3 | `@orkestrel/abort` `^0.0.16`, `@orkestrel/codec` `^0.0.9`, `@orkestrel/router` `^0.0.20`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22` | |
84
- | `@orkestrel/sqlite` | `0.0.17` | L1 | `@orkestrel/contract` `^0.0.22` | |
85
- | `@orkestrel/sse` | `0.0.13` | L2 | `@orkestrel/codec` `^0.0.9`, `@orkestrel/contract` `^0.0.22` | |
84
+ | `@orkestrel/sqlite` | `0.0.18` | L1 | `@orkestrel/contract` `^0.0.23` | |
85
+ | `@orkestrel/sse` | `0.0.14` | L2 | `@orkestrel/codec` `^0.0.10`, `@orkestrel/contract` `^0.0.23` | |
86
86
  | `@orkestrel/study` | `0.0.17` | L7 | `@orkestrel/tool` `^0.0.22`, `@orkestrel/abort` `^0.0.16`, `@orkestrel/agent` `^0.0.40`, `@orkestrel/budget` `^0.0.17`, `@orkestrel/ollama` `^0.0.34`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22` | |
87
- | `@orkestrel/table` | `0.0.15` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
88
- | `@orkestrel/template` | `0.0.13` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
87
+ | `@orkestrel/table` | `0.0.16` | L2 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
88
+ | `@orkestrel/template` | `0.0.14` | L2 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
89
89
  | `@orkestrel/terminal` | `0.0.24` | L3 | `@orkestrel/sse` `^0.0.13`, `@orkestrel/form` `^0.0.16`, `@orkestrel/console` `^0.0.19`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/database` `^0.0.22` | |
90
- | `@orkestrel/test` | `0.0.33` | L1 | `@orkestrel/contract` `^0.0.22` | `vitest` `^4.1.12 \|\| ^5.1.0`, `playwright` `^1.64.1` |
91
- | `@orkestrel/timeout` | `0.0.16` | L1 | `@orkestrel/contract` `^0.0.22` | |
92
- | `@orkestrel/tool` | `0.0.22` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
90
+ | `@orkestrel/test` | `0.0.34` | L1 | `@orkestrel/contract` `^0.0.23` | `vitest` `^4.1.12 \|\| ^5.1.0`, `playwright` `^1.65.0` |
91
+ | `@orkestrel/timeout` | `0.0.17` | L1 | `@orkestrel/contract` `^0.0.23` | |
92
+ | `@orkestrel/tool` | `0.0.23` | L2 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
93
93
  | `@orkestrel/toolbox` | `0.0.29` | L6 | `@orkestrel/form` `^0.0.16`, `@orkestrel/tool` `^0.0.22`, `@orkestrel/agent` `^0.0.40`, `@orkestrel/server` `^0.0.26`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/database` `^0.0.22`, `@orkestrel/relation` `^0.0.20`, `@orkestrel/terminal` `^0.0.24`, `@orkestrel/workflow` `^0.0.27`, `@orkestrel/workspace` `^0.0.16` | |
94
- | `@orkestrel/websocket` | `0.0.18` | L2 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22` | |
94
+ | `@orkestrel/websocket` | `0.0.19` | L2 | `@orkestrel/emitter` `^0.0.16`, `@orkestrel/contract` `^0.0.23` | |
95
95
  | `@orkestrel/worker` | `0.0.21` | L4 | `@orkestrel/pool` `^0.0.20`, `@orkestrel/queue` `^0.0.21`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/database` `^0.0.22` | |
96
96
  | `@orkestrel/workflow` | `0.0.27` | L4 | `@orkestrel/abort` `^0.0.16`, `@orkestrel/queue` `^0.0.21`, `@orkestrel/budget` `^0.0.17`, `@orkestrel/emitter` `^0.0.15`, `@orkestrel/timeout` `^0.0.16`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/database` `^0.0.22` | |
97
97
  | `@orkestrel/workspace` | `0.0.16` | L3 | `@orkestrel/emitter` `^0.0.15`, `@orkestrel/contract` `^0.0.22`, `@orkestrel/database` `^0.0.22` | |
@@ -21,7 +21,7 @@ import {
21
21
  } from 'node:fs'
22
22
  import { dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from 'node:path'
23
23
 
24
- export function hasAsciiUrlControl(value: string): boolean {
24
+ export function hasASCIIURLControl(value: string): boolean {
25
25
  for (const character of value) {
26
26
  const code = character.codePointAt(0)
27
27
  if (code !== undefined && (code <= 0x1f || code === 0x7f)) return true
@@ -468,7 +468,7 @@ export function environmentPathError(owner: string, target: string): string | un
468
468
 
469
469
  export function environmentSourceError(owner: string, source: string): string | undefined {
470
470
  const normalizedSource = source.replaceAll('\\', '/')
471
- if (hasAsciiUrlControl(normalizedSource)) {
471
+ if (hasASCIIURLControl(normalizedSource)) {
472
472
  return 'Environment module URLs cannot contain ASCII controls'
473
473
  }
474
474
  const [sourcePath] = normalizedSource.split(/[?#]/)
@@ -521,6 +521,7 @@ Declarative constructors for the `ContractShape` union (`src/core/shapers.ts`).
521
521
  | `stringShape` | function | `(options?: StringShapeOptions) => StringShape` | Builds a string `StringShape`. |
522
522
  | `numberShape` | function | `(options?: NumberShapeOptions) => NumberShape` | Builds a numeric `NumberShape`. |
523
523
  | `integerShape` | function | `(options?: Omit<NumberShapeOptions, 'integer'>) => NumberShape` | Builds an integer `NumberShape` — forces `integer: true`. |
524
+ | `dateShape` | function | `(options?: Omit<StringShapeOptions, 'date' \| 'pattern'>) => StringShape` | Builds a calendar-date `StringShape` — forces `date: true`. |
524
525
  | `booleanShape` | function | `(options?: BooleanShapeOptions) => BooleanShape` | Builds a `BooleanShape`. |
525
526
  | `nullShape` | function | `(options?: NullShapeOptions) => NullShape` | Builds a `NullShape`. |
526
527
  | `literalShape` | function | `<const T extends readonly LiteralValue[]>(values: T, options?: LiteralShapeOptions) => LiteralShape<Readonly<T>>` | Builds a literal shape from a fixed set of primitive values. |
@@ -541,6 +542,23 @@ An ordinary `oneOfShape` parser returns the input itself when exactly one arm ac
541
542
 
542
543
  **String bounds count code points.** `min` and `max` on a string count what the `minLength` and `maxLength` the shape emits count, so one astral character has a length of one and a lone surrogate counts as one. `stringOf` and the two reports share `matchesStringLength`, which decides from `.length` where it can: a string holds at most `.length` code points and at least half that. Only where a bound sits between those two figures does it call `computeSurrogatePairs`, which stops as soon as the pairs it has found settle the bound.
543
544
 
545
+ **Calendar dates.** `dateShape` builds a string shape whose guard and parser admit exactly a calendar-valid `YYYY-MM-DD` and coerce nothing, so `2026-02-30`, `2026-1-10`, a date-time, and a `Date` object all refuse. A refused date reports a `'constraint'` fault with `expected: 'date'` and `constraint: 'date'`, as a fraction against `integerShape` reports `'integer'`, and the emitted schema carries `format: 'date'` with no `pattern`. A strict `schemaToShape` reads that schema back as the date shape; a lenient one keeps `format` an annotation and builds a plain string shape. A string shape that declares both `date` and `pattern`, or bounds that exclude length 10, refuses at build.
546
+
547
+ This compiles a date field and shows what it admits, refuses, reports, and emits.
548
+
549
+ ```ts
550
+ import { createContract, dateShape, objectShape } from '@orkestrel/contract'
551
+
552
+ const booking = createContract(objectShape({ arrival: dateShape() }))
553
+
554
+ booking.is({ arrival: '2024-02-29' }) // true
555
+ booking.is({ arrival: '2026-02-29' }) // false — 2026 is not a leap year
556
+ booking.parse({ arrival: '2026-1-10' }) // undefined
557
+ booking.audit({ arrival: '2026-02-30' })
558
+ // [{ reason: 'constraint', path: ['arrival'], expected: 'date', constraint: 'date', received: '"2026-02-30"' }]
559
+ booking.schema.properties?.arrival // { type: 'string', format: 'date' }
560
+ ```
561
+
544
562
  **Field defaults.** `optionalShape(inner, { default })` lets a declaration state what an absent field reads as. The compiled parser fills the default where the property is absent or `undefined`, through the inner parser, on a fresh copy when the default is a container, so nested defaults apply and two parses share no tree. A default on a `jsonShape`, a `rawShape`, or a union inner reaches you as a frozen copy, because those parsers return their input by identity. `is`, `audit`, `explain`, and `generate` do not read a default: an absent optional stays canonical, so `is({})` is `true`, and `generate` keeps omitting the key or drawing from `inner`. The emitted property schema carries the keyword. `null` is a value and fills; a present `undefined` is a `structure` refusal, because absence is not a value.
545
563
 
546
564
  The builder and `cloneShape` own a frozen copy of a value that passes `isJSONValue`, so a stored shape survives a JSON round trip. Every compiler refuses a default its `inner` guard refuses, refinements included, with code `structure` at `[…path, 'default']`: a restored declaration never met a builder, and `validateShape` judges structure only. A shape holding a default builds the guard family for that check whichever artifact you read first; a shape holding none builds what it always built.
@@ -578,7 +596,7 @@ The precedence below assumes a readable node and a lenient conversion. A readabl
578
596
 
579
597
  A lenient conversion carries a property's `default` when the key is not in `required`, the object is closed with no union ancestor, and the value is one the property's primitive or literal guard accepts. It drops every other `default`, because a carried default that cannot compile would end the conversion's totality.
580
598
 
581
- **Strict conversion.** `schemaToShape(schema, { strict: true })` is the door for a foreign schema. It refuses, with code `structure` and the keyword's path, what the lenient walk would widen or read past: every node the walk would widen to `rawShape` (an empty schema, a `type` typo at any depth, a non-record child, an array with no `items`, exhausted depth, and a cycle), a keyword outside `STRICT_SCHEMA_KEYWORDS` (`$ref`, `$defs`, `definitions`, `const`, `allOf`, `$anchor`, `$dynamicAnchor`, the `content*` keywords, `nullable`, `discriminator`, `example`, `patternProperties`, `propertyNames`, and `prefixItems`), `pattern` and `format`, which no compiled shape asserts, a malformed keyword value or annotation, a boolean schema, an `enum` entry that is neither a finite primitive nor `null`, a contradictory or malformed bound, a keyword the node's type never reads, a `type` beside a union, a pair of keywords only one of which the walk would keep, an enum member its `type` contradicts, a `required` name not in `properties`, breadth past `INFER_BREADTH_LIMIT`, and a `default` with no optional property to fill or one its schema refuses. `oneOf` keeps exactly-one here, because this walk reads every keyword that could keep two arms apart. An object with no `additionalProperties` closes, unlike JSON Schema's own default, because a misspelled key at a foreign door must reach `audit`; an explicit `true` or schema value stays open. Below a `oneOf` it refuses instead, at any depth, because closing it could change which arms match: two arms declaring optional `a` and `b` both match `{ a: 'x' }` as written, and only one does once closed. It accepts the annotations a schema generator emits, which assert nothing and which the shape drops: `title`, `$schema`, `$id`, and `$comment` when strings, `examples` when an array, and `deprecated`, `readOnly`, and `writeOnly` when booleans. A default under a union or on an open object refuses with `placement` at its path in the schema, ending `properties`, the key, and `default`.
599
+ **Strict conversion.** `schemaToShape(schema, { strict: true })` is the door for a foreign schema. It refuses, with code `structure` and the keyword's path, what the lenient walk would widen or read past: every node the walk would widen to `rawShape` (an empty schema, a `type` typo at any depth, a non-record child, an array with no `items`, exhausted depth, and a cycle), a keyword outside `STRICT_SCHEMA_KEYWORDS` (`$ref`, `$defs`, `definitions`, `const`, `allOf`, `$anchor`, `$dynamicAnchor`, the `content*` keywords, `nullable`, `discriminator`, `example`, `patternProperties`, `propertyNames`, and `prefixItems`), `pattern` and every `format` but `'date'` on a string node, which no compiled shape asserts, a `format: 'date'` whose length bounds exclude length 10, a malformed keyword value or annotation, a boolean schema, an `enum` entry that is neither a finite primitive nor `null`, a contradictory or malformed bound, a keyword the node's type never reads, a `type` beside a union, a pair of keywords only one of which the walk would keep, an enum member its `type` contradicts, a `required` name not in `properties`, breadth past `INFER_BREADTH_LIMIT`, and a `default` with no optional property to fill or one its schema refuses. `oneOf` keeps exactly-one here, because this walk reads every keyword that could keep two arms apart. An object with no `additionalProperties` closes, unlike JSON Schema's own default, because a misspelled key at a foreign door must reach `audit`; an explicit `true` or schema value stays open. Below a `oneOf` it refuses instead, at any depth, because closing it could change which arms match: two arms declaring optional `a` and `b` both match `{ a: 'x' }` as written, and only one does once closed. It accepts the annotations a schema generator emits, which assert nothing and which the shape drops: `title`, `$schema`, `$id`, and `$comment` when strings, `examples` when an array, and `deprecated`, `readOnly`, and `writeOnly` when booleans. A default under a union or on an open object refuses with `placement` at its path in the schema, ending `properties`, the key, and `default`.
582
600
 
583
601
  **Round-trip law:** for any READABLE value `v` — including `NaN`, `±Infinity`, a `Map`, a `Set`, a class instance, a function, a symbol, a bigint, and readable cyclic hosts — `compileGuard(schemaToShape(valueToSchema(v)))(v) === true`, with widening as the ONLY source of looseness, never narrowing. An unreadable host is refused before the law produces a schema. The law otherwise retains its three limits: JSON absence, `Date` serialization, and unstable reads between inference and validation. A widened node cannot be auto-generated: `createContract(schemaToShape(x)).generate()` throws when the conversion widened anywhere; its parser returns `undefined` for readable invalid input and propagates the shared coded refusal when a required read fails.
584
602
 
@@ -602,7 +620,7 @@ what the resolution produces.
602
620
  | Name | Kind | Signature | Summary |
603
621
  | ---------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
604
622
  | `ContractShape` | type | `StringShape \| NumberShape \| BooleanShape \| NullShape \| LiteralShape \| ArrayShape \| ObjectShape \| UnionShape \| OptionalShape \| NullableShape \| JSONShape \| ShapeShape \| RawShape` | Describes a value declaratively — a declaration the shape builders build and the compilers turn into a guard, a parser, a JSON Schema, and a generator. |
605
- | `StringShape` | interface | `{ category, min?, max?, pattern?, description? }` | Describes a string with optional length and pattern constraints. |
623
+ | `StringShape` | interface | `{ category, min?, max?, pattern?, date?, description? }` | Describes a string with optional length, pattern, and calendar-date constraints. |
606
624
  | `NumberShape` | interface | `{ category, min?, max?, integer?, description? }` | Describes a number with optional bounds; `integer` restricts to whole numbers. |
607
625
  | `BooleanShape` | interface | `{ category, description? }` | Describes a boolean — accepts only `true` or `false`. |
608
626
  | `NullShape` | interface | `{ category, description? }` | Describes a null value — accepts only `null`. |
@@ -620,7 +638,7 @@ what the resolution produces.
620
638
  | `InferOpenIndex` | type | `[A] extends [false] ? unknown : [A] extends [true] ? { readonly [k: string]: unknown; } : [A] extends [ContractShape] ? { readonly [k: string]: unknown; } : unknown` | Computes the index-signature contribution of a MIXED object shape's `additionalProperties` — one with both fixed `properties` and an open tail. |
621
639
  | `InferMutable` | type | `{ -readonly [K in keyof Infer<S>]: Infer<S>[K]; }` | Strips the TOP-LEVEL `readonly` modifiers from `Infer` (a shallow strip — nested object/array properties stay readonly) — for consumers writing the parsed value's own fields. |
622
640
  | `InferUnion` | type | `V extends ReadonlyArray<infer U> ? (U extends ContractShape ? Infer<U> : never) : never` | Resolves `Infer` of a union shape's `variants` — the union of each variant's inferred type. |
623
- | `StringShapeOptions` | interface | `{ min?, max?, pattern?, description? }` | Groups the options for `StringShape` (through `stringShape`). |
641
+ | `StringShapeOptions` | interface | `{ min?, max?, pattern?, date?, description? }` | Groups the options for `StringShape` (through `stringShape`). |
624
642
  | `NumberShapeOptions` | interface | `{ min?, max?, integer?, description? }` | Groups the options for `NumberShape` (through `numberShape` / `integerShape`). |
625
643
  | `BooleanShapeOptions` | interface | `{ description? }` | Groups the options for `BooleanShape` (through `booleanShape`). |
626
644
  | `NullShapeOptions` | interface | `{ description? }` | Groups the options for `NullShape` (through `nullShape`). |
@@ -718,6 +736,8 @@ The canonicalization leaves (`canonicalStringify`, `encodeLeaf`) and the format-
718
736
  | `classifyFormat` | function | `(value: string) => SchemaFormat \| undefined` | Classifies an already-bounded string against the pattern-only and calendar-checked `SchemaFormat` vocabulary. |
719
737
  | `samplesToFormat` | function | `(values: readonly unknown[]) => SchemaFormat \| undefined` | Classifies a list of sample values against the `SchemaFormat` vocabulary, requiring unanimity. |
720
738
  | `matchesISOInstant` | function | `(value: string) => boolean` | Checks whether a supported ISO-8601 date or date-time names a real instant. |
739
+ | `matchesCalendarDate` | function | `(value: string) => boolean` | Checks whether a string is exactly a calendar-valid `YYYY-MM-DD` date. |
740
+ | `computeMonthLength` | function | `(year: number, month: number) => number` | Computes the number of days in a month of the Gregorian calendar. |
721
741
  | `ValueToSchemaOptions` | interface | `{ limits?, closed?, format?, enum? }` | Groups the options for `valueToSchema` / `samplesToSchema`. |
722
742
  | `ValueToSchemaLimits` | interface | `{ depth?, properties? }` | Holds the per-walk budgets `ValueToSchemaOptions` groups under `limits`. |
723
743
  | `SampleMemo` | interface | `{ rows, schemas }` | Holds the per-walk memo the multi-sample walk behind `samplesToSchema` owns, keyed by the ORDERED identities of the rows a slot collected. |
@@ -728,6 +748,7 @@ The canonicalization leaves (`canonicalStringify`, `encodeLeaf`) and the format-
728
748
  | `INFER_ENUM_LIMIT` | const | `12` | Caps by default at `12` the number of distinct values a multi-sample slot may hold before enum inference gives up and falls back to a bare `type`, frozen. |
729
749
  | `FORMAT_MAX_LENGTH` | const | `128` | Caps at `128` the string length `stringToFormat` attempts to classify, frozen. |
730
750
  | `FORMAT_PATTERNS` | const | `Readonly<Record<'uuid' \| 'email' \| 'uri', RegExp>>` | Holds the pure-regex matchers backing `stringToFormat`'s pattern-only formats (`uuid` / `email` / `uri`), frozen as data. |
751
+ | `DATE_LENGTH` | const | `10` | Holds `10`, the length of every `YYYY-MM-DD` date a date string shape admits. |
731
752
 
732
753
  Canonicalization classifies every non-null object at the read boundary before choosing a traversal. Arrays retain the dense indexed path; the shared realm-neutral `matchesRecordBrand` rule selects sorted own keys for ordinary, null-prototype, and foreign-realm plain records; every other readable exotic object — including a class whose prototype a caller reparented to `null` — keeps the existing `JSON.stringify` fallback. A failed prototype inspection is unreadable structure, reported as `canonicalStringify: value could not be read`.
733
754
 
@@ -774,8 +795,8 @@ One diagnostic for each artifact that answers yes-or-no. `compileReporter` is th
774
795
  | `Fault` | type | `{ readonly reason: 'type'; readonly path: FieldPath; readonly expected: FaultKind; readonly received: string; } \| { readonly reason: 'missing'; readonly path: FieldPath; readonly expected: FaultKind; } \| { readonly reason: 'constraint'; readonly path: FieldPath; readonly expected: FaultKind; readonly constraint: FaultConstraint; readonly limit?: number \| string; readonly received: string; } \| { readonly reason: 'variant'; readonly path: FieldPath; readonly variants: number; readonly key?: string; readonly expected?: readonly LiteralValue[]; } \| { readonly reason: 'oneOf'; readonly path: FieldPath; readonly matched: number; readonly key?: string; readonly expected?: readonly LiteralValue[]; }` | Represents a single structured parse-failure diagnostic — one entry of an `ContractInterface.explain` report. |
775
796
  | `ExtraFault` | interface | `{ reason, path }` | Represents a key present on a value that its closed object shape does not declare. |
776
797
  | `AuditFault` | type | `Fault \| ExtraFault` | Covers every fault an audit reports — the parse faults plus undeclared keys. |
777
- | `FaultKind` | type | `'string' \| 'number' \| 'integer' \| 'boolean' \| 'null' \| 'literal' \| 'array' \| 'object' \| 'union' \| 'json' \| 'shape'` | Names the kind of value a `Fault` expected — the shape-projected counterpart of a `ContractShape`'s `category`. |
778
- | `FaultConstraint` | type | `'min' \| 'max' \| 'pattern' \| 'integer'` | Names the refinement a `Fault` of reason `'constraint'` violates. |
798
+ | `FaultKind` | type | `'string' \| 'date' \| 'number' \| 'integer' \| 'boolean' \| 'null' \| 'literal' \| 'array' \| 'object' \| 'union' \| 'json' \| 'shape'` | Names the kind of value a `Fault` expected — the shape-projected counterpart of a `ContractShape`'s `category`. |
799
+ | `FaultConstraint` | type | `'min' \| 'max' \| 'pattern' \| 'date' \| 'integer'` | Names the refinement a `Fault` of reason `'constraint'` violates. |
779
800
 
780
801
  #### How a union is audited and reported
781
802
 
@@ -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).
@@ -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
@@ -16,7 +16,7 @@
16
16
  "storage": "agents/orchestration.md",
17
17
  "destination": ".agents/orchestration.md",
18
18
  "executable": false,
19
- "digest": "67e49a59459fba935c1948d26c9b9fa48001e96d3b0fe0cee194ed724ea96c35"
19
+ "digest": "a434e7b16e375549de56a078da62f14663dfd0b5da5749b3f5099b3e4975bb6e"
20
20
  },
21
21
  {
22
22
  "storage": "agents/platforms/posix.md",
@@ -628,7 +628,7 @@
628
628
  "storage": "claude/agents/orkestrel.md",
629
629
  "destination": ".claude/agents/orkestrel.md",
630
630
  "executable": false,
631
- "digest": "74c10351b39d44a2f59609664a42cfdfdcd7cc7e2839ef037e0221be2d04ca86"
631
+ "digest": "b2c55e267355a8865a03069be17858340f31773448598750e9e39768c67cef7a"
632
632
  },
633
633
  {
634
634
  "storage": "claude/agents/planner.md",
@@ -910,7 +910,7 @@
910
910
  "storage": "configs/helpers.ts",
911
911
  "destination": "configs/helpers.ts",
912
912
  "executable": false,
913
- "digest": "39e3d9607e51ece06a2fb7f1a71bfef75141e89a0c7785481a78913c1c0ff8a3"
913
+ "digest": "316a70bb0e3eb51d9831dad144b613e86092fc82c6288b9ce428d2bb0cc93ba0"
914
914
  },
915
915
  {
916
916
  "storage": "configs/policy.ts",
@@ -1036,7 +1036,7 @@
1036
1036
  "storage": "guides/contract.md",
1037
1037
  "destination": "guides/contract.md",
1038
1038
  "executable": false,
1039
- "digest": "839c8ee48aedbbe5cbd8bbaebf0074029c3d100256b2be3e211d31b006834ce1"
1039
+ "digest": "3092cdb3ef53f9dfcc59f2a06e665e609ddca3fda2b6a45686863461e383f277"
1040
1040
  },
1041
1041
  {
1042
1042
  "storage": "guides/csv.md",
@@ -1048,7 +1048,7 @@
1048
1048
  "storage": "guides/database.md",
1049
1049
  "destination": "guides/database.md",
1050
1050
  "executable": false,
1051
- "digest": "f7cb2796e7c1d4fe78ab54ebe04b80feb411a07891c04c7168fc1f48cfa0af61"
1051
+ "digest": "aa18f2aaed701023c831aef84aa069c4b4e74d9b0da3a29120a03e94e7a14188"
1052
1052
  },
1053
1053
  {
1054
1054
  "storage": "guides/emitter.md",
@@ -1198,7 +1198,7 @@
1198
1198
  "storage": "guides/scaffold.md",
1199
1199
  "destination": "guides/scaffold.md",
1200
1200
  "executable": false,
1201
- "digest": "9e17c6cdf212c440be057a5336983488329bb67bd66f334b85624d8e457c034a"
1201
+ "digest": "64be1c48b9d18dfb6cd7f139035ede8b6163c9efcb2de9bf2d7c55097b52c9cd"
1202
1202
  },
1203
1203
  {
1204
1204
  "storage": "guides/sea.md",
@@ -1336,7 +1336,7 @@
1336
1336
  "storage": "tests/config.test.ts",
1337
1337
  "destination": "tests/config.test.ts",
1338
1338
  "executable": false,
1339
- "digest": "5f0feb333edeb7269b433fc1ea573a153aa35b47107f9ca0ffef48204d8f8986"
1339
+ "digest": "f164d7ae0a443b1373798c09c14772fd5e097cfad7959f27e7eb2d3aea6a30d6"
1340
1340
  },
1341
1341
  {
1342
1342
  "storage": "tests/policy.test.ts",
@@ -1417,5 +1417,5 @@
1417
1417
  "scripts"
1418
1418
  ],
1419
1419
  "surface": [],
1420
- "digest": "76a071e6da224c1cfef62b9e73f4f08e16b7cf91ff8a68b9a2464da95eaed082"
1420
+ "digest": "226166ccc0bf247428a82035e08915bf36a9c9fe92a053c08d744e99a2c904eb"
1421
1421
  }
@@ -5174,7 +5174,7 @@ describe('configuration helpers', () => {
5174
5174
  'environmentSourceError',
5175
5175
  'fileSystemPath',
5176
5176
  'findPackageDirectory',
5177
- 'hasAsciiUrlControl',
5177
+ 'hasASCIIURLControl',
5178
5178
  'isBoundaryExemptModule',
5179
5179
  'isExtractorModule',
5180
5180
  'isOutsideWorkspacePath',
@@ -5462,8 +5462,8 @@ describe('configuration helpers', () => {
5462
5462
  "const module = import('./module.js')\nconst asset = new URL('./asset%20name.png', import.meta.url)\nvoid module\nvoid asset\n"
5463
5463
  writeFileSync(source, code, 'utf8')
5464
5464
 
5465
- expect(configHelpers.hasAsciiUrlControl('clean')).toBe(false)
5466
- expect(configHelpers.hasAsciiUrlControl('line\u0000break')).toBe(true)
5465
+ expect(configHelpers.hasASCIIURLControl('clean')).toBe(false)
5466
+ expect(configHelpers.hasASCIIURLControl('line\u0000break')).toBe(true)
5467
5467
  expect(configHelpers.isBoundaryExemptModule('virtual:control')).toBe(true)
5468
5468
  expect(configHelpers.isBoundaryExemptModule(resolve(POLICY_ROOT, 'src/core/index.ts'))).toBe(
5469
5469
  false,
@@ -4,7 +4,7 @@ let _orkestrel_template = require("@orkestrel/template");
4
4
  let _orkestrel_emitter = require("@orkestrel/emitter");
5
5
  var package_default = {
6
6
  name: "@orkestrel/scaffold",
7
- version: "0.0.131",
7
+ version: "0.0.132",
8
8
  description: "Scaffold workspaces with commands: new, audit, surface, repair, catalog, and overwrite.",
9
9
  keywords: [
10
10
  "audit",
@@ -96,27 +96,27 @@ var package_default = {
96
96
  "prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test && npm run test:templates && npm run test:distribution -- --mode release"
97
97
  },
98
98
  dependencies: {
99
- "@orkestrel/console": "^0.0.19",
100
- "@orkestrel/contract": "^0.0.22",
101
- "@orkestrel/emitter": "^0.0.15",
102
- "@orkestrel/markdown": "^0.0.20",
103
- "@orkestrel/process": "^0.0.18",
104
- "@orkestrel/template": "^0.0.13"
99
+ "@orkestrel/console": "^0.0.20",
100
+ "@orkestrel/contract": "^0.0.23",
101
+ "@orkestrel/emitter": "^0.0.16",
102
+ "@orkestrel/markdown": "^0.0.21",
103
+ "@orkestrel/process": "^0.0.19",
104
+ "@orkestrel/template": "^0.0.14"
105
105
  },
106
106
  devDependencies: {
107
107
  "@microsoft/api-extractor": "^7.60.1",
108
108
  "@orkestrel/browser": "^0.0.32",
109
109
  "@orkestrel/guide": "^0.0.30",
110
- "@orkestrel/html": "^0.0.15",
110
+ "@orkestrel/html": "^0.0.16",
111
111
  "@orkestrel/probe": "^0.0.29",
112
- "@orkestrel/test": "^0.0.33",
112
+ "@orkestrel/test": "^0.0.34",
113
113
  "@types/node": "^24.19.2",
114
114
  "@vitest/browser-playwright": "^5.1.0",
115
115
  "oxfmt": "^0.78.0",
116
116
  "oxlint": "^1.93.0",
117
117
  "playwright": "^1.64.1",
118
118
  "typescript": "^7.0.2",
119
- "vite": "^8.3.7",
119
+ "vite": "^8.3.8",
120
120
  "vitest": "^5.1.0"
121
121
  },
122
122
  engines: { "node": ">=22.18.0" }
@@ -3,7 +3,7 @@ import { fillTemplate } from "@orkestrel/template";
3
3
  import { Emitter } from "@orkestrel/emitter";
4
4
  var package_default = {
5
5
  name: "@orkestrel/scaffold",
6
- version: "0.0.131",
6
+ version: "0.0.132",
7
7
  description: "Scaffold workspaces with commands: new, audit, surface, repair, catalog, and overwrite.",
8
8
  keywords: [
9
9
  "audit",
@@ -95,27 +95,27 @@ var package_default = {
95
95
  "prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test && npm run test:templates && npm run test:distribution -- --mode release"
96
96
  },
97
97
  dependencies: {
98
- "@orkestrel/console": "^0.0.19",
99
- "@orkestrel/contract": "^0.0.22",
100
- "@orkestrel/emitter": "^0.0.15",
101
- "@orkestrel/markdown": "^0.0.20",
102
- "@orkestrel/process": "^0.0.18",
103
- "@orkestrel/template": "^0.0.13"
98
+ "@orkestrel/console": "^0.0.20",
99
+ "@orkestrel/contract": "^0.0.23",
100
+ "@orkestrel/emitter": "^0.0.16",
101
+ "@orkestrel/markdown": "^0.0.21",
102
+ "@orkestrel/process": "^0.0.19",
103
+ "@orkestrel/template": "^0.0.14"
104
104
  },
105
105
  devDependencies: {
106
106
  "@microsoft/api-extractor": "^7.60.1",
107
107
  "@orkestrel/browser": "^0.0.32",
108
108
  "@orkestrel/guide": "^0.0.30",
109
- "@orkestrel/html": "^0.0.15",
109
+ "@orkestrel/html": "^0.0.16",
110
110
  "@orkestrel/probe": "^0.0.29",
111
- "@orkestrel/test": "^0.0.33",
111
+ "@orkestrel/test": "^0.0.34",
112
112
  "@types/node": "^24.19.2",
113
113
  "@vitest/browser-playwright": "^5.1.0",
114
114
  "oxfmt": "^0.78.0",
115
115
  "oxlint": "^1.93.0",
116
116
  "playwright": "^1.64.1",
117
117
  "typescript": "^7.0.2",
118
- "vite": "^8.3.7",
118
+ "vite": "^8.3.8",
119
119
  "vitest": "^5.1.0"
120
120
  },
121
121
  engines: { "node": ">=22.18.0" }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@orkestrel/scaffold",
3
- "version": "0.0.131",
3
+ "version": "0.0.132",
4
4
  "description": "Scaffold workspaces with commands: new, audit, surface, repair, catalog, and overwrite.",
5
5
  "keywords": [
6
6
  "audit",
@@ -99,27 +99,27 @@
99
99
  "prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test && npm run test:templates && npm run test:distribution -- --mode release"
100
100
  },
101
101
  "dependencies": {
102
- "@orkestrel/console": "^0.0.19",
103
- "@orkestrel/contract": "^0.0.22",
104
- "@orkestrel/emitter": "^0.0.15",
105
- "@orkestrel/markdown": "^0.0.20",
106
- "@orkestrel/process": "^0.0.18",
107
- "@orkestrel/template": "^0.0.13"
102
+ "@orkestrel/console": "^0.0.20",
103
+ "@orkestrel/contract": "^0.0.23",
104
+ "@orkestrel/emitter": "^0.0.16",
105
+ "@orkestrel/markdown": "^0.0.21",
106
+ "@orkestrel/process": "^0.0.19",
107
+ "@orkestrel/template": "^0.0.14"
108
108
  },
109
109
  "devDependencies": {
110
110
  "@microsoft/api-extractor": "^7.60.1",
111
111
  "@orkestrel/browser": "^0.0.32",
112
112
  "@orkestrel/guide": "^0.0.30",
113
- "@orkestrel/html": "^0.0.15",
113
+ "@orkestrel/html": "^0.0.16",
114
114
  "@orkestrel/probe": "^0.0.29",
115
- "@orkestrel/test": "^0.0.33",
115
+ "@orkestrel/test": "^0.0.34",
116
116
  "@types/node": "^24.19.2",
117
117
  "@vitest/browser-playwright": "^5.1.0",
118
118
  "oxfmt": "^0.78.0",
119
119
  "oxlint": "^1.93.0",
120
120
  "playwright": "^1.64.1",
121
121
  "typescript": "^7.0.2",
122
- "vite": "^8.3.7",
122
+ "vite": "^8.3.8",
123
123
  "vitest": "^5.1.0"
124
124
  },
125
125
  "engines": {