@orkestrel/scaffold 0.0.137 → 0.0.139
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-parallel/scripts/lane.js +489 -23
- package/dist/bin/main.js +6 -6
- package/dist/host/agents/skills/orkestrel-journey/SKILL.md +33 -27
- package/dist/host/agents/skills/orkestrel-journey/references/captures.md +37 -16
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +628 -41
- package/dist/host/agents/skills/orkestrel-polish/references/capture-harness.md +5 -0
- package/dist/host/claude/agents/orkestrel.md +54 -54
- package/dist/host/claude/rules/typescript.md +4 -1
- package/dist/host/claude/rules/workspace.md +6 -4
- package/dist/host/guides/capture.md +442 -313
- package/dist/host/guides/contract.md +314 -210
- package/dist/host/guides/middleware.md +489 -259
- package/dist/host/guides/process.md +139 -53
- package/dist/host/guides/router.md +282 -165
- package/dist/host/guides/scaffold.md +35 -23
- package/dist/host/guides/server.md +417 -181
- package/dist/host/guides/test.md +353 -232
- package/dist/host/manifest.json +18 -18
- package/dist/host/scripts/browsers.sh +0 -0
- package/dist/host/scripts/codex.sh +0 -0
- package/dist/host/scripts/cursor.sh +0 -0
- package/dist/host/scripts/deps.sh +0 -0
- package/dist/host/scripts/npm.sh +0 -0
- package/dist/host/scripts/ollama.sh +0 -0
- package/dist/host/tests/config.test.ts +19 -27
- package/dist/src/core/index.cjs +139 -60
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +1 -1
- package/dist/src/core/index.d.ts +1 -1
- package/dist/src/core/index.js +139 -60
- package/dist/src/core/index.js.map +1 -1
- package/package.json +6 -6
|
@@ -29,52 +29,71 @@ isCapturePath('../escape.png') // false
|
|
|
29
29
|
|
|
30
30
|
Protocol shapes from [`types.ts`](../src/core/types.ts).
|
|
31
31
|
|
|
32
|
-
| Name
|
|
33
|
-
|
|
|
34
|
-
| `CaptureErrorCode`
|
|
35
|
-
| `CaptureErrorContext`
|
|
36
|
-
| `CaptureErrorOptions`
|
|
37
|
-
| `CaptureSelection`
|
|
38
|
-
| `CaptureIdentity`
|
|
39
|
-
| `CaptureRequest`
|
|
40
|
-
| `CaptureSources`
|
|
41
|
-
| `CaptureDigest`
|
|
42
|
-
| `
|
|
43
|
-
| `
|
|
44
|
-
| `
|
|
45
|
-
| `
|
|
46
|
-
| `
|
|
47
|
-
| `
|
|
48
|
-
| `
|
|
49
|
-
| `
|
|
50
|
-
| `
|
|
51
|
-
| `
|
|
52
|
-
| `
|
|
53
|
-
| `
|
|
54
|
-
| `
|
|
55
|
-
| `
|
|
56
|
-
| `
|
|
57
|
-
| `
|
|
58
|
-
| `
|
|
59
|
-
| `
|
|
60
|
-
| `
|
|
61
|
-
| `
|
|
32
|
+
| Name | Kind | Signature | Summary |
|
|
33
|
+
| --------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
|
|
34
|
+
| `CaptureErrorCode` | type | `(typeof CAPTURE_ERROR_CODES)[number]` | Names one condition axis a capture failure carries. |
|
|
35
|
+
| `CaptureErrorContext` | type | `Readonly<Record<string, unknown>>` | Carries structured facts about a capture failure beside its message. |
|
|
36
|
+
| `CaptureErrorOptions` | interface | `{ code, context?, cause? }` | Configures one capture failure's condition, optional context, and optional cause. |
|
|
37
|
+
| `CaptureSelection` | interface | `{ selector, case?, state? }` | Carries the selection fields a request and a parking check read. |
|
|
38
|
+
| `CaptureIdentity` | interface | `{ id, stage, pid, config }` | Identifies one runner invocation's producing stage and configuration. |
|
|
39
|
+
| `CaptureRequest` | interface | `{ version, command, mode?, variants, args }` | Carries a runner request through Vitest's provided-context protocol. |
|
|
40
|
+
| `CaptureSources` | interface | `{ own, shared, tests }` | Attributes product ownership and behavioral inputs separately. |
|
|
41
|
+
| `CaptureDigest` | interface | `{ patterns, files, digest }` | Records declared patterns, expanded file hashes, and their combined digest. |
|
|
42
|
+
| `CaptureDigestReference` | interface | `{ patterns, files, digest }` | Names a digest's file map by the key a document's population table stores it under. |
|
|
43
|
+
| `CaptureDestination` | interface | `{ portfolio, state, scope, part, section?, variant, project, file, case, sources }` | Identifies one required output pair and its declaring case. |
|
|
44
|
+
| `CaptureDeclaration` | interface | `{ case, owner, variant, eligible, states }` | Preserves a collected case's full behavioral declaration. |
|
|
45
|
+
| `CaptureEntry` | interface | `{ duration }` | Records an emitted destination and its producing case duration. |
|
|
46
|
+
| `CaptureArtifact` | interface | `{ file, digest }` | Names the journey artifact a final case wrote and the SHA-256 of its bytes. |
|
|
47
|
+
| `CaptureRun` | interface | `{ version, identity?, request?, variant, time, complete, reference, artifact?, declarations, registry, passed, observed, entries }` | Records collected declarations, successful observations, and emitted output separately. |
|
|
48
|
+
| `CaptureReceipt` | interface | `{ version, variant, time, report, inputs, declarations, registry, complete }` | Binds a complete registry reading to its report and input hashes. |
|
|
49
|
+
| `CaptureRegistry` | interface | `{ version, receipts, entries, digest }` | Collects validated registry receipts and their required output pairs. |
|
|
50
|
+
| `CaptureLookup` | interface | `{ registry, variant, case, owner, states, inputs, run }` | Binds a state-to-case lookup to its registry, inputs, and passing run. |
|
|
51
|
+
| `CaptureStamp` | interface | `{ identity, time, commit, dirty, own, shared, tests, image, registry }` | Stamps one emitted frame with execution, source, image, and registry provenance. |
|
|
52
|
+
| `CaptureManifest` | interface | `{ version, registry, entries, lookups }` | Holds the registry, frame stamps, and validated case lookups in one document. |
|
|
53
|
+
| `CaptureStatus` | type | `'current' \| (typeof CAPTURE_STATUS_PRECEDENCE)[number]` | Names the primary freshness classification of a required or discovered frame. |
|
|
54
|
+
| `CaptureFreshness` | interface | `{ file, state, variant, status, reasons }` | Reports a frame's freshness classification and every supporting reason. |
|
|
55
|
+
| `CaptureWarning` | interface | `{ files, cases }` | Identifies changed behavioral inputs and conservatively affected cases. |
|
|
56
|
+
| `CaptureCollectionReceipt` | interface | `{ project, registry, variant, inputs, run, report }` | Binds a successful full collection to the unchanged complete anchor and exact evidence bytes. |
|
|
57
|
+
| `CaptureExpandedManifest` | interface | `{ collections? }` | Extends the image manifest with independently authenticated collection evidence. |
|
|
58
|
+
| `CaptureLookupJournal` | interface | `{ collections?, version, manifest?, populations, lookups }` | Binds capture-free lookup publication to the exact manifest it supplements. |
|
|
59
|
+
| `CaptureManifestDocument` | interface | `{ version, populations, registry, entries, lookups, collections? }` | Stores a manifest with each distinct file map once, in a table keyed by the map's digest. |
|
|
60
|
+
| `CaptureViewport` | interface | `{ name, width, height }` | Declares a host viewport's name and pixel geometry without inferring it from a file name. |
|
|
61
|
+
| `CaptureBox` | interface | `{ x, y, width, height }` | Describes a logged viewport box a journey artifact records for pixel sampling. |
|
|
62
|
+
| `CaptureAssertion` | interface | `{ status, duration? }` | Carries the owner-bearing projection of a Vitest JSON assertion. |
|
|
63
|
+
| `CaptureReport` | interface | `{ start, end, assertions }` | Holds validated reporter assertions without copying Vitest's unrelated wire members. |
|
|
64
|
+
| `CaptureArtifactLines` | interface | `{ records, cases }` | Carries the run records a journey artifact binds and the cases it shows ran. |
|
|
65
|
+
| `CapturePortfolioRoot` | interface | `{ portfolio, directory, scoped }` | Supplies a host-authorized physical portfolio root without repeating its states or variants. |
|
|
66
|
+
| `CaptureMapping` | interface | `{ variant, states }` | Maps the states one portfolio writes to its output variant and physical root. |
|
|
67
|
+
| `CaptureMeta` | interface | `{ owner?, states?, variant?, eligible? }` | Declares the capture metadata a journey case carries in Vitest's task metadata. |
|
|
68
|
+
| `CaptureProvided` | interface | `{ variant, variants, directory, record, inputs, sources, final, first, uniform?, portfolios, standalone?, capture, request? }` | Declares the values a journey wrapper provides to each project, which the runner and the suite read. |
|
|
69
|
+
| `CaptureTaskResult` | interface | `{ state, duration? }` | Mirrors the members of Vitest's `TaskResult` that a run record reads. |
|
|
70
|
+
| `CaptureTask` | interface | `{ name, mode, tags?, meta, result?, filepath?, tasks? }` | Mirrors the members of a Vitest file, suite, or test task that case collection reads. |
|
|
71
|
+
| `CaptureCase` | interface | `{ name, mode, tags, meta, result? }` | Carries one collected case, including a case a runner filter excluded. |
|
|
72
|
+
| `CaptureTestInput` | interface | `{ owner?, states?, variant, eligible?, timeout?, tags? }` | Supplies one case's owner, states, producing variant, and harness registration values. |
|
|
73
|
+
| `CaptureTestOptions` | interface | `{ tags, meta, timeout? }` | Carries the Vitest test options a capture case registers with. |
|
|
74
|
+
| `CapturePartHandler` | type | `(state: string) => string` | Resolves a declared state to the canonical owner path of the part that renders it. |
|
|
75
|
+
| `CaptureSourcesHandler` | type | `(owner: string) => CaptureSources` | Resolves a canonical owner path to its own, shared, and behavioral source attribution. |
|
|
76
|
+
| `CaptureRules` | interface | `{ owners, part, sources }` | Supplies the host's owner population and its part and source resolvers. |
|
|
77
|
+
| `CaptureDestinationOptions` | interface | `{ project, portfolios }` | Configures the producing project and the portfolio mappings of a destination build. |
|
|
78
|
+
| `CaptureRunOptions` | interface | `{ cases, registry, observed, emitted, variant, time, request? }` | Supplies the collected cases, the destinations, and the observed and emitted states of one run record. |
|
|
62
79
|
|
|
63
80
|
### Constants
|
|
64
81
|
|
|
65
82
|
From [`constants.ts`](../src/core/constants.ts).
|
|
66
83
|
|
|
67
|
-
| Name | Kind | Signature
|
|
68
|
-
| --------------------------- | ----- |
|
|
69
|
-
| `CAPTURE_ERROR_CODES` | const | `readonly ["USAGE", "SELECTION", "HOST", "STAGE", "EVIDENCE", "CONTAINMENT"]`
|
|
70
|
-
| `CAPTURE_ERROR_BRAND` | const | `unique symbol`
|
|
71
|
-
| `CAPTURE_STATUS_PRECEDENCE` | const | `readonly ["duplicate", "orphan", "missing", "unstamped", "stale-shared", "stale-own"]`
|
|
72
|
-
| `CAPTURE_REQUEST_PREFIX` | const | `"journey-selection"`
|
|
73
|
-
| `CAPTURE_VERSION` | const | `
|
|
74
|
-
| `CAPTURE_PNG_SIGNATURE` | const | `readonly [137, 80, 78, 71, 13, 10, 26, 10]`
|
|
75
|
-
| `CAPTURE_REGISTRY_FILE` | const | `"registry.json"`
|
|
76
|
-
| `CAPTURE_MANIFEST_FILE` | const | `"manifest.json"`
|
|
77
|
-
| `CAPTURE_LOOKUPS_FILE` | const | `"lookups.json"`
|
|
84
|
+
| Name | Kind | Signature | Summary |
|
|
85
|
+
| --------------------------- | ----- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
|
|
86
|
+
| `CAPTURE_ERROR_CODES` | const | `readonly ["USAGE", "SELECTION", "HOST", "STAGE", "EVIDENCE", "REGISTRY", "LOOKUP", "CONTAINMENT"]` | Lists the condition axes a capture failure carries, in the order the executable reports them. |
|
|
87
|
+
| `CAPTURE_ERROR_BRAND` | const | `unique symbol` | Keys the global brand a capture error carries, so a duplicate installation recognizes it. |
|
|
88
|
+
| `CAPTURE_STATUS_PRECEDENCE` | const | `readonly ["duplicate", "orphan", "missing", "unstamped", "stale-shared", "stale-own"]` | Lists the non-current freshness classifications from highest precedence to lowest. |
|
|
89
|
+
| `CAPTURE_REQUEST_PREFIX` | const | `"journey-selection"` | Names the file prefix of a runner request, completed by the runner's process id and `.json`. |
|
|
90
|
+
| `CAPTURE_VERSION` | const | `2` | Holds the protocol version every request, record, receipt, registry, and manifest declares. |
|
|
91
|
+
| `CAPTURE_PNG_SIGNATURE` | const | `readonly [137, 80, 78, 71, 13, 10, 26, 10]` | Holds the eight bytes every PNG file opens with. |
|
|
92
|
+
| `CAPTURE_REGISTRY_FILE` | const | `"registry.json"` | Names the default accepted complete-run registry file inside a portfolio directory. |
|
|
93
|
+
| `CAPTURE_MANIFEST_FILE` | const | `"manifest.json"` | Names the default image-stamp manifest file inside a portfolio directory. |
|
|
94
|
+
| `CAPTURE_LOOKUPS_FILE` | const | `"lookups.json"` | Names the default lookup journal file inside a portfolio directory. |
|
|
95
|
+
| `CAPTURE_OWNER_PREFIX` | const | `"owner:"` | Names the tag prefix that marks a case's owner path and each ancestor of it. |
|
|
96
|
+
| `CAPTURE_ARTIFACT_PREFIXES` | const | `Readonly<{ readonly record: 'record='; readonly case: 'case-ran='; }>` | Names the journey artifact line prefixes that bind a run record and each case that ran. |
|
|
78
97
|
|
|
79
98
|
### Errors
|
|
80
99
|
|
|
@@ -91,262 +110,319 @@ The error guard accepts branded subclasses and errors from another installed cop
|
|
|
91
110
|
|
|
92
111
|
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.
|
|
93
112
|
|
|
94
|
-
| Name
|
|
95
|
-
|
|
|
96
|
-
| `isCapturePath`
|
|
97
|
-
| `isCapturePattern`
|
|
98
|
-
| `isCaptureSegment`
|
|
99
|
-
| `isCaptureSelector`
|
|
100
|
-
| `isCaptureHash`
|
|
101
|
-
| `isCaptureHashes`
|
|
102
|
-
| `isCaptureSources`
|
|
103
|
-
| `isCaptureIdentity`
|
|
104
|
-
| `isCaptureRequest`
|
|
105
|
-
| `isCaptureDeclaration`
|
|
106
|
-
| `isCaptureDestination`
|
|
107
|
-
| `isCaptureEntry`
|
|
108
|
-
| `isCaptureArtifact`
|
|
109
|
-
| `isCaptureRun`
|
|
110
|
-
| `isCaptureDigest`
|
|
111
|
-
| `isCaptureReceipt`
|
|
112
|
-
| `isCaptureRegistry`
|
|
113
|
-
| `isCaptureLookup`
|
|
114
|
-
| `isCaptureLookupJournal`
|
|
115
|
-
| `isCaptureStamp`
|
|
116
|
-
| `isCaptureManifest`
|
|
117
|
-
| `isCaptureCollection`
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
113
|
+
| Name | Kind | Signature | Summary |
|
|
114
|
+
| --------------------------- | -------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
115
|
+
| `isCapturePath` | function | `(value: unknown) => value is string` | Checks whether a serialized path stays within the portable relative-path vocabulary. |
|
|
116
|
+
| `isCapturePattern` | function | `(value: unknown) => value is string` | Checks whether a native glob declaration uses relative portable path segments. |
|
|
117
|
+
| `isCaptureSegment` | function | `(value: unknown) => value is string` | Checks whether a protocol identity can occupy one portable path segment. |
|
|
118
|
+
| `isCaptureSelector` | function | `(value: unknown) => value is string` | Checks whether an owner selector uses canonical colon-separated segments. |
|
|
119
|
+
| `isCaptureHash` | function | `(value: unknown) => value is string` | Checks whether a value is a SHA-256 hexadecimal digest. |
|
|
120
|
+
| `isCaptureHashes` | function | `(value: unknown) => value is Readonly<Record<string, string>>` | Checks whether a file-hash map has portable keys and valid digests. |
|
|
121
|
+
| `isCaptureSources` | function | `(value: unknown) => value is CaptureSources` | Checks whether source attribution separates own, shared, and behavioral patterns. |
|
|
122
|
+
| `isCaptureIdentity` | function | `(value: unknown) => value is CaptureIdentity` | Checks whether an execution identity carries its required authorization fields. |
|
|
123
|
+
| `isCaptureRequest` | function | `(value: unknown) => value is CaptureRequest` | Checks whether a request has the supported version and complete execution identity. |
|
|
124
|
+
| `isCaptureDeclaration` | function | `(value: unknown) => value is CaptureDeclaration` | Checks whether a collected declaration preserves its full owner and state population. |
|
|
125
|
+
| `isCaptureDestination` | function | `(value: unknown) => value is CaptureDestination` | Checks whether a destination supplies canonical identity and source attribution fields. |
|
|
126
|
+
| `isCaptureEntry` | function | `(value: unknown) => value is CaptureEntry` | Checks whether an emitted entry includes a finite nonnegative case duration. |
|
|
127
|
+
| `isCaptureArtifact` | function | `(value: unknown) => value is CaptureArtifact` | Checks whether a record names its journey artifact by portable path and SHA-256 digest. |
|
|
128
|
+
| `isCaptureRun` | function | `(value: unknown) => value is CaptureRun` | Checks whether a final record preserves declarations, observations, and output separately. |
|
|
129
|
+
| `isCaptureDigest` | function | `(value: unknown) => value is CaptureDigest` | Checks whether a shared-source digest retains both patterns and expanded file hashes. |
|
|
130
|
+
| `isCaptureReceipt` | function | `(value: unknown) => value is CaptureReceipt` | Checks whether a complete-run receipt binds the report, inputs, and declaration registry. |
|
|
131
|
+
| `isCaptureRegistry` | function | `(value: unknown) => value is CaptureRegistry` | Checks whether a registry document retains its receipts and required output pairs. |
|
|
132
|
+
| `isCaptureLookup` | function | `(value: unknown) => value is CaptureLookup` | Checks whether a lookup binds a passing case to its full run record and input hashes. |
|
|
133
|
+
| `isCaptureLookupJournal` | function | `(value: unknown) => value is CaptureLookupJournal` | Checks the separate lookup journal and its optional predecessor manifest digest. |
|
|
134
|
+
| `isCaptureStamp` | function | `(value: unknown) => value is CaptureStamp` | Checks whether a stamp binds an emitted image to source and execution provenance. |
|
|
135
|
+
| `isCaptureManifest` | function | `(value: unknown) => value is CaptureManifest` | Checks whether an expanded manifest has the supported schema without discarding malformed rows. |
|
|
136
|
+
| `isCaptureCollection` | function | `(value: unknown) => value is CaptureCollectionReceipt` | Checks whether collection evidence pins complete input membership and both external artifacts. |
|
|
137
|
+
| `isCaptureExpandedManifest` | function | `(value: unknown) => value is CaptureExpandedManifest` | Checks whether an expanded manifest and its optional collection receipts have the supported schema. |
|
|
138
|
+
| `isCaptureDigestReference` | function | `(value: unknown) => value is CaptureDigestReference` | Checks whether a digest names its file map by a table key beside its patterns and combined digest. |
|
|
139
|
+
| `isCaptureManifestDocument` | function | `(value: unknown) => value is CaptureManifestDocument` | Checks whether a stored manifest holds its population table and every member that names a table key. |
|
|
140
|
+
| `isCaptureGeometry` | function | `(value: unknown) => value is CaptureViewport` | Checks the host's declared viewport without deriving geometry from an output name. |
|
|
141
|
+
| `isCaptureBox` | function | `(value: unknown) => value is CaptureBox` | Checks a journey artifact's recorded sampling box. |
|
|
121
142
|
|
|
122
143
|
### Helpers
|
|
123
144
|
|
|
124
145
|
Pure leaves from [`helpers.ts`](../src/core/helpers.ts). A helper that refuses a document throws a `CaptureError` with the `EVIDENCE` condition.
|
|
125
146
|
|
|
126
|
-
| Name | Kind | Signature
|
|
127
|
-
| ---------------------------- | -------- |
|
|
128
|
-
| `describeCaptureError` | function | `(error: unknown) => string`
|
|
129
|
-
| `collectCaptureDuplicates` | function | `(values: readonly string[], folded?: boolean) => readonly string[]`
|
|
130
|
-
| `requireCaptureUnique` | function | `(values: readonly string[], label: string, folded?: boolean) => void`
|
|
131
|
-
| `matchesCaptureMembers` | function | `(left: readonly string[], right: readonly string[]) => boolean`
|
|
132
|
-
| `matchesCaptureSelector` | function | `(owner: string, selector: string) => boolean`
|
|
133
|
-
| `resolveCaptureOwner` | function | `(entry: CaptureDestination) => string`
|
|
134
|
-
| `resolveCaptureKey` | function | `(entry: CaptureDestination) => string`
|
|
135
|
-
| `describeCaptureDestination` | function | `(entry: CaptureDestination) => string`
|
|
136
|
-
| `describeCaptureIdentity` | function | `(entry: CaptureDestination) => string`
|
|
137
|
-
| `describeCaptureDeclaration` | function | `(entry: CaptureDeclaration) => string`
|
|
138
|
-
| `describeCaptureRequest` | function | `(request: CaptureRequest) => string`
|
|
139
|
-
| `collectCaptureChanges` | function | `(previous: Readonly<Record<string, string>>, current: Readonly<Record<string, string>>) => readonly string[]`
|
|
140
|
-
| `resolveLookupKey` | function | `(lookup: Pick<CaptureLookup, 'variant' \| 'case'>) => string`
|
|
141
|
-
| `readCaptureReport` | function | `(value: unknown) => CaptureReport`
|
|
142
|
-
| `validateCaptureRun` | function | `(run: CaptureRun, report: CaptureReport, project: string) => void`
|
|
143
|
-
| `resolveCaptureStatus` | function | `(statuses: readonly CaptureStatus[]) => CaptureStatus`
|
|
144
|
-
| `readCaptureDirty` | function | `(output: string) => readonly string[]`
|
|
145
|
-
| `validateCaptureReceipt` | function | `(receipt: CaptureReceipt, report: CaptureReport) => void`
|
|
147
|
+
| Name | Kind | Signature | Summary |
|
|
148
|
+
| ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
149
|
+
| `describeCaptureError` | function | `(error: unknown) => string` | Describes a caught failure as one reportable line. |
|
|
150
|
+
| `collectCaptureDuplicates` | function | `(values: readonly string[], folded?: boolean) => readonly string[]` | Finds repeated identities before a keyed collection could discard them. |
|
|
151
|
+
| `requireCaptureUnique` | function | `(values: readonly string[], label: string, folded?: boolean) => void` | Refuses duplicate declarations or portable storage-key collisions before indexing. |
|
|
152
|
+
| `matchesCaptureMembers` | function | `(left: readonly string[], right: readonly string[]) => boolean` | Compares complete populations without erasing duplicates. |
|
|
153
|
+
| `matchesCaptureSelector` | function | `(owner: string, selector: string) => boolean` | Compares an owner with an explicit selector at colon boundaries. |
|
|
154
|
+
| `resolveCaptureOwner` | function | `(entry: CaptureDestination) => string` | Builds the canonical owner from a destination's registry identity. |
|
|
155
|
+
| `resolveCaptureKey` | function | `(entry: CaptureDestination) => string` | Builds a manifest identity independently of the physical image path. |
|
|
156
|
+
| `describeCaptureDestination` | function | `(entry: CaptureDestination) => string` | Serializes a destination's identity and attribution in a deterministic field order. |
|
|
157
|
+
| `describeCaptureIdentity` | function | `(entry: CaptureDestination) => string` | Serializes only the registry's execution and output identity, independent of input revisions. |
|
|
158
|
+
| `describeCaptureDeclaration` | function | `(entry: CaptureDeclaration) => string` | Serializes a complete behavioral declaration without dropping eligibility or states. |
|
|
159
|
+
| `describeCaptureRequest` | function | `(request: CaptureRequest) => string` | Serializes every request field, retaining the exact argv order. |
|
|
160
|
+
| `collectCaptureChanges` | function | `(previous: Readonly<Record<string, string>>, current: Readonly<Record<string, string>>) => readonly string[]` | Names every changed, added, or removed file in hash populations. |
|
|
161
|
+
| `resolveLookupKey` | function | `(lookup: Pick<CaptureLookup, 'variant' \| 'case'>) => string` | Builds the stable case identity used to merge separate lookup receipts. |
|
|
162
|
+
| `readCaptureReport` | function | `(value: unknown) => CaptureReport` | Reads successful Vitest JSON output and validates every owner-bearing assertion. |
|
|
163
|
+
| `validateCaptureRun` | function | `(run: CaptureRun, report: CaptureReport, project: string) => void` | Validates declaration, reporter, observation, completeness, and output-projection agreement. |
|
|
164
|
+
| `resolveCaptureStatus` | function | `(statuses: readonly CaptureStatus[]) => CaptureStatus` | Chooses the primary classification while retaining all findings separately. |
|
|
165
|
+
| `readCaptureDirty` | function | `(output: string) => readonly string[]` | Reads Git's NUL-delimited porcelain paths without treating spaces or quoted names as separators. |
|
|
166
|
+
| `validateCaptureReceipt` | function | `(receipt: CaptureReceipt, report: CaptureReport) => void` | Validates a complete receipt against full reporter declarations and eligible output coverage. |
|
|
167
|
+
| `collectCaptureAncestors` | function | `(owner: string) => readonly string[]` | Expands an owner path into its prefixes, from its scope through the owner itself. |
|
|
168
|
+
| `buildCaptureTags` | function | `(owners: readonly string[]) => readonly string[]` | Builds the owner and capture tags a wrapper declares for its owner population. |
|
|
169
|
+
| `buildCaptureTest` | function | `(input: CaptureTestInput, rules: CaptureRules) => CaptureTestOptions` | Builds the Vitest test options of one capture case from its declaration. |
|
|
170
|
+
| `collectCaptureCases` | function | `(task: CaptureTask, ancestors?: readonly string[]) => readonly CaptureCase[]` | Collects every leaf case under a task, keeping cases a runner filter excluded and their results. |
|
|
171
|
+
| `requireCaptureCases` | function | `(cases: readonly CaptureCase[], rules: CaptureRules, selection?: CaptureSelection) => void` | Refuses a selection whose cases place states owned outside the selected owner. |
|
|
172
|
+
| `buildCaptureDestinations` | function | `(cases: readonly CaptureCase[], rules: CaptureRules, options: CaptureDestinationOptions) => readonly CaptureDestination[]` | Builds the required output pair of each state an eligible owner-bearing case declares. |
|
|
173
|
+
| `buildCaptureRun` | function | `(options: CaptureRunOptions) => CaptureRun` | Builds a run record from collected cases, the run's destinations, and its observed and emitted states. |
|
|
174
|
+
| `renderCaptureArtifact` | function | `(record: string, run: Pick<CaptureRun, 'passed'>) => readonly string[]` | Renders the journey artifact lines that bind a run record and each case that passed in it. |
|
|
175
|
+
| `readCaptureArtifact` | function | `(text: string) => CaptureArtifactLines` | Reads the record bindings and the ran cases from a journey artifact's text. |
|
|
176
|
+
|
|
177
|
+
The record helpers build what the validator and the preflight reader check, and take every product rule as data or as an injected resolver. A wrapper declares the tags `buildCaptureTags` returns for its owners, and each case registers with the options `buildCaptureTest` returns. Before any case writes a frame, a `beforeAll` hook passes the file's `collectCaptureCases` result to `requireCaptureCases`, which refuses a parked selection. The final case collects every case again, maps each state to its frame with `buildCaptureDestinations`, and builds the record with `buildCaptureRun` from the states it observed and the state-to-path pairs it wrote. The builder refuses only an owner-bearing case with no variant and an emitted pair it cannot bind to a destination and a measured duration; `validateCaptureRun` decides whether the record is valid. The final case writes the `renderCaptureArtifact` lines into its journey artifact and binds the artifact's digest to the record, and the preflight reads those lines back through `readCaptureArtifact`. For a typed `meta` option and typed `inject` values, extend Vitest's `TaskMeta` with `CaptureMeta` and its `ProvidedContext` with `CaptureProvided` in the workspace's own module declaration.
|
|
178
|
+
|
|
179
|
+
For a typed frame command, extend the `BrowserCommands` interface of `vitest/browser` with `readCaptureFrames: () => Promise<readonly string[]>` in a module declaration; a browser test awaits the command's answer.
|
|
146
180
|
|
|
147
181
|
### Server types
|
|
148
182
|
|
|
149
183
|
Engine, runner, preflight, and contact-sheet contracts from [`types.ts`](../src/server/types.ts).
|
|
150
184
|
|
|
151
|
-
| Name | Kind | Signature
|
|
152
|
-
| -------------------------------- | --------- |
|
|
153
|
-
| `CaptureCommand` | type | `CaptureRequest['command'] \| 'stale'`
|
|
154
|
-
| `
|
|
155
|
-
| `
|
|
156
|
-
| `
|
|
157
|
-
| `
|
|
158
|
-
| `
|
|
159
|
-
| `
|
|
160
|
-
| `
|
|
161
|
-
| `
|
|
162
|
-
| `
|
|
163
|
-
| `
|
|
164
|
-
| `
|
|
165
|
-
| `
|
|
166
|
-
| `
|
|
167
|
-
| `
|
|
168
|
-
| `
|
|
169
|
-
| `
|
|
170
|
-
| `
|
|
171
|
-
| `
|
|
172
|
-
| `
|
|
173
|
-
| `
|
|
174
|
-
| `
|
|
175
|
-
| `
|
|
176
|
-
| `
|
|
177
|
-
| `
|
|
178
|
-
| `
|
|
179
|
-
| `
|
|
180
|
-
| `
|
|
181
|
-
| `
|
|
182
|
-
| `
|
|
183
|
-
| `
|
|
184
|
-
| `
|
|
185
|
-
| `
|
|
186
|
-
| `
|
|
187
|
-
| `
|
|
188
|
-
| `
|
|
189
|
-
| `
|
|
190
|
-
| `
|
|
191
|
-
| `
|
|
192
|
-
| `
|
|
193
|
-
| `
|
|
194
|
-
| `
|
|
195
|
-
| `
|
|
196
|
-
| `
|
|
197
|
-
| `
|
|
198
|
-
| `CaptureInvocationInterface` | interface | `{ id, request, directory, signal, interrupted, attach(), release(), prepare(), holders(), publish(), retract(), launched(), spawn() }`
|
|
199
|
-
| `CaptureDiscoveryRequest` | interface | `{ version, phase, id, nonce, config, mode?, pid, args }`
|
|
200
|
-
| `CaptureHostEntry` | interface | `{ project, viewport? }`
|
|
201
|
-
| `CaptureHostDescription` | interface | `{ version, id, nonce, config, parent, pid, projects }`
|
|
202
|
-
| `CaptureDescriptionExpectation` | interface | `{ id, nonce, config, parent, pid }`
|
|
203
|
-
| `CaptureDiscoveryOptions` | interface | `{ ppid, argv, directory?, config, projects }`
|
|
204
|
-
| `
|
|
205
|
-
| `
|
|
206
|
-
| `
|
|
207
|
-
| `
|
|
208
|
-
| `
|
|
209
|
-
| `
|
|
210
|
-
| `
|
|
211
|
-
| `
|
|
212
|
-
| `
|
|
213
|
-
| `
|
|
214
|
-
| `
|
|
215
|
-
| `
|
|
216
|
-
| `
|
|
217
|
-
| `
|
|
218
|
-
| `
|
|
219
|
-
| `
|
|
220
|
-
| `
|
|
221
|
-
| `
|
|
222
|
-
| `
|
|
223
|
-
| `
|
|
224
|
-
| `
|
|
225
|
-
| `
|
|
226
|
-
| `
|
|
227
|
-
| `
|
|
228
|
-
| `
|
|
229
|
-
| `
|
|
230
|
-
| `
|
|
231
|
-
| `
|
|
232
|
-
| `
|
|
233
|
-
| `
|
|
234
|
-
| `
|
|
235
|
-
| `
|
|
185
|
+
| Name | Kind | Signature | Summary |
|
|
186
|
+
| -------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
187
|
+
| `CaptureCommand` | type | `CaptureRequest['command'] \| 'stale'` | Names one command the runner executes: a journey, a frame capture, or a stale reading. |
|
|
188
|
+
| `CaptureHashHandler` | type | `(bytes: Uint8Array) => string` | Digests the exact bytes of one file reading and returns the lowercase hexadecimal digest. |
|
|
189
|
+
| `CaptureIntegrityOptions` | interface | `{ inputs, root, directory, manifest, registry, lookups, portfolios, hash? }` | Configures the engine's workspace and separate evidence documents. |
|
|
190
|
+
| `CaptureStageProject` | interface | `{ name, variant, record, inputs }` | Supplies one selected project's expected final record and bounded input population. |
|
|
191
|
+
| `CaptureParsedArguments` | type | `{ readonly [Key in keyof ReturnType<typeof parseArgs<{ readonly options: Options; readonly tokens: true; readonly strict: true; readonly allowPositionals: true; readonly allowNegative: true; }>>]: Readonly<ReturnType<typeof parseArgs<{ readonly options: Options; readonly tokens: true; readonly strict: true; readonly allowPositionals: true; readonly allowNegative: true; }>>[Key]>; }` | Carries the typed values and tokens of a strictly parsed capture command line. |
|
|
192
|
+
| `CaptureExecutionResult` | interface | `{ code, signal, pid?, expired? }` | Carries the supervised child outcome without treating a signal as a successful exit. |
|
|
193
|
+
| `CaptureExecutionHandler` | type | `() => Promise<CaptureExecutionResult>` | Executes the runner's child after the engine captures its input snapshot. |
|
|
194
|
+
| `CaptureStageOptions` | interface | `{ request, projects, report, execute, signal? }` | Binds a stage transaction to its exact request, projects, reporter, and process boundary. |
|
|
195
|
+
| `CaptureFileSnapshot` | interface | `{ file, image, changed }` | Records one physical file's bytes and native modification readings at a stage boundary. |
|
|
196
|
+
| `CaptureProjectSnapshot` | interface | `{ project, inputs }` | Preserves one project's declared patterns and sorted expansion before execution. |
|
|
197
|
+
| `CaptureSnapshot` | interface | `{ time, projects, files }` | Holds a stage boundary's input populations and existing output identities. |
|
|
198
|
+
| `CaptureProjectResult` | interface | `{ project, variant, record, declarations, passed }` | Reports validated project evidence, retaining empty successful selections explicitly. |
|
|
199
|
+
| `CaptureStageResult` | interface | `{ request, projects, entries, lookups, duration }` | Reports the successful stage's committed stamps and validated lookup evidence. |
|
|
200
|
+
| `CaptureReadOptions` | interface | `{ variants?, portfolio? }` | Selects a declaration population without requiring current images or passing state lookups. |
|
|
201
|
+
| `CaptureStaleOptions` | interface | `{ declared? }` | Selects a freshness population and names the producing variants the host wrapper declares. |
|
|
202
|
+
| `CaptureCheckOptions` | interface | `{ variants, portfolio? }` | Selects required output pairs and attributable extras for a freshness reading. |
|
|
203
|
+
| `CaptureReadResult` | interface | `{ registry, entries }` | Returns the exact current declaration destinations and their complete-anchor identity. |
|
|
204
|
+
| `CaptureCheckResult` | interface | `{ required, entries, warnings, duration }` | Reports the exact judged population, every mismatch reason, and conservative test warnings. |
|
|
205
|
+
| `CaptureLookupOptions` | interface | `{ state, variants, portfolio? }` | Requests a state-to-case resolution before the runner starts any selected project. |
|
|
206
|
+
| `CaptureLookupResult` | interface | `{ case, entries, lookups }` | Resolves one declaring case and its actual output pairs with their passing evidence. |
|
|
207
|
+
| `CaptureRunEvidence` | interface | `{ file, run }` | Binds a decoded run record to the physical file whose digest authenticated it. |
|
|
208
|
+
| `CaptureDirectoryResult` | interface | `{ directory, ancestors }` | Carries one physical-directory ancestry while enumerating logical portfolio paths. |
|
|
209
|
+
| `CaptureEvidence` | interface | `{ registry, collections, manifest?, lookups, runs }` | Carries accepted registry anchors and separately persisted passing run evidence. |
|
|
210
|
+
| `CaptureCollectionEvidence` | interface | `{ receipt }` | Carries the authenticated external record beside its collection receipt. |
|
|
211
|
+
| `CaptureReceiptInput` | interface | `{ receipt, report, outcome, capped }` | Supplies a verifier's actual process outcome and exact reporter bytes for registry import. |
|
|
212
|
+
| `CaptureIntegrityInterface` | interface | `{ changed(), read(), stamp(), check(), lookup() }` | Defines the shared stage transaction, freshness reading, and state resolution engine. |
|
|
213
|
+
| `CaptureProject` | interface | `{ name, variant, tags, variants, directory, record, inputs, final, first, uniform?, portfolios, standalone }` | Preserves the wrapper's host declarations, including optional uniform scopes, for consumers. |
|
|
214
|
+
| `CaptureRunnerOptions` | interface | `{ command, root, config, requests, argv, stdout?, stderr?, integrity?, deadline? }` | Configures one runner invocation: its command, its workspace, and the command line it reads. |
|
|
215
|
+
| `CaptureRunnerArguments` | interface | `{ selector?, changed?, plan?, bail?, config, mode?, variants, case?, state?, portfolio? }` | Carries parsed runner arguments, including an optional wrapper mode, while leaving omitted selectors available to the usage diagnostic. |
|
|
216
|
+
| `CaptureRunnerInterface` | interface | `{ execute() }` | Drives selected owners through one journey stage or staged frame captures. |
|
|
217
|
+
| `CaptureChange` | interface | `{ path, classification, owners }` | Classifies one changed Git path against accepted source attribution. |
|
|
218
|
+
| `CaptureChangePlan` | interface | `{ changes, owners }` | Holds changed paths and the stable owner selection reduced by ancestry. |
|
|
219
|
+
| `CaptureOwnerOutcome` | interface | `{ owner, code, ran }` | Records one changed owner's exit and whether an execution child started. |
|
|
220
|
+
| `CaptureWriteHandler` | type | `(text: string) => unknown` | Writes one chunk of runner output to the stream the host chooses. |
|
|
221
|
+
| `CaptureCLIOptions` | interface | `{ root?, stdout?, stderr? }` | Configures the executable's workspace and its report and diagnostic writers. |
|
|
222
|
+
| `CaptureCLIInterface` | interface | `{ execute() }` | Runs capture command lines through injected output writers. |
|
|
223
|
+
| `CaptureIntegrityHandler` | type | `(options: CaptureIntegrityOptions) => CaptureIntegrityInterface` | Creates the integrity engine the runner reads and stamps through, from the options it derives. |
|
|
224
|
+
| `CaptureStagePlan` | interface | `{ name, variants }` | Names one planned stage and the variants it runs in one Vitest process. |
|
|
225
|
+
| `CaptureArgumentsOptions` | interface | `{ entry, config, report, progress, bail?, projects, filter?, case?, final, mode?, titles? }` | Configures the Vitest argument list one stage spawns with. |
|
|
226
|
+
| `CaptureRequestOptions` | interface | `{ ppid, argv, directory?, config, owners, variants }` | Configures how a wrapper reads the runner's request for its own Vitest process. |
|
|
227
|
+
| `CaptureOutcome` | interface | `{ project, variant, count }` | Carries one project's owner-bearing passed work count from a finished stage. |
|
|
228
|
+
| `CaptureRunPlan` | interface | `{ command, projects, selector, filter, case?, state?, final, directory, config, mode?, bail? }` | Carries everything every stage of one invocation shares. |
|
|
229
|
+
| `CaptureInvocationOptions` | interface | `{ command, root, requests, stdout, stderr, terminate?, ownership? }` | Configures one runner invocation's identity, workspace, and output. |
|
|
230
|
+
| `CaptureChildTerminationHandler` | type | `(child: DuplexInterface) => Promise<boolean>` | Terminates one supervised child and reports whether its exit was confirmed. |
|
|
231
|
+
| `CaptureHolder` | interface | `{ pid, inspected }` | Describes another process that holds a request file in the request directory. |
|
|
232
|
+
| `CaptureInvocationInterface` | interface | `{ id, request, directory, signal, interrupted, attach(), release(), prepare(), holders(), publish(), retract(), launched(), spawn() }` | Owns one runner invocation's identity, request file, children, and interruption. |
|
|
233
|
+
| `CaptureDiscoveryRequest` | interface | `{ version, phase, id, nonce, config, mode?, pid, args }` | Carries the request the runner publishes for the discovery child that reads its wrapper. |
|
|
234
|
+
| `CaptureHostEntry` | interface | `{ project, viewport? }` | Describes one wrapper project to the runner: its host declarations and, when it has one, its viewport. |
|
|
235
|
+
| `CaptureHostDescription` | interface | `{ version, id, nonce, config, parent, pid, projects }` | Carries the description a wrapper writes back to the runner that discovered it. |
|
|
236
|
+
| `CaptureDescriptionExpectation` | interface | `{ id, nonce, config, parent, pid }` | Names what a description must echo for the runner to accept it. |
|
|
237
|
+
| `CaptureDiscoveryOptions` | interface | `{ ppid, argv, directory?, config, projects }` | Configures how a wrapper answers the runner's discovery request. |
|
|
238
|
+
| `CaptureDiscoveryConfig` | interface | `{ test }` | Describes the empty Node configuration a wrapper returns after it has answered a discovery request. |
|
|
239
|
+
| `CaptureWrapperOverride` | interface | `{ test }` | Describes the values capture merges into each variant's Vitest project. |
|
|
240
|
+
| `CaptureProjectHandler` | type | `(variant: CaptureViewport, override: CaptureWrapperOverride) => TProject` | Builds one variant's Vitest project from the host's own defaults and capture's override. |
|
|
241
|
+
| `CaptureWrapperOptions` | interface | `{ url, variants, owners, first, final, directory, inputs, sources, portfolios, uniform?, project }` | Configures the journey wrapper `buildCaptureWrapper` assembles. |
|
|
242
|
+
| `CaptureWrapperConfig` | interface | `{ plugins, test }` | Describes the Vitest configuration a journey wrapper returns for an execution child. |
|
|
243
|
+
| `CaptureProgress` | interface | `{ file, runs, uninspected }` | Carries the progress file of the stage that ran last in a workspace, and every run it holds. |
|
|
244
|
+
| `CaptureDiscoveryRunOptions` | interface | `{ root, config, invocation, mode?, deadline? }` | Configures one discovery: the workspace, the wrapper, the invocation that owns the child, and its bounds. |
|
|
245
|
+
| `CaptureDiscoveryInterface` | interface | `{ describe() }` | Reads a consumer's wrapper by running its installed Vitest in discovery mode. |
|
|
246
|
+
| `CapturePicture` | interface | `{ width, height, pixels }` | Carries a decoded RGB image for the image checks and the contact sheets. |
|
|
247
|
+
| `CaptureReaderOptions` | interface | `{ root, config, mode?, selection, journeys, checks?, requests?, deadline?, stdout?, stderr? }` | Configures a read-only capture consumer using the wrapper's host declarations. |
|
|
248
|
+
| `CaptureProducer` | interface | `{ project }` | Declares the viewport one wrapper project produces beside the project's own name. |
|
|
249
|
+
| `CaptureReaderDefaults` | interface | `{ config, journeys, requests? }` | Supplies the wrapper path, the journey artifact directory, and the request directory a reader command line falls back to. |
|
|
250
|
+
| `CaptureReaderSelection` | interface | `{ integrity, population, variants, directory, uniform? }` | Returns a reader's authenticated selection, uniform scopes, and engine for pixel classification. |
|
|
251
|
+
| `CaptureArtifactResult` | interface | `{ record, run, file, text }` | Carries a judged run record and the verified text of the journey artifact it names. |
|
|
252
|
+
| `CaptureJudgedRecord` | interface | `{ record, case }` | Names the run record a judged frame's stamp points at and the case that stamped it. |
|
|
253
|
+
| `CaptureJudgedFrame` | interface | `{ entry, artifact, issues }` | Pairs a judged frame with its verified artifact, when one was read, and its coverage issues. |
|
|
254
|
+
| `CaptureDecodedImage` | interface | `{ entry, picture, digest, size }` | Records one selected image's real bytes, geometry, and canonical destination. |
|
|
255
|
+
| `CaptureImageResult` | interface | `{ picture, thumbnail }` | Retains source geometry and a bounded sheet thumbnail after a full frame has been judged. |
|
|
256
|
+
| `CaptureOwnership` | interface | `{ pid, id }` | Identifies the process and invocation that own a request directory. |
|
|
257
|
+
| `CaptureOwnershipHost` | interface | `{ platform, read, write, link, remove, alive }` | Supplies the filesystem and liveness boundary for ownership arbitration. |
|
|
258
|
+
| `CapturePngLimits` | interface | `{ pixels, side, bytes }` | Bounds a PNG's decoded pixels, side length, and encoded bytes. |
|
|
259
|
+
| `CaptureCheckFrame` | interface | `{ entry, picture, artifact }` | Carries one judged frame to a host check: its destination, its decoded pixels, and its artifact. |
|
|
260
|
+
| `CaptureCheckHandler` | type | `(frame: CaptureCheckFrame) => readonly string[]` | Reads one judged frame against a host rule and returns the issues it finds, none when it passes. |
|
|
261
|
+
| `CapturePreflightResult` | interface | `{ mixed, variants, directory, selection, freshness, images, issues }` | Reports selected image checks without upgrading their engine freshness classifications. |
|
|
262
|
+
| `CapturePreflightInterface` | interface | `{ read(), check(), execute() }` | Reads the selected population's frames and reports their freshness, mixed observations, and coverage. |
|
|
263
|
+
| `CaptureSheetOptions` | interface | `{ reader, output }` | Carries a contact-sheet output request separately from the population selection. |
|
|
264
|
+
| `CaptureSheetCell` | interface | `{ entry, picture, source, factor, clipped, freshness }` | Holds one contact-sheet cell: a frame's destination, its shrunk picture, and what the sheet reports about it. |
|
|
265
|
+
| `CaptureSheetGroup` | interface | `{ identity, cells, picture }` | Holds the cells of one portfolio, owner, and state side by side as one composite picture. |
|
|
266
|
+
| `CaptureSheetRow` | interface | `{ groups, picture }` | Holds a pair of groups side by side as one composite picture. |
|
|
267
|
+
| `CaptureSheetPage` | interface | `{ file, rows, picture }` | Holds one written sheet: its file name, the rows it stacks, and the composite picture. |
|
|
268
|
+
| `CaptureReaderReport` | interface | `{ selection, freshness, mixed, issues, identical, sizes, acceptance }` | Holds the report a preflight prints on its `READER` line and a contact-sheet index carries. |
|
|
269
|
+
| `CaptureSheetIndex` | interface | `{ sheets }` | Holds a contact-sheet run's `index.json` document, which its `SHEETS` line also prints. |
|
|
270
|
+
| `CaptureReaderCommand` | interface | `{ reader, output? }` | Carries parsed reader arguments and an optional contact-sheet output directory. |
|
|
271
|
+
| `CaptureSheetsInterface` | interface | `{ execute() }` | Composes exactly the authenticated sparse state and output pairs for iteration review. |
|
|
272
|
+
| `CaptureRegistryArguments` | interface | `{ config, variants, mode?, bail? }` | Carries the parsed registry command line: the wrapper, the variants to refresh, and the mode. |
|
|
273
|
+
| `CaptureRegistrarOptions` | interface | `{ root, config, requests, argv, stdout?, stderr?, deadline? }` | Configures one registry refresh: its workspace, wrapper default, request directory, and command line. |
|
|
274
|
+
| `CaptureRegistrarInterface` | interface | `{ execute() }` | Refreshes the accepted registry from one complete capture-free journey stage over the selected variants. |
|
|
275
|
+
| `CaptureInputHandler` | type | `(file: string) => string \| undefined` | Reads a contained input through an owning operation's file snapshot memo. |
|
|
276
|
+
| `CaptureRetractionHandler` | type | `() => void` | Removes one invocation's published request during shutdown. |
|
|
277
|
+
| `CaptureTerminationHandler` | type | `() => Promise<boolean>` | Begins one independent child termination only after request removal has been attempted. |
|
|
236
278
|
|
|
237
279
|
### Server constants
|
|
238
280
|
|
|
239
281
|
The runner's names and bounds from [`constants.ts`](../src/server/constants.ts).
|
|
240
282
|
|
|
241
|
-
| Name
|
|
242
|
-
|
|
|
243
|
-
| `CAPTURE_COMMAND_NAMES`
|
|
244
|
-
| `CAPTURE_COMMAND_OPTIONS`
|
|
245
|
-
| `CAPTURE_EXIT`
|
|
246
|
-
| `
|
|
247
|
-
| `
|
|
248
|
-
| `
|
|
249
|
-
| `
|
|
250
|
-
| `
|
|
251
|
-
| `
|
|
252
|
-
| `
|
|
253
|
-
| `
|
|
254
|
-
| `
|
|
255
|
-
| `
|
|
256
|
-
| `
|
|
257
|
-
| `
|
|
258
|
-
| `
|
|
259
|
-
| `
|
|
260
|
-
| `
|
|
261
|
-
| `
|
|
262
|
-
| `
|
|
263
|
-
| `
|
|
264
|
-
| `
|
|
265
|
-
| `
|
|
266
|
-
| `
|
|
267
|
-
| `
|
|
268
|
-
| `
|
|
269
|
-
| `
|
|
270
|
-
| `
|
|
283
|
+
| Name | Kind | Signature | Summary |
|
|
284
|
+
| --------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
285
|
+
| `CAPTURE_COMMAND_NAMES` | const | `Readonly<{ readonly journey: 'journey'; readonly capture: 'frames'; readonly stale: 'stale'; }>` | Names the executable subcommand each runner command answers to. |
|
|
286
|
+
| `CAPTURE_COMMAND_OPTIONS` | const | `Readonly<{ readonly journey: Readonly<{ config: Readonly<{ type: "string"; }>; variant: Readonly<{ type: "string"; multiple: true; }>; case: Readonly<{ type: "string"; }>; changed: Readonly<{ type: "string"; }>; plan: Readonly<{ type: "boolean"; }>; bail: Readonly<{ type: "boolean"; default: true; }>; mode: Readonly<{ type: "string"; }>; }>; readonly capture: Readonly<{ config: Readonly<{ type: "string"; }>; variant: Readonly<{ type: "string"; multiple: true; }>; case: Readonly<{ type: "string"; }>; state: Readonly<{ type: "string"; }>; changed: Readonly<{ type: "string"; }>; plan: Readonly<{ type: "boolean"; }>; bail: Readonly<{ type: "boolean"; default: true; }>; mode: Readonly<{ type: "string"; }>; }>; readonly stale: Readonly<{ config: Readonly<{ type: "string"; }>; variant: Readonly<{ type: "string"; multiple: true; }>; case: Readonly<{ type: "string"; }>; state: Readonly<{ type: "string"; }>; portfolio: Readonly<{ type: "string"; }>; mode: Readonly<{ type: "string"; }>; }>; readonly preflight: Readonly<{ variant: Readonly<{ type: "string"; multiple: true; }>; state: Readonly<{ type: "string"; }>; case: Readonly<{ type: "string"; }>; portfolio: Readonly<{ type: "string"; }>; config: Readonly<{ type: "string"; }>; journeys: Readonly<{ type: "string"; }>; checks: Readonly<{ type: "string"; }>; mode: Readonly<{ type: "string"; }>; }>; readonly sheets: Readonly<{ variant: Readonly<{ type: "string"; multiple: true; }>; state: Readonly<{ type: "string"; }>; case: Readonly<{ type: "string"; }>; portfolio: Readonly<{ type: "string"; }>; config: Readonly<{ type: "string"; }>; journeys: Readonly<{ type: "string"; }>; checks: Readonly<{ type: "string"; }>; mode: Readonly<{ type: "string"; }>; output: Readonly<{ type: "string"; }>; }>; readonly registry: Readonly<{ variant: Readonly<{ type: "string"; multiple: true; }>; config: Readonly<{ type: "string"; }>; bail: Readonly<{ type: "boolean"; default: true; }>; mode: Readonly<{ type: "string"; }>; }>; readonly progress: Readonly<{}>; }>` | Defines each command's frozen options for Node's standard argument parser. |
|
|
287
|
+
| `CAPTURE_EXIT` | const | `Readonly<{ readonly passed: 0; readonly failed: 1; readonly usage: 64; }>` | Holds the exit status each runner outcome maps to. |
|
|
288
|
+
| `CAPTURE_RECOVERIES` | const | `Readonly<Record<CaptureErrorCode, 'registry' \| 'journey' \| undefined>>` | Names the command that clears each refusal condition, or none where no command clears it. |
|
|
289
|
+
| `CAPTURE_STATUS_RECOVERIES` | const | `Readonly<Record<CaptureStatus, 'capture' \| undefined>>` | Names the command that clears each freshness classification, or none where no command clears it. |
|
|
290
|
+
| `CAPTURE_OWNER_FILE` | const | `".capture-owner"` | Names the exclusive workspace invocation marker. |
|
|
291
|
+
| `CAPTURE_PID_LIMIT` | const | `2147483647` | Holds the largest process id a POSIX or Windows host can assign, the signed 32-bit maximum. |
|
|
292
|
+
| `CAPTURE_REFUSAL_LIMIT` | const | `16` | Caps each refusal population so hostile records cannot flood a terminal or agent context. |
|
|
293
|
+
| `CAPTURE_STAGES` | const | `Readonly<{ readonly selected: 'selected'; readonly first: 'narrow'; readonly rest: 'rest'; }>` | Names the selected journey stage and the narrow and remaining frame stages. |
|
|
294
|
+
| `CAPTURE_TAG_OPERATORS` | const | `readonly string[]` | Lists the words a tag name can never be, because a tag filter reads them as operators. |
|
|
295
|
+
| `CAPTURE_FLAG` | const | `"CAPTURE"` | Names the environment variable that turns frame capture on for a Vitest child. |
|
|
296
|
+
| `CAPTURE_FLAG_VALUE` | const | `"1"` | Holds the one value of the capture variable that turns frame capture on. |
|
|
297
|
+
| `CAPTURE_VITEST_ENTRY` | const | `"node_modules/vitest/vitest.mjs"` | Names the repository-relative path of the Vitest entry the runner spawns through Node. |
|
|
298
|
+
| `CAPTURE_RUNS_DIRECTORY` | const | `"runs"` | Names the directory beneath a portfolio or request directory that holds one invocation's records. |
|
|
299
|
+
| `CAPTURE_PROGRESS_SUFFIX` | const | `".progress.jsonl"` | Names the ending of the progress file each stage writes beneath its invocation's run directory. |
|
|
300
|
+
| `CAPTURE_WRAPPER_PREFIXES` | const | `Readonly<{ readonly scratch: 'no-capture-'; readonly direct: 'direct-'; }>` | Names the prefixes a journey wrapper derives its own paths from. |
|
|
301
|
+
| `CAPTURE_SURVIVORS_FILE` | const | `"survivors.json"` | Names the create-only child record beneath an invocation's run directory. |
|
|
302
|
+
| `CAPTURE_MINIMUM_IMAGE` | const | `4000` | Holds the byte count under which an image is too small to be a real frame. |
|
|
303
|
+
| `CAPTURE_REPORT_LINES` | const | `Readonly<{ readonly preflight: 'READER'; readonly sheets: 'SHEETS'; }>` | Names the first word of the line a reader prints, followed by its JSON report. |
|
|
304
|
+
| `CAPTURE_SHEET` | const | `Readonly<{ readonly cell: 320; readonly limit: 400; readonly mark: Readonly<{ width: 160; height: 20; present: 220; absent: 20; }>; readonly gap: 12; readonly pairs: 2; readonly rows: 4; }>` | Holds the contact-sheet geometry: how wide a cell shrinks toward, how tall it may grow, the mark that stands in for an unreadable image, the gap between neighbors, and how many cells, rows, and pairs a row and a sheet hold. |
|
|
305
|
+
| `CAPTURE_SHEET_FILES` | const | `Readonly<{ readonly prefix: 'sheet-'; readonly digits: 3; readonly index: 'index.json'; readonly notes: 'index.md'; }>` | Names the contact-sheet files: the sheet prefix and digits, and the two index documents. |
|
|
306
|
+
| `CAPTURE_REGISTRY_STAGE` | const | `"registry"` | Names the one stage a registry refresh runs every selected producing variant's complete journey in. |
|
|
307
|
+
| `CAPTURE_REGISTRY_LINE` | const | `"REGISTRY"` | Names the first word of the line the registry refresh prints, followed by its JSON summary. |
|
|
308
|
+
| `CAPTURE_REQUESTS_FLAG` | const | `"CAPTURE_REQUESTS"` | Names the environment variable that carries the absolute request directory to a Vitest child. |
|
|
309
|
+
| `CAPTURE_DISCOVERY` | const | `Readonly<{ readonly phase: 'discover'; readonly description: 'description.json'; readonly arguments: readonly string[]; readonly deadline: 60000; }>` | Holds the discovery exchange's fixed names and bound. |
|
|
310
|
+
| `CAPTURE_SUBCOMMANDS` | const | `readonly string[]` | Names the executable's subcommands in the order its usage text lists them. |
|
|
311
|
+
| `CAPTURE_DEFAULTS` | const | `Readonly<{ readonly config: 'configs/app/vite.journey.config.ts'; readonly requests: 'tmp/capture'; readonly journeys: 'tmp/journey'; }>` | Holds the repository-relative paths the executable falls back to when the command line names none. |
|
|
312
|
+
| `CAPTURE_USAGE` | const | `string` | Holds the usage text the executable prints when it is given no subcommand or an unknown one. |
|
|
313
|
+
| `CAPTURE_PNG_LIMITS` | const | `Readonly<{ readonly pixels: number; readonly side: 131072; readonly bytes: number; }>` | Bounds decoded image memory, row metadata, and PNG input bytes independently of untrusted headers. |
|
|
314
|
+
| `CAPTURE_OWNER_TIMEOUT` | const | `1000` | Bounds a synchronous ownership retry sequence in milliseconds, including host contention. |
|
|
315
|
+
| `CAPTURE_OWNER_BACKOFF` | const | `10` | Yields between ownership probes in milliseconds so filesystem contention can settle. |
|
|
316
|
+
| `CAPTURE_MESSAGE_LIMIT` | const | `1024` | Bounds external diagnostic text while retaining the number of omitted characters. |
|
|
271
317
|
|
|
272
318
|
### Server helpers
|
|
273
319
|
|
|
274
|
-
Leaves from [`helpers.ts`](../src/server/helpers.ts): hashing, digests, registry import, flag reading, the PNG codec, the runner's parsing, and the few reads and writes of the filesystem the runner
|
|
275
|
-
|
|
276
|
-
| Name | Kind | Signature
|
|
277
|
-
| ------------------------------ | -------- |
|
|
278
|
-
| `computeCaptureHash` | function | `(bytes: string \| Uint8Array) => string`
|
|
279
|
-
| `normalizeSlashes` | function | `(path: string) => string`
|
|
280
|
-
| `buildCaptureDigest` | function | `(patterns: readonly string[], files: Readonly<Record<string, string>>) => CaptureDigest`
|
|
281
|
-
| `
|
|
282
|
-
| `
|
|
283
|
-
| `
|
|
284
|
-
| `
|
|
285
|
-
| `
|
|
286
|
-
| `
|
|
287
|
-
| `
|
|
288
|
-
| `
|
|
289
|
-
| `
|
|
290
|
-
| `
|
|
291
|
-
| `
|
|
292
|
-
| `
|
|
293
|
-
| `
|
|
294
|
-
| `
|
|
295
|
-
| `
|
|
296
|
-
| `
|
|
297
|
-
| `
|
|
298
|
-
| `
|
|
299
|
-
| `
|
|
300
|
-
| `
|
|
301
|
-
| `
|
|
302
|
-
| `
|
|
303
|
-
| `
|
|
304
|
-
| `
|
|
305
|
-
| `
|
|
306
|
-
| `
|
|
307
|
-
| `
|
|
308
|
-
| `
|
|
309
|
-
| `
|
|
310
|
-
| `
|
|
311
|
-
| `
|
|
312
|
-
| `
|
|
313
|
-
| `
|
|
314
|
-
| `
|
|
315
|
-
| `
|
|
316
|
-
| `
|
|
317
|
-
| `
|
|
318
|
-
| `
|
|
319
|
-
| `
|
|
320
|
-
| `
|
|
321
|
-
| `
|
|
322
|
-
| `
|
|
323
|
-
| `
|
|
324
|
-
| `
|
|
325
|
-
| `
|
|
326
|
-
| `
|
|
327
|
-
| `
|
|
328
|
-
| `
|
|
329
|
-
| `
|
|
330
|
-
| `
|
|
331
|
-
| `
|
|
332
|
-
| `
|
|
333
|
-
| `
|
|
334
|
-
| `
|
|
335
|
-
| `
|
|
336
|
-
| `
|
|
337
|
-
| `
|
|
338
|
-
| `
|
|
339
|
-
| `
|
|
340
|
-
| `
|
|
341
|
-
| `
|
|
342
|
-
| `
|
|
343
|
-
| `
|
|
344
|
-
| `
|
|
345
|
-
| `
|
|
346
|
-
| `
|
|
347
|
-
| `
|
|
348
|
-
| `
|
|
349
|
-
| `
|
|
320
|
+
Leaves from [`helpers.ts`](../src/server/helpers.ts): hashing, digests, registry import, flag reading, the PNG codec, the runner's parsing, and the few reads and writes of the filesystem the runner, the registry refresh, the wrapper, and the progress command make (`resolveCaptureWrapperProject`, `answerCaptureDiscovery`, `buildCaptureWrapper`, `readCaptureFrames`, `readCaptureListing`, `readCaptureInputs`, `readCaptureProgress`, `readCaptureRequest`, `writeCaptureDocument`). With the capture variable unset, `buildCaptureWrapper` removes each variant's `no-capture-<variant>` scratch directory and creates it again, empty. A helper that refuses an image or a receipt throws a `CaptureError` with the `EVIDENCE` condition; an image file the host cannot open surfaces the host's own error. `composeCapturePictures` refuses with that condition a width, a height, or a gap that is not a whole number from 0 to `CAPTURE_PNG_LIMITS.side`, and a composite wider or taller than that side or larger than the `CAPTURE_PNG_LIMITS.pixels` budget; one refusal names every faulty value, up to `CAPTURE_REFUSAL_LIMIT` of them.
|
|
321
|
+
|
|
322
|
+
| Name | Kind | Signature | Summary |
|
|
323
|
+
| ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
324
|
+
| `computeCaptureHash` | function | `(bytes: string \| Uint8Array) => string` | Hashes exact source or image bytes with SHA-256. |
|
|
325
|
+
| `normalizeSlashes` | function | `(path: string) => string` | Normalizes a host path to forward slashes. |
|
|
326
|
+
| `buildCaptureDigest` | function | `(patterns: readonly string[], files: Readonly<Record<string, string>>) => CaptureDigest` | Computes the digest of both pattern declarations and expanded path and hash membership. |
|
|
327
|
+
| `computeCaptureMatchKey` | function | `(inputs: CaptureDigest, patterns: readonly string[]) => string` | Computes the key under which a pattern list's matched subset of one input population is memoized. |
|
|
328
|
+
| `filterCaptureInputs` | function | `(inputs: CaptureDigest, patterns: readonly string[]) => ReadonlySet<string>` | Filters an input population's paths that match any listed pattern. |
|
|
329
|
+
| `buildCaptureLookupJournal` | function | `(lookups: readonly CaptureLookup[], collections: readonly CaptureCollectionReceipt[], manifest?: string) => CaptureLookupJournal` | Stores each distinct lookup input population once in a manifest-bound journal. |
|
|
330
|
+
| `readCaptureLookupJournal` | function | `(value: unknown, file: string) => CaptureLookupJournal` | Admits a decoded lookup journal, checking its declared version before its schema. |
|
|
331
|
+
| `readCaptureLookups` | function | `(journal: CaptureLookupJournal, file: string) => readonly CaptureLookup[]` | Resolves journal lookup references after verifying each stored input population's digest. |
|
|
332
|
+
| `computeCaptureTableKey` | function | `(files: Readonly<Record<string, string>>, memo: Map<Readonly<Record<string, string>>, CaptureDigest>) => string` | Computes the table key of a file map, the digest from `buildCaptureDigest([], files)`, once per map. |
|
|
333
|
+
| `buildCaptureTable` | function | `(memo: ReadonlyMap<Readonly<Record<string, string>>, CaptureDigest>) => Readonly<Record<string, Readonly<Record<string, string>>>>` | Builds a document's population table from the memo its table keys were computed through. |
|
|
334
|
+
| `readCaptureTable` | function | `(table: Readonly<Record<string, Readonly<Record<string, string>>>>, subject: string) => ReadonlyMap<string, Readonly<Record<string, string>>>` | Reads a document's population table after verifying that each map hashes to the key it is stored under. |
|
|
335
|
+
| `requireCaptureTableEntry` | function | `(table: ReadonlyMap<string, Readonly<Record<string, string>>>, key: string, subject: string, field: string) => Readonly<Record<string, string>>` | Returns the verified map a table key names, refusing a key the table does not hold. |
|
|
336
|
+
| `buildCaptureManifestDocument` | function | `(manifest: CaptureExpandedManifest) => CaptureManifestDocument` | Stores each distinct file map of an expanded manifest once, in a table keyed by the map's digest. |
|
|
337
|
+
| `readCaptureManifest` | function | `(value: unknown, file: string) => CaptureExpandedManifest` | Admits a stored manifest and expands every table reference into the file map it names. |
|
|
338
|
+
| `requireCaptureVersion` | function | `(value: unknown, subject: string, file: string, removal: readonly string[]) => void` | Refuses a document that declares a numeric version other than `CAPTURE_VERSION`, naming what to remove and the refresh commands. |
|
|
339
|
+
| `matchesCaptureVersionRefusal` | function | `(error: unknown) => boolean` | Checks whether an error is the refusal `requireCaptureVersion` throws for another document version. |
|
|
340
|
+
| `resolveCaptureRegistryFault` | function | `(error: unknown) => unknown` | Classifies a failure raised while reading the accepted registry as the registry condition. |
|
|
341
|
+
| `collectCaptureProducers` | function | `(evidence: Pick<CaptureEvidence, 'registry' \| 'runs'>) => ReadonlyMap<string, readonly string[]>` | Collects the variants that produce each destination across the registry receipts and the lookup runs. |
|
|
342
|
+
| `requireCaptureProducer` | function | `(destination: CaptureDestination, producers: ReadonlyMap<string, readonly string[]>) => string` | Returns the one variant that produces a destination, refusing a destination with none or several. |
|
|
343
|
+
| `computeRegistryDigest` | function | `(registry: Pick<CaptureRegistry, 'version' \| 'receipts' \| 'entries'>) => string` | Computes the registry identity from its authenticated receipts and exact output population. |
|
|
344
|
+
| `buildCaptureRegistry` | function | `(inputs: readonly CaptureReceiptInput[]) => CaptureRegistry` | Imports complete receipts only after their actual exits and exact report bytes validate. |
|
|
345
|
+
| `matchesCaptureSignature` | function | `(bytes: Uint8Array) => boolean` | Checks whether bytes open with the eight-byte PNG signature. |
|
|
346
|
+
| `predictCaptureByte` | function | `(left: number, up: number, corner: number) => number` | Computes the PNG Paeth predictor used by both image readers. |
|
|
347
|
+
| `readCaptureChunks` | function | `(bytes: Buffer, offset?: number) => readonly Buffer[]` | Reads PNG compressed-data chunks while refusing truncated or corrupt image bytes. |
|
|
348
|
+
| `scanCaptureChunks` | function | `(bytes: Buffer, position: number, count: number) => readonly number[]` | Walks a PNG's checked chunks from one header and returns each header's offset, up to the closing chunk. |
|
|
349
|
+
| `describeCaptureChunk` | function | `(bytes: Buffer, position: number) => string` | Describes the PNG chunk whose header sits at an offset by its type, offset, and length. |
|
|
350
|
+
| `unfilterCaptureRow` | function | `(filter: number, line: Uint8Array, above: Uint8Array \| undefined, channels: number) => Uint8Array` | Reconstructs one filtered PNG scanline from its filter byte and the row above. |
|
|
351
|
+
| `inflateCaptureStream` | function | `(data: Buffer, length: number) => Buffer` | Inflates a PNG's compressed stream, refusing one that is corrupt or longer than declared. |
|
|
352
|
+
| `decodeCapturePicture` | function | `(bytes: Buffer) => CapturePicture` | Decodes the eight-bit, non-interlaced PNGs the capture readers consume. |
|
|
353
|
+
| `encodeCaptureWord` | function | `(value: number) => Buffer` | Encodes an unsigned 32-bit integer as four big-endian bytes. |
|
|
354
|
+
| `encodeCaptureChunk` | function | `(name: string, data: Buffer) => Buffer` | Encodes one checked PNG chunk for contact-sheet output. |
|
|
355
|
+
| `encodeCapturePicture` | function | `(picture: CapturePicture, compressed?: boolean) => Buffer` | Encodes an RGB picture using the contact-sheet writer's native PNG format. |
|
|
356
|
+
| `sumCaptureRow` | function | `(pixels: Uint8Array, start: number, columns: number) => number` | Sums a run of samples three bytes apart, one channel of consecutive RGB pixels. |
|
|
357
|
+
| `sumCaptureBlock` | function | `(picture: CapturePicture, top: number, left: number, row: number, rows: number, columns: number) => number` | Sums one channel of a picture over a block of source rows. |
|
|
358
|
+
| `shrinkCapturePicture` | function | `(picture: CapturePicture, factor: number, limit: number) => CapturePicture` | Scales a picture with an exact area average and clips its displayed height. |
|
|
359
|
+
| `composeCapturePictures` | function | `(pictures: readonly CapturePicture[], vertical: boolean, gap?: number) => CapturePicture` | Composes pictures on the contact-sheet gray background. |
|
|
360
|
+
| `computeCaptureComposite` | function | `(pictures: ReadonlyArray<Pick<CapturePicture, 'width' \| 'height'>>, vertical: boolean, gap?: number) => Pick<CapturePicture, 'width' \| 'height'>` | Computes the width and height of the composite that `composeCapturePictures` builds from pictures of these sizes. |
|
|
361
|
+
| `matchesCaptureLimits` | function | `(picture: Pick<CapturePicture, 'width' \| 'height'>) => boolean` | Checks whether a picture size fits `CAPTURE_PNG_LIMITS`, per side and in pixels. |
|
|
362
|
+
| `readCaptureRequestOwner` | function | `(name: string) => number \| undefined` | Reads the process id that a request file, or its temporary sibling, names. |
|
|
363
|
+
| `describeCaptureHolders` | function | `(holders: readonly CaptureHolder[], directory: string) => string` | Describes the request holders that keep a workspace busy, naming apart those the host could not inspect. |
|
|
364
|
+
| `resolveCaptureRelative` | function | `(root: string, target: string) => string` | Resolves a path to the slash-separated form the evidence documents store, relative to a root. |
|
|
365
|
+
| `escapeCapturePattern` | function | `(text: string) => string` | Escapes every regular-expression metacharacter so a case name matches only itself. |
|
|
366
|
+
| `buildCaptureFilter` | function | `(command: CaptureCommand, selector: string, selectors: readonly string[]) => string` | Builds the tag expression that selects an owner population, and its capture tags for frames. |
|
|
367
|
+
| `resolveCaptureStages` | function | `(variants: readonly string[], first: string, command: CaptureRequest['command']) => readonly CaptureStagePlan[]` | Plans one selected journey stage or narrow and remaining frame stages. |
|
|
368
|
+
| `resolveCaptureVariants` | function | `(selected: readonly string[], projects: readonly CaptureProject[]) => readonly string[]` | Resolves selected producing variants in declaration order and requires their projects. |
|
|
369
|
+
| `buildCaptureChangePlan` | function | `(paths: readonly string[], entries: readonly CaptureDestination[]) => CaptureChangePlan` | Classifies changed paths through accepted patterns and reduces owners by ancestry. |
|
|
370
|
+
| `renderCaptureCommand` | function | `(command: CaptureCommand \| 'registry', parsed: CaptureRunnerArguments, selector: string \| undefined, root: string) => string` | Renders an exact owner command with the selected variants and filters in host shell syntax. |
|
|
371
|
+
| `buildCaptureArguments` | function | `(options: CaptureArgumentsOptions) => readonly string[]` | Builds the exact Node argument array that spawns one Vitest stage. |
|
|
372
|
+
| `readCaptureOptions` | function | `<Options extends ParseArgsOptionsConfig>(argv: readonly string[], options: Options, usage: string) => CaptureParsedArguments<Options>` | Parses standard option tokens and refuses empty values, terminators, and repeated single options. |
|
|
373
|
+
| `readCaptureArguments` | function | `(argv: readonly string[], command: CaptureCommand, root: string, fallback: string) => CaptureRunnerArguments` | Reads the runner's command line into one selector, its flags, and the resolved wrapper path. |
|
|
374
|
+
| `readCapturePortfolios` | function | `(value: unknown, subject: string) => readonly CapturePortfolioRoot[]` | Reads the physical portfolio roots a wrapper declares and refuses a malformed or repeated root. |
|
|
375
|
+
| `readCaptureProject` | function | `(test: unknown) => CaptureProject` | Reads one wrapper project's host declarations from its Vitest test configuration. |
|
|
376
|
+
| `describeCapturePortfolios` | function | `(project: Pick<CaptureProject, 'portfolios' \| 'standalone'>) => readonly string[]` | Describes a project's portfolio roots as comparable lines, primary roots apart from standalone ones. |
|
|
377
|
+
| `requireCaptureProjects` | function | `(projects: readonly CaptureProject[]) => CaptureProject` | Refuses a wrapper project set whose members repeat or disagree on a host declaration. |
|
|
378
|
+
| `describeCaptureSelectorFault` | function | `(selector: string, selectors: readonly string[]) => string \| undefined` | Describes why a selector names nothing the wrapper declares, naming the first unknown segment. |
|
|
379
|
+
| `buildCaptureRequestRefusal` | function | `(file: string, cause?: unknown) => CaptureError` | Builds the refusal a wrapper raises for a request file it cannot accept as its parent's. |
|
|
380
|
+
| `readCaptureRequest` | function | `(options: CaptureRequestOptions) => CaptureRequest \| undefined` | Reads and validates the request the runner wrote for the wrapper process that is its child. |
|
|
381
|
+
| `readCaptureReaderArguments` | function | `(argv: readonly string[], root: string, defaults: CaptureReaderDefaults, command?: 'preflight' \| 'sheets') => CaptureReaderCommand` | Reads a reader's command line into its selection, its flags, and the resolved paths. |
|
|
382
|
+
| `readCaptureViewport` | function | `(test: unknown) => CaptureViewport` | Reads the viewport a wrapper project's producing variant declares. |
|
|
383
|
+
| `buildCaptureIntegrityOptions` | function | `(root: string, project: CaptureProject, standalone?: CapturePortfolioRoot) => CaptureIntegrityOptions` | Derives the integrity engine's options from a wrapper project's host declarations. |
|
|
384
|
+
| `scanCaptureFrames` | function | `(images: readonly CaptureImageResult[], producers: readonly CaptureProducer[]) => readonly string[]` | Reports a portfolio, owner, and viewport whose frames mix cropped, viewport-sized, and page-sized images. |
|
|
385
|
+
| `collectCaptureIdentical` | function | `(images: readonly CaptureImageResult[]) => ReadonlyArray<readonly string[]>` | Groups the selected images whose bytes are identical. |
|
|
386
|
+
| `buildCaptureReaderReport` | function | `(result: CapturePreflightResult) => CaptureReaderReport` | Builds the report a preflight prints and a contact-sheet index carries from one preflight result. |
|
|
387
|
+
| `collectCaptureErrors` | function | `(file: string, text: string) => readonly string[]` | Finds the journey artifact lines that report an uncaught, unhandled, or logged error. |
|
|
388
|
+
| `resolveCaptureWrapperProject` | function | `(input: unknown, mode?: string) => Promise<unknown>` | Resolves one entry of a wrapper's project list to the project it declares. |
|
|
389
|
+
| `readCaptureEntry` | function | `(value: unknown) => CaptureHostEntry` | Reads one wrapper project, as the description file holds it, into its host declarations and viewport. |
|
|
390
|
+
| `resolveCaptureRequests` | function | `(directory?: string) => string` | Resolves the directory that holds the runner's request files for the process that reads them. |
|
|
391
|
+
| `buildCaptureDiscoveryConfig` | function | `() => CaptureDiscoveryConfig` | Builds the empty Node configuration a wrapper returns once it has answered a discovery request. |
|
|
392
|
+
| `readCaptureDescription` | function | `(value: unknown, expected: CaptureDescriptionExpectation) => CaptureHostDescription` | Accepts the description a wrapper wrote only when it answers this exchange and no other. |
|
|
393
|
+
| `answerCaptureDiscovery` | function | `(options: CaptureDiscoveryOptions) => Promise<boolean>` | Answers the runner's discovery request from the wrapper, before the wrapper does any other work. |
|
|
394
|
+
| `readCaptureListing` | function | `<TEntry>(directory: string, list: (path: string) => readonly TEntry[]) => readonly TEntry[]` | Lists a directory through a reader, answering an empty list for a missing directory. |
|
|
395
|
+
| `readCaptureFrames` | function | `(directory: string, scopes: readonly string[]) => readonly string[]` | Lists the frames a portfolio directory holds, as paths relative to it, in sorted order. |
|
|
396
|
+
| `readCaptureProgress` | function | `(root: string, requests: string, now?: number, alive?: (pid: number) => boolean \| undefined) => CaptureProgress` | Reads the progress file of the stage that is running, or that ran last, in a workspace. |
|
|
397
|
+
| `renderCaptureProgress` | function | `(progress: CaptureProgress) => string` | Renders a progress reading as the text `capture progress` prints. |
|
|
398
|
+
| `buildCaptureOverride` | function | `(options: Omit<CaptureWrapperOptions<unknown>, 'url' \| 'project'>, variant: CaptureViewport, provided: Pick<CaptureProvided, 'directory' \| 'record' \| 'capture' \| 'request'>) => CaptureWrapperOverride` | Builds the values capture merges into one variant's Vitest project. |
|
|
399
|
+
| `buildCaptureWrapper` | function | `<TProject>(options: CaptureWrapperOptions<TProject>) => Promise<CaptureWrapperConfig<TProject> \| CaptureDiscoveryConfig>` | Builds a journey wrapper's Vitest configuration as plain data, answering discovery first. |
|
|
400
|
+
| `readCaptureRegistryArguments` | function | `(argv: readonly string[], root: string, fallback: string) => CaptureRegistryArguments` | Reads the registry command line into the wrapper path, the variants to refresh, and the mode. |
|
|
401
|
+
| `readCaptureInputs` | function | `(root: string, patterns: readonly string[], hash?: CaptureHashHandler, read?: CaptureInputHandler) => Readonly<Record<string, string>>` | Reads the bounded input population a project declares, as file paths and content hashes. |
|
|
402
|
+
| `writeCaptureDocument` | function | `(path: string, value: unknown, signal?: AbortSignal) => void` | Writes one JSON document atomically, so a reader sees the old bytes or the new and never a part. |
|
|
403
|
+
| `readCaptureAncestor` | function | `(path: string) => string` | Finds the nearest existing path without following a dangling link. |
|
|
404
|
+
| `resolveCapturePhysical` | function | `(path: string) => string` | Resolves an existing path or its nearest existing ancestor to its physical destination. |
|
|
405
|
+
| `requireCaptureContained` | function | `(root: string, path: string) => string` | Validates a physical destination against a physical root before any read or write. |
|
|
406
|
+
| `resolveCaptureSheetIdentity` | function | `(entry: CaptureDestination) => string` | Names a sheet group by portfolio, owner, and state independently of its output variant. |
|
|
407
|
+
| `splitCapturePages` | function | `<T>(entries: readonly T[], size: number) => ReadonlyArray<readonly T[]>` | Splits a list into consecutive pages with at most the requested size. |
|
|
408
|
+
| `splitCaptureSheets` | function | `<T extends Pick<CapturePicture, 'width' \| 'height'>>(rows: readonly T[], size: number, gap: number) => ReadonlyArray<readonly T[]>` | Splits contact-sheet rows into consecutive pages of at most `size` rows whose stacked composite fits `CAPTURE_PNG_LIMITS`. |
|
|
409
|
+
| `matchesCaptureFile` | function | `(previous: CaptureFileSnapshot, current: CaptureFileSnapshot \| undefined) => boolean` | Compares file content, size, modification time, and change time across two snapshots. |
|
|
410
|
+
| `mergeCaptureLookups` | function | `(previous: readonly CaptureLookup[], lookups: readonly CaptureLookup[]) => readonly CaptureLookup[]` | Merges unique lookup populations with incoming identities replacing inherited ones. |
|
|
411
|
+
| `describeCaptureFault` | function | `(path: string, value: unknown, expected: string, candidates?: readonly string[], required?: readonly string[], allowed?: readonly string[]) => string` | Describes a refusal with its key path, bounded preview, correction, and member differences. |
|
|
412
|
+
| `resolveCaptureExit` | function | `(error: unknown) => number` | Maps usage refusals to exit 64 and every other failure to exit 1. |
|
|
413
|
+
| `requireCaptureArgument` | function | `(root: string, path: string, flag: string) => string` | Validates a supplied path argument before work and classifies an outside value as usage. |
|
|
414
|
+
| `matchesCaptureTransient` | function | `(error: unknown, platform?: NodeJS.Platform) => boolean` | Recognizes filesystem contention codes that ownership arbitration can retry. |
|
|
415
|
+
| `settleCaptureShutdown` | function | `(retract: CaptureRetractionHandler, terminations: readonly CaptureTerminationHandler[]) => Promise<readonly unknown[]>` | Settles independent request removal and child termination without hiding either failure. |
|
|
416
|
+
| `describeCaptureMembers` | function | `(members: readonly string[]) => string` | Describes a bounded member population and the number omitted from its preview. |
|
|
417
|
+
| `describeCaptureOutput` | function | `(output: string) => string` | Caps external diagnostic text and names the number of omitted characters. |
|
|
418
|
+
| `requireCaptureSelection` | function | `(selector: string, variants: readonly string[], projects: readonly CaptureProject[], outputs?: readonly string[], portfolio?: string) => void` | Refuses unknown command selections from the wrapper before authenticating disk evidence. |
|
|
419
|
+
| `collectCaptureOwners` | function | `(projects: readonly CaptureProject[]) => readonly string[]` | Collects the owner selectors the projects' owner tags declare, once each, in tag order. |
|
|
420
|
+
| `resolveCaptureStandalone` | function | `(roots: readonly CapturePortfolioRoot[], selector: string, portfolio?: string) => CapturePortfolioRoot \| undefined` | Picks the standalone portfolio root a selection names by its selector or its portfolio. |
|
|
421
|
+
| `readCaptureVariants` | function | `(root: string, file: string) => readonly string[]` | Reads output variant candidates without authenticating or accepting registry evidence. |
|
|
422
|
+
| `readCaptureImage` | function | `(file: string) => Buffer` | Reads an image only after its opened file's size is inside the compressed-byte budget. |
|
|
423
|
+
| `readCaptureSeparator` | function | `(entry: string) => string` | Reads the installed workspace Vitest's exact title separator, refusing unsupported majors. |
|
|
424
|
+
| `readCaptureTitles` | function | `(root: string, file: string, selector?: string) => Readonly<Record<string, readonly string[]>>` | Reads original title segments from the accepted registry's authenticated JSON reporter files. |
|
|
425
|
+
| `requireCaptureImageSize` | function | `(size: number) => void` | Refuses compressed image bytes before file reads or chunk-buffer allocation. |
|
|
350
426
|
|
|
351
427
|
### Server classes and factories
|
|
352
428
|
|
|
@@ -475,13 +551,17 @@ const result = await integrity.check({ selector: 'pages:mail' })
|
|
|
475
551
|
result.entries.map((entry) => entry.status) // one classification per selected frame
|
|
476
552
|
```
|
|
477
553
|
|
|
478
|
-
`stamp` is the only method that writes. It snapshots the bounded inputs, runs the runner's child once, and validates every selected final record against the reporter before it replaces the manifest in one atomic rename; a failure before that rename leaves the prior manifest bytes untouched, and a journey publishes lookups and full-collection receipts in the separate journal instead. `check` classifies each selected frame as `duplicate`, `orphan`, `missing`, `unstamped`, `stale-shared`, `stale-own`, or `current`, and keeps every finding that justified the class. `read` and `lookup` start no process: they resolve a selection or a state from evidence
|
|
554
|
+
`stamp` is the only method that writes. It snapshots the bounded inputs, runs the runner's child once, and validates every selected final record against the reporter before it replaces the manifest in one atomic rename; a failure before that rename leaves the prior manifest bytes untouched, and a journey publishes lookups and full-collection receipts in the separate journal instead. `check` classifies each selected frame as `duplicate`, `orphan`, `missing`, `unstamped`, `stale-shared`, `stale-own`, or `current`, and keeps every finding that justified the class. `read` and `lookup` start no process: they resolve a selection or a state from evidence. A `read` refusal names the explicit refresh to prepare. A `lookup` refusal of the requested state, under `USAGE`, `SELECTION`, or `LOOKUP`, names the owner's journey refresh, and a fault in the evidence it read keeps its own text, a `REGISTRY` refusal included.
|
|
479
555
|
|
|
480
|
-
Every refusal is a `CaptureError`. An unknown value for a declared selector,
|
|
556
|
+
Every refusal is a `CaptureError`. An unknown value for a declared selector, state, case, or portfolio is `USAGE`, as is an empty selector; internal selection disagreements carry `SELECTION`. The engine does not check a selected variant against the wrapper's declarations, so `read`, `check`, and `lookup` code a selected variant outside the registry's attested set `REGISTRY`. Before that read, `journey` and `frames` refuse a variant the wrapper does not declare as `USAGE`; `stale`, `preflight`, and `sheets` also accept an output variant the registry holds. A wrapper fault is `HOST`; a stage that did not complete or whose inputs moved is `STAGE`; a registry that is absent, fails authentication, or lags the declarations is `REGISTRY`, and an absent or stale state lookup is `LOOKUP`; a record, report, or manifest that fails its protocol is `EVIDENCE`; and a path that leaves the integrity root or an authorized portfolio root is `CONTAINMENT`. The executable maps `USAGE` to exit 64 and every other failure to exit 1. Commands check selectors against the discovered wrapper before registry authentication. Reader variants derive from the selected owner and portfolio before state and case validation, so an unknown state or case names its own candidates.
|
|
481
557
|
|
|
482
558
|
The engine reads each file once per pass through a memo it discards when the pass ends, so a source hashed before the child, in the record pass, and in the final check costs three readings, never one per destination. Evidence reading also memoizes validated physical paths for that pass. The record pass and final check each validate an identical own/shared/tests pattern triple once against its pre-stage input population. Physical-image comparisons read each path's identity once per pass. The final check rereads disk with fresh memos, so a file changed between passes refuses the stage.
|
|
483
559
|
|
|
484
|
-
**Lookup journal.** `lookups.json` holds `version`, an optional predecessor `manifest` digest,
|
|
560
|
+
**Lookup journal.** `lookups.json` holds `version`, an optional predecessor `manifest` digest, a `populations` table, `lookups`, and optional `collections`. Each table key is the digest from `buildCaptureDigest([], files)`, where `files` is the stored path-to-hash map. Each lookup's `inputs` field names a table key, so lookups that share the same input population store that map once. `readCaptureLookupJournal` admits the journal for the engine and the registry refresh, checking its declared version before its schema. The engine verifies each table map's digest before expanding the active journal. A missing reference refuses with `Lookup journal at FILE names an unknown inputs digest` and the digest, where `FILE` is the journal path; an altered map refuses with `Lookup journal at FILE stores a population that does not hash to its key` and the key. Malformed schemas, duplicate lookup identities, missing or changed run records, unauthorized runner records, registry declaration disagreements, and mismatches with passing declarations retain their refusals. Stale input hashes still refuse state resolution. Journal publication uses the same atomic rename, and the predecessor manifest digest still determines whether the journal applies. Returned lookup results carry expanded input maps.
|
|
561
|
+
|
|
562
|
+
**Manifest table.** `manifest.json` holds `version`, a `populations` table, the `registry`, `entries`, `lookups`, and optional `collections`, the `CaptureManifestDocument` shape. The table follows the journal's key rule: it stores each distinct path-to-hash map once, under the digest from `buildCaptureDigest([], files)`. Each stamp's `shared.files`, each lookup's `inputs`, and each collection receipt's `inputs.files` names a table key, so stamps that share a shared-source population, and lookups and collections that share an input population, store that map once. A stamp's `own` and `tests` maps and the registry stay in place. `stamp` writes the table through `buildCaptureManifestDocument`. `readCaptureManifest` admits the document for the engine, the preflight, and the registry refresh: it verifies each table map's digest, expands every reference, and returns the expanded `CaptureExpandedManifest` the engine works on. Every refusal names the manifest path. An altered map refuses with `Manifest at FILE stores a population that does not hash to its key` and the key; a reference to a key the table does not hold refuses with `Manifest at FILE names an unknown FIELD digest` and the key, where `FIELD` is the referencing field: `shared.files`, `inputs`, or `inputs.files`.
|
|
563
|
+
|
|
564
|
+
**Document version.** `CAPTURE_VERSION` is 2, and every request, record, receipt, registry, journal, and manifest declares it. A registry, lookup journal, or manifest that declares another version, such as a version-1 document that capture 0.0.9 wrote, is refused as `EVIDENCE` before its schema is read, and no conversion runs. `requireCaptureVersion` builds the refusal: it names the file, what to remove, and the refresh, `capture registry`, then `capture frames all`. A registry refusal names the registry, the manifest, and the lookup journal; a journal refusal names the journal; a manifest refusal names the manifest and its lookup journal. `read`, `lookup`, the registry refresh, and the runner commands pass the refusal through unchanged, so it carries its own recovery alone: the runner prints no `NEXT` line after it, and a `--changed` run ends at it with no `SUMMARY`. `matchesCaptureVersionRefusal` recognizes it.
|
|
485
565
|
|
|
486
566
|
### Runner
|
|
487
567
|
|
|
@@ -511,13 +591,15 @@ const runner = createCaptureRunner({
|
|
|
511
591
|
const exit = await runner.execute() // 0 when every stage passed and work ran
|
|
512
592
|
```
|
|
513
593
|
|
|
514
|
-
The exit is 0 when every stage is green and work ran, 64 for `USAGE`, and 1 for every other failure. Unknown selector, variant, state, case, and portfolio arguments, empty selectors, and refused command syntax carry `USAGE`. A wrapper fault is `HOST`; a failed or interrupted stage is `STAGE`. Discovery, ownership, and evidence failures can occur before an execution child starts and still exit 1. The runner maps the condition, never the message text or whether a child started. Before any execution stage, an explicit case is checked against the accepted registry's authenticated reporter collection. A missing registry refuses with `capture registry`; an unknown case refuses with its candidates and exit 64.
|
|
594
|
+
The exit is 0 when every stage is green and work ran, 64 for `USAGE`, and 1 for every other failure. Unknown selector, variant, state, case, and portfolio arguments, empty selectors, and refused command syntax carry `USAGE`. A wrapper fault is `HOST`; a failed or interrupted stage is `STAGE`. An accepted registry that is absent, fails authentication, or lags the declarations is `REGISTRY`, a variant the wrapper declares and the registry never attested is `REGISTRY` under `--variant` too, and an absent or stale state lookup is `LOOKUP`. Discovery, ownership, and evidence failures can occur before an execution child starts and still exit 1. The runner maps the condition, never the message text or whether a child started. Before any execution stage, an explicit case is checked against the accepted registry's authenticated reporter collection. A missing registry refuses with `capture registry`; an unknown case refuses with its candidates and exit 64.
|
|
595
|
+
|
|
596
|
+
**Next commands.** Every outcome prints its `NEXT` lines once each, after its last report line: on stdout after a `STAGES`, `SUMMARY`, or `INTEGRITY` report, and otherwise on stderr after the refusal. `CAPTURE_RECOVERIES` maps each condition to the command that clears it: `REGISTRY` prints `capture registry`, and `LOOKUP` prints `capture journey <selector>`. The registry refresh writes the primary registry alone, so a `REGISTRY` refusal of a `stale` reading that selects a standalone root prints no `NEXT` line. A run whose execution child launched and did not pass, or that was interrupted during discovery or a stage, then prints its own command; a changed run interrupted in discovery has no selector, so it prints none. Every other condition prints no `NEXT` line, and neither does a document version refusal. `renderCaptureCommand` renders each printed command. A command that keeps the run's selection, which is the owner command, the retry, or the lookup refresh, carries each flag of the run that its own command declares. The registry refresh carries `--mode` and the wrapper, and the complete journey also carries `--variant`. No printed command carries `--changed` or `--plan`. After a `stale` report, `CAPTURE_STATUS_RECOVERIES` decides the line: a `missing`, `unstamped`, `stale-shared`, or `stale-own` frame prints `capture frames <selector>` with `--case`, `--mode`, and the wrapper, and no `--state` or `--variant`, because a frames run over the selector restamps every state and every producing variant. A `duplicate`, an `orphan`, a current reading, and a standalone selection print none.
|
|
515
597
|
|
|
516
|
-
**Journey stage.** A journey runs all selected variants in declaration order in one execution child with `--bail=1`, under the stage name `selected`. Its stage line names every selected variant, its request carries that same list, and one stamping transaction validates all selected records before publishing lookup and collection receipts. Records remain keyed by run, stage, and variant at `<directory>/runs/<id>/selected/<variant>.json`. A failed, bailed, or interrupted child publishes no evidence from that stage. An invocation with no applicable work exits 1.
|
|
598
|
+
**Journey stage.** A journey runs all selected variants in declaration order in one execution child with `--bail=1`, under the stage name `selected`. `--no-bail` on journey, frames, or registry omits the flag, so a stage runs every selected case after a failure, and the stage's request and each printed `NEXT` command that names a selected owner carry the choice. Its stage line names every selected variant, its request carries that same list, and one stamping transaction validates all selected records before publishing lookup and collection receipts. Records remain keyed by run, stage, and variant at `<directory>/runs/<id>/selected/<variant>.json`. A failed, bailed, or interrupted child publishes no evidence from that stage. An invocation with no applicable work exits 1 as `SELECTION`, with no `NEXT` line, because rerunning that selection finds the same empty workload.
|
|
517
599
|
|
|
518
|
-
**Frame stages.** `frames` keeps the `first` variant alone in `narrow`, then every other selected variant together in `rest`, so narrow frames can be inspected first. Omitting the first variant runs only `rest`; the runner adds no unselected variant. A failed stage stops later stages. An inapplicable narrow stage prints why the rest stage carries the selector and continues. A `STAGES` JSON line names the stages run, passed, failed, and not run, with the reason
|
|
600
|
+
**Frame stages.** `frames` keeps the `first` variant alone in `narrow`, then every other selected variant together in `rest`, so narrow frames can be inspected first. Omitting the first variant runs only `rest`; the runner adds no unselected variant. A failed stage stops later stages. An inapplicable narrow stage prints why the rest stage carries the selector and continues. A `STAGES` JSON line names the stages run, passed, failed, and not run, with the reason. A run of one selector then prints its `NEXT` lines: the command its refusal's condition maps to, then the owner's exact command after a stage that launched and did not pass. After a pass it prints `capture journey all` with the run's variants, mode, and wrapper, unless the run is itself a journey of `all` with no `--case`, whatever its `--no-bail`. A document version refusal prints none.
|
|
519
601
|
|
|
520
|
-
**Changed selection.** For journey or frames, use `--changed <ref>` instead of a selector. The flag takes exactly one Git ref and cannot accompany a positional selector. `HEAD` selects uncommitted work. The engine authenticates the accepted registry, resolves the ref's merge-base with HEAD, reads `git diff --name-only --no-renames -z <merge-base> --`, and adds `git ls-files --others --exclude-standard -z`. Renames contribute both paths; deleted paths and names containing spaces remain intact. Every Git read uses `executeSync` with a 30-second deadline and a 64 MiB output limit; failed or truncated reads are refused before any NUL-separated names are consumed. An unknown ref, failed Git read, timeout, or truncated result exits 1 as a `HOST` failure. A missing registry prints `Missing accepted registry; run the explicit complete-registry refresh`
|
|
602
|
+
**Changed selection.** For journey or frames, use `--changed <ref>` instead of a selector. The flag takes exactly one Git ref and cannot accompany a positional selector. `HEAD` selects uncommitted work. The engine authenticates the accepted registry, resolves the ref's merge-base with HEAD, reads `git diff --name-only --no-renames -z <merge-base> --`, and adds `git ls-files --others --exclude-standard -z`. Renames contribute both paths; deleted paths and names containing spaces remain intact. Every Git read uses `executeSync` with a 30-second deadline and a 64 MiB output limit; failed or truncated reads are refused before any NUL-separated names are consumed. An unknown ref, failed Git read, timeout, or truncated result exits 1 as a `HOST` failure. A missing registry prints `Missing accepted registry; run the explicit complete-registry refresh`. A refused changed selection prints `capture registry` with the wrapper as its one `NEXT` line when the refusal is `REGISTRY`, and no `NEXT` line otherwise.
|
|
521
603
|
|
|
522
604
|
Each path gets exactly one class through the registry's native glob patterns. `own` matches a destination's own sources and names every matching owner. `shared` matches any shared or test pattern and names every destination owner; it takes precedence when a path also matches own sources. `outside` matches no source pattern and names no owner. The selected owners come from own paths, sorted and reduced by colon-delimited ancestry, so selecting a page drops its selected sections.
|
|
523
605
|
|
|
@@ -530,9 +612,9 @@ SUMMARY {"run":[],"passed":[],"failed":[],"notrun":["pages:mail"],"reason":"--pl
|
|
|
530
612
|
NEXT capture journey pages:mail --config configs/app/vite.journey.config.ts
|
|
531
613
|
```
|
|
532
614
|
|
|
533
|
-
Any shared path refuses the whole changed run with exit 64, listing those paths and explaining that every destination reads them, so they cannot be narrowed. This refusal is usage because the invocation must change to an explicit journey selection. The output includes per-owner commands for own changes and `capture journey all` with the effective wrapper and variant flags for the shared proof. No owner starts automatically. Without own or shared paths, an execution exits 1 with `No journey input changed
|
|
615
|
+
Any shared path refuses the whole changed run with exit 64, listing those paths and explaining that every destination reads them, so they cannot be narrowed. This refusal is usage because the invocation must change to an explicit journey selection. The output includes per-owner commands for own changes and `capture journey all` with the effective wrapper and variant flags for the shared proof. No owner starts automatically. Without own or shared paths, an execution exits 1 with `No journey input changed`, lists the outside paths, and prints `capture journey all` with the effective wrapper and variant flags as its `NEXT` line.
|
|
534
616
|
|
|
535
|
-
Without `--plan`, the runner executes each reduced owner through the ordinary single-selector path in stable order and stops at the first red owner. Every owner gets a distinct run ID, so its stage records remain available. The final `SUMMARY` names owners run, passed, failed, and not run, gives the stopping reason
|
|
617
|
+
Without `--plan`, the runner executes each reduced owner through the ordinary single-selector path in stable order and stops at the first red owner. Every owner gets a distinct run ID, so its stage records remain available. An owner refused before execution, an unusable request directory included, prints its refusal and counts as failed and not run, so the run still reaches its `SUMMARY`. The final `SUMMARY` names owners run, passed, failed, and not run, and gives the stopping reason. Its `NEXT` lines give the lines the failed owner's run recorded, then the exact command of each owner not run, or `capture journey all` with the effective wrapper, variant, and mode flags when every owner passed; an owner's own `STAGES` line is followed by none. A document version refusal ends the run before the `SUMMARY`, with no `NEXT` line. `--variant`, `--case`, and the frames-only `--state` retain their ordinary meanings; a command printed for the shared proof carries no case or state narrowing. The changed flags never enter the request protocol.
|
|
536
618
|
|
|
537
619
|
### Choosing what to run
|
|
538
620
|
|
|
@@ -546,11 +628,13 @@ Climb from the smallest applicable selection to the gate:
|
|
|
546
628
|
- A group: `capture journey pages`.
|
|
547
629
|
- The gate: `capture journey all`.
|
|
548
630
|
|
|
631
|
+
**Recommended pass.** To judge the whole population, run `capture registry`, `capture frames all`, `capture stale all`, and `capture sheets all --output tmp/sheets`, in that order. The `sheets` command runs the preflight read and prints every member of the `READER` line in its `SHEETS` line, so `capture preflight all` adds nothing after it. `capture journey all` adds nothing after `registry`, which already runs every journey case. The limit: a scoped `--state` request still needs journey or frames evidence for that state, because `sheets` reads only frames that exist.
|
|
632
|
+
|
|
549
633
|
Use only owner and case names the wrapper declares. Follow a refusal's exact next commands before widening a selection.
|
|
550
634
|
|
|
551
635
|
### Runner selection and process protocol
|
|
552
636
|
|
|
553
|
-
**Selection.** A selector is `all` or an owner path the wrapper's tags declare; each segment is checked, and the refusal names the first unknown one, labelled `scope` at the first depth and `owner` below it. A journey filters on `owner:<selector>`. A capture also intersects the capture tag, which is the selector's scope and part, and `all` unions every declared scope. `--case` selects one case by its exact full name, and the runner passes the anchored pattern for that case and the final case with every regular-expression metacharacter quoted. The runner reads original title segments from authenticated registry reporters and joins them with the installed Vitest major's separator
|
|
637
|
+
**Selection.** A selector is `all` or an owner path the wrapper's tags declare; each segment is checked, and the refusal names the first unknown one, labelled `scope` at the first depth and `owner` below it. A journey filters on `owner:<selector>`. A capture also intersects the capture tag, which is the selector's scope and part, and `all` unions every declared scope. `--case` selects one case by its exact full name, and the runner passes the anchored pattern for that case and the final case with every regular-expression metacharacter quoted. The runner reads original title segments from authenticated registry reporters and joins them with the installed Vitest major's separator, a `>` character surrounded by spaces for Vitest 5. `--state` asks the engine for the declaring case after discovery and refuses before any execution child when the engine's evidence is missing, stale, or ambiguous.
|
|
554
638
|
|
|
555
639
|
**Discovery.** Before it plans anything, the runner publishes an atomic request whose phase is `discover` and spawns the consumer's installed Vitest entry directly (`process.execPath` with `node_modules/vitest/vitest.mjs`) as `list --filesOnly --config <wrapper> --configLoader runner`, with the capture variable set so a wrapper's destructive no-capture initialization never runs. The wrapper calls `answerCaptureDiscovery` before it does any other work, writes its description atomically beside the invocation's logs, and returns `buildCaptureDiscoveryConfig()`, an empty Node configuration, so Vitest sets up no browser, initializes no output, and collects no test. The runner accepts the description only after the child exited zero and every echo in it matches the exchange: the invocation, a fresh challenge, the wrapper, the runner as the wrapper's parent, and the spawned child as its writer. A wrapper that never answers, answers another exchange, writes an unreadable or empty description, exits nonzero, or outlives the deadline (`CAPTURE_DISCOVERY.deadline`, replaceable through the `deadline` option) is refused as a `HOST` condition, and a request from another parent, with other arguments, version, identity, or wrapper, is refused by the wrapper. A syntax error in the command line refuses before any child; an unknown selector or variant refuses after discovery and before any execution child.
|
|
556
640
|
|
|
@@ -569,9 +653,35 @@ const answered = await answerCaptureDiscovery({
|
|
|
569
653
|
export default answered ? buildCaptureDiscoveryConfig() : { test: { projects } }
|
|
570
654
|
```
|
|
571
655
|
|
|
656
|
+
**Wrapper.** `buildCaptureWrapper` assembles the whole wrapper from the host's declarations and returns plain configuration, so a wrapper is one call inside its own `defineConfig` callback:
|
|
657
|
+
|
|
658
|
+
```ts
|
|
659
|
+
import { buildCaptureWrapper } from '@orkestrel/capture/server'
|
|
660
|
+
import { defineConfig } from 'vitest/config'
|
|
661
|
+
|
|
662
|
+
export default defineConfig(() =>
|
|
663
|
+
buildCaptureWrapper({
|
|
664
|
+
url: import.meta.url,
|
|
665
|
+
variants: [{ name: 'light-390', width: 390, height: 844 }],
|
|
666
|
+
owners: ['pages:mail'],
|
|
667
|
+
first: 'light-390',
|
|
668
|
+
final: 'closes the run',
|
|
669
|
+
directory: 'tmp/captures/states',
|
|
670
|
+
inputs: ['src/**'],
|
|
671
|
+
sources: { shared: ['src/core/**'], tests: ['tests/**'] },
|
|
672
|
+
portfolios: [{ portfolio: 'states', directory: 'tmp/captures/states', scoped: true }],
|
|
673
|
+
project: (variant, override) => ({
|
|
674
|
+
test: { ...override.test, name: `journey:${variant.name}` },
|
|
675
|
+
}),
|
|
676
|
+
}),
|
|
677
|
+
)
|
|
678
|
+
```
|
|
679
|
+
|
|
680
|
+
It answers discovery first, describing each project as `{ name, tags, provide }` under the name the host's `project` chose, and returns `buildCaptureDiscoveryConfig()`. The wrapper path is `url` relative to the working directory, which is the workspace root for every child the runner spawns. A variant whose name is no capture segment refuses as `HOST` before any directory work, as does a variant whose `no-capture-<variant>` scratch directory is, contains, or sits inside the evidence root or a portfolio root. An execution child reads the runner's request and passes each variant's `CaptureWrapperOverride` to the host's `project`: the owner tags `buildCaptureTags` derives, the values `CaptureProvided` declares except `standalone`, and the browser command `readCaptureFrames`, which lists the frames under the project's provided directory with the scopes the owners declare. The factory provides no standalone roots. Each run record sits at `<directory>/runs/<id>/<stage>/<variant>.json`, or at `<directory>/runs/direct-<uuid>/<variant>.json` when no runner is the parent. With the capture variable unset, each variant writes to its own `no-capture-<variant>` sibling of the evidence root, which must resolve inside the workspace and is emptied first. The result's root `plugins` holds one `createProgressPlugin()`, which makes the package's `@orkestrel/test` peer a runtime import of its server face. The host keeps every product rule: its `project` names and shapes each project, and the suite keeps its part and source resolvers.
|
|
681
|
+
|
|
572
682
|
**Request directory.** The one default is `CAPTURE_DEFAULTS.requests`. The runner hands the directory it publishes to every child it spawns in `CAPTURE_REQUESTS`, and `readCaptureRequest` and `answerCaptureDiscovery` read it from there when the wrapper names no `directory` of its own, so a consumer never repeats a constant it could mismatch. A wrapper that does name one declares it, and it must be the runner's.
|
|
573
683
|
|
|
574
|
-
**Request.** Before each stage the runner writes `journey-selection-<pid>.json` in the request directory, named by its own process id, through a temporary sibling and a rename, and removes both in a `finally` block. Before it writes, it removes every request file named for a process that is no
|
|
684
|
+
**Request.** Before each stage the runner writes `journey-selection-<pid>.json` in the request directory, named by its own process id, through a temporary sibling and a rename, and removes both in a `finally` block. Before it writes, it removes every request file named for a process that has ended, and keeps one named for a process that is running or whose state the host cannot read. A name whose process id is above `CAPTURE_PID_LIMIT` is malformed: the sweep keeps it and no holder lists it, as for any other malformed name. A directory that carries a request file's name stays in place. The wrapper reads the file back through `readCaptureRequest`, which accepts only the file its parent's id names, only a record whose `pid` matches, and only arguments equal to its own process's.
|
|
575
685
|
|
|
576
686
|
The execution wrapper reads its parent's selection request:
|
|
577
687
|
|
|
@@ -588,7 +698,7 @@ const request = readCaptureRequest({
|
|
|
588
698
|
request?.selector // 'pages:mail' when a runner is the parent, otherwise undefined
|
|
589
699
|
```
|
|
590
700
|
|
|
591
|
-
**Processes.** The runner spawns `process.execPath` with the installed `node_modules/vitest/vitest.mjs`, an argument array, and no shell. The child inherits the environment
|
|
701
|
+
**Processes.** The runner spawns `process.execPath` with the installed `node_modules/vitest/vitest.mjs`, an argument array, and no shell. The child inherits the environment through the `@orkestrel/process` merge, which drops every inherited name that matches `CAPTURE` or `CAPTURE_REQUESTS` in any case. The runner sets `CAPTURE_REQUESTS` to the request directory, and a `capture` command, like discovery, sets exactly one `CAPTURE=1`; every other child receives no `CAPTURE` name. Each stage writes its own log and JSON report under `<requests>/runs/<id>/`, and the child's output is teed to the host's streams and the log. Each stage also passes `--outputFile.progress=<requests>/runs/<id>/<stage>.progress.jsonl`; a wrapper whose root `plugins` holds `createProgressPlugin()` from `@orkestrel/test/server` writes that file, and Vitest ignores the flag in a wrapper without it. The progress file is an observation of the run and never evidence: no stamp, receipt, or reader reads it. The argument travels in the request's `args`, so the wrapper's exact-argument check and the run record's request comparison cover it as they cover every other argument. Each child runs through `@orkestrel/process` `createDuplex` with stdin closed immediately. Its byte output is decoded with `StringDecoder`, preserving split UTF-8, carriage returns, and missing final newlines, and the decoder is flushed at termination. A writer or log failure, or a session whose output did not drain before its observation bound, refuses the stage. An interrupt aborts the stage's signal and ends each child's tree: Windows tree termination, or POSIX `SIGTERM` followed by `SIGKILL` after a 250 ms grace. A pre-aborted invocation launches no child. The invocation then removes its request and releases its handlers.
|
|
592
702
|
|
|
593
703
|
**Host evidence (2026-10-28).** A real console Ctrl+C on Windows and a process-group SIGINT through the built executable on Linux each ended the stage tree, started no later stage, removed the request, and left the manifest bytes unchanged. The Windows reading uses a console-capable terminal; the POSIX automated case runs only where its process-group mechanism is available.
|
|
594
704
|
|
|
@@ -619,9 +729,9 @@ await createCaptureSheets({ reader, output: `${process.cwd()}/tmp/sheets` }).exe
|
|
|
619
729
|
|
|
620
730
|
**Preflight.** `check` judges freshness, images, artifact coverage, logged errors, and host checks; both `execute` and the sheets consume that result. `execute` prints one `READER` line of JSON and returns 0 when every selected frame is current and no issue was found. It returns 64 for `USAGE`, including unknown or empty selectors, and 1 for every other failure, including wrapper, checks-module, containment, and evidence failures. A thrown refusal goes to the error writer without a report. The report carries the selection, the freshness the engine classified, the mixed observations, every issue, the groups of byte-identical images, the size of each image, and `acceptance: false`: a passing preflight is iteration evidence and never assembled-portfolio acceptance. The preflight upgrades no freshness classification, and it widens no selection.
|
|
621
731
|
|
|
622
|
-
**Images.** Each selected destination is read from disk, refused below 4,000 bytes, and decoded. The reader judges each decoded frame and runs its host checks before moving to the next frame. The returned `images` hold source dimensions in `picture` and a bounded `thumbnail` for sheets; full pixel buffers reach host checks and are not retained in the result. A frame whose image cannot be read stays in the report as an issue and, in the sheets, as a red mark
|
|
732
|
+
**Images.** Each selected destination is read from disk, refused below 4,000 bytes, and decoded. The reader judges each decoded frame and runs its host checks before moving to the next frame. The returned `images` hold source dimensions in `picture` and a bounded `thumbnail` for sheets; full pixel buffers reach host checks and are not retained in the result. A frame whose image cannot be read stays in the report as an issue and, in the sheets, as a red mark with no source size; its index cell carries the freshness the engine classified, `missing` for an absent file. The frame scan groups the source geometry by portfolio, owner, and declared viewport width, and names a group whose frames mix cropped, viewport-sized, and page-sized images. It reads only a frame at its own producing variant, and it never decides which framing was intended. When the wrapper declares `uniform`, only images whose owner matches a declared selector enter those groups; an empty list produces no mixed observations. Without the declaration, every scope enters. Frames outside the declared scopes retain their freshness, coverage, image issues, host checks, and sheet cells.
|
|
623
733
|
|
|
624
|
-
`CAPTURE_PNG_LIMITS` caps decoded frames at 20,971,520 pixels, with about 19.5% margin over the fleet's largest measured Chromium full-page frame, 1170 × 15000; 2880 × 6000 also fits. Each side is capped at 131,072 pixels. The byte budget is `ceil((4 × pixels + side) × 1.2)`, or 100,820,583 bytes: maximum RGBA scanlines plus a 20% allowance for deflate overhead, chunk framing, and metadata. The file size is checked before reading and before compressed chunks are joined; a single IDAT is inflated directly from its view. Pixel and side checks precede inflation.
|
|
734
|
+
`CAPTURE_PNG_LIMITS` caps decoded frames at 20,971,520 pixels, with about 19.5% margin over the fleet's largest measured Chromium full-page frame, 1170 × 15000; 2880 × 6000 also fits. Each side is capped at 131,072 pixels. The byte budget is `ceil((4 × pixels + side) × 1.2)`, or 100,820,583 bytes: maximum RGBA scanlines plus a 20% allowance for deflate overhead, chunk framing, and metadata. The file size is checked before reading and before compressed chunks are joined; a single IDAT is inflated directly from its view. The IHDR checksum is checked before any header field is judged, so a corrupt header field, width through interlace, refuses as a checksum failure. Pixel and side checks precede inflation. The chunk walk refuses a second IHDR chunk, a critical chunk other than IHDR, PLTE, IDAT, and IEND, and IDAT chunks that are not consecutive. Every decode refusal names what it found, such as the chunk's offset, type, and length, the dimensions, or the bit depth, colour type, and interlace, beside what decode accepts. `scanCaptureChunks` walks PNG chunks by halving the chunk count at each level and reads no more chunks than the file bytes hold, so the call depth stays logarithmic and a valid many-chunk encoder stream is admitted. Isolated Node runs on Windows on 2026-10-28 peaked at 276–333 MiB process RSS for the fleet frames, 438 MiB for stored-deflate RGBA at the pixel boundary, 456 MiB for 131072 × 160, and 171 MiB for a valid 1 × 1 PNG padded to the byte boundary. A file one byte over refused before reading at 74 MiB process RSS. These are fixture measurements, not a universal RSS ceiling. The budget limits each decode; selected frame counts do not multiply retained full-frame storage.
|
|
625
735
|
|
|
626
736
|
**Artifacts.** The reader judges each frame by the run record its own stamp names, never by a variant's latest file. It reads that record, requires the journey artifact the record names to sit inside the journeys directory and to match the record's digest, and then requires the record to cover the frame, the artifact to bind the record with a `record=` line, and the artifact to show the stamping case with a `case-ran=` line. It also reports every artifact line that logs an uncaught, unhandled, or error entry. A frame with no stamp is an issue, never a guess. A standalone portfolio root the wrapper declares has no stamping route, so a selection that names one reads that root alone and reports its frames as unstamped.
|
|
627
737
|
|
|
@@ -642,11 +752,11 @@ export const CAPTURE_CHECKS = [
|
|
|
642
752
|
|
|
643
753
|
A module that cannot be loaded, exports no list of functions, or holds a reader that returns something other than a list of strings refuses the run as a `HOST` condition before a report prints.
|
|
644
754
|
|
|
645
|
-
**Sheets.** `execute` validates the supplied output path after claiming ownership and before preflight work. It reads the selection through the preflight, so it judges the same population and keeps its refusals. It requires an output directory that does not exist, lies inside the workspace, has an existing parent, and lies outside every selected capture directory. A supplied outside or unreadable path refuses with exit 64; other output refusals and containment caught at write time exit 1 before writing. It shrinks each frame by a whole factor toward 320 pixels wide with an exact box area average over typed arrays. Every source pixel in a displayed block contributes once, and the divisor is that block's actual pixel count, including partial edge blocks.
|
|
755
|
+
**Sheets.** `execute` validates the supplied output path after claiming ownership and before preflight work. It reads the selection through the preflight, so it judges the same population and keeps its refusals. It requires an output directory that does not exist, lies inside the workspace, has an existing parent, and lies outside every selected capture directory. A supplied outside or unreadable path refuses with exit 64; other output refusals and containment caught at write time exit 1 before writing. It shrinks each frame by a whole factor toward 320 pixels wide with an exact box area average over typed arrays. Every source pixel in a displayed block contributes once, and the divisor is that block's actual pixel count, including partial edge blocks. Each output byte sums its own block and is written once, in row order, into a preallocated typed array; no accumulator carries a sum between bytes. It clips thumbnails at 400 pixels tall, places a state's variants side by side, pairs two states per row, and stacks up to four rows per sheet, opening the next sheet at the row that would take a sheet past `CAPTURE_PNG_LIMITS`. A row that alone passes those limits refuses with exit 64 before any sheet is written, and the refusal names the row's composite, the limits, and the recovery: select fewer variants with `--variant`. Work is proportional to the source pixels used by the displayed blocks; the 131072 × 160 and largest accepted frame performance proofs enforce a 1,000 ms ceiling. It writes `sheet-001.png` and onward, an `index.json` of every cell with its source and displayed size, its freshness, and the mixed observations, and an `index.md` that links each frame. The index also carries every member of the preflight's `READER` line, because `buildCaptureReaderReport` builds both: the selection, freshness, mixed observations, issues, identical-frame groups, image sizes, and `acceptance: false`. It prints the index as one `SHEETS` line and returns the exit status the preflight would, except for the output refusals stated earlier in this paragraph and that row refusal.
|
|
646
756
|
|
|
647
757
|
### Registry refresh
|
|
648
758
|
|
|
649
|
-
The command that bootstraps or replaces the accepted registry. The stage transaction refuses to run until a registry exists, so the refresh cannot stamp through the engine: it imports complete runs instead. `createCaptureRegistrar` takes the same options as the runner minus the command, and `execute` reads the wrapper through the same `CaptureDiscovery` the runner uses, forwarding `--mode` to discovery, the factory, and the execution child. It takes the same invocation entity and request file, and runs every selected producing variant in one stage, one Vitest child that receives each variant's project, with the `all` selector, the `journey` command, and no capture variable.
|
|
759
|
+
The command that bootstraps or replaces the accepted registry. The stage transaction refuses to run until a registry exists, so the refresh cannot stamp through the engine: it imports complete runs instead. `createCaptureRegistrar` takes the same options as the runner minus the command, and `execute` reads the wrapper through the same `CaptureDiscovery` the runner uses, forwarding `--mode` to discovery, the factory, and the execution child. It takes the same invocation entity and request file, and runs every selected producing variant in one stage, one Vitest child that receives each variant's project, with the `all` selector, the `journey` command, and no capture variable. The stage passes no tag filter and runs the whole suite, ownerless cases included, which stands in for the consumer's complete test run.
|
|
650
760
|
|
|
651
761
|
Refresh a selected producing variant through the registrar:
|
|
652
762
|
|
|
@@ -664,7 +774,7 @@ const exit = await registrar.execute() // 0 when the registry was published
|
|
|
664
774
|
|
|
665
775
|
**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.
|
|
666
776
|
|
|
667
|
-
**Inherited evidence.** Before any stage, the command reads an existing manifest and lookup journal and checks
|
|
777
|
+
**Inherited evidence.** Before any stage, the command reads an existing manifest and lookup journal and checks each declared version, then each schema. A document of another version refuses the refresh with the removal and the refresh commands the Integrity section's Document version paragraph lists, and with no other recovery. An unreadable document or an unsupported schema refuses the refresh and names the file to inspect and repair before retrying. Publication still authenticates inherited evidence through the integrity engine.
|
|
668
778
|
|
|
669
779
|
**Stages.** The one stage is named `registry`, so its reporter is `<requests>/runs/<id>/registry.json` and each variant's record is `<directory>/runs/<id>/registry/<variant>.json`. A partial refresh runs only the named variants in that stage. The command takes each selected project's declared input population and its content hashes before the child starts and again after, and refuses when they differ. A child that exits unsuccessfully refuses the refresh with a message that names the stage and its variants. The command then reads the reporter once and, for each variant, reads the final record, requires it to carry the stage's own request, to name the variant, to fall between the start of the refresh and the end of the reporter, to agree with every collected declaration of that variant, 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. Every receipt the stage builds names the same reporter and digest.
|
|
670
780
|
|
|
@@ -678,14 +788,22 @@ Serialize capture commands and the host's Vitest work per workspace. Preparation
|
|
|
678
788
|
request directory and checks that it is a directory. An invocation writes `{pid,id}` once to
|
|
679
789
|
a unique `.capture-owner.<pid>.<id>.tmp` file with flag `wx`, then claims `.capture-owner`
|
|
680
790
|
with `linkSync`. The marker stays byte-identical from that link until its own invocation
|
|
681
|
-
unlinks it after confirmed child termination. It stays held between stages. The
|
|
682
|
-
|
|
683
|
-
|
|
791
|
+
unlinks it after confirmed child termination. It stays held between stages. The claim
|
|
792
|
+
attempt then removes its temporary; a removal failure never replaces the claim's result,
|
|
793
|
+
and the leftover names a live pid, so a later claim sweeps it after that process ends.
|
|
794
|
+
A dead pid's leftover claim temporary is swept best effort; sweep errors are ignored, and
|
|
795
|
+
the temporary of a live pid, or of a pid whose state cannot be read, is never touched.
|
|
684
796
|
The marker does not coordinate another request directory or unrelated Vitest processes.
|
|
685
797
|
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
798
|
+
Liveness comes from `inspectProcess` of `@orkestrel/process`, or from the host's `alive`
|
|
799
|
+
operation. EPERM from the pid probe counts as alive. Where the host publishes a `/proc`
|
|
800
|
+
process table, an exited process its parent has not reaped counts as ended once every one
|
|
801
|
+
of its threads has exited. An `undefined` answer counts as neither: the holder keeps its
|
|
802
|
+
marker, its request file, and its claim temporary, `holders` lists it, and the claim
|
|
803
|
+
refuses with the uninspectable-holder message.
|
|
804
|
+
|
|
805
|
+
A held marker is parsed as `{pid,id}`, ignoring extra members. After the liveness probe
|
|
806
|
+
the claim re-reads the marker; a vanished or changed marker retries. Deletion advice for a dead holder requires identical content on
|
|
689
807
|
that re-read. A live-holder refusal makes any deletion conditional on confirming that no
|
|
690
808
|
capture process or surviving child is running. Empty or malformed markers require
|
|
691
809
|
identical reads separated by backoff and ask for inspection. A permanent read error
|
|
@@ -695,8 +813,9 @@ Marker reads, links, and removals retry only `EBUSY` and `EMFILE` on POSIX, and
|
|
|
695
813
|
codes plus `EPERM` and `EACCES` on Windows, with synchronous 10 ms backoff within
|
|
696
814
|
1,000 ms. On POSIX, a link failure with `EPERM`, `ENOTSUP`, `EOPNOTSUPP`, `ENOSYS`,
|
|
697
815
|
or `EXDEV` refuses immediately with the hard-link requirement. Exhaustion names the
|
|
698
|
-
error code and gives no deletion advice
|
|
699
|
-
|
|
816
|
+
error code and gives no deletion advice; a marker that kept changing until the deadline
|
|
817
|
+
says so in place of a code. Other temporary-write or link errors refuse permanently and
|
|
818
|
+
name the operation and code.
|
|
700
819
|
|
|
701
820
|
Release awaits signal-driven termination, retracts its request, and stops every child.
|
|
702
821
|
It reads its marker and checks its invocation id before acting; an absent or foreign
|
|
@@ -710,14 +829,17 @@ command, every unconfirmed child pid, and the ISO timestamp of the attempt:
|
|
|
710
829
|
{"pid":1234,"id":"RUN_ID","command":"journey","children":[5678],"at":"2026-10-28T00:00:00.000Z"}
|
|
711
830
|
```
|
|
712
831
|
|
|
713
|
-
Release throws STAGE, naming the unconfirmed pids
|
|
832
|
+
Release throws STAGE, naming the unconfirmed pids. It names the marker only when it kept
|
|
833
|
+
its own marker, and the record only when the record exists after the write. A later release
|
|
714
834
|
in the same process retries the stop. After termination is confirmed, release removes
|
|
715
835
|
only its own marker, re-reading and checking its id on every removal retry. A successful
|
|
716
836
|
release leaves no claim temporary or marker from that invocation. An exhausted or
|
|
717
837
|
permanent removal failure retains the marker and joins the shutdown failure.
|
|
718
838
|
|
|
719
|
-
A dead-holder refusal reads `runs/<holder id>/survivors.json` once, without retry
|
|
720
|
-
|
|
839
|
+
A dead-holder refusal reads `runs/<holder id>/survivors.json` once, without retry, and only
|
|
840
|
+
for a holder id of the version 4 UUID shape an invocation generates; another id reads no
|
|
841
|
+
record and says so. A well-formed record names its path and its pids, at most
|
|
842
|
+
`CAPTURE_REFUSAL_LIMIT` of them followed by the count omitted. ENOENT reports absence; other errors report
|
|
721
843
|
the code, and malformed content reports EINVAL. The record is advisory; the marker
|
|
722
844
|
provides ownership exclusion. A recorded pid is unconfirmed, not a claim that it is alive.
|
|
723
845
|
Stop any recorded children and confirm the marker's content before deleting it.
|
|
@@ -731,13 +853,18 @@ Capture ownership process PID is not running; invocation "RUN_ID". RECORD_STATUS
|
|
|
731
853
|
Unconfirmed child processes: PIDS; stop them before deleting. Child record: RECORD.
|
|
732
854
|
No child record exists at RECORD.
|
|
733
855
|
Child record could not be read (CODE): RECORD.
|
|
856
|
+
Invocation "RUN_ID" is not an invocation id; no child record is read.
|
|
734
857
|
Another runner holds this workspace (process PID); invocation "RUN_ID"; serialize capture commands. If this pid is not a capture run, confirm no capture process or surviving child is running and re-read MARKER to confirm it still names pid PID before deleting
|
|
858
|
+
Capture ownership process PID could not be inspected; invocation "RUN_ID"; serialize capture commands. Confirm no capture process or surviving child is running and re-read MARKER to confirm it still names pid PID before deleting
|
|
735
859
|
Capture shutdown failed; child termination was not confirmed for process PIDS; ownership marker retained: MARKER; child record: RECORD
|
|
860
|
+
Capture shutdown failed; child termination was not confirmed for process PIDS; ownership marker retained: MARKER
|
|
861
|
+
Capture shutdown failed; child termination was not confirmed for process PIDS
|
|
736
862
|
Cannot write capture child record (CODE): RECORD
|
|
737
863
|
Cannot write capture ownership temporary (CODE): TEMPORARY
|
|
738
864
|
Cannot link capture ownership (CODE): MARKER; the store directory must support hard links
|
|
739
865
|
Cannot link capture ownership (CODE): MARKER; inspect the filesystem error and rerun
|
|
740
866
|
Capture ownership marker is temporarily unavailable (CODE): MARKER; rerun after serializing capture commands
|
|
867
|
+
Capture ownership marker kept changing until the deadline: MARKER; rerun after serializing capture commands
|
|
741
868
|
Capture ownership marker is unreadable: MARKER; rerun after inspecting the filesystem error
|
|
742
869
|
Capture request directory is unavailable: DIRECTORY
|
|
743
870
|
Capture ownership marker is empty; confirm no capture process or surviving child is running and inspect this file: MARKER; its holder cannot be established
|
|
@@ -753,7 +880,8 @@ host supplies read, write, link, remove, platform, and liveness operations; its
|
|
|
753
880
|
uses flag `wx` for both claim temporaries and survivor records. Omitted members use the local
|
|
754
881
|
host. Request publication and retraction retain their own lifecycle. Runner, registrar, and
|
|
755
882
|
preflight report release failures without changing their decided result. Registry refresh also
|
|
756
|
-
checks live request-file holders
|
|
883
|
+
checks live request-file holders, and its refusal names apart each holder whose state the host
|
|
884
|
+
could not inspect.
|
|
757
885
|
|
|
758
886
|
**Exit.** 0 for a published registry, 64 for `USAGE` such as a refused command line, unknown variant, or supplied wrapper path outside the workspace, and 1 for every other failure, including a refused lease, failed or interrupted stage, altered or incomplete record, or refused registry. A refresh writes no frame, and it widens no scoped run: it is a named command, never a tail of `journey`.
|
|
759
887
|
|
|
@@ -761,18 +889,19 @@ checks live request-file holders.
|
|
|
761
889
|
|
|
762
890
|
The `capture` executable dispatches the following subcommands through the server implementations:
|
|
763
891
|
|
|
764
|
-
- `capture journey <selector>` calls `createCaptureRunner` with the `journey` command and reads `--variant` (repeats), `--case`, `--mode`, and `--config`. Replace the selector with `--changed <ref>` and optionally add `--plan`.
|
|
765
|
-
- `capture frames <selector>` calls `createCaptureRunner` with the `capture` command and reads `--variant` (repeats), `--case`, `--state`, `--mode`, and `--config`. Replace the selector with `--changed <ref>` and optionally add `--plan`.
|
|
892
|
+
- `capture journey <selector>` calls `createCaptureRunner` with the `journey` command and reads `--variant` (repeats), `--case`, `--no-bail`, `--mode`, and `--config`. Replace the selector with `--changed <ref>` and optionally add `--plan`.
|
|
893
|
+
- `capture frames <selector>` calls `createCaptureRunner` with the `capture` command and reads `--variant` (repeats), `--case`, `--state`, `--no-bail`, `--mode`, and `--config`. Replace the selector with `--changed <ref>` and optionally add `--plan`.
|
|
766
894
|
- `capture stale <selector>` calls `createCaptureRunner` with the `stale` command and reads `--variant` (repeats), `--case`, `--state`, `--portfolio`, `--mode`, and `--config`.
|
|
767
895
|
- `capture preflight <selector>` calls `createCapturePreflight` and reads `--variant` (repeats), `--state`, `--case`, `--portfolio`, `--mode`, `--config`, `--journeys`, and `--checks`.
|
|
768
896
|
- `capture sheets <selector> --output <directory>` calls `createCaptureSheets` with the preflight's flags, including `--mode`, and a required `--output`.
|
|
769
|
-
- `capture registry` calls `createCaptureRegistrar` and reads `--variant` (repeats), `--mode`, and `--config`.
|
|
897
|
+
- `capture registry` calls `createCaptureRegistrar` and reads `--variant` (repeats), `--no-bail`, `--mode`, and `--config`.
|
|
898
|
+
- `capture progress` takes no argument. It calls `readCaptureProgress` over `CAPTURE_DEFAULTS.requests` and prints the progress file of the stage that is running, or that ran last, then one summary per writing process from `renderProgress` in `@orkestrel/test/server`: the cases done against the cases known, the failures, the case running, and the time elapsed. A run whose file holds no `end` line reads its writer, the process id its `init` line records, through `inspectProcess` from `@orkestrel/process/server`: a writer that has ended, such as a killed stage, prints the run as `interrupted` with no running case and its time elapsed up to its last line, and a writer the host cannot inspect keeps the `live` state its file records and prints a `state unknown` line beneath it. A file whose only line is still partial prints that no run has written a complete line. Before a stage writes its first line, the command reports the previous stage, whose run line names it finished or interrupted. No progress file, and a complete line that is not a progress event, refuse as `STAGE` with exit 1.
|
|
770
899
|
|
|
771
|
-
`frames` runs the request command `capture`, because `capture capture` would stutter. Node's `node:util` `parseArgs` reads one frozen option table per command. Every flag except the valueless `--plan` takes one nonempty value, either `--flag value` or `--flag=value`. A value beginning with `-` must use equals form, such as `--case=-draft`. Only `--variant` repeats; a repeated boolean, a repeated single-value option (including mixed forms), an empty value, an unknown or command-inappropriate option, and the `--` terminator are refused. Runner flags may precede or follow the selector; preflight and sheets retain a leading selector; registry takes no positional arguments. Parser refusals carry `USAGE`, the parser diagnostic, and the command's usage text. The executable falls back to `CAPTURE_DEFAULTS` when the command line names none: the wrapper `configs/app/vite.journey.config.ts`, the request directory `tmp/capture`, and the journey artifact directory `tmp/journey`. The request directory reaches the wrapper through `CAPTURE_REQUESTS`, so the wrapper repeats nothing.
|
|
900
|
+
`frames` runs the request command `capture`, because `capture capture` would stutter. Node's `node:util` `parseArgs` reads one frozen option table per command. `--no-bail` is the one negated flag: `bail` defaults to `true`, and the `--no-` form of every other flag is refused as unknown. Every flag except the valueless `--plan` and `--no-bail` takes one nonempty value, either `--flag value` or `--flag=value`. A value beginning with `-` must use equals form, such as `--case=-draft`. Only `--variant` repeats; a repeated boolean, a repeated single-value option (including mixed forms), an empty value, an unknown or command-inappropriate option, and the `--` terminator are refused. Runner flags may precede or follow the selector; preflight and sheets retain a leading selector; registry takes no positional arguments. Parser refusals carry `USAGE`, the parser diagnostic, and the command's usage text. The executable falls back to `CAPTURE_DEFAULTS` when the command line names none: the wrapper `configs/app/vite.journey.config.ts`, the request directory `tmp/capture`, and the journey artifact directory `tmp/journey`. The request directory reaches the wrapper through `CAPTURE_REQUESTS`, so the wrapper repeats nothing.
|
|
772
901
|
|
|
773
902
|
The bin entry declares nothing: it calls `createCaptureCLI().execute(process.argv.slice(2))` and assigns the returned code to `process.exitCode`. `CaptureCLI` takes optional `root`, `stdout`, and `stderr` options (`CaptureCLIOptions`) and exposes `execute(argv): Promise<number>`; every command's report and refusal uses those writers, so a host can drive the whole executable in process.
|
|
774
903
|
|
|
775
|
-
**Exit.** 0 when the work passed, 64 for `USAGE`, and 1 for every other failure. An unknown or empty selector is checked against the wrapper before registry authentication and is usage under journey, frames, stale, preflight, and sheets; registry refuses every selector as usage. An unknown variant is usage under every command. Git, wrapper, plan-derived owner, ownership, containment, and evidence failures exit 1. A runner reports a release failure without replacing its already decided exit. Parser refusals include command usage, and an unknown or missing subcommand prints the whole usage text on the error stream. Selector lists and shared-input paths in diagnostics carry capped previews and the number omitted; Git stderr is capped with an omitted-character count. The preflight takes no `--output`, which belongs to the sheets, and the sheets require one.
|
|
904
|
+
**Exit.** 0 when the work passed, 64 for `USAGE`, and 1 for every other failure. An unknown or empty selector is checked against the wrapper before registry authentication and is usage under journey, frames, stale, preflight, and sheets; registry refuses every selector as usage. An unknown variant is usage under every command, and a contact-sheet row too large for `CAPTURE_PNG_LIMITS` is usage under sheets. Git, wrapper, plan-derived owner, ownership, containment, and evidence failures exit 1. A runner reports a release failure without replacing its already decided exit. Parser refusals include command usage, and an unknown or missing subcommand prints the whole usage text on the error stream. Selector lists and shared-input paths in diagnostics carry capped previews and the number omitted; Git stderr is capped with an omitted-character count. The preflight takes no `--output`, which belongs to the sheets, and the sheets require one.
|
|
776
905
|
|
|
777
906
|
The subcommand names are declared in `CAPTURE_SUBCOMMANDS`; `frames` maps to the protocol's `capture` command. The dated interrupt evidence is recorded in the Runner section.
|
|
778
907
|
|