@orkestrel/scaffold 0.0.119 → 0.0.121

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/dist/bin/main.js +19 -19
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
  4. package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
  5. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
  6. package/dist/host/claude/agents/orkestrel.md +52 -51
  7. package/dist/host/claude/rules/tests.md +2 -2
  8. package/dist/host/claude/rules/typescript.md +2 -3
  9. package/dist/host/guides/abort.md +0 -4
  10. package/dist/host/guides/agent.md +5 -5
  11. package/dist/host/guides/brief.md +7 -15
  12. package/dist/host/guides/browser.md +1 -1
  13. package/dist/host/guides/budget.md +1 -5
  14. package/dist/host/guides/capture.md +2 -2
  15. package/dist/host/guides/codec.md +18 -3
  16. package/dist/host/guides/console.md +4 -30
  17. package/dist/host/guides/contract.md +23 -44
  18. package/dist/host/guides/csv.md +86 -93
  19. package/dist/host/guides/database.md +0 -4
  20. package/dist/host/guides/emitter.md +0 -2
  21. package/dist/host/guides/form.md +26 -47
  22. package/dist/host/guides/guide.md +0 -1
  23. package/dist/host/guides/html.md +3 -7
  24. package/dist/host/guides/indexeddb.md +28 -32
  25. package/dist/host/guides/interpret.md +165 -182
  26. package/dist/host/guides/jsonrpc.md +187 -0
  27. package/dist/host/guides/lsp.md +26 -51
  28. package/dist/host/guides/markdown.md +132 -141
  29. package/dist/host/guides/mcp.md +220 -276
  30. package/dist/host/guides/middleware.md +14 -22
  31. package/dist/host/guides/msg.md +47 -63
  32. package/dist/host/guides/ndjson.md +0 -4
  33. package/dist/host/guides/ollama.md +1 -3
  34. package/dist/host/guides/pool.md +0 -4
  35. package/dist/host/guides/probe.md +71 -80
  36. package/dist/host/guides/process.md +71 -79
  37. package/dist/host/guides/program.md +26 -35
  38. package/dist/host/guides/qualifier.md +0 -6
  39. package/dist/host/guides/queue.md +0 -4
  40. package/dist/host/guides/rater.md +6 -12
  41. package/dist/host/guides/reason.md +30 -36
  42. package/dist/host/guides/relation.md +0 -2
  43. package/dist/host/guides/router.md +11 -18
  44. package/dist/host/guides/scaffold.md +148 -144
  45. package/dist/host/guides/sea.md +47 -51
  46. package/dist/host/guides/server.md +15 -19
  47. package/dist/host/guides/sqlite.md +0 -4
  48. package/dist/host/guides/sse.md +6 -10
  49. package/dist/host/guides/table.md +481 -493
  50. package/dist/host/guides/template.md +0 -4
  51. package/dist/host/guides/terminal.md +0 -26
  52. package/dist/host/guides/test.md +46 -66
  53. package/dist/host/guides/timeout.md +0 -6
  54. package/dist/host/guides/tool.md +2 -6
  55. package/dist/host/guides/toolbox.md +0 -10
  56. package/dist/host/guides/websocket.md +0 -4
  57. package/dist/host/guides/worker.md +57 -57
  58. package/dist/host/guides/workflow.md +13 -26
  59. package/dist/host/guides/workspace.md +15 -21
  60. package/dist/host/manifest.json +64 -909
  61. package/dist/src/core/index.cjs +128 -181
  62. package/dist/src/core/index.cjs.map +1 -1
  63. package/dist/src/core/index.d.cts +213 -213
  64. package/dist/src/core/index.d.ts +213 -213
  65. package/dist/src/core/index.js +117 -170
  66. package/dist/src/core/index.js.map +1 -1
  67. package/dist/src/server/index.cjs +35 -34
  68. package/dist/src/server/index.cjs.map +1 -1
  69. package/dist/src/server/index.d.cts +62 -58
  70. package/dist/src/server/index.d.ts +62 -58
  71. package/dist/src/server/index.js +36 -35
  72. package/dist/src/server/index.js.map +1 -1
  73. package/package.json +13 -13
