@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 +10 -10
- package/dist/host/agents/orchestration.md +4 -3
- package/dist/host/claude/agents/orkestrel.md +28 -28
- package/dist/host/configs/helpers.ts +2 -2
- package/dist/host/guides/contract.md +26 -5
- package/dist/host/guides/database.md +43 -37
- package/dist/host/guides/scaffold.md +2 -2
- package/dist/host/manifest.json +8 -8
- package/dist/host/tests/config.test.ts +3 -3
- package/dist/src/core/index.cjs +10 -10
- package/dist/src/core/index.js +10 -10
- package/package.json +10 -10
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.
|
|
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.
|
|
106
|
-
"@orkestrel/contract": "^0.0.
|
|
107
|
-
"@orkestrel/emitter": "^0.0.
|
|
108
|
-
"@orkestrel/markdown": "^0.0.
|
|
109
|
-
"@orkestrel/process": "^0.0.
|
|
110
|
-
"@orkestrel/template": "^0.0.
|
|
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.
|
|
116
|
+
"@orkestrel/html": "^0.0.16",
|
|
117
117
|
"@orkestrel/probe": "^0.0.29",
|
|
118
|
-
"@orkestrel/test": "^0.0.
|
|
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.
|
|
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,
|
|
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,
|
|
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,
|
|
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.
|
|
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.
|
|
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.
|
|
53
|
-
| `@orkestrel/console` | `0.0.
|
|
54
|
-
| `@orkestrel/contract` | `0.0.
|
|
55
|
-
| `@orkestrel/csv` | `0.0.
|
|
56
|
-
| `@orkestrel/database` | `0.0.
|
|
57
|
-
| `@orkestrel/emitter` | `0.0.
|
|
58
|
-
| `@orkestrel/form` | `0.0.
|
|
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.
|
|
61
|
-
| `@orkestrel/indexeddb` | `0.0.
|
|
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.
|
|
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.
|
|
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.
|
|
69
|
-
| `@orkestrel/ndjson` | `0.0.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
81
|
-
| `@orkestrel/scaffold` | `0.0.
|
|
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.
|
|
85
|
-
| `@orkestrel/sse` | `0.0.
|
|
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.
|
|
88
|
-
| `@orkestrel/template` | `0.0.
|
|
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.
|
|
91
|
-
| `@orkestrel/timeout` | `0.0.
|
|
92
|
-
| `@orkestrel/tool` | `0.0.
|
|
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.
|
|
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
|
|
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 (
|
|
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
|
|
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? }`
|
|
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? }`
|
|
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'`
|
|
778
|
-
| `FaultConstraint` | type | `'min' \| 'max' \| 'pattern' \| 'integer'`
|
|
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
|
|
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).
|
|
@@ -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
|
package/dist/host/manifest.json
CHANGED
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
"storage": "agents/orchestration.md",
|
|
17
17
|
"destination": ".agents/orchestration.md",
|
|
18
18
|
"executable": false,
|
|
19
|
-
"digest": "
|
|
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": "
|
|
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": "
|
|
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": "
|
|
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": "
|
|
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": "
|
|
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": "
|
|
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": "
|
|
1420
|
+
"digest": "226166ccc0bf247428a82035e08915bf36a9c9fe92a053c08d744e99a2c904eb"
|
|
1421
1421
|
}
|
|
@@ -5174,7 +5174,7 @@ describe('configuration helpers', () => {
|
|
|
5174
5174
|
'environmentSourceError',
|
|
5175
5175
|
'fileSystemPath',
|
|
5176
5176
|
'findPackageDirectory',
|
|
5177
|
-
'
|
|
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.
|
|
5466
|
-
expect(configHelpers.
|
|
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,
|
package/dist/src/core/index.cjs
CHANGED
|
@@ -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.
|
|
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.
|
|
100
|
-
"@orkestrel/contract": "^0.0.
|
|
101
|
-
"@orkestrel/emitter": "^0.0.
|
|
102
|
-
"@orkestrel/markdown": "^0.0.
|
|
103
|
-
"@orkestrel/process": "^0.0.
|
|
104
|
-
"@orkestrel/template": "^0.0.
|
|
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.
|
|
110
|
+
"@orkestrel/html": "^0.0.16",
|
|
111
111
|
"@orkestrel/probe": "^0.0.29",
|
|
112
|
-
"@orkestrel/test": "^0.0.
|
|
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.
|
|
119
|
+
"vite": "^8.3.8",
|
|
120
120
|
"vitest": "^5.1.0"
|
|
121
121
|
},
|
|
122
122
|
engines: { "node": ">=22.18.0" }
|
package/dist/src/core/index.js
CHANGED
|
@@ -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.
|
|
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.
|
|
99
|
-
"@orkestrel/contract": "^0.0.
|
|
100
|
-
"@orkestrel/emitter": "^0.0.
|
|
101
|
-
"@orkestrel/markdown": "^0.0.
|
|
102
|
-
"@orkestrel/process": "^0.0.
|
|
103
|
-
"@orkestrel/template": "^0.0.
|
|
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.
|
|
109
|
+
"@orkestrel/html": "^0.0.16",
|
|
110
110
|
"@orkestrel/probe": "^0.0.29",
|
|
111
|
-
"@orkestrel/test": "^0.0.
|
|
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.
|
|
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.
|
|
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.
|
|
103
|
-
"@orkestrel/contract": "^0.0.
|
|
104
|
-
"@orkestrel/emitter": "^0.0.
|
|
105
|
-
"@orkestrel/markdown": "^0.0.
|
|
106
|
-
"@orkestrel/process": "^0.0.
|
|
107
|
-
"@orkestrel/template": "^0.0.
|
|
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.
|
|
113
|
+
"@orkestrel/html": "^0.0.16",
|
|
114
114
|
"@orkestrel/probe": "^0.0.29",
|
|
115
|
-
"@orkestrel/test": "^0.0.
|
|
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.
|
|
122
|
+
"vite": "^8.3.8",
|
|
123
123
|
"vitest": "^5.1.0"
|
|
124
124
|
},
|
|
125
125
|
"engines": {
|