@orkestrel/scaffold 0.0.113 → 0.0.115
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/agents/skills/orkestrel-publish/scripts/wave.js +83 -16
- package/dist/bin/main.js +71 -23
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +5 -3
- package/dist/host/agents/platforms/windows.md +1 -0
- package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
- package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +4 -4
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -1
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +8 -2
- package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +1 -0
- package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +7 -7
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +31 -11
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +150 -49
- package/dist/host/claude/agents/analyst.md +1 -1
- package/dist/host/claude/agents/astra.md +2 -2
- package/dist/host/claude/agents/builder.md +4 -4
- package/dist/host/claude/agents/opus.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +57 -59
- package/dist/host/claude/agents/planner.md +8 -2
- package/dist/host/claude/rules/campaign.md +2 -1
- package/dist/host/claude/rules/documentation.md +1 -0
- package/dist/host/claude/rules/tests.md +13 -8
- package/dist/host/claude/rules/workspace.md +28 -28
- package/dist/host/claude/rules/writing.md +1 -0
- package/dist/host/claude/skills/enterprise-bootstrap/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-align/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-build/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-debrief/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-falsify/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-journey/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-polish/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +8 -5
- package/dist/host/codex/agents/astra.toml +4 -5
- package/dist/host/codex/agents/builder.toml +5 -5
- package/dist/host/codex/agents/opus.toml +3 -4
- package/dist/host/codex/agents/orkestrel.toml +2 -1
- package/dist/host/codex/agents/planner.toml +8 -5
- package/dist/host/codex/agents/reviewer.toml +5 -4
- package/dist/host/guides/agent.md +13 -13
- package/dist/host/guides/brief.md +4 -0
- package/dist/host/guides/browser.md +162 -44
- package/dist/host/guides/budget.md +1 -1
- package/dist/host/guides/capture.md +4 -0
- package/dist/host/guides/console.md +13 -0
- package/dist/host/guides/contract.md +38 -3
- package/dist/host/guides/csv.md +5 -0
- package/dist/host/guides/database.md +58 -8
- package/dist/host/guides/form.md +17 -0
- package/dist/host/guides/guide.md +36 -33
- package/dist/host/guides/html.md +72 -44
- package/dist/host/guides/indexeddb.md +4 -0
- package/dist/host/guides/lsp.md +49 -8
- package/dist/host/guides/markdown.md +146 -1
- package/dist/host/guides/mcp.md +117 -22
- package/dist/host/guides/middleware.md +194 -26
- package/dist/host/guides/msg.md +9 -5
- package/dist/host/guides/pool.md +8 -1
- package/dist/host/guides/probe.md +13 -1
- package/dist/host/guides/process.md +102 -90
- package/dist/host/guides/program.md +4 -0
- package/dist/host/guides/qualifier.md +4 -0
- package/dist/host/guides/rater.md +4 -0
- package/dist/host/guides/reason.md +6 -4
- package/dist/host/guides/relation.md +4 -0
- package/dist/host/guides/scaffold.md +32 -14
- package/dist/host/guides/server.md +29 -13
- package/dist/host/guides/sqlite.md +6 -0
- package/dist/host/guides/sse.md +6 -0
- package/dist/host/guides/study.md +473 -473
- package/dist/host/guides/table.md +3 -0
- package/dist/host/guides/template.md +3 -0
- package/dist/host/guides/test.md +38 -20
- package/dist/host/guides/tool.md +3 -0
- package/dist/host/guides/toolbox.md +21 -0
- package/dist/host/guides/websocket.md +3 -1
- package/dist/host/guides/workflow.md +103 -11
- package/dist/host/guides/workspace.md +4 -0
- package/dist/host/manifest.json +84 -84
- package/dist/host/tests/config.test.ts +7 -13
- package/dist/src/core/index.cjs +20 -28
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +7 -7
- package/dist/src/core/index.d.ts +7 -7
- package/dist/src/core/index.js +20 -28
- package/dist/src/core/index.js.map +1 -1
- package/package.json +12 -12
|
@@ -26,7 +26,7 @@ Source: [core](../src/core), [server](../src/server), [browser](../src/browser),
|
|
|
26
26
|
|
|
27
27
|
`BrowserPage`, `BrowserFrame`, `BrowserPageElement`, `BrowserElementManager`, `BrowserDOMElement`, `BrowserDOMElementManager`, and `BrowserJourneyToolset` are internal classes: their owners construct them and return their public interfaces. `BrowserDialog`, `BrowserDownload`, `BrowserWebSocket`, `BrowserCodegen`, `BrowserRouteManager`, `BrowserFileChooser`, `BrowserHandle`, `BrowserHold`, `BrowserNavigationRecord`, `BrowserRegistry`, `BrowserRoute`, `BrowserWorker`, and `FileBrowserStore` are internal for the same reason. Construct a context with `createBrowserContext`, obtain pages from its owner, and construct a toolset with `createBrowserToolset` over either a page or a DOM view. A caller owns that view; destroying the toolset releases its registrations and observers.
|
|
28
28
|
|
|
29
|
-
The owners also construct `BrowserClock`, `BrowserCookieManager`, `BrowserEmulationManager`, `BrowserHARManager`, `BrowserNetworkManager`, `BrowserKeyboard`, `BrowserMouse`, `BrowserTouch`, `BrowserNavigationManager`, `BrowserPermissionManager`, `BrowserScriptManager`, `BrowserStorageManager`, `
|
|
29
|
+
The owners also construct `BrowserClock`, `BrowserCookieManager`, `BrowserEmulationManager`, `BrowserHARManager`, `BrowserNetworkManager`, `BrowserKeyboard`, `BrowserMouse`, `BrowserTouch`, `BrowserNavigationManager`, `BrowserPermissionManager`, `BrowserScriptManager`, `BrowserStorageManager`, `BrowserTrace`, `BrowserCoverage`, `BrowserPerformance`, `BrowserProfiler`, `BrowserDiagnostics`, and `BrowserAccessibility`. These classes are internal; the page or context exposes their public interfaces. `BrowserTraceCapture`, `BrowserPopupArrivals`, and `BrowserJourneyRecord` are internal operation owners constructed by the trace and toolsets. `BrowserErrorContext` is internal to error metadata validation.
|
|
30
30
|
|
|
31
31
|
### Connect to a browser and drive a page
|
|
32
32
|
|
|
@@ -188,8 +188,8 @@ The core supplies the entities a browser session and an agent use. Its host-spec
|
|
|
188
188
|
| `BrowserTiming` | interface | Holds network timing values in milliseconds relative to request time. |
|
|
189
189
|
| `BrowserTimingRange` | interface | Describes the start/end pair for one network timing phase. |
|
|
190
190
|
| `BrowserTouchInterface` | interface | Provides touch input operations bound to one frame target session. |
|
|
191
|
-
| `
|
|
192
|
-
| `
|
|
191
|
+
| `BrowserTraceInterface` | interface | Drives the trace capture lifecycle. |
|
|
192
|
+
| `BrowserTraceResult` | interface | Describes the result of a trace capture. |
|
|
193
193
|
| `BrowserTransitionInterface` | interface | Represents one asynchronous transition shared by every caller that arrives while it runs. |
|
|
194
194
|
| `BrowserUserAgent` | interface | Describes user-agent metadata accepted by Chromium emulation. |
|
|
195
195
|
| `BrowserViewInterface` | interface | Provides the document operations shared by remote and DOM-native views. |
|
|
@@ -217,7 +217,7 @@ The core supplies the entities a browser session and an agent use. Its host-spec
|
|
|
217
217
|
| `BrowserScreenshotOptions` | interface | Describes the options for taking a page screenshot. |
|
|
218
218
|
| `BrowserSettlementOptions` | interface | Configures a record's settlement. |
|
|
219
219
|
| `BrowserStorageOptions` | interface | Describes the options for collecting storage state from selected origins. |
|
|
220
|
-
| `
|
|
220
|
+
| `BrowserTraceOptions` | interface | Describes the options for a Chromium trace capture. |
|
|
221
221
|
| `BrowserTraversalOptions` | interface | Describes the options for traversing a browser snapshot. |
|
|
222
222
|
| `BrowserWaitOptions` | interface | Configures a text or element wait, including whether absence satisfies it. |
|
|
223
223
|
| `validateBrowserContextOptions` | function | Validates isolated-context options before creating remote state. |
|
|
@@ -473,9 +473,9 @@ validateBrowserViewport({ width: 1280, height: 720 })
|
|
|
473
473
|
|
|
474
474
|
| API | Kind | Summary |
|
|
475
475
|
| ------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
476
|
-
| `
|
|
476
|
+
| `BrowserContent` | class | Represents one captured document, parsed one time and projected to Markdown or plain text in bounded slices. |
|
|
477
477
|
| `BrowserSnapshot` | class | Represents a navigable, serializable browser DOM snapshot. |
|
|
478
|
-
| `
|
|
478
|
+
| `createBrowserContent` | function | Creates a `BrowserContentInterface` over a captured document, parsing its HTML one time. |
|
|
479
479
|
| `createBrowserSnapshot` | function | Creates a navigable `BrowserSnapshotInterface` over decoded `BrowserSnapshotInput` data. |
|
|
480
480
|
| `BrowserAccessibilityInterface` | interface | Inspects the accessibility tree. |
|
|
481
481
|
| `BrowserAccessibilitySnapshot` | interface | Describes a serializable accessibility-tree snapshot. |
|
|
@@ -495,8 +495,8 @@ validateBrowserViewport({ width: 1280, height: 720 })
|
|
|
495
495
|
| `BrowserOutlineNode` | interface | Associates an outline row with its frame, session, and optional actionable reference. |
|
|
496
496
|
| `BrowserPageElementInterface` | interface | Provides trusted page input and capture for a referenced element. |
|
|
497
497
|
| `BrowserPoint` | interface | Describes a point in viewport CSS pixels. |
|
|
498
|
-
| `
|
|
499
|
-
| `
|
|
498
|
+
| `BrowserContentInput` | interface | Describes the captured document a reading is built from. |
|
|
499
|
+
| `BrowserContentInterface` | interface | Represents one captured document, parsed one time and projected to Markdown or plain text in bounded slices. |
|
|
500
500
|
| `BrowserReadResult` | interface | Describes one slice of a reading's projection. |
|
|
501
501
|
| `BrowserSearch` | interface | Carries the opening line and optional search text of an addressed window. |
|
|
502
502
|
| `BrowserSnapshotInput` | interface | Describes the serializable input for a navigable browser snapshot — the form a `BrowserSnapshot` is built from and serializes back to. |
|
|
@@ -896,7 +896,7 @@ const waitQuery = compileQueryWaitExpression(5_000, 'wait-2')
|
|
|
896
896
|
| `BROWSER_CODEGEN_BINDING_NAME` | const | Names the CDP runtime binding the codegen recorder script calls into, `'__orkestrelBrowserCodegen'`. |
|
|
897
897
|
| `BROWSER_CODEGEN_SOURCE` | const | Holds the self-contained document listener installed before a frame resumes. Password input carries a marker; only Enter carries a key. Node indices are local to a document. |
|
|
898
898
|
| `BROWSER_JOURNEY_ACTIONS` | const | Names the native actions a journey step can hold: `click`, `type`, `press`, `navigate`, `wait`, `dialog`, and `switch`. |
|
|
899
|
-
| `
|
|
899
|
+
| `BROWSER_JOURNEY_EMPTY_LIST` | const | Holds the result the `journeys` tool returns when no journey is saved. |
|
|
900
900
|
| `BROWSER_JOURNEY_FORMAT_VERSION` | const | Holds the journey and run file format this package writes and reads, `1`. |
|
|
901
901
|
| `BROWSER_JOURNEY_IDLE_REFUSAL` | const | Holds the refusal `save` returns when no journey is recording. |
|
|
902
902
|
| `BROWSER_JOURNEY_SAVE_SAVED_REFUSAL` | const | Holds the refusal `save` returns after a successful save when no journey is recording. |
|
|
@@ -1021,19 +1021,85 @@ compileBrowserJourneyValue(
|
|
|
1021
1021
|
compileBrowserJourney(journey, { language: 'typescript' }) // { source, gaps: [] }
|
|
1022
1022
|
```
|
|
1023
1023
|
|
|
1024
|
+
#### Execution and projection state
|
|
1025
|
+
|
|
1026
|
+
These entities own state for one traversal, edit, or replay. Construct a fresh entity for each operation. The existing capture, rendering, and replay entry points construct them for callers.
|
|
1027
|
+
|
|
1028
|
+
| API | Kind | Summary |
|
|
1029
|
+
| --------------------------------- | --------- | --------------------------------------------------------------------------------------- |
|
|
1030
|
+
| `BrowserLineWrap` | class | Wraps one semantic line while retaining its continuation and reference boundaries. |
|
|
1031
|
+
| `BrowserOutlineRows` | class | Projects outline nodes into wrapped lines while retaining listing totals and focus. |
|
|
1032
|
+
| `BrowserOutlineAncestors` | class | Traverses outline parents lazily through the supplied index. |
|
|
1033
|
+
| `BrowserOrdinals` | class | Yields positive ordinals for fallback secret parameter names. |
|
|
1034
|
+
| `BrowserJourneyEditor` | class | Applies one journey edit batch and retains the edit responsible for a refusal. |
|
|
1035
|
+
| `renderBrowserSearchQuote` | function | Chooses a bounded reference-bearing quote for a search outside the requested range. |
|
|
1036
|
+
| `boundBrowserTail` | function | Fits a character-range footer by narrowing a UTF-16 slice boundary. |
|
|
1037
|
+
| `findBrowserWrapSpace` | function | Finds a soft wrap before a reference token without splitting its preceding name. |
|
|
1038
|
+
| `skipBrowserWhitespace` | function | Finds the next non-whitespace offset after a soft line break. |
|
|
1039
|
+
| `BrowserNavigationStep` | type | Carries one recorded navigation event and its frame identity. |
|
|
1040
|
+
| `BrowserNavigationSelection` | interface | Carries the settlement selected after a navigation event. |
|
|
1041
|
+
| `BrowserJourneyEditorInterface` | interface | Exposes the result of one atomic journey edit batch. |
|
|
1042
|
+
| `BrowserToolObservation` | interface | Identifies one form-submission observation and the frames it watches. |
|
|
1043
|
+
| `BrowserToolSettlement` | interface | Carries the initial command outcome and the receipt deadline. |
|
|
1044
|
+
| `BrowserWindowRow` | interface | Retains an accepted projection row and its footer eligibility. |
|
|
1045
|
+
| `BrowserTextRange` | type | Names the UTF-16 boundaries of a reference span. |
|
|
1046
|
+
| `BrowserTeardown` | class | Runs teardown steps in order while retaining the first failure, including undefined. |
|
|
1047
|
+
| `BrowserTeardownInterface` | interface | Exposes completion after every teardown step has run. |
|
|
1048
|
+
| `BrowserSnapshotTables` | interface | Names the undecoded tables supplied by a CDP snapshot response. |
|
|
1049
|
+
| `isBrowserSnapshotTables` | function | Checks the outer tables of a CDP snapshot without decoding their entries. |
|
|
1050
|
+
| `BrowserOutlineRowsInput` | interface | Supplies the nodes, location, limits, and secrets for an outline projection. |
|
|
1051
|
+
| `BrowserToolHandler` | type | Executes a tool action and returns its body and footer. |
|
|
1052
|
+
| `BrowserJourneyPagesInterface` | type | Iterates pages of journey revisions from a store. |
|
|
1053
|
+
| `BrowserReplayExecution` | class | Owns the hold, captures, and completion of one prepared replay call. |
|
|
1054
|
+
| `BrowserJourneyPages` | class | Iterates a store listing while retaining its offset between page requests. |
|
|
1055
|
+
| `BrowserNavigationScan` | class | Yields the settlement selected after each navigation step. |
|
|
1056
|
+
| `BrowserReplayExecutionInterface` | interface | Exposes the result of one prepared replay execution. |
|
|
1057
|
+
| `BROWSER_ERROR_CODES` | const | Holds the declared codes accepted by the browser error guard. |
|
|
1058
|
+
| `BROWSER_ERROR_BRAND` | const | Identifies browser errors across installed copies and module formats. |
|
|
1059
|
+
| `BROWSER_STEP_ERROR_BRAND` | const | Identifies journey step errors across installed copies and module formats. |
|
|
1060
|
+
| `isBrowserErrorContext` | function | Checks error metadata, including non-finite numbers that describe refused input values. |
|
|
1061
|
+
| `isBrowserAction` | function | Checks whether a step error carries the declared action members. |
|
|
1062
|
+
|
|
1063
|
+
The quote helper uses a passage and search result prepared by the projection pipeline.
|
|
1064
|
+
|
|
1065
|
+
```ts
|
|
1066
|
+
import type { BrowserPassage, BrowserSearch } from '@orkestrel/browser'
|
|
1067
|
+
import {
|
|
1068
|
+
renderBrowserSearchQuote,
|
|
1069
|
+
boundBrowserTail,
|
|
1070
|
+
findBrowserWrapSpace,
|
|
1071
|
+
skipBrowserWhitespace,
|
|
1072
|
+
isBrowserErrorContext,
|
|
1073
|
+
isBrowserSnapshotTables,
|
|
1074
|
+
isBrowserAction,
|
|
1075
|
+
} from '@orkestrel/browser'
|
|
1076
|
+
|
|
1077
|
+
declare const passage: BrowserPassage
|
|
1078
|
+
declare const found: BrowserSearch
|
|
1079
|
+
renderBrowserSearchQuote(passage, found, [], 400, passage.lines.length)
|
|
1080
|
+
boundBrowserTail('A long document. '.repeat(20), 80, 'read', 80)
|
|
1081
|
+
findBrowserWrapSpace('alpha beta', 0, 5, []) // 5
|
|
1082
|
+
skipBrowserWhitespace('alpha beta', 5) // 8
|
|
1083
|
+
isBrowserErrorContext({ limit: 0 }) // true
|
|
1084
|
+
isBrowserAction(undefined) // false
|
|
1085
|
+
isBrowserSnapshotTables({ strings: [], documents: [] }) // true
|
|
1086
|
+
```
|
|
1087
|
+
|
|
1024
1088
|
#### Errors
|
|
1025
1089
|
|
|
1026
|
-
| API | Kind | Summary
|
|
1027
|
-
| ------------------------ | -------- |
|
|
1028
|
-
| `BrowserError` | class | Reports a browser failure with a typed code and optional JSON context.
|
|
1029
|
-
| `BrowserStepError` | class | Reports an incomplete journey step with its action and the code `STEP`.
|
|
1030
|
-
| `BrowserErrorCode` | type | Identifies a browser refusal, lifecycle failure, or protocol failure.
|
|
1031
|
-
| `describeBrowserRefusal` | function | Describes an element refusal, adding a fresh-reference instruction for `GONE`.
|
|
1032
|
-
| `isBrowserError` | function | Checks whether
|
|
1033
|
-
| `isBrowserStepError` | function | Checks whether a
|
|
1090
|
+
| API | Kind | Summary |
|
|
1091
|
+
| ------------------------ | -------- | --------------------------------------------------------------------------------------------- |
|
|
1092
|
+
| `BrowserError` | class | Reports a browser failure with a typed code and optional JSON context. |
|
|
1093
|
+
| `BrowserStepError` | class | Reports an incomplete journey step with its action and the code `STEP`. |
|
|
1094
|
+
| `BrowserErrorCode` | type | Identifies a browser refusal, lifecycle failure, or protocol failure. |
|
|
1095
|
+
| `describeBrowserRefusal` | function | Describes an element refusal, adding a fresh-reference instruction for `GONE`. |
|
|
1096
|
+
| `isBrowserError` | function | Checks whether an error carries the browser brand and declared members across package copies. |
|
|
1097
|
+
| `isBrowserStepError` | function | Checks whether a branded browser error carries the step brand and declared action members. |
|
|
1034
1098
|
|
|
1035
1099
|
A caught `BrowserStepError` is also a `BrowserError`; check the step guard first when the action matters. Branch on `code`, and use `context.reason` for an `ELEMENT` refusal. `describeBrowserRefusal` builds its receipt. Abort signals reject with their original `signal.reason`, so a caught value need not be a browser error.
|
|
1036
1100
|
|
|
1101
|
+
The error guards require a global `Error` with a non-base prototype, its own self-valued package brand, a declared code, and its declared members. They accept subclasses and errors from another installed copy without requiring an exact `name`. They refuse look-alikes, transparent proxies, and plain branded objects.
|
|
1102
|
+
|
|
1037
1103
|
The bare code union follows. `TOOLSET_SETTLED` and `TOOLSET_RECEIPT` are **internal** control signals; callers receive their resulting receipt. `TOOLSET_PAGE` refuses a page-only operation on another view. A replay records `JOURNEY_DIALOG` as a step refusal when no interrupted action precedes a dialog step.
|
|
1038
1104
|
|
|
1039
1105
|
```ts
|
|
@@ -1318,7 +1384,6 @@ await browser.destroy()
|
|
|
1318
1384
|
| `launchBrowserProcess` | function | Launches a browser process with raw-CDP debugging flags. |
|
|
1319
1385
|
| `normalizeExecutablePath` | function | Normalizes an executable path for cross-source deduplication (case-insensitive on Windows). |
|
|
1320
1386
|
| `probePathNames` | function | Probes PATH (`which`/`where`) for every resolvable command name, in the given order. |
|
|
1321
|
-
| `probeProcess` | function | Probes whether a process has not been confirmed absent. |
|
|
1322
1387
|
| `readBrowserEndpoint` | function | Reads the CDP endpoint a launched browser announces on its standard error. |
|
|
1323
1388
|
| `readFirstLine` | function | Returns the first non-empty line of a command's output, without its surrounding whitespace. |
|
|
1324
1389
|
| `removeBrowserProfile` | function | Removes a library-owned isolated browser profile. |
|
|
@@ -1356,6 +1421,18 @@ await browser.destroy()
|
|
|
1356
1421
|
| `BROWSER_WINDOWS_ROOT_FALLBACKS` | const | Lists the fallback Windows install roots used when `PROGRAMFILES`, `PROGRAMFILES(X86)`, or `LOCALAPPDATA` is absent. |
|
|
1357
1422
|
| `BROWSER_WINDOWS_SUFFIXES` | const | Lists the Windows install-root-relative suffixes for Chrome/Edge/Chromium, joined against each candidate root (`PROGRAMFILES`, `PROGRAMFILES(X86)`, `LOCALAPPDATA`). |
|
|
1358
1423
|
|
|
1424
|
+
##### Launch and holder state
|
|
1425
|
+
|
|
1426
|
+
| API | Kind | Summary |
|
|
1427
|
+
| ------------------------------ | --------- | ---------------------------------------------------------------------------------------- |
|
|
1428
|
+
| `BrowserProcessDrainInterface` | interface | Exposes whether a process remainder disappeared before its deadline. |
|
|
1429
|
+
| `BrowserServerSlot` | interface | Pairs a pooled browser with its profile directory. |
|
|
1430
|
+
| `BrowserServerGeneration` | interface | Owns a holder's context, toolset, and download directory. |
|
|
1431
|
+
| `BrowserServerHolder` | interface | Identifies an admitted holder and its cancellation lifetime. |
|
|
1432
|
+
| `BrowserServerLease` | interface | Pairs a pool token with the generation it owns. |
|
|
1433
|
+
| `BrowserEndpoint` | class | Reads the announced CDP endpoint while continuing to drain the browser's standard error. |
|
|
1434
|
+
| `BrowserProcessDrain` | class | Waits for a process remainder whose host exposes no exit event. |
|
|
1435
|
+
|
|
1359
1436
|
##### Discover and launch
|
|
1360
1437
|
|
|
1361
1438
|
| API | Kind | Summary |
|
|
@@ -1525,6 +1602,33 @@ The browser face supplies an untrusted DOM view. Drive a same-origin child docum
|
|
|
1525
1602
|
| `BROWSER_SELECTED_ROLES` | const | Names the roles whose selection state the DOM outline reads. |
|
|
1526
1603
|
| `BROWSER_TYPED_INPUTS` | const | Names the `input` type states whose value an untrusted `fill` sets as typed text. |
|
|
1527
1604
|
|
|
1605
|
+
##### Capture state
|
|
1606
|
+
|
|
1607
|
+
| API | Kind | Summary |
|
|
1608
|
+
| ---------------------------- | --------- | ---------------------------------------------------------------------------------- |
|
|
1609
|
+
| `BrowserAncestors` | class | Traverses ancestors lazily while retaining the previously yielded node. |
|
|
1610
|
+
| `BrowserCaptureSiblings` | class | Traverses paired live and inert siblings while preserving pointers across pruning. |
|
|
1611
|
+
| `BrowserDOMOutline` | class | Captures one flat-tree subtree while retaining its text and visibility state. |
|
|
1612
|
+
| `readBrowserCaptureValue` | function | Derives rendered form values and SVG fragments for an inert capture. |
|
|
1613
|
+
| `readBrowserCaptureOmission` | function | Checks shadow-slot ancestors for capture omission without skipping style reads. |
|
|
1614
|
+
| `BrowserDOMOutlineInput` | interface | Supplies the document subtree, row sinks, and traversal operations for an outline. |
|
|
1615
|
+
| `BrowserDOMOutlineInterface` | interface | Captures the rows of one document subtree. |
|
|
1616
|
+
| `BrowserAncestorReader` | type | Reads the next ancestor, ending at the platform's null boundary. |
|
|
1617
|
+
| `BrowserCaptureSibling` | interface | Pairs the current live and inert nodes during sibling traversal. |
|
|
1618
|
+
| `BrowserCaptureCursor` | interface | Retains the sibling pointers read before a capture prunes its copy. |
|
|
1619
|
+
| `BrowserCaptureValue` | interface | Carries rendered lines, fragments, or a container retained by a capture. |
|
|
1620
|
+
| `BrowserDOMSubmission` | class | Observes whether one form submission dispatches its submit event. |
|
|
1621
|
+
|
|
1622
|
+
```ts
|
|
1623
|
+
import { readBrowserCaptureValue, readBrowserCaptureOmission } from '@orkestrel/browser/browser'
|
|
1624
|
+
|
|
1625
|
+
const live = document.documentElement
|
|
1626
|
+
const inert = document.implementation.createHTMLDocument('')
|
|
1627
|
+
const twin = inert.importNode(live, true)
|
|
1628
|
+
readBrowserCaptureValue(live, twin, window, inert, false, live.localName)
|
|
1629
|
+
readBrowserCaptureOmission(live, live.firstChild ?? live, window, live.isConnected, false)
|
|
1630
|
+
```
|
|
1631
|
+
|
|
1528
1632
|
##### DOM helpers
|
|
1529
1633
|
|
|
1530
1634
|
The following fence reads one button the page appends to its own document.
|
|
@@ -1735,7 +1839,7 @@ page.emitter.on('download', async (download) => {
|
|
|
1735
1839
|
| `click` | Clicks the element, refusing with a coded `BrowserError` when it is gone, hidden, covered, or disabled. |
|
|
1736
1840
|
| `fill` | Replaces the value of a text control with `value`, dispatching the input events that typing fires. |
|
|
1737
1841
|
| `focus` | Moves focus to the element. |
|
|
1738
|
-
| `read` | Captures the element's rendered markup with its document's URL and title as a reading whose `stale` flag tracks later navigations of that document; `
|
|
1842
|
+
| `read` | Captures the element's rendered markup with its document's URL and title as a reading whose `stale` flag tracks later navigations of that document; `BrowserContentInput` defines the rendered markup. |
|
|
1739
1843
|
| `select` | Selects the options of a `select` element whose value or label matches `values`, dispatching `input` and `change`. |
|
|
1740
1844
|
| `submit` | Submits the form the element belongs to. The CDP placement focuses the element and presses Enter through a trusted key pair, sending the release even after an abort; the DOM placement calls the form's `requestSubmit()` and reports the outcome through a `submit` listener. |
|
|
1741
1845
|
|
|
@@ -1817,7 +1921,7 @@ page.emitter.on('chooser', async (chooser) => {
|
|
|
1817
1921
|
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1818
1922
|
| `evaluate` | Evaluates an expression in the frame execution world under the result-size guard. |
|
|
1819
1923
|
| `handle` | Evaluates an expression by reference and returns a disposable remote object handle. |
|
|
1820
|
-
| `read` | Captures the document URL, title, and rendered HTML in one size-guarded evaluation in the frame's isolated world and returns them as a reading whose `stale` flag tracks later navigations. The owning page supplies the navigation counter. `
|
|
1924
|
+
| `read` | Captures the document URL, title, and rendered HTML in one size-guarded evaluation in the frame's isolated world and returns them as a reading whose `stale` flag tracks later navigations. The owning page supplies the navigation counter. `BrowserContentInput` defines the rendered markup. |
|
|
1821
1925
|
| `send` | Issues a raw CDP method in the frame's current target session, with a trailing `BrowserCallOptions` carrying a per-call `timeout` overriding the client-wide default and a `signal` that aborts the call. |
|
|
1822
1926
|
| `subscribe` | Subscribes to a CDP event in the frame's current target session. |
|
|
1823
1927
|
| `title` | Resolves the frame document title. |
|
|
@@ -1829,7 +1933,7 @@ The following example uses an instance supplied by its owner.
|
|
|
1829
1933
|
const child = await page.frame('checkout')
|
|
1830
1934
|
const title = await child?.title()
|
|
1831
1935
|
const result = await child?.evaluate('document.readyState', { timeout: 2_000 })
|
|
1832
|
-
const reading = await child?.read() //
|
|
1936
|
+
const reading = await child?.read() // BrowserContentInterface
|
|
1833
1937
|
const handle = await child?.handle('document.body')
|
|
1834
1938
|
await handle?.destroy()
|
|
1835
1939
|
const onLoad = () => log('loaded')
|
|
@@ -2067,7 +2171,7 @@ await page.network.destroy()
|
|
|
2067
2171
|
| `hover` | Moves the pointer onto the element with a trusted mouse event. |
|
|
2068
2172
|
| `press` | Focuses the element and presses `key` through a trusted key pair, sending the release even after an abort. |
|
|
2069
2173
|
| `quad` | Resolves the element's content quad in page coordinates, composed through every frame between the element and the page. |
|
|
2070
|
-
| `read` | Captures the element's rendered markup with its document's URL and title as a reading whose `stale` flag tracks later navigations of that document; `
|
|
2174
|
+
| `read` | Captures the element's rendered markup with its document's URL and title as a reading whose `stale` flag tracks later navigations of that document; `BrowserContentInput` defines the rendered markup. |
|
|
2071
2175
|
| `screenshot` | Captures the page clipped to the element's box. |
|
|
2072
2176
|
| `select` | Selects the options of a `select` element whose value or label matches `values`, dispatching `input` and `change`. |
|
|
2073
2177
|
| `submit` | Submits the form the element belongs to. The CDP placement focuses the element and presses Enter through a trusted key pair, sending the release even after an abort; the DOM placement calls the form's `requestSubmit()` and reports the outcome through a `submit` listener. |
|
|
@@ -2112,7 +2216,7 @@ A context creates and publishes its pages. The page supplies stable managers and
|
|
|
2112
2216
|
| `handle` | Evaluates an expression by reference and returns a disposable remote object handle. |
|
|
2113
2217
|
| `navigate` | Goes to a URL, waits for the requested load condition, and returns the final URL with its response correlation. |
|
|
2114
2218
|
| `pdf` | Prints the page to PDF bytes, optionally persisted through the injected writer. |
|
|
2115
|
-
| `read` | Captures the document URL, title, and rendered HTML in one size-guarded evaluation in the frame's isolated world and returns them as a reading whose `stale` flag tracks later navigations. The owning page supplies the navigation counter. `
|
|
2219
|
+
| `read` | Captures the document URL, title, and rendered HTML in one size-guarded evaluation in the frame's isolated world and returns them as a reading whose `stale` flag tracks later navigations. The owning page supplies the navigation counter. `BrowserContentInput` defines the rendered markup. |
|
|
2116
2220
|
| `reload` | Reloads the page and returns the final URL with its response correlation. |
|
|
2117
2221
|
| `screenshot` | Captures PNG or JPEG bytes, optionally full-page and persisted through an injected writer. |
|
|
2118
2222
|
| `send` | Issues a raw CDP method in the frame's current target session, with a trailing `BrowserCallOptions` carrying a per-call `timeout` overriding the client-wide default and a `signal` that aborts the call. |
|
|
@@ -2212,7 +2316,7 @@ const profile = await page.diagnostics.profiler.stop() // { start, end, nodes, s
|
|
|
2212
2316
|
await page.diagnostics.profiler.destroy()
|
|
2213
2317
|
```
|
|
2214
2318
|
|
|
2215
|
-
#### `
|
|
2319
|
+
#### `BrowserContentInterface`
|
|
2216
2320
|
|
|
2217
2321
|
| Method | Summary |
|
|
2218
2322
|
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
@@ -2231,9 +2335,9 @@ const main = reading.text({ distill: true }) // main content without navigation
|
|
|
2231
2335
|
```
|
|
2232
2336
|
|
|
2233
2337
|
```ts
|
|
2234
|
-
import {
|
|
2338
|
+
import { createBrowserContent, collectBrowserWords } from '@orkestrel/browser'
|
|
2235
2339
|
|
|
2236
|
-
const reading =
|
|
2340
|
+
const reading = createBrowserContent({
|
|
2237
2341
|
url: 'https://example.test/',
|
|
2238
2342
|
title: '',
|
|
2239
2343
|
html: '<nav>Menu</nav><main><p>Blue kettle</p></main>',
|
|
@@ -2542,7 +2646,7 @@ The following example uses an instance supplied by its owner.
|
|
|
2542
2646
|
await page.touch.tap({ x: 120, y: 240 })
|
|
2543
2647
|
```
|
|
2544
2648
|
|
|
2545
|
-
#### `
|
|
2649
|
+
#### `BrowserTraceInterface`
|
|
2546
2650
|
|
|
2547
2651
|
| Method | Summary |
|
|
2548
2652
|
| --------- | ------------------------------------------------------------------------------------------------- |
|
|
@@ -2550,12 +2654,14 @@ await page.touch.tap({ x: 120, y: 240 })
|
|
|
2550
2654
|
| `start` | Begins tracing with the given categories. Throws a `BrowserError` when a trace is already active. |
|
|
2551
2655
|
| `stop` | Ends tracing, drains the IO stream, and writes it through the page writer when a path was set. |
|
|
2552
2656
|
|
|
2657
|
+
A pending `start` reserves the trace: another `start` rejects as already active, while `stop` rejects as not active until initialization finishes. A `start` during a draining `stop` waits for the previous capture's stream cleanup before it starts collecting events.
|
|
2658
|
+
|
|
2553
2659
|
The following example uses an instance supplied by its owner.
|
|
2554
2660
|
|
|
2555
2661
|
```ts
|
|
2556
|
-
await page.diagnostics.
|
|
2557
|
-
const trace = await page.diagnostics.
|
|
2558
|
-
await page.diagnostics.
|
|
2662
|
+
await page.diagnostics.trace.start({ screenshots: true, samples: true })
|
|
2663
|
+
const trace = await page.diagnostics.trace.stop() // { bytes, path }
|
|
2664
|
+
await page.diagnostics.trace.destroy()
|
|
2559
2665
|
```
|
|
2560
2666
|
|
|
2561
2667
|
#### `BrowserTransitionInterface`
|
|
@@ -2578,7 +2684,7 @@ const joined = starting.pending // the in-flight promise, or undefined
|
|
|
2578
2684
|
|
|
2579
2685
|
| Method | Summary |
|
|
2580
2686
|
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
2581
|
-
| `read` | Captures the document URL, title, and rendered markup as a reading whose `stale` flag tracks later navigations; `
|
|
2687
|
+
| `read` | Captures the document URL, title, and rendered markup as a reading whose `stale` flag tracks later navigations; `BrowserContentInput` defines the rendered markup. |
|
|
2582
2688
|
| `screenshot` | Captures PNG or JPEG bytes of the view. |
|
|
2583
2689
|
| `title` | Resolves the document title. |
|
|
2584
2690
|
| `wait` | Resolves when the main document body’s `innerText` contains `text`, or lacks it with `absent`; rejects with a `BrowserError` coded `TIMEOUT` at the deadline, and with `signal.reason` on abort. |
|
|
@@ -2739,7 +2845,7 @@ This interface inherits the element operations without adding a method. DOM acti
|
|
|
2739
2845
|
| `click` | Clicks the element, refusing with a coded `BrowserError` when it is gone, hidden, covered, or disabled. |
|
|
2740
2846
|
| `fill` | Replaces the value of a text control with `value`, dispatching the input events that typing fires. |
|
|
2741
2847
|
| `focus` | Moves focus to the element. |
|
|
2742
|
-
| `read` | Captures the element's rendered markup with its document's URL and title as a reading whose `stale` flag tracks later navigations of that document; `
|
|
2848
|
+
| `read` | Captures the element's rendered markup with its document's URL and title as a reading whose `stale` flag tracks later navigations of that document; `BrowserContentInput` defines the rendered markup. |
|
|
2743
2849
|
| `select` | Selects the options of a `select` element whose value or label matches `values`, dispatching `input` and `change`. |
|
|
2744
2850
|
| `submit` | Submits the form the element belongs to. The CDP placement focuses the element and presses Enter through a trusted key pair, sending the release even after an abort; the DOM placement calls the form's `requestSubmit()` and reports the outcome through a `submit` listener. |
|
|
2745
2851
|
|
|
@@ -2750,7 +2856,7 @@ The owner supplies a same-origin document from a surviving realm. `trusted` is `
|
|
|
2750
2856
|
| Method | Summary |
|
|
2751
2857
|
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
2752
2858
|
| `destroy` | Releases the navigation listeners and every element reference. |
|
|
2753
|
-
| `read` | Captures the document URL, title, and rendered markup as a reading whose `stale` flag tracks later navigations; `
|
|
2859
|
+
| `read` | Captures the document URL, title, and rendered markup as a reading whose `stale` flag tracks later navigations; `BrowserContentInput` defines the rendered markup. |
|
|
2754
2860
|
| `screenshot` | Captures PNG or JPEG bytes of the view. |
|
|
2755
2861
|
| `title` | Resolves the document title. |
|
|
2756
2862
|
| `wait` | Resolves when the main document body’s `innerText` contains `text`, or lacks it with `absent`; rejects with a `BrowserError` coded `TIMEOUT` at the deadline, and with `signal.reason` on abort. |
|
|
@@ -2767,6 +2873,19 @@ const reading = await view.read()
|
|
|
2767
2873
|
view.destroy()
|
|
2768
2874
|
```
|
|
2769
2875
|
|
|
2876
|
+
#### `BrowserDOMOutlineInterface`
|
|
2877
|
+
|
|
2878
|
+
| Method | Summary |
|
|
2879
|
+
| --------- | ------------------------------------------------------------------ |
|
|
2880
|
+
| `capture` | Appends the captured rows through the supplied outline operations. |
|
|
2881
|
+
|
|
2882
|
+
```ts
|
|
2883
|
+
import type { BrowserDOMOutlineInterface } from '@orkestrel/browser/browser'
|
|
2884
|
+
|
|
2885
|
+
declare const outline: BrowserDOMOutlineInterface
|
|
2886
|
+
outline.capture()
|
|
2887
|
+
```
|
|
2888
|
+
|
|
2770
2889
|
#### `BrowserDOMWaitInterface`
|
|
2771
2890
|
|
|
2772
2891
|
| Method | Summary |
|
|
@@ -2857,7 +2976,7 @@ In the following table, `URL` is an address, `REF` an element reference, `ROLE`
|
|
|
2857
2976
|
|
|
2858
2977
|
| Situation | Text |
|
|
2859
2978
|
| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
2860
|
-
| A heading row, an element row, and a text row | `# NAME`, `ROLE "NAME" [ref=REF]` with `value="…"`, `pressed=true
|
|
2979
|
+
| A heading row, an element row, and a text row | `# NAME`, `ROLE "NAME" [ref=REF]` with `value="…"`, `pressed=true\ | false\ | mixed`, `expanded=true\ | false`, `selected=true\ | false`, `[checked]`, `[disabled]`, or `[tool=NAME]` after it, in that order, and the text itself |
|
|
2861
2980
|
| A page header | `page "TITLE" URL (TOTAL lines)` |
|
|
2862
2981
|
| A page continuation | `[lines START–END of TOTAL; BELOW below; call read with from NEXT for more]` |
|
|
2863
2982
|
| A whole page | `[lines 1–7 of 7; the whole page]` |
|
|
@@ -3049,7 +3168,7 @@ The following table names each adapter, the contract on each side, and the proof
|
|
|
3049
3168
|
|
|
3050
3169
|
## Declared conformance gaps
|
|
3051
3170
|
|
|
3052
|
-
`npm run test:conformance` runs [`tests/conformance.test.ts`](../tests/conformance.test.ts) in Node with the browser disabled, and `npm test` includes it. It starts no browser: it reads three vendored mirrors through [`tests/
|
|
3171
|
+
`npm run test:conformance` runs [`tests/conformance.test.ts`](../tests/conformance.test.ts) in Node with the browser disabled, and `npm test` includes it. It starts no browser: it reads three vendored mirrors through [`tests/setupServer.ts`](../tests/setupServer.ts), whose reader checks each file's raw-byte SHA-256 against a pinned constant at module load, so a changed byte throws before a row runs. Each row compares one coordinate of an authority with what this package ships and is ruled implement, retain, or exclude; every exclusion names its closer.
|
|
3053
3172
|
|
|
3054
3173
|
The following table records each mirror's upstream, revision, and pin.
|
|
3055
3174
|
|
|
@@ -3061,7 +3180,7 @@ The following table records each mirror's upstream, revision, and pin.
|
|
|
3061
3180
|
|
|
3062
3181
|
The whole protocol file the domain was cut from is pinned without being vendored, at `672d8481c92832907211e85488e216cd5b1a922fde273faff72f7f6cf765899e`. The web-platform-tests `webmcp/` tree at revision `e6ba3d7abea7` is recorded as a listing, [`wpt-webmcp-e6ba3d7abea7.txt`](../tests/mirrors/wpt-webmcp-e6ba3d7abea7.txt). Refresh the mirrors on each version bump of this package and whenever `@orkestrel/mcp`'s bridge advances its reading date: fetch the three files at their upstream heads, record each commit, cut the domain again by byte range, pin the digests again, and rule every row that reddens as implement, retain, or exclude.
|
|
3063
3182
|
|
|
3064
|
-
**The web-platform-tests cases do not run.** The listing at `e6ba3d7abea7` holds 88 entries, 55 under `webmcp/imperative/` and 28 under `webmcp/declarative/`. Those cases drive a browser's `document.modelContext`, and none of them runs against this package's double, [`tests/
|
|
3183
|
+
**The web-platform-tests cases do not run.** The listing at `e6ba3d7abea7` holds 88 entries, 55 under `webmcp/imperative/` and 28 under `webmcp/declarative/`. Those cases drive a browser's `document.modelContext`, and none of them runs against this package's double, [`tests/setup.ts`](../tests/setup.ts). **What it costs:** the double is checked member by member against webref's IDL, and its behavior is checked only by this package's own composition cases. **Closer:** a testharness runner under the Playwright provider that runs those cases against the double.
|
|
3065
3184
|
|
|
3066
3185
|
**The domain's `Tool.stackTrace` is not read.** Every other property of the mirror's `Tool`, `Annotation`, and `RemovedTool` types is one name a parser reads. **What it costs:** an agent never sees where in the page a tool was registered. **Closer:** a developer diagnostics consumer; `stackTrace` is a developer datum, excluded from the agent surface.
|
|
3067
3186
|
|
|
@@ -3091,7 +3210,7 @@ These invariants hold across the four faces (`src/core`, `src/browser`, `src/ser
|
|
|
3091
3210
|
4. **Captured bytes never touch a filesystem in core.** A page accepts an optional `BrowserWriterInterface`, injected through `BrowserContext`, and calls `write(path, bytes)` only when a screenshot, PDF, trace, or HAR request carries a `path`; the server supplies `createFileBrowserWriter` through `Browser`. A replay takes each capture's bytes from the view without a `path` and hands them to its run store's `capture`, which writes them only into the run directory its `create` created and creates no directory; the memory run store keeps no bytes. [`tests/src/server/writers/FileBrowserWriter.test.ts`](../tests/src/server/writers/FileBrowserWriter.test.ts) pins the writer, the capture cases of [`tests/src/core/BrowserReplay.test.ts`](../tests/src/core/BrowserReplay.test.ts) pin that no path reaches the page, and [`tests/src/server/stores/FileBrowserRunStore.test.ts`](../tests/src/server/stores/FileBrowserRunStore.test.ts) pins the capture's confinement.
|
|
3092
3211
|
5. **Browser options name their owner.** `browsers.engine` selects discovery; there is no top-level engine option. `BrowserMCPServerOptions.browser` carries `headless`, `executable`, and `viewport`; `pool` carries `size`, `contexts`, and `launch`; `journeys` carries `readonly`. The binary maps its environment into those groups. [Browser](../tests/src/server/Browser.test.ts), [MCP server](../tests/src/server/BrowserMCPServer.test.ts), and [binary](../tests/src/bin/main.test.ts) prove the mappings.
|
|
3093
3212
|
6. **Lifecycle events are observable, never polled.** `BrowserInterface.emitter` fires `idle`, `discover`, `connect`, `disconnect`, `launch`, `page`, `context`, `error`, and `destroy`; `CDPClientInterface.emitter` fires `connect`, `close`, `drop`, and `error`; a recorder, `page.recorder` included, fires `start`, `step`, `stop`, and `clear`, and a replay fires `step`. A page fires `navigate` with `[url, same]` for both a cross-document and a same-document navigation, `session` when an out-of-process frame's session attaches, `popup` for each page it opens, and `dialog`, `close`, and the network and worker events; a context fires `page` for each page it publishes, popups included. A page a context constructs holds its target on the client's connection, and the first such page on a connection enables `Target.setDiscoverTargets` for it; a second live page for a held target is refused with `TARGET_HELD`, and a `create()` that meets a page another path published for its target joins that page, or rejects with `CLOSED` when that page closed. A discovered popup is published one time, after its opener, through the opener's `popup`, the context's `page`, and `pages()`. Limit: when the page holding a popup's target fails its setup, discovery publishes nothing, and a later `sync()` adds the target without a `popup` from its opener. Limit: when `Target.setDiscoverTargets` fails, or the connection ends and another opens, the next page a context constructs on that connection sends it again, and nothing sends it before then; `sync()` is the recovery for a popup that discovery missed meanwhile. The registry fires `change`, `invoke`, and `respond`, and the toolset `adopt`, `skip`, `select`, `action`, `hold`, and `release`. A journey store never polls: a held `journey.lock` refuses at once with `STORE_LOCKED`, and the tool tells the model to call again. Every wait parks on a protocol event, a DOM observer, or an abort signal, and a `setTimeout` survives only as a deadline; the one liveness probe with no event source is the bounded drain of a terminated process group, at `BROWSER_DRAIN_INTERVAL_MS` in `src/server`. An external disconnect emits a coded `error` before `disconnect`; transport loss with the process alive is resumable, and a process exit is terminal. [`tests/src/core/BrowserPage.test.ts`](../tests/src/core/BrowserPage.test.ts), [`tests/src/core/recorders/BrowserCodegen.test.ts`](../tests/src/core/recorders/BrowserCodegen.test.ts), [`tests/src/core/recorders/BrowserRecorder.test.ts`](../tests/src/core/recorders/BrowserRecorder.test.ts), and [`tests/src/core/BrowserToolset.test.ts`](../tests/src/core/BrowserToolset.test.ts) pin the page, recorder, and toolset events, [`tests/src/server/stores/FileBrowserJourneyStore.test.ts`](../tests/src/server/stores/FileBrowserJourneyStore.test.ts) pins the lock refused at once, and [`tests/src/core/BrowserContext.test.ts`](../tests/src/core/BrowserContext.test.ts) pins target ownership, the joined creation, and popup publication.
|
|
3094
|
-
7. **Two error classes cover the runtime.** `BrowserError` carries a bare `BrowserErrorCode` and optional JSON context; `BrowserStepError` adds its typed action and the code `STEP`. Guards narrow both. `ARGUMENT`, `CLOSED`, `PROTOCOL`, and `NAVIGATION` distinguish invalid input, closed state, malformed protocol data, and navigation failure. Remote CDP failures use `REMOTE`, disconnected requests use `DISCONNECTED`, and deadlines use `TIMEOUT`. The navigation-load, clock, tracing, and registry deadlines name their operation in context. Shared storage failures use `STORE_*` codes for both journey and run stores. [Errors](../tests/src/core/errors.test.ts), [CDP client](../tests/src/core/CDPClient.test.ts), [page navigation](../tests/src/core/BrowserPage.test.ts), [clock](../tests/src/core/BrowserClock.test.ts), [tracing](../tests/src/core/
|
|
3213
|
+
7. **Two error classes cover the runtime.** `BrowserError` carries a bare `BrowserErrorCode` and optional JSON context; `BrowserStepError` adds its typed action and the code `STEP`. Guards narrow both. `ARGUMENT`, `CLOSED`, `PROTOCOL`, and `NAVIGATION` distinguish invalid input, closed state, malformed protocol data, and navigation failure. Remote CDP failures use `REMOTE`, disconnected requests use `DISCONNECTED`, and deadlines use `TIMEOUT`. The navigation-load, clock, tracing, and registry deadlines name their operation in context. Shared storage failures use `STORE_*` codes for both journey and run stores. [Errors](../tests/src/core/errors.test.ts), [CDP client](../tests/src/core/CDPClient.test.ts), [page navigation](../tests/src/core/BrowserPage.test.ts), [clock](../tests/src/core/BrowserClock.test.ts), [tracing](../tests/src/core/BrowserTrace.test.ts), and [registry](../tests/src/core/BrowserRegistry.test.ts) prove these contracts.
|
|
3095
3214
|
8. **Oversized results fail clean.** `evaluate()` and `read()` wrap their in-page result with `compileGuardedEvaluateExpression(expression, BROWSER_RESULT_LIMIT)`, which throws the `BROWSER_RESULT_LIMIT_SENTINEL_PREFIX` sentinel before an oversized result could overflow the transport frame; the frame recognizes it through `BROWSER_RESULT_LIMIT_PATTERN` and rejects with `BrowserError` with code `RESULT_LIMIT`, and the connection and the browser process are unaffected. [`tests/service/browser.test.ts`](../tests/service/browser.test.ts) pins both against a real browser.
|
|
3096
3215
|
9. **The page recorder records semantic steps, and a journey compiles to a module that runs as a replay does.** `page.recorder` records each gesture by role and exact accessible name, collapses consecutive edits on one field while the edit is open, and never across a submission, a focus departure, a navigation, or `stop`. `compileBrowserJourney` emits one `follow` call per step on a toolset the module constructs, as `'javascript'` or `'typescript'`, and throws at a gap step. [`tests/src/core/recorders/BrowserCodegen.test.ts`](../tests/src/core/recorders/BrowserCodegen.test.ts) pins the recorder, [`tests/service/codegen.test.ts`](../tests/service/codegen.test.ts) pins its gestures on Chromium against the fixture's own event log, [`tests/src/core/compilers.test.ts`](../tests/src/core/compilers.test.ts) pins the module byte for byte, and the `compiled module equality` block of [`tests/service/journey.test.ts`](../tests/service/journey.test.ts) runs each generated module and its replay to one page outcome with the same receipts.
|
|
3097
3216
|
10. **Doc ↔ source method bijection.** Each `## Methods` table lists exactly the call-signature members of its interface, inherited members included, and each implementing class named for its interface exposes no public method its table omits: the internal page recorder and `BrowserRecorder`, `BrowserReplay`, `BrowserHold`, `BrowserJourneyToolset`, `BrowserMCPServer`, the two memory stores, and the two file stores pair with their interfaces as every earlier class does. The remaining exports are functions, constants, and data contracts. [`tests/guides.test.ts`](../tests/guides.test.ts) pins it.
|
|
@@ -3100,7 +3219,7 @@ These invariants hold across the four faces (`src/core`, `src/browser`, `src/ser
|
|
|
3100
3219
|
13. **A launch owns the process that serves its endpoint, through the inherited pipe.** Chrome and Chromium serve the endpoint from the process they spawn. A launcher such as Microsoft Edge on Windows instead re-executes the browser with the same `--remote-debugging-port` and exits 0 before the endpoint answers, and the process it spawned inherits its standard error, so `connect()` treats that clean exit as a hand-off: it keeps reading the same pipe on the same `timeout` budget until the `DevTools listening on` line arrives, then reads the `browser` entry of CDP `SystemInfo.getProcessInfo` and owns the process named there. A nonzero exit or a signal rejects at once with a `BrowserError` naming the exit; a pipe that closes without the line rejects with the readiness failure; an endpoint that names no browser process rejects after a best-effort `Browser.close`. The Windows Edge launch reading is recorded in limit 26. The launcher hand-off cases in [`tests/src/server/Browser.test.ts`](../tests/src/server/Browser.test.ts) pin the rest.
|
|
3101
3220
|
14. **A snapshot is serializable data plus navigation.** `BrowserSnapshot` holds exactly `documents` and `styles`, so `JSON.stringify(snapshot)` yields `{ documents, styles }` and `createBrowserSnapshot(parsed)` navigates it again; every method takes and returns bare `BrowserNode` values, and containment is derived from `ancestors`. [`tests/src/core/BrowserSnapshot.test.ts`](../tests/src/core/BrowserSnapshot.test.ts) pins it.
|
|
3102
3221
|
15. **A reference names one element for as long as that element exists.** A reference is `e` followed by a positive integer. On CDP every page's element manager mints from one counter its browser context owns and binds the reference to `SESSION:BACKEND`, because backend node ids are per renderer; in the DOM placement the view owns the counter and binds a `WeakRef`. The allocator never reuses a number within the context. Across consecutive documents in one tab, a link keeps its reference when its role (`link`), accessible name, and resolved `href` match exactly one link in each document. Duplicate identities in either document, changed names or destinations, and every non-link receive fresh references. Buttons never carry. A child frame's navigation or detachment drops that frame's bindings. The toolset retains each shown reference's last role and name for missing-reference refusals until teardown. A never-shown reference keeps the unknown-reference refusal. A successful action still resets the accepted set; carried references are accepted again because its result lists them. `parseBrowserReference` accepts `e12`, `E12`, `[e12]`, `ref=e12`, and `[ref=e12]`. A journey's `reference` is evidence a developer reads, never a lookup: replay resolves each target by role and exact name. [`tests/src/core/elements/BrowserElementManager.test.ts`](../tests/src/core/elements/BrowserElementManager.test.ts), [`tests/src/core/parsers.test.ts`](../tests/src/core/parsers.test.ts), and [`tests/src/browser/elements/BrowserDOMElementManager.test.ts`](../tests/src/browser/elements/BrowserDOMElementManager.test.ts) pin it, and the `journey semantic replay` block of [`tests/service/journey.test.ts`](../tests/service/journey.test.ts) pins that a changed page resolves by name and that neither a stored reference nor a matching CSS selector resolves a target.
|
|
3103
|
-
16. **A reading is captured one time and sliced from one projection.** `frame.read()` issues one size-guarded evaluation in the isolated world; `markdown` and `text` each project the capture one time per mode and cut every slice from it, ending a bounded slice after the last line break in its window when one lies past `offset`. Truncation is derived as `offset + text.length < total`, and `stale` is derived from the navigation epoch, never stored. [`tests/src/core/
|
|
3222
|
+
16. **A reading is captured one time and sliced from one projection.** `frame.read()` issues one size-guarded evaluation in the isolated world; `markdown` and `text` each project the capture one time per mode and cut every slice from it, ending a bounded slice after the last line break in its window when one lies past `offset`. Truncation is derived as `offset + text.length < total`, and `stale` is derived from the navigation epoch, never stored. [`tests/src/core/BrowserContent.test.ts`](../tests/src/core/BrowserContent.test.ts) and [`tests/src/core/BrowserPage.test.ts`](../tests/src/core/BrowserPage.test.ts) pin it.
|
|
3104
3223
|
17. **The registry mirrors the domain and settles every invocation.** `start()` subscribes before it enables, because enabling reports every registered tool; a `-32601` answer unsubscribes and resolves `false`, and any other failure rethrows. `execute` never passes the signal to `invokeTool`, so the invocation id always arrives; an abort or a deadline sends `WebMCP.cancelInvocation` with that id and rejects without waiting for `Canceled`; a navigation or detachment of the tool's frame and `destroy` reject; every terminal status resolves a `BrowserInvocationResult`. A `toolResponded` with an unknown id is held only while an `invokeTool` reply is pending. [`tests/src/core/BrowserRegistry.test.ts`](../tests/src/core/BrowserRegistry.test.ts) pins it.
|
|
3105
3224
|
18. **Actions run one at a time.** The toolset runs actions in first-in, first-out order, and an action holds the queue until its receipt is produced; an action whose signal aborts while queued sends nothing. After a `mousePressed` or `keyDown` is sent, the matching release is sent without the signal, so an abort never leaves a button or key down, and the next action waits for a pending release. Every complete browser or journey tool result and error message fits the smaller of `limit` and `BROWSER_TOOL_LIMIT`, including its footer. A `click`, `type`, or `press` on a page opens `page.navigation.record(frame)` before its first input and settles its receipt through that record, so the receipt's view follows the navigation the record selects, and the toolset holds no frame, session, or loader state of its own. While a replay holds the toolset, an action admitted after the hold that does not carry the hold's token is refused with `TOOLSET_BUSY` rather than queued, and the actions admitted before the hold complete first. The queue, bounds, destroy, hold, and navigation settlement cases in [`tests/src/core/BrowserToolset.test.ts`](../tests/src/core/BrowserToolset.test.ts), the selection cases in [`tests/src/core/BrowserNavigationRecord.test.ts`](../tests/src/core/BrowserNavigationRecord.test.ts), and the `claim 6` block of [`tests/service/journey.test.ts`](../tests/service/journey.test.ts) pin it.
|
|
3106
3225
|
19. **A dialog interrupts every tool and stages `dialog`.** Every pending step of every tool is raced against the page's `dialog` event, so a tool returns a receipt naming the dialog while the blocked command waits; the `dialog` tool is advertised while the dialog is open and bypasses the queue, and every other tool refuses with a message naming the open dialog and ending `call dialog.` A replay admits a `dialog` step only after an `interrupted` action, the continuation the toolset stages, and under a hold a `dialog` from another caller is refused with `TOOLSET_BUSY`. The dialog cases in [`tests/src/core/BrowserToolset.test.ts`](../tests/src/core/BrowserToolset.test.ts) and [`tests/src/core/BrowserReplay.test.ts`](../tests/src/core/BrowserReplay.test.ts), the `confirm()` and `beforeunload` dialog cases in [`tests/service/toolset.test.ts`](../tests/service/toolset.test.ts), and the `claim 6` block of [`tests/service/journey.test.ts`](../tests/service/journey.test.ts) pin it.
|
|
@@ -3637,7 +3756,7 @@ if (driven !== null && bridge !== undefined) {
|
|
|
3637
3756
|
|
|
3638
3757
|
The suites run as Vitest projects, each with a fixed scope:
|
|
3639
3758
|
|
|
3640
|
-
- `src:core` runs [`tests/src/core`](../tests/src/core) in Node against real entities over an in-memory CDP transport whose replies each test scripts; `src:server` runs [`tests/src/server`](../tests/src/server) in Node against spawned stand-in processes and in-process CDP servers; `src:browser` runs [`tests/src/browser`](../tests/src/browser) in Playwright's Chromium, with a browser launched by this package's own `createBrowser` for the socket transport. `npm run test:src` runs all three. `src:bin` runs [`tests/src/bin`](../tests/src/bin) in Node against the built `dist/bin/main.js`, through `npm run test:src:bin` after `npm run build`.
|
|
3759
|
+
- `src:core` runs [`tests/src/core`](../tests/src/core) in Node against real entities over an in-memory CDP transport whose replies each test scripts; `src:server` runs [`tests/src/server`](../tests/src/server) in Node against spawned stand-in processes and in-process CDP servers; `src:browser` runs [`tests/src/browser`](../tests/src/browser) in Playwright's Chromium, with a browser launched by this package's own `createBrowser` for the socket transport. `npm run test:src` runs all three. `src:bin` runs [`tests/src/bin`](../tests/src/bin) in Node against the built `dist/bin/main.js`, through `npm run test:src:bin` after `npm run build`. Before any case spawns, `requireBrowserBuild` refuses an absent entry or an entry older than any file under `src/`, with a message naming `npm run build`.
|
|
3641
3760
|
- `guides` runs [`tests/guides.test.ts`](../tests/guides.test.ts) in Node through `npm run test:guides`; `conformance` runs [`tests/conformance.test.ts`](../tests/conformance.test.ts) in Node against the pinned mirrors; `policy`, `config`, `setup`, and `setup:browser` prove the workspace rules, the configuration, and the shared test infrastructure. `npm test` runs every project named so far.
|
|
3642
3761
|
- `service` runs [`tests/service`](../tests/service) against a real Chromium-family browser on the host and is outside `npm test`; `distribution` packs and installs the package and runs from `prepublishOnly`.
|
|
3643
3762
|
|
|
@@ -3648,11 +3767,10 @@ The following list names each test file and what it proves.
|
|
|
3648
3767
|
- [`tests/policy.test.ts`](../tests/policy.test.ts): the workspace rules, including the banned-term sweep over authored Markdown.
|
|
3649
3768
|
- [`tests/config.test.ts`](../tests/config.test.ts): the aliases, the registered projects and their scopes, the target wrappers, and the scripts that gate each proof.
|
|
3650
3769
|
- [`tests/distribution.test.ts`](../tests/distribution.test.ts): the packed archive a consumer installs, its three faces, and their declarations under every module resolution; the `generated journey module` case, which type-checks the modules `compileBrowserJourney` emits against the installed declarations and imports them under Node; and the `packed browse binary` case, which spawns the installed binary through `@orkestrel/mcp`'s stdio client, lists the vocabulary with Chromium absent, then records, saves, lists, edits, and replays a journey.
|
|
3651
|
-
- [`tests/setup.test.ts`](../tests/setup.test.ts): the scripted CDP fixtures, the element and registry replies, the popup discovery fixtures, the journey module instrument, and the compiled-timer instrument the core suites use
|
|
3770
|
+
- [`tests/setup.test.ts`](../tests/setup.test.ts): the scripted CDP fixtures, the element and registry replies, the popup discovery fixtures, the journey module instrument, and the compiled-timer instrument the core suites use. The shared journey and run case tables live in `tests/setup.ts`; the mirrored store tests register the cases and assert their observations.
|
|
3652
3771
|
- [`tests/setupBrowser.test.ts`](../tests/setupBrowser.test.ts): the same-origin probe documents the in-page suites drive.
|
|
3653
|
-
- [`tests/setupConformance.test.ts`](../tests/setupConformance.test.ts): the mirror reader's digest refusal on a changed byte and the row readers the conformance project uses.
|
|
3654
3772
|
- [`tests/setupGlobal.test.ts`](../tests/setupGlobal.test.ts): the global setup that serves fixtures and launches the browser the in-page suites reach.
|
|
3655
|
-
- [`tests/setupServer.test.ts`](../tests/setupServer.test.ts): the ports, processes, scratch directories, CDP test server, fixture pages, the journey module stage, and the browse launch double and stdio pair the server and service suites share
|
|
3773
|
+
- [`tests/setupServer.test.ts`](../tests/setupServer.test.ts): the mirror reader's digest refusal and conformance row readers, the ports, processes, scratch directories, CDP test server, fixture pages, the journey module stage, the built-entry freshness refusal, and the browse launch double and stdio pair the server and service suites share. The filesystem case table lives in `tests/setupServer.ts`; the mirrored file-store test registers its cases and asserts their observations, including competing processes over one directory.
|
|
3656
3774
|
- [`tests/setupService.test.ts`](../tests/setupService.test.ts): the service project's browser flags, engine selection, and registry reading.
|
|
3657
3775
|
- [`tests/service/browser.test.ts`](../tests/service/browser.test.ts): a real browser's launch, navigation, elements, frames, routes, snapshots, PDF, result limits, reattachment, transport loss, and shutdown; the out-of-process frame click, occlusion, hit-test, stale-reference, reading, and wait proofs; and the `WebMCP` domain reading and its live case.
|
|
3658
3776
|
|
|
@@ -3667,7 +3785,7 @@ The following list names each test file and what it proves.
|
|
|
3667
3785
|
- [`tests/src/core/BrowserPage.test.ts`](../tests/src/core/BrowserPage.test.ts): navigation, both navigation events, the navigation steps and their ownership rule, out-of-process frame sessions attached paused and resumed after their enablement, DOM readiness, the page input stream, text waits, popups, and the popup records.
|
|
3668
3786
|
- [`tests/src/core/BrowserFrame.test.ts`](../tests/src/core/BrowserFrame.test.ts): evaluation, readings, handles, sends with timeouts and signals, and the result-size guard of one frame.
|
|
3669
3787
|
- [`tests/src/core/BrowserTransition.test.ts`](../tests/src/core/BrowserTransition.test.ts): the shared in-flight transition every joining caller awaits.
|
|
3670
|
-
- [`tests/src/core/
|
|
3788
|
+
- [`tests/src/core/BrowserContent.test.ts`](../tests/src/core/BrowserContent.test.ts): distilled and whole Markdown and text, line-break slicing with a constant total, and derived staleness.
|
|
3671
3789
|
- [`tests/src/core/BrowserRegistry.test.ts`](../tests/src/core/BrowserRegistry.test.ts): detection, the mirror, invocation settlement, cancellation, adoption, and destroy over the `WebMCP` domain.
|
|
3672
3790
|
- [`tests/src/core/BrowserToolset.test.ts`](../tests/src/core/BrowserToolset.test.ts): the vocabulary, reserved names, dialogs, the action queue, the submit observers and the navigation settlement of each action, views and tabs, page-tool adoption, bounds, destroy, the trust marker, `execute` and its actions, the hold, the secret receipt, the popup a click settles on, the `tabs()` listing, `follow` and its target and tab resolution, and the construction under `journeys`.
|
|
3673
3791
|
- [`tests/src/core/elements/BrowserPageElement.test.ts`](../tests/src/core/elements/BrowserPageElement.test.ts): the ordered trusted click, its refusals, key and pointer releases after an abort, and the remaining element actions.
|
|
@@ -3688,7 +3806,7 @@ The following list names each test file and what it proves.
|
|
|
3688
3806
|
- [`tests/src/core/BrowserClock.test.ts`](../tests/src/core/BrowserClock.test.ts): the virtual clock.
|
|
3689
3807
|
- [`tests/src/core/BrowserCoverage.test.ts`](../tests/src/core/BrowserCoverage.test.ts): JavaScript and CSS coverage.
|
|
3690
3808
|
- [`tests/src/core/BrowserProfiler.test.ts`](../tests/src/core/BrowserProfiler.test.ts): the sampled CPU profile.
|
|
3691
|
-
- [`tests/src/core/
|
|
3809
|
+
- [`tests/src/core/BrowserTrace.test.ts`](../tests/src/core/BrowserTrace.test.ts): a trace streamed back through the IO domain.
|
|
3692
3810
|
- [`tests/src/core/BrowserPerformance.test.ts`](../tests/src/core/BrowserPerformance.test.ts): Performance-domain metrics.
|
|
3693
3811
|
- [`tests/src/core/BrowserDiagnostics.test.ts`](../tests/src/core/BrowserDiagnostics.test.ts): the diagnostics teardown, which discards a failure from an already-stopped capability.
|
|
3694
3812
|
- [`tests/src/core/BrowserCookieManager.test.ts`](../tests/src/core/BrowserCookieManager.test.ts): context-scoped cookies.
|
|
@@ -124,7 +124,7 @@ These invariants hold across `src/core` ↔ `budget.md`:
|
|
|
124
124
|
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
125
|
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
126
|
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.error')`, 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
|
|
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.error')`, 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
128
|
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
129
|
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
130
|
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.
|
|
@@ -85,6 +85,8 @@ From [`errors.ts`](../src/core/errors.ts). The executable maps a `USAGE` conditi
|
|
|
85
85
|
| `CaptureError` | class | Reports one capture failure under a stable condition axis. |
|
|
86
86
|
| `isCaptureError` | function | Checks whether an unknown value is a capture error. |
|
|
87
87
|
|
|
88
|
+
The error guard accepts branded subclasses and errors from another installed copy. Its context may be absent, an object, or a callable object, including a class instance. It requires an own brand whose value is the tested error itself, so it refuses a transparent proxy and a plain branded object. It does not require an exact error name.
|
|
89
|
+
|
|
88
90
|
### Validators
|
|
89
91
|
|
|
90
92
|
Total guards from [`validators.ts`](../src/core/validators.ts). Each returns `false` for a value that throws on read, a cycle, or a non-record, and never throws.
|
|
@@ -662,6 +664,8 @@ const exit = await registrar.execute() // 0 when the registry was published
|
|
|
662
664
|
|
|
663
665
|
**Flags.** `--variant` repeats and names the producing variants to refresh; without it every variant the wrapper declares is refreshed. `--config` replaces the wrapper. `--mode` is forwarded to the wrapper's Vitest process as `--mode <name>` and recorded in the request, so a wrapper that selects another registry by mode is refreshed by naming it. The command takes no selector, and every flag takes one value.
|
|
664
666
|
|
|
667
|
+
**Inherited evidence.** Before any stage, the command reads an existing manifest and lookup journal and checks their schemas. An unreadable or unsupported document refuses the refresh and names the file to inspect and repair before retrying. Publication still authenticates inherited evidence through the integrity engine.
|
|
668
|
+
|
|
665
669
|
**Stages.** The stage for a variant is named `registry-<variant>`, so each variant's records sit under `<directory>/runs/<id>/registry-<variant>/`. The command takes the project's declared input population and its content hashes before the child starts and again after, and refuses when they differ. It then reads the reporter and the final record, requires the record to carry the stage's own request, to fall between the start of the refresh and the end of the reporter, to agree with every collected declaration, and to be complete, and builds one receipt from them: the variant, the record's time, the reporter's path and digest, the input hashes, and the record's declarations and registry.
|
|
666
670
|
|
|
667
671
|
**Publication.** `buildCaptureRegistry` imports the receipts only after each exit is zero and each reporter digest still equals its receipt. The registry is written to a candidate beside `registry.json`, read back through the integrity engine pointed at the candidate, and only then renamed over the target, so a registry the engine would refuse never replaces a good one and the old bytes survive a failed or interrupted refresh. The command prints one `REGISTRY` line of JSON: the file, the digest, the variants in the registry, the variants this run refreshed, and the entry count.
|