@@ -34,6 +34,7 @@ import {
34
34
  isRendered,
35
35
  mount,
36
36
  pressKeys,
37
+ readControlValue,
37
38
  readFocus,
38
39
  readHit,
39
40
  readName,
@@ -43,7 +44,6 @@ import {
43
44
  readRole,
44
45
  readStates,
45
46
  readText,
46
- readValue,
47
47
  removeDatabase,
48
48
  render,
49
49
  resolveAccessible,
@@ -109,12 +109,12 @@ A journey verb resolves its own target from role and accessible name, and refuse
109
109
  component instance, or a selector from the caller. A reader, a fixture builder, and a capture each
110
110
  take one, because their subject is a node the caller already holds.
111
111
 
112
- | Population | Takes an element |
113
- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
114
- | `resolveAccessible`, `resolveRendered`, `clickAccessible`, `clickAccessibleWithin`, `clickDisclosure`, `typeAccessible`, `fillAccessible`, `traverseAccessible`, `pressKeys`, `waitForState`, `readRefusal`, `readPerception`, `readPage`, `readFocus`, `readValue` | No |
115
- | `readText`, `readRole`, `readName`, `readStates`, `describeTree`, `describeFocus`, `isReachable`, `isRendered`, `readHit`, `waitForAnimations` | Yes |
116
- | `readContrast`, `readRing`, `readLayers`, `readBackdrop`, `readStyle`, `readToken`, `readPixels`, `readClasses`, `readCensus`, `extractStyles`, `extractOrphans`, `readRows` | Yes |
117
- | `mount`, `typeInput`, `commitInput`, `captureFrame`, and a portfolio's `place` | Yes |
112
+ | Population | Takes an element |
113
+ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
114
+ | `resolveAccessible`, `resolveRendered`, `clickAccessible`, `clickAccessibleWithin`, `clickDisclosure`, `typeAccessible`, `fillAccessible`, `traverseAccessible`, `pressKeys`, `waitForState`, `readRefusal`, `readPerception`, `readPage`, `readFocus`, `readControlValue` | No |
115
+ | `readText`, `readRole`, `readName`, `readStates`, `describeTree`, `describeFocus`, `isReachable`, `isRendered`, `readHit`, `waitForAnimations` | Yes |
116
+ | `readContrast`, `readRing`, `readLayers`, `readBackdrop`, `readStyle`, `readToken`, `readPixels`, `readClasses`, `readCensus`, `extractStyles`, `extractOrphans`, `readRows` | Yes |
117
+ | `mount`, `typeInput`, `commitInput`, `captureFrame`, and a portfolio's `place` | Yes |
118
118
 
119
119
  - Never pass an element to a verb from a journey step. Read a step that would pass one as a missing
120
120
  verb, and add the verb instead.
@@ -169,7 +169,7 @@ the capture voices in [captures.md](captures.md), and every other voice in `guid
169
169
  | Forward Tab never lands on the target | `Interactive target "<name>" is not reachable through forward Tab traversal: <trail>` | `traverseAccessible` |
170
170
  | The named region is hidden | `Named region "<name>" is not visible` | `readPerception` |
171
171
  | Several named regions carry the name | `Named region "<name>" is ambiguous across <n> elements` | `readPerception` |
172
- | The resolved control renders no value | `Interactive target "<name>" does not carry a value` | `readValue` |
172
+ | The resolved control renders no value | `Interactive target "<name>" does not carry a value` | `readControlValue` |
173
173
  | A key sequence reached nothing | `Key sequence "<keys>" was sent with nothing focused` | `pressKeys` |
174
174
  | A host withholds `getItem`, `setItem`, or `removeItem` | `Access is denied for <operation> "<key>"` | `createStorage` |
175
175
  | A host withholds `length`, `clear`, or `key` | `Access is denied for <operation>` | `createStorage` |
@@ -281,7 +281,7 @@ beside each.
281
281
  | `document.elementFromPoint` | `readHit` |
282
282
  | `element.focus()` | `traverseAccessible`, `pressKeys` |
283
283
  | A navigation a journey step performs by a router call | The visible link or control that navigates, through `clickAccessible` or `clickAccessibleWithin` |
284
- | A store or route state read standing in for a rendered assertion | `readPerception`, `readValue`, `readStates`, `waitForText` |
284
+ | A store or route state read standing in for a rendered assertion | `readPerception`, `readControlValue`, `readStates`, `waitForText` |
285
285
 
286
286
  - Admit a selector only for a population that carries no role, declared in the workspace's browser
287
287
  test setup module with the reason beside it.
@@ -318,7 +318,7 @@ dialog, table, tab panel, alert, or status. Quote that text in assertions.
318
318
  the layout hides. Descendant visually-hidden text stays in, which is what a screen reader
319
319
  perceives.
320
320
  - Reach for `readPage` for a cross-region sentence and the vocabulary sweep, `readFocus` for the
321
- active element's rendered text, and `readValue` for a resolved control's rendered value. A
321
+ active element's rendered text, and `readControlValue` for a resolved control's rendered value. A
322
322
  perception assertion may quote that value: it is a rendered fact rather than internal state.
323
323
  - Reach for `describeTree` and `describeFocus` where the subject is the accessible tree itself —
324
324
  roles, names, states, and focus order. They are the accessibility snapshot a written artifact
@@ -174,7 +174,7 @@ it('walks the disclosure statechart', async () => {
174
174
  `buildRefusal(name, cause)` from `@orkestrel/test` builds that same error, so an assertion on
175
175
  a refused build compares against what it returns rather than against a spelled string.
176
176
  - Never assert the entity's internal state in `assert` where the transition is one a person drives.
177
- Assert what the interface renders, through `readPerception`, `readValue`, or `readStates`.
177
+ Assert what the interface renders, through `readPerception`, `readControlValue`, or `readStates`.
178
178
 
179
179
  ## Drive the act the way the transition happens
180
180
 
@@ -12,9 +12,9 @@ import type {
12
12
  CaptureVariant,
13
13
  CensusFixture,
14
14
  CensusResult,
15
- Color,
16
15
  ContrastFixture,
17
16
  EscapeFixture,
17
+ RGBA,
18
18
  } from '@orkestrel/test/browser'
19
19
  import {
20
20
  CANVAS_COLOR,
@@ -25,7 +25,7 @@ import {
25
25
  extractOrphans,
26
26
  extractStyles,
27
27
  findKeyframes,
28
- findRule,
28
+ findStyleRule,
29
29
  matchesColor,
30
30
  measureContrast,
31
31
  measureLuminance,
@@ -57,7 +57,7 @@ import { inject } from 'vitest'
57
57
  - Read `readPixels` as a measured contribution rather than a parsed length. A resolved value
58
58
  carrying no leading number reads as `0`, so read the text with `readStyle` where an unparsable
59
59
  value and a genuine zero are different findings.
60
- - Never substitute `findRule` for a resolved read. It proves a declaration exists, and another rule
60
+ - Never substitute `findStyleRule` for a resolved read. It proves a declaration exists, and another rule
61
61
  may still win; reach for it where the stylesheet itself is the subject, and for `findKeyframes`
62
62
  where the animation's declaration is.
63
63
  - Compare a color through `matchesColor` or `parseCSSColor` rather than by string. A browser normalizes a color
@@ -43,57 +43,58 @@ 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.14` | L1 | `@orkestrel/contract` `^0.0.20` | |
47
- | `@orkestrel/agent` | `0.0.33` | L5 | `@orkestrel/tool` `^0.0.20`, `@orkestrel/abort` `^0.0.14`, `@orkestrel/queue` `^0.0.18`, `@orkestrel/budget` `^0.0.15`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/timeout` `^0.0.14`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/database` `^0.0.19`, `@orkestrel/workflow` `^0.0.24`, `@orkestrel/workspace` `^0.0.13` | |
48
- | `@orkestrel/brief` | `0.0.13` | L4 | `@orkestrel/reason` `^0.0.15`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/interpret` `^0.0.18` | |
49
- | `@orkestrel/browser` | `0.0.30` | L5 | `@orkestrel/mcp` `^0.0.40`, `@orkestrel/html` `^0.0.13`, `@orkestrel/pool` `^0.0.18`, `@orkestrel/tool` `^0.0.20`, `@orkestrel/codec` `^0.0.7`, `@orkestrel/router` `^0.0.18`, `@orkestrel/server` `^0.0.24`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/process` `^0.0.16`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/markdown` `^0.0.18`, `@orkestrel/websocket` `^0.0.16` | |
50
- | `@orkestrel/budget` | `0.0.15` | L1 | `@orkestrel/contract` `^0.0.20` | |
51
- | `@orkestrel/capture` | `0.0.2` | L3 | `@orkestrel/process` `^0.0.16`, `@orkestrel/timeout` `^0.0.14`, `@orkestrel/contract` `^0.0.20` | `vite` `^8.3.5`, `vitest` `^4.1.12 \|\| ^5.0.5`, `playwright` `^1.61.0`, `@vitest/browser-playwright` `^4.1.12 \|\| ^5.0.5` |
52
- | `@orkestrel/codec` | `0.0.7` | L1 | `@orkestrel/contract` `^0.0.20` | |
53
- | `@orkestrel/console` | `0.0.17` | L2 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
54
- | `@orkestrel/contract` | `0.0.20` | L0 | | |
55
- | `@orkestrel/csv` | `0.0.11` | L1 | `@orkestrel/contract` `^0.0.20` | |
56
- | `@orkestrel/database` | `0.0.19` | L2 | `@orkestrel/sqlite` `^0.0.15`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/indexeddb` `^0.0.15` | |
57
- | `@orkestrel/emitter` | `0.0.13` | L1 | `@orkestrel/contract` `^0.0.20` | |
58
- | `@orkestrel/form` | `0.0.14` | L2 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
59
- | `@orkestrel/guide` | `0.0.28` | L3 | `@orkestrel/contract` `^0.0.20`, `@orkestrel/markdown` `^0.0.18` | |
60
- | `@orkestrel/html` | `0.0.13` | L1 | `@orkestrel/contract` `^0.0.20` | |
61
- | `@orkestrel/indexeddb` | `0.0.15` | L1 | `@orkestrel/contract` `^0.0.20` | |
62
- | `@orkestrel/interpret` | `0.0.18` | L3 | `@orkestrel/reason` `^0.0.15`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/template` `^0.0.11` | |
63
- | `@orkestrel/lsp` | `0.0.12` | L3 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/process` `^0.0.16`, `@orkestrel/contract` `^0.0.20` | |
64
- | `@orkestrel/markdown` | `0.0.18` | L2 | `@orkestrel/html` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
65
- | `@orkestrel/mcp` | `0.0.40` | L4 | `@orkestrel/sse` `^0.0.11`, `@orkestrel/tool` `^0.0.20`, `@orkestrel/codec` `^0.0.7`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/process` `^0.0.16`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/websocket` `^0.0.16` | `@orkestrel/router` `^0.0.18`, `@orkestrel/server` `^0.0.24` |
66
- | `@orkestrel/middleware` | `0.0.26` | L4 | `@orkestrel/abort` `^0.0.14`, `@orkestrel/budget` `^0.0.15`, `@orkestrel/timeout` `^0.0.14`, `@orkestrel/contract` `^0.0.20` | `@orkestrel/server` `^0.0.24`, `@orkestrel/database` `^0.0.19` |
67
- | `@orkestrel/msg` | `0.0.14` | L1 | `@orkestrel/contract` `^0.0.20` | |
68
- | `@orkestrel/ndjson` | `0.0.13` | L1 | `@orkestrel/contract` `^0.0.20` | |
69
- | `@orkestrel/ollama` | `0.0.27` | L6 | `@orkestrel/tool` `^0.0.20`, `@orkestrel/agent` `^0.0.33`, `@orkestrel/budget` `^0.0.15`, `@orkestrel/ndjson` `^0.0.13`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/process` `^0.0.16`, `@orkestrel/contract` `^0.0.20` | |
70
- | `@orkestrel/pool` | `0.0.18` | L2 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
71
- | `@orkestrel/probe` | `0.0.26` | L5 | `@orkestrel/lsp` `^0.0.12`, `@orkestrel/mcp` `^0.0.40`, `@orkestrel/pool` `^0.0.18`, `@orkestrel/tool` `^0.0.20`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/process` `^0.0.16`, `@orkestrel/timeout` `^0.0.14`, `@orkestrel/contract` `^0.0.20` | `vitest` `^4.1.12 \|\| ^5.0.5`, `typescript` `^6.0.3 \|\| ^7.0.2` |
72
- | `@orkestrel/process` | `0.0.16` | L2 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
73
- | `@orkestrel/program` | `0.0.18` | L4 | `@orkestrel/rater` `^0.0.19`, `@orkestrel/reason` `^0.0.15`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/qualifier` `^0.0.19` | |
74
- | `@orkestrel/qualifier` | `0.0.19` | L3 | `@orkestrel/reason` `^0.0.15`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
75
- | `@orkestrel/queue` | `0.0.18` | L3 | `@orkestrel/abort` `^0.0.14`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/timeout` `^0.0.14`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/database` `^0.0.19` | |
76
- | `@orkestrel/rater` | `0.0.19` | L3 | `@orkestrel/reason` `^0.0.15`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
77
- | `@orkestrel/reason` | `0.0.15` | L2 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
78
- | `@orkestrel/relation` | `0.0.17` | L3 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/database` `^0.0.19` | |
79
- | `@orkestrel/router` | `0.0.18` | L2 | `@orkestrel/abort` `^0.0.14`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
80
- | `@orkestrel/scaffold` | `0.0.116` | L3 | `@orkestrel/console` `^0.0.17`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/process` `^0.0.16`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/markdown` `^0.0.18`, `@orkestrel/template` `^0.0.11` | |
81
- | `@orkestrel/sea` | `0.0.20` | L3 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/process` `^0.0.16`, `@orkestrel/contract` `^0.0.20` | |
82
- | `@orkestrel/server` | `0.0.24` | L3 | `@orkestrel/abort` `^0.0.14`, `@orkestrel/codec` `^0.0.7`, `@orkestrel/router` `^0.0.18`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/timeout` `^0.0.14`, `@orkestrel/contract` `^0.0.20` | |
83
- | `@orkestrel/sqlite` | `0.0.15` | L1 | `@orkestrel/contract` `^0.0.20` | |
84
- | `@orkestrel/sse` | `0.0.11` | L1 | `@orkestrel/contract` `^0.0.20` | |
85
- | `@orkestrel/study` | `0.0.7` | L7 | `@orkestrel/tool` `^0.0.20`, `@orkestrel/abort` `^0.0.14`, `@orkestrel/agent` `^0.0.33`, `@orkestrel/budget` `^0.0.15`, `@orkestrel/ollama` `^0.0.27`, `@orkestrel/timeout` `^0.0.14`, `@orkestrel/contract` `^0.0.20` | |
86
- | `@orkestrel/table` | `0.0.13` | L2 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
87
- | `@orkestrel/template` | `0.0.11` | L2 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
88
- | `@orkestrel/terminal` | `0.0.21` | L3 | `@orkestrel/sse` `^0.0.11`, `@orkestrel/form` `^0.0.14`, `@orkestrel/console` `^0.0.17`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/database` `^0.0.19` | |
89
- | `@orkestrel/test` | `0.0.31` | L1 | `@orkestrel/contract` `^0.0.20` | `vitest` `^4.1.12 \|\| ^5.0.5`, `playwright` `^1.64.1` |
90
- | `@orkestrel/timeout` | `0.0.14` | L1 | `@orkestrel/contract` `^0.0.20` | |
91
- | `@orkestrel/tool` | `0.0.20` | L2 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
92
- | `@orkestrel/toolbox` | `0.0.22` | L6 | `@orkestrel/form` `^0.0.14`, `@orkestrel/tool` `^0.0.20`, `@orkestrel/agent` `^0.0.33`, `@orkestrel/server` `^0.0.24`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/database` `^0.0.19`, `@orkestrel/relation` `^0.0.17`, `@orkestrel/terminal` `^0.0.21`, `@orkestrel/workflow` `^0.0.24`, `@orkestrel/workspace` `^0.0.13` | |
93
- | `@orkestrel/websocket` | `0.0.16` | L2 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
94
- | `@orkestrel/worker` | `0.0.18` | L4 | `@orkestrel/pool` `^0.0.18`, `@orkestrel/queue` `^0.0.18`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/database` `^0.0.19` | |
95
- | `@orkestrel/workflow` | `0.0.24` | L4 | `@orkestrel/abort` `^0.0.14`, `@orkestrel/queue` `^0.0.18`, `@orkestrel/budget` `^0.0.15`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/timeout` `^0.0.14`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/database` `^0.0.19` | |
96
- | `@orkestrel/workspace` | `0.0.13` | L3 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/database` `^0.0.19` | |
46
+ | `@orkestrel/abort` | `0.0.15` | L1 | `@orkestrel/contract` `^0.0.21` | |
47
+ | `@orkestrel/agent` | `0.0.34` | L5 | `@orkestrel/tool` `^0.0.21`, `@orkestrel/abort` `^0.0.15`, `@orkestrel/queue` `^0.0.19`, `@orkestrel/budget` `^0.0.16`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/timeout` `^0.0.15`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/database` `^0.0.20`, `@orkestrel/workflow` `^0.0.25`, `@orkestrel/workspace` `^0.0.14` | |
48
+ | `@orkestrel/brief` | `0.0.14` | L4 | `@orkestrel/reason` `^0.0.16`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/interpret` `^0.0.19` | |
49
+ | `@orkestrel/browser` | `0.0.31` | L5 | `@orkestrel/mcp` `^0.0.41`, `@orkestrel/html` `^0.0.14`, `@orkestrel/pool` `^0.0.19`, `@orkestrel/tool` `^0.0.21`, `@orkestrel/codec` `^0.0.8`, `@orkestrel/router` `^0.0.19`, `@orkestrel/server` `^0.0.25`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/process` `^0.0.17`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/markdown` `^0.0.19`, `@orkestrel/websocket` `^0.0.17` | |
50
+ | `@orkestrel/budget` | `0.0.16` | L1 | `@orkestrel/contract` `^0.0.21` | |
51
+ | `@orkestrel/capture` | `0.0.3` | L3 | `@orkestrel/process` `^0.0.17`, `@orkestrel/timeout` `^0.0.15`, `@orkestrel/contract` `^0.0.21` | `vite` `^8.3.5`, `vitest` `^4.1.12 \|\| ^5.0.5`, `playwright` `^1.61.0`, `@vitest/browser-playwright` `^4.1.12 \|\| ^5.0.5` |
52
+ | `@orkestrel/codec` | `0.0.8` | L1 | `@orkestrel/contract` `^0.0.21` | |
53
+ | `@orkestrel/console` | `0.0.18` | L2 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
54
+ | `@orkestrel/contract` | `0.0.21` | L0 | | |
55
+ | `@orkestrel/csv` | `0.0.12` | L2 | `@orkestrel/codec` `^0.0.8`, `@orkestrel/contract` `^0.0.21` | |
56
+ | `@orkestrel/database` | `0.0.20` | L2 | `@orkestrel/sqlite` `^0.0.16`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/indexeddb` `^0.0.16` | |
57
+ | `@orkestrel/emitter` | `0.0.14` | L1 | `@orkestrel/contract` `^0.0.21` | |
58
+ | `@orkestrel/form` | `0.0.15` | L2 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
59
+ | `@orkestrel/guide` | `0.0.29` | L3 | `@orkestrel/contract` `^0.0.21`, `@orkestrel/markdown` `^0.0.19` | |
60
+ | `@orkestrel/html` | `0.0.14` | L1 | `@orkestrel/contract` `^0.0.21` | |
61
+ | `@orkestrel/indexeddb` | `0.0.16` | L1 | `@orkestrel/contract` `^0.0.21` | |
62
+ | `@orkestrel/interpret` | `0.0.19` | L3 | `@orkestrel/reason` `^0.0.16`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/template` `^0.0.12` | |
63
+ | `@orkestrel/jsonrpc` | `0.0.1` | L1 | `@orkestrel/contract` `^0.0.21` | |
64
+ | `@orkestrel/lsp` | `0.0.13` | L3 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/jsonrpc` `^0.0.1`, `@orkestrel/process` `^0.0.17`, `@orkestrel/contract` `^0.0.21` | |
65
+ | `@orkestrel/markdown` | `0.0.19` | L2 | `@orkestrel/html` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
66
+ | `@orkestrel/mcp` | `0.0.41` | L4 | `@orkestrel/sse` `^0.0.12`, `@orkestrel/tool` `^0.0.21`, `@orkestrel/codec` `^0.0.8`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/jsonrpc` `^0.0.1`, `@orkestrel/process` `^0.0.17`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/websocket` `^0.0.17` | `@orkestrel/router` `^0.0.19`, `@orkestrel/server` `^0.0.25` |
67
+ | `@orkestrel/middleware` | `0.0.27` | L4 | `@orkestrel/abort` `^0.0.15`, `@orkestrel/budget` `^0.0.16`, `@orkestrel/timeout` `^0.0.15`, `@orkestrel/contract` `^0.0.21` | `@orkestrel/server` `^0.0.25`, `@orkestrel/database` `^0.0.20` |
68
+ | `@orkestrel/msg` | `0.0.15` | L2 | `@orkestrel/codec` `^0.0.8`, `@orkestrel/contract` `^0.0.21` | |
69
+ | `@orkestrel/ndjson` | `0.0.14` | L1 | `@orkestrel/contract` `^0.0.21` | |
70
+ | `@orkestrel/ollama` | `0.0.28` | L6 | `@orkestrel/tool` `^0.0.21`, `@orkestrel/agent` `^0.0.34`, `@orkestrel/budget` `^0.0.16`, `@orkestrel/ndjson` `^0.0.14`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/process` `^0.0.17`, `@orkestrel/contract` `^0.0.21` | |
71
+ | `@orkestrel/pool` | `0.0.19` | L2 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
72
+ | `@orkestrel/probe` | `0.0.27` | L5 | `@orkestrel/lsp` `^0.0.13`, `@orkestrel/mcp` `^0.0.41`, `@orkestrel/pool` `^0.0.19`, `@orkestrel/tool` `^0.0.21`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/process` `^0.0.17`, `@orkestrel/timeout` `^0.0.15`, `@orkestrel/contract` `^0.0.21` | `vitest` `^4.1.12 \|\| ^5.0.5`, `typescript` `^6.0.3 \|\| ^7.0.2` |
73
+ | `@orkestrel/process` | `0.0.17` | L2 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
74
+ | `@orkestrel/program` | `0.0.19` | L4 | `@orkestrel/rater` `^0.0.20`, `@orkestrel/reason` `^0.0.16`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/qualifier` `^0.0.20` | |
75
+ | `@orkestrel/qualifier` | `0.0.20` | L3 | `@orkestrel/reason` `^0.0.16`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
76
+ | `@orkestrel/queue` | `0.0.19` | L3 | `@orkestrel/abort` `^0.0.15`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/timeout` `^0.0.15`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/database` `^0.0.20` | |
77
+ | `@orkestrel/rater` | `0.0.20` | L3 | `@orkestrel/reason` `^0.0.16`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
78
+ | `@orkestrel/reason` | `0.0.16` | L2 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
79
+ | `@orkestrel/relation` | `0.0.18` | L3 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/database` `^0.0.20` | |
80
+ | `@orkestrel/router` | `0.0.19` | L2 | `@orkestrel/abort` `^0.0.15`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
81
+ | `@orkestrel/scaffold` | `0.0.120` | L3 | `@orkestrel/console` `^0.0.17`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/process` `^0.0.17`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/markdown` `^0.0.19`, `@orkestrel/template` `^0.0.12` | |
82
+ | `@orkestrel/sea` | `0.0.21` | L3 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/process` `^0.0.17`, `@orkestrel/contract` `^0.0.21` | |
83
+ | `@orkestrel/server` | `0.0.25` | L3 | `@orkestrel/abort` `^0.0.15`, `@orkestrel/codec` `^0.0.8`, `@orkestrel/router` `^0.0.19`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/timeout` `^0.0.15`, `@orkestrel/contract` `^0.0.21` | |
84
+ | `@orkestrel/sqlite` | `0.0.16` | L1 | `@orkestrel/contract` `^0.0.21` | |
85
+ | `@orkestrel/sse` | `0.0.12` | L2 | `@orkestrel/codec` `^0.0.8`, `@orkestrel/contract` `^0.0.21` | |
86
+ | `@orkestrel/study` | `0.0.8` | L7 | `@orkestrel/tool` `^0.0.21`, `@orkestrel/abort` `^0.0.15`, `@orkestrel/agent` `^0.0.34`, `@orkestrel/budget` `^0.0.16`, `@orkestrel/ollama` `^0.0.28`, `@orkestrel/timeout` `^0.0.15`, `@orkestrel/contract` `^0.0.21` | |
87
+ | `@orkestrel/table` | `0.0.14` | L2 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
88
+ | `@orkestrel/template` | `0.0.12` | L2 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
89
+ | `@orkestrel/terminal` | `0.0.22` | L3 | `@orkestrel/sse` `^0.0.12`, `@orkestrel/form` `^0.0.15`, `@orkestrel/console` `^0.0.17`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/database` `^0.0.20` | |
90
+ | `@orkestrel/test` | `0.0.32` | L1 | `@orkestrel/contract` `^0.0.21` | `vitest` `^4.1.12 \|\| ^5.0.5`, `playwright` `^1.64.1` |
91
+ | `@orkestrel/timeout` | `0.0.15` | L1 | `@orkestrel/contract` `^0.0.21` | |
92
+ | `@orkestrel/tool` | `0.0.21` | L2 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
93
+ | `@orkestrel/toolbox` | `0.0.23` | L6 | `@orkestrel/form` `^0.0.15`, `@orkestrel/tool` `^0.0.21`, `@orkestrel/agent` `^0.0.34`, `@orkestrel/server` `^0.0.25`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/database` `^0.0.20`, `@orkestrel/relation` `^0.0.18`, `@orkestrel/terminal` `^0.0.22`, `@orkestrel/workflow` `^0.0.25`, `@orkestrel/workspace` `^0.0.14` | |
94
+ | `@orkestrel/websocket` | `0.0.17` | L2 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
95
+ | `@orkestrel/worker` | `0.0.19` | L4 | `@orkestrel/pool` `^0.0.19`, `@orkestrel/queue` `^0.0.19`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/database` `^0.0.20` | |
96
+ | `@orkestrel/workflow` | `0.0.25` | L4 | `@orkestrel/abort` `^0.0.15`, `@orkestrel/queue` `^0.0.19`, `@orkestrel/budget` `^0.0.16`, `@orkestrel/emitter` `^0.0.14`, `@orkestrel/timeout` `^0.0.15`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/database` `^0.0.20` | |
97
+ | `@orkestrel/workspace` | `0.0.14` | L3 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21`, `@orkestrel/database` `^0.0.20` | |
97
98
 
98
99
  <!-- /orkestrel:catalog -->
99
100
 
@@ -283,9 +283,9 @@ Import `createScratch` from `@orkestrel/test/server` when a proof needs real fil
283
283
 
284
284
  Browser/style setup exposes shared assertions/builders:
285
285
 
286
- `mount`, `render`, `build`, `readStyle`, `readToken`, `readRootToken`, `readPixels`, `parseCSSColor`, `matchesColor`, `findRule`.
286
+ `mount`, `render`, `build`, `readStyle`, `readToken`, `readRootToken`, `readPixels`, `parseCSSColor`, `matchesColor`, `findStyleRule`.
287
287
 
288
- `findRule` proves a declaration exists in the cascade; `readStyle()` reads the resolved result.
288
+ `findStyleRule` proves a declaration exists in the cascade; `readStyle()` reads the resolved result.
289
289
 
290
290
  ## Browser tests
291
291
 
@@ -210,9 +210,8 @@ type Result<T, E = Error> = Success<T> | Failure<E>
210
210
  `isInstance` function against the class.
211
211
  - Brand every public error class for that guard:
212
212
  - key the brand `Symbol.for('<package>.<ClassName>')`, where `<package>` is the manifest's `name`
213
- field and `<ClassName>` is the class identifier, and keep a key the package has published, such
214
- as `Symbol.for('@orkestrel/contract.error')`, because a changed key stops recognizing every
215
- earlier copy;
213
+ field and `<ClassName>` is the class identifier. When you rename the class, rename the key in
214
+ the same change, and keep no earlier key;
216
215
  - in the constructor, define an own non-enumerable, non-writable property under that key whose
217
216
  value is the error itself, so that a subclass instance holds its own identity there and a
218
217
  transparent `Proxy` object over the error forwards its target's;
@@ -45,8 +45,6 @@ Construction is a strict JavaScript boundary. `validateAbortOptions` normalizes
45
45
 
46
46
  ### Validators
47
47
 
48
- In a guard table a `Shape` cell holds the type the guard narrows to.
49
-
50
48
  | Name | Kind | Signature | Summary |
51
49
  | --------------- | -------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
52
50
  | `isAbortSignal` | function | `(value: unknown) => value is AbortSignal` | Determines whether a value is a native `AbortSignal`, staying total for structural spoofs and for hostile or revoked proxies. |
@@ -59,8 +57,6 @@ In a guard table a `Shape` cell holds the type the guard narrows to.
59
57
 
60
58
  ### Types
61
59
 
62
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
63
-
64
60
  | Name | Kind | Signature | Summary |
65
61
  | ---------------- | --------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
66
62
  | `AbortOptions` | interface | `{ id?, signal? }` | Represents the options for `createAbort` and `Abort` construction. |
@@ -695,7 +695,7 @@ The wire is strictly narrower than the domain on purpose. `providerRequestContra
695
695
 
696
696
  The root holds the package's shared vocabulary: the message and judge value types, the role list, the judge abort error, the message and tool-call wire shapes with the message contract, and the cloner, helpers, and guards that more than one module reads.
697
697
 
698
- Each module section lists its exports by kind file, and a `Shape` cell reads by table. On a constant it holds the declared type. On a type it holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, with an extended interface's name before `plus`, or a type alias's own type literal with a union's arms escaped as `\|`. On a shape it holds the projected record's members in the same notation, on a contract the domain type the contract narrows to, and on a guard the type the guard narrows to. Each guard reads an `unknown`, returns `false` off-shape, and never throws, and an error guard stays in its module's Errors table beside the error it narrows.
698
+ Each module section lists its exports by kind file. Each guard reads an `unknown`, returns `false` off-shape, and never throws, and an error guard stays in its module's Errors table beside the error it narrows.
699
699
 
700
700
  #### Types
701
701
 
@@ -935,7 +935,7 @@ The following table lists the helpers the providers module declares:
935
935
  | `buildProviderResult` | function | `(content: string, thinking: string, tools: readonly ToolCall[], usage: TokenUsage \| undefined, truncated: boolean \| undefined) => ProviderResult` | Assembles a provider result with only populated optional fields. |
936
936
  | `armReaderAbort` | function | `(reader: ReadableStreamDefaultReader<Uint8Array>, signal: AbortSignal \| undefined) => Promise<AbortController>` | Arms signal propagation to a byte reader and returns the controller that removes the listener. |
937
937
  | `readFailure` | function | `(response: Response, prefix: string, signal: AbortSignal) => Promise<FailureRead>` | Reads a bounded HTTP failure excerpt and preserves an unreadable body's cause. |
938
- | `readText` | function | `(body: ReadableStream<Uint8Array>, limit?: number, signal?: AbortSignal) => Promise<TextRead>` | Reads a UTF-8 prefix of a byte stream and cancels its remainder. |
938
+ | `readBodyText` | function | `(body: ReadableStream<Uint8Array>, limit?: number, signal?: AbortSignal) => Promise<TextRead>` | Reads a UTF-8 prefix of a byte stream and cancels its remainder. |
939
939
  | `readChunks` | function | `(body: ReadableStream<Uint8Array>, signal?: AbortSignal) => AsyncGenerator<string>` | Decodes UTF-8 chunks with a final flush and releases the stream on every exit. |
940
940
  | `releaseReader` | function | `(reader: ReadableStreamDefaultReader<Uint8Array>) => Promise<void>` | Cancels a stream reader and releases its lock, swallowing a cancellation failure so the caller's own outcome stands. |
941
941
  | `computeReading` | function | `(answer: JudgeAnswer) => Reading` | Derives the winner, its probability, the published confidence, and a score answer's expected level from a judge answer's distribution. |
@@ -1907,7 +1907,7 @@ These invariants hold across `src/core` ↔ `agent.md`:
1907
1907
  - **`sanitizeUsage`.** `sanitizeToken` turns a non-finite or non-positive count into `0` and floors a positive fraction, and `sanitizeUsage` applies it to each field. The loop sanitizes a provider's usage and an abort partial's usage before charging or folding it.
1908
1908
  - **`AgentError` — the concurrency guard.** `stream()` throws `AgentError` with code `CONCURRENCY` and `context: { agent }` synchronously when a run is in flight and the agent carries a `window`, or when the run's effective `budget` or `allowance` is an instance a live run holds; runs holding distinct instances with no `window` overlap. The refused run never starts either bound, so the live run stays bound to it. A `budget` or `allowance` that does not implement `BudgetInterface` throws `ContractError` with code `placement` before either bound starts. `isAgentError` narrows a caught value, and a `REGISTRY` error's `context` names the `category` and `name`.
1909
1909
  - **`agentResultToJSON` — the portable `AgentResult` projection.** The helper accepts `unknown`, never throws, reads each structural field once, and returns a fresh exact `{ content, thinking?, usage?, partial, stop? }` `JSONValue`, or `undefined` for invalid input; a malformed `stop` refuses the whole value. Finite negative and fractional usage counts are preserved, and extra fields are dropped.
1910
- - **The provider engine's request and stream.** The engine posts `JSON.stringify(encode(request))` to `url + (path ?? '')` with a JSON content type the `headers` hook can extend, decodes the body through `readChunks`, and feeds every framed record and the `finish` tail through `read`. A record whose `read` returns a `result` ends the call with that result, and with `strict: true` a stream that ends with no settled result throws `ProviderError` with code `PROTOCOL`. A non-OK body is read through `readText` to at most `MAX_ERROR_BODY_LENGTH` bytes and its remainder cancelled, and each reader releases its lock on every exit.
1910
+ - **The provider engine's request and stream.** The engine posts `JSON.stringify(encode(request))` to `url + (path ?? '')` with a JSON content type the `headers` hook can extend, decodes the body through `readChunks`, and feeds every framed record and the `finish` tail through `read`. A record whose `read` returns a `result` ends the call with that result, and with `strict: true` a stream that ends with no settled result throws `ProviderError` with code `PROTOCOL`. A non-OK body is read through `readBodyText` to at most `MAX_ERROR_BODY_LENGTH` bytes and its remainder cancelled, and each reader releases its lock on every exit.
1911
1911
  - **The wire shapes and the compiled contracts.** The shapes declare each JSON projection and the contracts compile them, each strictly narrower than its domain type, so a value JSON can't carry is refused rather than dropped and a `ToolContext` appears in no wire shape. `RelayProvider.encode` projects the request through `requestToRelay`, which reads each declared member as the request presents it: a getter runs, and an inherited declared member crosses. The clone of that projection uses property descriptors and consults no getter, prototype, or `toJSON` serializer; a non-JSON value is refused before fetching.
1912
1912
  - **The relay protocol (`createRelay` / `RelayStream` / `RelayProvider`).** The request is a `POST` of one `providerRequestContract` document, and the response is newline-delimited `RelayFrame` records under `RELAY_CONTENT_TYPE`, written under backpressure, with every upstream failure reduced to `RELAY_PROVIDER_MESSAGE`. `authorize` is mandatory and runs before the body is read; the handler answers `401`, `413` at the byte `limit`, `400`, or `502` with no body, and the browser receives each as a `ProviderError` with code `HTTP`. An inbound abort, a client disconnecting included, cancels the upstream turn.
1913
1913
  - **`ProviderError` and its codes.** `ProviderError` carries a `code` and, for `HTTP` alone, a `status`: `HTTP` reports a non-OK response as `provider error: <status>` with ` - <excerpt>` only when the error body had text, `PROTOCOL` a missing body, a refused record, or a `strict` stream with no settled result, and `PROVIDER` a relay `error` frame. A cancel throws `ProviderAbortError`, never `ProviderError`.
@@ -2753,7 +2753,7 @@ The following practices apply when you build on this package:
2753
2753
  - **Run many durable agents with `createAgentQueue`** — describe each agent as a serializable `AgentJobInput` (names for the provider / tools / authority / scheduler, data for the rest), register the live pieces once in a `createAgentRegistry`, and enqueue the jobs. Persist them with a `store` so `restore()` re-runs outstanding work after a crash. Decide the partial policy up front — `partial: false` (default) retries a cancelled job, `true` accepts the partial.
2754
2754
  - **Fan out sub-agents with `createAgentRunner`** — declare a parent job's sub-agents in its `children`; the runner spawns each through `controller.spawn` on the same bounded queue. Don't reach for the controller yourself — express fan-out as data on the job (it stays serializable) and let the runner spawn it.
2755
2755
  - **Pull and push surfaces on the `Agent`, none elsewhere** — observe the `Agent` each way: pull the `AgentChunk` stream for per-token / per-thinking deltas + usage/tool chunks, or push `agent.emitter.on(...)` (`AgentEventMap`) for lifecycle + usage/tool/deny moments a fire-and-forget observer wants. A listener throw can never corrupt the loop (the emitter isolates it, routing it to the `error` option). Don't reach for an Emitter on the provider contract, the tool registry, the conversation store, the context, or the job layer — those stay event-free; and don't expect per-token `token` or `think` events (those stay the stream's job).
2756
- - **Create and edit files through `@orkestrel/workspace`** — the file domain is that package's, and `AgentContext` borrows only its `isText` / `isBinary` guards to decide a file's carrier. The rendering belongs to this package: the `## Workspace` fencing and the binary-plus-`image/` attachment are prompt policy that belongs here, not workspace helpers that belong there.
2756
+ - **Create and edit files through `@orkestrel/workspace`** — the file domain is that package's, and `AgentContext` borrows only its `isTextContent` / `isBinary` guards to decide a file's carrier. The rendering belongs to this package: the `## Workspace` fencing and the binary-plus-`image/` attachment are prompt policy that belongs here, not workspace helpers that belong there.
2757
2757
  - **Judge the argument the model passed** — a tool handler that asks a judge about a model's tool call judges the argument that call carried, or its tool description says it judges a fixed input.
2758
2758
  - **Write a refusal as the next step** — a refusal text a tool returns names the one next call and says nothing about who asked, because a reasoning model mid-task reads a refusal that addresses the user as a user turn.
2759
2759
  - **Give the model both halves of a workspace** — `context.workspaces` is what it reads, rendered by carrier every turn, active-only and filtered by `scope.files`; the `createWorkspaceTool` published by `@orkestrel/toolbox` over that same registry is what it writes. For workspace editing, errors, and persistence, see [Workspace](workspace.md); for tool dispatch semantics, see [Tool](tool.md).
@@ -2776,7 +2776,7 @@ The following test files back this guide:
2776
2776
  - [`tests/src/core/providers/AgentJudge.test.ts`](../tests/src/core/providers/AgentJudge.test.ts) — the judge engine's identity and request composition, refusals before inference, HTTP and protocol failures, header hook, and cancellation partials.
2777
2777
  - [`tests/src/core/providers/SystemOneJudge.test.ts`](../tests/src/core/providers/SystemOneJudge.test.ts) — the System One wire against the bodies recorded on 2026-10-07.
2778
2778
  - [`tests/src/core/providers/factories.test.ts`](../tests/src/core/providers/factories.test.ts) — the `createThinkSplitter` factory and the authorization, body-limit, malformed-body, and upstream-construction refusals of `createRelay`.
2779
- - [`tests/src/core/providers/helpers.test.ts`](../tests/src/core/providers/helpers.test.ts) — `buildProviderResult`, `armReaderAbort`, `readFailure`, `readText`, `readChunks`, `computeReading`, `buildJudgeResult`, `buildProviderHeaders`, `requestToRelay`, the System One helpers, and `releaseReader`.
2779
+ - [`tests/src/core/providers/helpers.test.ts`](../tests/src/core/providers/helpers.test.ts) — `buildProviderResult`, `armReaderAbort`, `readFailure`, `readBodyText`, `readChunks`, `computeReading`, `buildJudgeResult`, `buildProviderHeaders`, `requestToRelay`, the System One helpers, and `releaseReader`.
2780
2780
  - [`tests/src/core/providers/contracts.test.ts`](../tests/src/core/providers/contracts.test.ts) — the request, result, and relay-frame contracts' round trips, malformed paths, and non-JSON refusals.
2781
2781
  - [`tests/src/core/providers/shapers.test.ts`](../tests/src/core/providers/shapers.test.ts) — the request, result, and relay wire shapes assignable to their domain types.
2782
2782
  - [`tests/src/core/providers/validators.test.ts`](../tests/src/core/providers/validators.test.ts) — the System One guards `isSystemOneResponse` and `isSystemOneAnswer` over recorded, transliterated, and hostile envelopes.
@@ -91,8 +91,6 @@ pipeline at all.
91
91
 
92
92
  ### Types
93
93
 
94
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
95
-
96
94
  | Name | Kind | Signature | Summary |
97
95
  | ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
98
96
  | `TaskOperation` | type | `'create' \| 'refactor' \| 'debug' \| 'extract' \| 'migrate' \| 'explain' \| 'review' \| 'optimize' \| 'audit' \| 'test' \| 'document' \| 'plan'` | Names the closed vocabulary of what a brief asks for. |
@@ -139,8 +137,6 @@ check, met or missed, narrated by the reasoner.
139
137
 
140
138
  ### Constants
141
139
 
142
- A `Shape` cell holds the constant's declared type.
143
-
144
140
  | Name | Kind | Signature | Summary |
145
141
  | ------------------------ | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
146
142
  | `TASK_OPERATIONS` | const | `readonly TaskOperation[]` | Lists the `TaskOperation` values, frozen. |
@@ -212,13 +208,17 @@ try {
212
208
  Throws are reserved for caller misuse: `assertBrief` and `snapshotBrief` throw `INVALID` on
213
209
  data the contract refuses, and any method after `destroy()` throws `DESTROYED`. Blocking gaps
214
210
  are not an error — the gate fails closed into an incomplete `Briefing` whose `failures` carry
215
- a `BLOCKED` marker, mirroring interprets `NO_TEMPLATE` visible-incomplete outcome.
211
+ a `BLOCKED` marker, mirroring interprets `NO_RECIPE` visible-incomplete outcome.
216
212
 
217
213
  Each code carries the `context` it can actually supply, and they are not uniform: `DRAFT_FAILED`
218
214
  carries `{ stage, field }`, `GATE_FAILED` carries `{ stage, field, reasoning }`, `INVALID`
219
215
  carries `{ field }` plus the offending value where the code has one — the hash on a
220
216
  content-hash collision — and `DESTROYED` carries none.
221
217
 
218
+ A stage failure's `message` and its stage record's `error` carry the thrown value's message as
219
+ `errorToMessage`, from `@orkestrel/contract`, reads it: a thrown value that cannot be read, or
220
+ that reads as empty text, records `'unknown failure'`.
221
+
222
222
  ### Validators
223
223
 
224
224
  Total guards composed from the `@orkestrel/contract` combinators. Adversarial input — junk,
@@ -236,8 +236,6 @@ guards the same way with `@orkestrel/interpret`'s published `isInterpretation`,
236
236
  doors: the borrowed engine's return and a caller-supplied `interpretation`. A malformed value at
237
237
  either door records `INTERPRET_FAILED` instead of throwing out of `compile`.
238
238
 
239
- In a guard table a `Shape` cell holds the type the guard narrows to.
240
-
241
239
  | Name | Kind | Signature | Summary |
242
240
  | ----------------- | ----- | ---------------------- | ------------------------------------------------------------------------------------------------ |
243
241
  | `isText` | const | `Guard<string>` | Checks whether the value is a string holding no line terminator, empty included. |
@@ -313,8 +311,6 @@ over the same values and fails the moment they diverge, and `createBriefContract
313
311
  `ContractInterface<Brief>` return type makes the compiler prove `Infer<typeof briefShape>`
314
312
  is exactly `Brief`.
315
313
 
316
- A `Shape` cell holds the constant's declared type.
317
-
318
314
  | Name | Kind | Signature | Summary |
319
315
  | ---------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
320
316
  | `textShape` | const | `StringShape` | Describes a single-line string of any length, including empty — the shape mirror of `isText`. |
@@ -492,7 +488,6 @@ consumes a whole and returns a derived view of it.
492
488
  | `deriveTask` | function | `(intent: Intent, text: string, actions: Readonly<Record<string, TaskOperation>>, domains: Readonly<Record<string, TaskDomain>>) => Task \| undefined` | Derives a `Task` from an interprets `Intent` through the caller's vocabularies. |
493
489
  | `deriveGivens` | function | `(entities: readonly Entity[]) => readonly Given[]` | Derives `Given[]` from an interprets `Entity[]`. |
494
490
  | `deriveGaps` | function | `(ambiguities: readonly Ambiguity[]) => readonly Gap[]` | Derives `Gap[]` from an interprets `Ambiguity[]`. |
495
- | `errorToMessage` | function | `(error: unknown) => string` | Renders a value thrown by a stage into a message. |
496
491
  | `freezeDeep` | function | `<T>(value: T) => T` | Freezes a value and everything reachable from it. |
497
492
  | `freezeBranch` | function | `<T>(value: T, seen: WeakSet<object>) => T` | Freezes one branch of a value graph, skipping what the visited set already holds. |
498
493
 
@@ -510,7 +505,6 @@ import {
510
505
  deriveGivens,
511
506
  deriveStatement,
512
507
  deriveTask,
513
- errorToMessage,
514
508
  freezeDeep,
515
509
  findBlockingGaps,
516
510
  findUngrantedAuthority,
@@ -548,8 +542,6 @@ deriveTask(
548
542
  ) // { operation: 'migrate', domain: 'code', statement: 'Migrate the stores.' }
549
543
  deriveGivens([{ name: 'count', value: 3, provenance: { category: 'extracted' }, confidence: 1 }]) // [{ category: 'extracted', name: 'count', value: '3' }]
550
544
  deriveGaps([{ field: 'output', question: 'Diff or files?', candidates: [], required: true }])
551
- errorToMessage(new Error('boom')) // 'boom'
552
- errorToMessage(Object.create(null)) // 'an unreadable object was thrown' — never throws
553
545
  freezeDeep({ outcomes: [{ rank: 1 }] }) // nested array frozen too, unlike Object.freeze
554
546
 
555
547
  const leaf = () => 'ready'
@@ -934,7 +926,7 @@ const migrations = createBriefCompiler({
934
926
  numbers: [3],
935
927
  }),
936
928
  },
937
- templates: [
929
+ recipes: [
938
930
  {
939
931
  id: 'migration',
940
932
  name: 'Migration',
@@ -973,7 +965,7 @@ migration.brief !== undefined // true
973
965
  migrations.destroy()
974
966
  ```
975
967
 
976
- Drop the templates and the same call blocks instead, carrying interprets own question
968
+ Drop the recipes and the same call blocks instead, carrying interprets own question
977
969
  (`Which domain and action did you mean?`) as a blocking gap. That is the design working, not
978
970
  a defect: a contract built on a request the language pipeline could not resolve is exactly
979
971
  what the gate exists to refuse. A caller who does not want interpretation omits `text` and