@orkestrel/scaffold 0.0.118 → 0.0.120
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 +15 -15
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/platforms/windows.md +2 -1
- package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
- package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +2 -1
- package/dist/host/claude/agents/orkestrel.md +27 -26
- package/dist/host/claude/rules/names.md +3 -2
- package/dist/host/claude/rules/tests.md +4 -2
- package/dist/host/claude/rules/typescript.md +2 -3
- package/dist/host/claude/rules/workspace.md +2 -1
- package/dist/host/guides/abort.md +0 -4
- package/dist/host/guides/budget.md +1 -5
- package/dist/host/guides/codec.md +18 -3
- package/dist/host/guides/contract.md +23 -44
- package/dist/host/guides/csv.md +86 -93
- package/dist/host/guides/database.md +0 -4
- package/dist/host/guides/emitter.md +0 -2
- package/dist/host/guides/form.md +26 -47
- package/dist/host/guides/html.md +3 -7
- package/dist/host/guides/indexeddb.md +28 -32
- package/dist/host/guides/jsonrpc.md +187 -0
- package/dist/host/guides/markdown.md +132 -141
- package/dist/host/guides/msg.md +47 -63
- package/dist/host/guides/ndjson.md +0 -4
- package/dist/host/guides/pool.md +0 -4
- package/dist/host/guides/process.md +71 -79
- package/dist/host/guides/reason.md +30 -36
- package/dist/host/guides/router.md +11 -18
- package/dist/host/guides/scaffold.md +147 -137
- package/dist/host/guides/sqlite.md +0 -4
- package/dist/host/guides/sse.md +6 -10
- package/dist/host/guides/table.md +481 -493
- package/dist/host/guides/template.md +0 -4
- package/dist/host/guides/test.md +46 -66
- package/dist/host/guides/timeout.md +0 -6
- package/dist/host/guides/tool.md +2 -6
- package/dist/host/guides/websocket.md +0 -4
- package/dist/host/manifest.json +100 -428
- package/dist/host/tests/setupPolicy.ts +18 -6
- package/dist/src/core/index.cjs +171 -122
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +236 -213
- package/dist/src/core/index.d.ts +236 -213
- package/dist/src/core/index.js +159 -111
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +62 -39
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +59 -54
- package/dist/src/server/index.d.ts +59 -54
- package/dist/src/server/index.js +63 -40
- package/dist/src/server/index.js.map +1 -1
- package/package.json +9 -9
|
@@ -4,7 +4,8 @@ The commands an agent runs on a Windows host, and their quirks. `.claude/rules/p
|
|
|
4
4
|
|
|
5
5
|
## Processes
|
|
6
6
|
|
|
7
|
-
-
|
|
7
|
+
- Before `npm ci`, list the processes holding a file under the checkout's `node_modules`: `tasklist /M <file>.node` for a loaded native module, and the `ExecutablePath` of each `Get-CimInstance Win32_Process` row for an executable such as a language server. When one is held, skip `npm ci` and recover per the following bullet.
|
|
8
|
+
- When a held file under `node_modules` blocks or interrupts an install, identify its holders, terminate no process the session did not launch, and record the partial installation state. Rebuild from the unchanged lockfile with `npm install`, verify the manifest and lockfile identities and the tree with `npm ls --all`, and report the clean-install criterion the recovery did not prove.
|
|
8
9
|
- Read liveness with `Get-Process -Id <pid>` in PowerShell, or under Git Bash from the output of `tasklist //FI "PID eq <pid>" //NH`: a row naming the pid means alive, and the `INFO:` line means gone. Never read liveness from `tasklist`'s exit code, `kill -0`, or `ps -eo`.
|
|
9
10
|
- List descendants with `Get-CimInstance Win32_Process -Filter "ParentProcessId=<pid>"`, applied to each listed id in turn. Under Git Bash, run it through `powershell -NoProfile -Command`, and write every Windows slash option as `//`.
|
|
10
11
|
- Kill a recorded tree with `taskkill /pid <pid> /T /F`. `launch.ts` kills the tree at its cap on this host.
|
|
@@ -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
|
|
113
|
-
|
|
|
114
|
-
| `resolveAccessible`, `resolveRendered`, `clickAccessible`, `clickAccessibleWithin`, `clickDisclosure`, `typeAccessible`, `fillAccessible`, `traverseAccessible`, `pressKeys`, `waitForState`, `readRefusal`, `readPerception`, `readPage`, `readFocus`, `
|
|
115
|
-
| `readText`, `readRole`, `readName`, `readStates`, `describeTree`, `describeFocus`, `isReachable`, `isRendered`, `readHit`, `waitForAnimations`
|
|
116
|
-
| `readContrast`, `readRing`, `readLayers`, `readBackdrop`, `readStyle`, `readToken`, `readPixels`, `readClasses`, `readCensus`, `extractStyles`, `extractOrphans`, `readRows`
|
|
117
|
-
| `mount`, `typeInput`, `commitInput`, `captureFrame`, and a portfolio's `place`
|
|
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` | `
|
|
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`, `
|
|
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 `
|
|
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`, `
|
|
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
|
-
|
|
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 `
|
|
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
|
|
@@ -35,6 +35,7 @@ When a consumer needs a dependency's unpublished source, to meet a defect that l
|
|
|
35
35
|
## The scaffold surface
|
|
36
36
|
|
|
37
37
|
- After a package's first publish, run `scaffold catalog --all` in the scaffold checkout and release scaffold, so the `surface` rule reads the package's guide from that release.
|
|
38
|
+
- When a `@orkestrel/guide` release refuses a guide form its parser read before, push each catalog package's conforming guide to that package's `main`, the releasing package's own included, before the scaffold release that carries the catalog refresh; the `surface` rule parses every hosted guide, a target's own among them.
|
|
38
39
|
- `scaffold` is a development dependency of every package, so it publishes on its own and propagates as files, never as a cascade. Each package builds against the published `scaffold`.
|
|
39
40
|
- `scaffold` ships `dist/host`, the vendored file set every target receives through `repair`. Bump and publish `scaffold` when any vendored byte or the set of vendored paths changes.
|
|
40
41
|
- After a vendored-only release, re-pin `@orkestrel/scaffold` in each target, run `repair` there, and prove that target's gates still green. A target bumps only when its own published surface moved.
|
|
@@ -167,7 +167,8 @@ registry copy over any staged tip, so every consumer stays red until that tip is
|
|
|
167
167
|
|
|
168
168
|
## Prepare a layer
|
|
169
169
|
|
|
170
|
-
- After the re-pin and before `prepublishOnly`, run `scaffold surface` live over every candidate checkout of the layer, never with `--offline`. Stop the upload on any exit but `0`, and resolve every name it reports under `.claude/rules/names.md` § Fleet name ownership. In scaffold's own layer, run `scaffold catalog` and then `scaffold surface --from .`.
|
|
170
|
+
- After the re-pin and before `prepublishOnly`, run `scaffold surface` live over every candidate checkout of the layer, never with `--offline`. Stop the upload on any exit but `0`, and resolve every name it reports under `.claude/rules/names.md` § Fleet name ownership. In scaffold's own layer, run `scaffold catalog`, then `npm run build`, so `host.json` records the refreshed files' digests, and then `scaffold surface --from .`.
|
|
171
|
+
- In the scaffold release that opens a transfer under `.claude/rules/names.md` § Fleet name ownership rule 5, declare it in `SURFACE_TRANSFERS` before `npm run build`. In the scaffold visit that closes it, remove the declaration before the build and confirm `host.json` no longer records the name.
|
|
171
172
|
- When `scaffold surface` prints an advisory, rule it under `.claude/rules/names.md` § Fleet name ownership before the upload; an advisory never stops the upload.
|
|
172
173
|
- Begin each release chain plan with the clean reinstall and the clean, whether it runs in a clone or the checkout.
|
|
173
174
|
- When a writer owns a script the preparation needs, run its installed built twin and record the executable's identity.
|
|
@@ -43,54 +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.15` | L1 | `@orkestrel/contract` `^0.0.21` | |
|
|
47
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
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
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.
|
|
50
|
+
| `@orkestrel/budget` | `0.0.16` | L1 | `@orkestrel/contract` `^0.0.21` | |
|
|
51
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.
|
|
52
|
+
| `@orkestrel/codec` | `0.0.8` | L1 | `@orkestrel/contract` `^0.0.21` | |
|
|
53
53
|
| `@orkestrel/console` | `0.0.17` | L2 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
|
|
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.
|
|
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
59
|
| `@orkestrel/guide` | `0.0.28` | L3 | `@orkestrel/contract` `^0.0.20`, `@orkestrel/markdown` `^0.0.18` | |
|
|
60
|
-
| `@orkestrel/html` | `0.0.
|
|
61
|
-
| `@orkestrel/indexeddb` | `0.0.
|
|
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
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/jsonrpc` | `0.0.1` | L1 | `@orkestrel/contract` `^0.0.21` | |
|
|
63
64
|
| `@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.
|
|
65
|
+
| `@orkestrel/markdown` | `0.0.19` | L2 | `@orkestrel/html` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
|
|
65
66
|
| `@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
67
|
| `@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.
|
|
68
|
-
| `@orkestrel/ndjson` | `0.0.
|
|
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` | |
|
|
69
70
|
| `@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.
|
|
71
|
+
| `@orkestrel/pool` | `0.0.19` | L2 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
|
|
71
72
|
| `@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.
|
|
73
|
+
| `@orkestrel/process` | `0.0.17` | L2 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
|
|
73
74
|
| `@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
75
|
| `@orkestrel/qualifier` | `0.0.19` | L3 | `@orkestrel/reason` `^0.0.15`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
|
|
75
76
|
| `@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
77
|
| `@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.
|
|
78
|
+
| `@orkestrel/reason` | `0.0.16` | L2 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
|
|
78
79
|
| `@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.
|
|
80
|
-
| `@orkestrel/scaffold` | `0.0.
|
|
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.119` | 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
82
|
| `@orkestrel/sea` | `0.0.20` | L3 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/process` `^0.0.16`, `@orkestrel/contract` `^0.0.20` | |
|
|
82
83
|
| `@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.
|
|
84
|
-
| `@orkestrel/sse` | `0.0.
|
|
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` | |
|
|
85
86
|
| `@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.
|
|
87
|
-
| `@orkestrel/template` | `0.0.
|
|
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` | |
|
|
88
89
|
| `@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.
|
|
90
|
-
| `@orkestrel/timeout` | `0.0.
|
|
91
|
-
| `@orkestrel/tool` | `0.0.
|
|
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` | |
|
|
92
93
|
| `@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.
|
|
94
|
+
| `@orkestrel/websocket` | `0.0.17` | L2 | `@orkestrel/emitter` `^0.0.14`, `@orkestrel/contract` `^0.0.21` | |
|
|
94
95
|
| `@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
96
|
| `@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
97
|
| `@orkestrel/workspace` | `0.0.13` | L3 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/database` `^0.0.19` | |
|
|
@@ -134,14 +134,15 @@ Export a bare name from one environment of its package. When two environments of
|
|
|
134
134
|
|
|
135
135
|
Before adding a public name, check it against the fleet with `scaffold surface`. `.claude/rules/workspace.md` § Policy instruments owns the `surface` policy rule.
|
|
136
136
|
|
|
137
|
-
The rule grandfathers a source name the target's own hosted guide claims, because that guide is the target's own claim to it. It grandfathers no root `tests/setup*.ts` export. A vendored `tests/setup*.ts` module a scaffold release stages sits outside the inspected population.
|
|
137
|
+
The rule grandfathers a source name the target's own hosted guide claims, because that guide is the target's own claim to it, and a source name whose installed collision record names the target as an owner: the hosted `manifest.json` in a target, and the committed `host.json` in the `@orkestrel/scaffold` checkout. It grandfathers no root `tests/setup*.ts` export. A vendored `tests/setup*.ts` module a scaffold release stages sits outside the inspected population.
|
|
138
138
|
|
|
139
139
|
Resolve a reported collision with these rules, in order.
|
|
140
140
|
|
|
141
141
|
1. **Reuse before renaming.** Where the colliding declarations carry the same contract, delete this one and import the owner's export. Declare the dependency that import needs, or stop and report that the dependency is not authorized.
|
|
142
142
|
2. **The subject keeps the name.** Where the contracts differ, leave the name with the package whose domain the name describes, and rename the other declaration for the thing it is. Refuse a rename that makes the renamed declaration vaguer; name its own contract instead.
|
|
143
143
|
3. **Qualify rather than extract.** Extract a shared package only where a proof shows the colliding declarations interchangeable and the dependency change is authorized. Otherwise qualify the name in place for the domain it serves, and route the extraction through a design round rather than renaming by fiat.
|
|
144
|
-
4. **Close the collision in the code.** Change a declaration; the rule reads no allowlist a target can add a name to, and it carries no suppression. Never suppress the violation, and never edit a vendored policy instrument to clear it. In the `@orkestrel/scaffold` checkout, shrink the committed `host.json` collision record by closing a collision, and
|
|
144
|
+
4. **Close the collision in the code.** Change a declaration; the rule reads no allowlist a target can add a name to, and it carries no suppression. Never suppress the violation, and never edit a vendored policy instrument to clear it. In the `@orkestrel/scaffold` checkout, shrink the committed `host.json` collision record by closing a collision, and widen it only by the keeper a transfer under rule 5 declares.
|
|
145
|
+
5. **Transfer a name through a declared keeper.** When a `ROADMAP.md` item rules that one package gains a bare name other packages export, declare the transfer in `SURFACE_TRANSFERS` in `src/core/constants.ts` of the `@orkestrel/scaffold` checkout as the name, its keeper, and the item, one keeper per name, in the scaffold release that precedes the keeper's visit. A declared transfer admits exactly that keeper into that name's recorded owner set and admits nothing else: the stage still refuses any other added owner, and a collision no transfer names stays closed in the code under rule 4. The keeper exports the name under the transfer; each giver deletes its copy and imports the keeper's at its own visit under rule 1. Remove the transfer in the scaffold visit after the last giver publishes; the stage refuses a transfer whose keeper's mirrored guide alone claims the name.
|
|
145
146
|
|
|
146
147
|
## Acronyms
|
|
147
148
|
|
|
@@ -170,6 +170,8 @@ A test that spawns a process, packs, installs, or drives a real build is a proof
|
|
|
170
170
|
`.claude/rules/workspace.md` fixes where each isolated project runs, and that placement
|
|
171
171
|
differs between a publishing and a `private: true` workspace.
|
|
172
172
|
- Use `distribution` and `service` as the fixed expensive-proof projects.
|
|
173
|
+
- When a change alters what a package ships, such as an export, its declaration text, or a packed
|
|
174
|
+
path, run its `distribution` project before accepting the change.
|
|
173
175
|
- Put a study's proofs under `tests/studies/` in the `studies` project, which
|
|
174
176
|
`.claude/rules/workspace.md` § Test project matrix places.
|
|
175
177
|
- Put in `studies` only the proofs the `@orkestrel/study` engine drives. Place a slow end-to-end proof of
|
|
@@ -281,9 +283,9 @@ Import `createScratch` from `@orkestrel/test/server` when a proof needs real fil
|
|
|
281
283
|
|
|
282
284
|
Browser/style setup exposes shared assertions/builders:
|
|
283
285
|
|
|
284
|
-
`mount`, `render`, `build`, `readStyle`, `readToken`, `readRootToken`, `readPixels`, `parseCSSColor`, `matchesColor`, `
|
|
286
|
+
`mount`, `render`, `build`, `readStyle`, `readToken`, `readRootToken`, `readPixels`, `parseCSSColor`, `matchesColor`, `findStyleRule`.
|
|
285
287
|
|
|
286
|
-
`
|
|
288
|
+
`findStyleRule` proves a declaration exists in the cascade; `readStyle()` reads the resolved result.
|
|
287
289
|
|
|
288
290
|
## Browser tests
|
|
289
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
|
|
214
|
-
|
|
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;
|
|
@@ -352,7 +352,8 @@ Build/check config alignment:
|
|
|
352
352
|
comparison leaves out the setup modules scaffold owns in every target: each vendored `HOST_PATHS`
|
|
353
353
|
member and the `tests/setupDistribution.ts` harness. `.claude/rules/names.md` § Fleet name
|
|
354
354
|
ownership defines the bare name that comparison matches and decides which declaration gives a
|
|
355
|
-
claimed name up.
|
|
355
|
+
claimed name up. The `surface` rule also grandfathers a name the installed record admits the
|
|
356
|
+
target to under `.claude/rules/names.md` § Fleet name ownership rule 5.
|
|
356
357
|
- Keep every barrel statement in the form `.claude/rules/architecture.md` § Barrel exports fixes.
|
|
357
358
|
The sweep refuses a barrel population it cannot read whole and reports that refusal as a `surface`
|
|
358
359
|
violation rather than passing over the statements it did read. A catalog row with no hosted guide,
|
|
@@ -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. |
|
|
@@ -36,8 +36,6 @@ budget.consume(7_000) // crosses 10_000 — fires `signal`
|
|
|
36
36
|
|
|
37
37
|
### Validators
|
|
38
38
|
|
|
39
|
-
In a guard table a `Shape` cell holds the type the guard narrows to.
|
|
40
|
-
|
|
41
39
|
| Name | Kind | Signature | Summary |
|
|
42
40
|
| ---------------- | -------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
43
41
|
| `isBudget` | function | `(value: unknown) => value is BudgetInterface<unknown>` | Determines whether a value implements `BudgetInterface`, returning `false` rather than throwing on hostile input. |
|
|
@@ -72,8 +70,6 @@ In a guard table a `Shape` cell holds the type the guard narrows to.
|
|
|
72
70
|
|
|
73
71
|
### Types
|
|
74
72
|
|
|
75
|
-
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 `\|`.
|
|
76
|
-
|
|
77
73
|
| Name | Kind | Signature | Summary |
|
|
78
74
|
| -------------------- | --------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
79
75
|
| `BudgetOptions` | interface | `{ id?, max, consumer, signal? }` | Represents the options for constructing a cumulative budget, accepted by the `createBudget` function and the `Budget` constructor. |
|
|
@@ -124,7 +120,7 @@ These invariants hold across `src/core` ↔ `budget.md`:
|
|
|
124
120
|
8. **Traceable identity.** `id` is a stable string for the handle's lifetime — caller-supplied through `options.id`, including an empty string, or a `crypto.randomUUID()` default only when `id` is omitted. `max` is the validated ceiling, exposed read-only. The abort reason on owned exhaustion is a `BudgetError` coded `'exhaust'` with the fixed message `budget reached its ceiling`, whose `context` holds the `id`, `max`, and `consumed` at the crossing; a parent abort keeps the parent's reason, including when the parent aborted before the crossing and nothing had read the composite signal. `consume` tests the composed signal, not the owned controller, before it aborts the controller, so the parent's reason survives whether or not the host's `AbortSignal.any` has propagated the parent's abort yet; on Node 24.22.0 the propagation is eager and an owned-controller test gives the same reason.
|
|
125
121
|
9. **Strict once-read boundaries.** `validateBudgetOptions`, `validateTokenBudgetOptions`, `validateMeterOptions`, and `validateTokenMeterOptions` accept the typed contracts while defending their hostile JavaScript boundary: they require a plain record, read each declared property exactly once inside a contained boundary, validate with structured `ContractError` taxonomy/context, and return a fresh normalized object that omits absent optional keys. `Budget` calls the budget helper before allocating its controller; `createTokenBudget` calls the token helper before creating its consumer and public budget; `Meter` calls the meter helper before it stores anything; `createTokenMeter` calls the token-meter helper before it composes the meter.
|
|
126
122
|
10. **Validated token accounting.** `TokenScope` is the public `'completion' | 'total' | 'prompt'` selector and defaults to `completion` in `createTokenBudget`. Token factories reject unsupported scopes and malformed usage; all three `TokenUsage` fields must be finite and nonnegative before the selected charge is used.
|
|
127
|
-
11. **Total guards and cross-copy recognition.** `isBudget`, `isBudgetAmount`, `isBudgetError`, `isBudgetSignal`, `isTokenScope`, and `isTokenUsage` return `false`, rather than throw, for off-shape, hostile, or revoked input. `isBudgetError` uses the identity brand instead of `instanceof BudgetError`, while retaining the native `Error` base check. The constructor stamps `BUDGET_ERROR_BRAND`, the registry-global `Symbol.for('@orkestrel/budget.
|
|
123
|
+
11. **Total guards and cross-copy recognition.** `isBudget`, `isBudgetAmount`, `isBudgetError`, `isBudgetSignal`, `isTokenScope`, and `isTokenUsage` return `false`, rather than throw, for off-shape, hostile, or revoked input. `isBudgetError` uses the identity brand instead of `instanceof BudgetError`, while retaining the native `Error` base check. The constructor stamps `BUDGET_ERROR_BRAND`, the registry-global `Symbol.for('@orkestrel/budget.BudgetError')`, as a non-enumerable own property whose value is the error itself. The guard requires that exact identity, the native `Error` base, a prototype other than `Error.prototype`, the code `'exhaust'`, and a `context` holding a string `id` and number `max` and `consumed`. Subclass instances and renamed errors pass without reading `name`. One rule serves every copy: a reason built by another installation, or by the CommonJS entry when the guard came from the ESM entry, narrows exactly as one built by the same copy, and the reverse holds too. A transparent proxy over a genuine error is refused, because its forwarded descriptor stores the target. An unbranded `Error` carrying `code: 'exhaust'`, and an error from a copy that stamps no brand, such as 0.0.13, stay outside the type. The brand is a recognition marker, not proof of origin: a complete forgery that stamps its own identity under the key passes.
|
|
128
124
|
12. **Signal-only observation.** Neither `Budget` nor `Meter` has an Emitter, `EventMap`, or `on` hook. The budget's native `AbortSignal` is the observation mechanism.
|
|
129
125
|
13. **DOC ↔ SOURCE method bijection.** The `## Methods` tables list exactly the public methods of `BudgetInterface` and `MeterInterface` — exhaustive, both directions — and `Budget` and `Meter` expose the same public methods as their interfaces, no more.
|
|
130
126
|
14. **Growth metering.** `charge(delta)` refuses a non-string delta with a `literal`-coded `ContractError` before any state changes. It then counts the delta, estimates the whole text, refuses a nonfinite or negative estimate with a `range`-coded `ContractError`, and measures the estimate's growth over the growth the budget has accepted plus the growth of every charge still in flight. Only when that growth is positive does it consume `producer(growth)`. Each charge in flight holds a per-call claim of its growth from before the producer runs until the charge settles, so a charge that re-enters the meter synchronously, through the producer, the budget's consumer, or an abort listener the crossing fires, measures its own growth past the claims and the nested and outer charges sum to the serial result. `charged` is the total growth the budget accepted from this meter: it rises by a charge's growth only after the budget's `consume` returns, and a throw from the producer or the budget drops the claim and raises nothing. For a budget the meter alone charges and never clears, `charged` therefore equals the budget's `consumed` whenever no charge is in flight, in serial use, under re-entry through the producer or the budget's consumer, and under refusal. A nested charge an abort listener makes is added before the outer charge, which the budget added first, so with growths that are not integers the two can differ in the last digit. In serial use `charged` equals the latest accepted estimate up to floating-point rounding. A throw from the estimator, or a refused estimate, claims nothing. Every refusal leaves the delta counted, and the next charge measures the growth from the text that includes it. A meter has no reset; create one per stream.
|
|
@@ -121,6 +121,17 @@ read — is module data rather than public API, for the reason the Base64 alphab
|
|
|
121
121
|
| `decodeUTF16LE` | function | `(bytes: Uint8Array) => string \| undefined` | Decodes little-endian UTF-16 bytes into their text, reading two bytes per code unit, low byte first. An odd length and an unpaired surrogate are `undefined`. A leading FF FE is kept as U+FEFF rather than stripped. |
|
|
122
122
|
| `isUTF16LE` | function | `(value: unknown) => value is Uint8Array` | Checks whether a value is bytes that decode as UTF-16LE — true for exactly the byte sequences `decodeUTF16LE` answers text for. An odd length and an unpaired surrogate are false. Total on any value: a string, `null`, a sibling view kind, or a proxy is false rather than a throw. |
|
|
123
123
|
|
|
124
|
+
### Marks
|
|
125
|
+
|
|
126
|
+
The marks module, [`marks/constants.ts`](../src/core/marks/constants.ts), holds the byte order mark a
|
|
127
|
+
consumer writes or strips around a coding. `BOM` is the one public constant in this package, kept
|
|
128
|
+
in its own module so the lookup tables behind the codings stay module data. The
|
|
129
|
+
[BOM stance](#the-bom-stance) states how each charset face carries it.
|
|
130
|
+
|
|
131
|
+
| Name | Kind | Signature | Summary |
|
|
132
|
+
| ----- | ----- | ---------- | ------------------------------------------------------------- |
|
|
133
|
+
| `BOM` | const | `"\uFEFF"` | Holds the byte order mark, U+FEFF, as a one-character string. |
|
|
134
|
+
|
|
124
135
|
## The laws
|
|
125
136
|
|
|
126
137
|
Each face keeps the round-trip and canonical-form laws, and the suite drives both as sweeps rather
|
|
@@ -206,8 +217,9 @@ A byte order mark is data here, not a signal. `EF BB BF` decodes to U+FEFF on th
|
|
|
206
217
|
`FF FE` decodes to U+FEFF on the UTF-16LE face, in leading position exactly as anywhere else, and
|
|
207
218
|
each encodes back to those bytes. The round-trip law forces it: a decoder that dropped a leading BOM
|
|
208
219
|
would answer a text whose re-encoding is shorter than the bytes it was given, and no amount of
|
|
209
|
-
documentation makes that a round trip. A consumer that wants the mark removed
|
|
210
|
-
way a consumer wanting lenient Base64 normalizes
|
|
220
|
+
documentation makes that a round trip. A consumer that wants the mark removed compares the leading
|
|
221
|
+
character against `BOM` and removes it, the same way a consumer wanting lenient Base64 normalizes
|
|
222
|
+
first.
|
|
211
223
|
|
|
212
224
|
### Where this package parts from WHATWG
|
|
213
225
|
|
|
@@ -377,6 +389,7 @@ to UTF-16LE.
|
|
|
377
389
|
|
|
378
390
|
```ts
|
|
379
391
|
import {
|
|
392
|
+
BOM,
|
|
380
393
|
decodeLatin1,
|
|
381
394
|
decodeUTF8,
|
|
382
395
|
decodeUTF16LE,
|
|
@@ -392,6 +405,7 @@ encodeUTF8('hi') // Uint8Array [104, 105]
|
|
|
392
405
|
decodeUTF8(new Uint8Array([104, 105])) // 'hi'
|
|
393
406
|
encodeUTF8('\ud800') // undefined — a lone surrogate has no UTF-8 spelling
|
|
394
407
|
decodeUTF8(new Uint8Array([0xc0, 0x80])) // undefined — the overlong spelling of U+0000
|
|
408
|
+
encodeUTF8(BOM) // Uint8Array [239, 187, 191]
|
|
395
409
|
decodeUTF8(new Uint8Array([0xef, 0xbb, 0xbf])) // '\ufeff' — the BOM is data, not a signal
|
|
396
410
|
|
|
397
411
|
// ISO-8859-1 is the identity on a byte, so only its encode side can refuse.
|
|
@@ -461,7 +475,8 @@ measureUTF8('\ud800') // undefined — ill-formed text has no UTF-8 spelling
|
|
|
461
475
|
round-trip law walks a well-formed text population built from characters spanning every UTF-8
|
|
462
476
|
width threshold, the BOM, the Latin-1 ceiling, the Windows-1252 bands, and the code points on
|
|
463
477
|
either side of the surrogate range, and pins each width threshold at the byte length the
|
|
464
|
-
specification fixes.
|
|
478
|
+
specification fixes. A named case carries `BOM` through both faces, leading position included, and
|
|
479
|
+
pins it against `String.fromCodePoint(0xfeff)`. The canonical-form law walks the exhaustive two-byte space on every charset
|
|
465
480
|
face, re-encoding every admitted pair to itself, and reads the Windows-1252 defined mapping as a
|
|
466
481
|
bijection and the Latin-1 mapping as the identity bijection. Beside the sweeps sit the written-out
|
|
467
482
|
refusal rows — the overlongs, the encoded surrogates, the out-of-range and truncated sequences,
|