@orkestrel/scaffold 0.0.113 → 0.0.115
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +83 -16
- package/dist/bin/main.js +71 -23
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +5 -3
- package/dist/host/agents/platforms/windows.md +1 -0
- package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
- package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +4 -4
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -1
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +8 -2
- package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +1 -0
- package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +7 -7
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +31 -11
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +150 -49
- package/dist/host/claude/agents/analyst.md +1 -1
- package/dist/host/claude/agents/astra.md +2 -2
- package/dist/host/claude/agents/builder.md +4 -4
- package/dist/host/claude/agents/opus.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +57 -59
- package/dist/host/claude/agents/planner.md +8 -2
- package/dist/host/claude/rules/campaign.md +2 -1
- package/dist/host/claude/rules/documentation.md +1 -0
- package/dist/host/claude/rules/tests.md +13 -8
- package/dist/host/claude/rules/workspace.md +28 -28
- package/dist/host/claude/rules/writing.md +1 -0
- package/dist/host/claude/skills/enterprise-bootstrap/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-align/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-build/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-debrief/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-falsify/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-journey/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-polish/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +8 -5
- package/dist/host/codex/agents/astra.toml +4 -5
- package/dist/host/codex/agents/builder.toml +5 -5
- package/dist/host/codex/agents/opus.toml +3 -4
- package/dist/host/codex/agents/orkestrel.toml +2 -1
- package/dist/host/codex/agents/planner.toml +8 -5
- package/dist/host/codex/agents/reviewer.toml +5 -4
- package/dist/host/guides/agent.md +13 -13
- package/dist/host/guides/brief.md +4 -0
- package/dist/host/guides/browser.md +162 -44
- package/dist/host/guides/budget.md +1 -1
- package/dist/host/guides/capture.md +4 -0
- package/dist/host/guides/console.md +13 -0
- package/dist/host/guides/contract.md +38 -3
- package/dist/host/guides/csv.md +5 -0
- package/dist/host/guides/database.md +58 -8
- package/dist/host/guides/form.md +17 -0
- package/dist/host/guides/guide.md +36 -33
- package/dist/host/guides/html.md +72 -44
- package/dist/host/guides/indexeddb.md +4 -0
- package/dist/host/guides/lsp.md +49 -8
- package/dist/host/guides/markdown.md +146 -1
- package/dist/host/guides/mcp.md +117 -22
- package/dist/host/guides/middleware.md +194 -26
- package/dist/host/guides/msg.md +9 -5
- package/dist/host/guides/pool.md +8 -1
- package/dist/host/guides/probe.md +13 -1
- package/dist/host/guides/process.md +102 -90
- package/dist/host/guides/program.md +4 -0
- package/dist/host/guides/qualifier.md +4 -0
- package/dist/host/guides/rater.md +4 -0
- package/dist/host/guides/reason.md +6 -4
- package/dist/host/guides/relation.md +4 -0
- package/dist/host/guides/scaffold.md +32 -14
- package/dist/host/guides/server.md +29 -13
- package/dist/host/guides/sqlite.md +6 -0
- package/dist/host/guides/sse.md +6 -0
- package/dist/host/guides/study.md +473 -473
- package/dist/host/guides/table.md +3 -0
- package/dist/host/guides/template.md +3 -0
- package/dist/host/guides/test.md +38 -20
- package/dist/host/guides/tool.md +3 -0
- package/dist/host/guides/toolbox.md +21 -0
- package/dist/host/guides/websocket.md +3 -1
- package/dist/host/guides/workflow.md +103 -11
- package/dist/host/guides/workspace.md +4 -0
- package/dist/host/manifest.json +84 -84
- package/dist/host/tests/config.test.ts +7 -13
- package/dist/src/core/index.cjs +20 -28
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +7 -7
- package/dist/src/core/index.d.ts +7 -7
- package/dist/src/core/index.js +20 -28
- package/dist/src/core/index.js.map +1 -1
- package/package.json +12 -12
|
@@ -20,6 +20,9 @@ copy. Table-owned refusals raise `TableError`, and each one names a caller mista
|
|
|
20
20
|
|
|
21
21
|
## Surface
|
|
22
22
|
|
|
23
|
+
The core and browser error guards recognize self-branded errors across package copies and
|
|
24
|
+
subclasses. They validate declared members and refuse transparent proxies and unbranded look-alikes.
|
|
25
|
+
|
|
23
26
|
The core surface is exported from `@orkestrel/table` ([`src/core`](../src/core)); the native binding
|
|
24
27
|
surface comes from `@orkestrel/table/browser` ([`src/browser`](../src/browser)). The manager
|
|
25
28
|
classes and the key-set shell they compose are the module's internal declarations: they stay out
|
|
@@ -81,6 +81,9 @@ FILL_PATTERN.source // the `{{name}}` / `\{{` substitution pattern
|
|
|
81
81
|
|
|
82
82
|
### Errors
|
|
83
83
|
|
|
84
|
+
The guard recognizes self-branded errors across package copies and subclasses.
|
|
85
|
+
It refuses transparent proxies and unbranded look-alikes.
|
|
86
|
+
|
|
84
87
|
| API | Kind | Summary |
|
|
85
88
|
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
86
89
|
| `TemplateError` | class | Represents an error thrown by the template layer — a machine-readable `TemplateErrorCode` and an optional `context` record naming the offending id or placeholder name. |
|
package/dist/host/guides/test.md
CHANGED
|
@@ -118,6 +118,7 @@ it adds after.
|
|
|
118
118
|
| `RetryOptions` | interface | `WaitOptions` plus `{ attempts? }` | Configures a bounded retry, adding an optional producer-call limit to a bounded wait's bounds. |
|
|
119
119
|
| `TextWaitOptions` | interface | `WaitOptions` plus `{ exact?, absent? }` | Configures a bounded wait over a reading of text. |
|
|
120
120
|
| `EventSubscriber` | type | `(listener) => cleanup \| void` | Subscribes a listener to one event source. |
|
|
121
|
+
| `RetryObservation` | interface | `{ last, cause }` | Holds the latest produced text and producer refusal across a retry history. |
|
|
121
122
|
| `RecorderInterface` | interface | `{ calls, count, handler }` plus `clear` | Records every call made to its handler. |
|
|
122
123
|
| `EventSourceInterface` | interface | `{} plus on` | Subscribes handlers to a typed event source. |
|
|
123
124
|
| `RecorderMap` | type | `{ readonly [K in TName]: RecorderInterface<TMap[K]> }` | Maps event names to recorders for their delivered argument tuples. |
|
|
@@ -151,6 +152,7 @@ A `Shape` cell holds the constant's declared type.
|
|
|
151
152
|
|
|
152
153
|
| API | Kind | Shape | Summary |
|
|
153
154
|
| ----------------------- | ----- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
|
|
155
|
+
| `TIMER_LEAD` | const | `number` | Bounds how far a real timer can end short of its duration, in whole milliseconds. |
|
|
154
156
|
| `STATECHART_ATTRIBUTES` | const | `Readonly<Record<'status' \| 'passed' \| 'failed' \| 'total' \| 'scenario' \| 'result' \| 'state', string>>` | Names the attributes a statechart harness publishes, keyed by the fact each one carries. |
|
|
155
157
|
| `STATECHART_STATUSES` | const | `readonly ['pending', 'idle', 'running', 'passed', 'failed']` | Lists every value a statechart harness reports through its `status` attribute. |
|
|
156
158
|
|
|
@@ -192,6 +194,8 @@ instead of propagating.
|
|
|
192
194
|
| `waitForEvent` | function | `(subscribe, description, options?) => Promise<TArgs>` | Waits for the first delivery from an event subscription. |
|
|
193
195
|
| `waitForText` | function | `(description, read, text, options?) => Promise<string>` | Waits until a reading of text carries an expected sentence. |
|
|
194
196
|
| `checkBounds` | function | `(subject: string, budget: number, interval: number) => void` | Checks the resolved bounds one bounded wait runs under. |
|
|
197
|
+
| `captureProduction` | function | `<T>(produce: () => T \| Promise<T>) => Promise<Readonly<PromiseSettledResult<T>>>` | Captures a synchronous or asynchronous producer's value or exact refusal. |
|
|
198
|
+
| `renderRetryValue` | function | `(value: unknown) => string` | Renders a retry value as JSON, plain text, or an unreadable-value marker. |
|
|
195
199
|
| `buildRetryExhausted` | function | `(description, budget, elapsed, last, cause) => Error` | Builds the error `retryUntil` raises when its elapsed-time budget runs out. |
|
|
196
200
|
| `buildRefusal` | function | `(name: string, cause: unknown) => Error` | Builds the error a refused fixture build raises, named for the row it was building for. |
|
|
197
201
|
| `dropRegistration` | function | `(registrations: SignalRegistration[], installed) => SignalRegistration \| undefined` | Drops the registration an instrumented signal installed for one listener. |
|
|
@@ -364,11 +368,13 @@ A `Shape` cell holds the constant's declared type.
|
|
|
364
368
|
| `computeNamePattern` | function | `(name: string) => RegExp` | Computes the pattern that matches one accessible name a decorative glyph may sit beside. |
|
|
365
369
|
| `isOutsideViewport` | function | `(rectangle: DOMRectReadOnly) => boolean` | Determines whether a rectangle lies wholly outside the browser viewport. |
|
|
366
370
|
| `isRendered` | function | `(element: Element) => boolean` | Determines whether the accessibility tree presents one element at all. |
|
|
371
|
+
| `collectShadowHosts` | function | `(element: Element, root?: Node) => readonly Element[]` | Collects an element and the successive hosts of its containing shadow roots. |
|
|
367
372
|
| `isReachable` | function | `(element: Element) => boolean` | Determines whether a person can click one element where it sits. |
|
|
368
373
|
| `readHit` | function | `(element: Element) => Element \| undefined` | Reads the topmost element at one element's bounding-box centre. |
|
|
369
374
|
| `clickAccessible` | function | `(name: string) => Promise<void>` / `(role: string, name: string) => Promise<void>` | Clicks one visible, focus-reachable control by its accessible name through the browser provider. |
|
|
370
375
|
| `clickAccessibleWithin` | function | `(region: string, role: string, name: string) => Promise<void>` | Clicks one human-reachable control by role and accessible-name text inside a named region. |
|
|
371
376
|
| `clickDisclosure` | function | `(name: string) => Promise<void>` | Opens or closes one native details disclosure by its rendered summary. |
|
|
377
|
+
| `readProtocolSession` | function | `() => readonly [unknown, unknown]` | Reads the browser provider's DevTools session and its send member. |
|
|
372
378
|
| `sendProtocol` | function | `(method: string, params?: Readonly<Record<string, unknown>>) => Promise<unknown>` | Sends one DevTools protocol command through the browser provider. |
|
|
373
379
|
| `readProtocolPoint` | function | `(element: Element, offset?: ProtocolPoint) => ProtocolPoint` | Projects a point of one element through every frame that holds it into the browser's top-level viewport. |
|
|
374
380
|
| `readProtocolNode` | function | `(element: Element) => Promise<number>` | Resolves one element to the node the browser's DOM tree holds for it. |
|
|
@@ -450,6 +456,9 @@ A `Shape` cell holds the constant's declared type.
|
|
|
450
456
|
| `stageMedia` | function | `(options: MediaOptions) => Promise<void>` | Stages the tester's print medium, motion preference, forced colours, and pointer precision through the browser provider. |
|
|
451
457
|
| `releaseMedia` | function | `() => Promise<void>` | Restores the media readings observed before the first stage as explicit emulation. With nothing staged, clears every override and waits for a stable reading, not a proved engine baseline. Checks the budget between polls, so a frame that never paints is not bounded by it. |
|
|
452
458
|
| `waitForStability` | function | `(description: string, read: () => string, options?: StabilityOptions) => Promise<void>` | Waits for a reading to hold across its last `frames + 1` reads, each later read taken after a painted frame, with the interval slept between polls. Checks the budget between reads, so a frame that never paints is not bounded by it. |
|
|
459
|
+
| `settleFrame` | function | `(options, element, prepared, pane?, covered?, stage?) => Promise<void>` | Restages a capture until its content extent equals the pane height. |
|
|
460
|
+
| `readFrameHeight` | function | `(options: FrameOptions, element: Element \| undefined, pane: number) => number \| undefined` | Reads a capture subject's height after applying its native scroll clearance. |
|
|
461
|
+
| `takeFrameShot` | function | `(options: FrameOptions, element: Element \| undefined) => Promise<FrameShot>` | Takes a screenshot while temporarily positioning the runner frame around its subject. |
|
|
453
462
|
| `captureFrame` | function | `(options: FrameOptions) => Promise<string>` | Shoots one frame at one viewport size and proves the file on disk holds this run's bytes. |
|
|
454
463
|
| `readCaptureReader` | function | `() => CaptureReader \| undefined` | Reads the optional disk-digest command the tester page registered. |
|
|
455
464
|
| `verifyFrame` | function | `(shot: FrameShot, path: string, reader?: CaptureReader) => Promise<void>` | Verifies a screenshot's destination and compares its returned bytes with the written file. |
|
|
@@ -534,16 +543,17 @@ the requested one by punctuation alone satisfies it.
|
|
|
534
543
|
over the presented elements too, so a region labelled by a heading that carries a glyph is read
|
|
535
544
|
under the heading's words, and a region the tree does not present is refused as not visible.
|
|
536
545
|
|
|
537
|
-
`
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
546
|
+
`resolveAccessibleWithin` matches the region's name exactly, then queries the control in tiers.
|
|
547
|
+
The exact tier uses `computeNamePattern(name)` with `exact: true, includeHidden: true`. It is
|
|
548
|
+
case-sensitive, normalizes whitespace, and accepts a decorative glyph beside the requested words.
|
|
549
|
+
Any exact candidates determine the result: none reachable throws `not reachable inside`, and several
|
|
550
|
+
reachable candidates throw `ambiguous ... inside`. A hidden or disabled exact control therefore
|
|
551
|
+
prevents a longer loose match from taking its place.
|
|
552
|
+
|
|
553
|
+
Only an empty exact tier falls back to the loose name query with `exact: false, includeHidden: true`.
|
|
554
|
+
That tier keeps the same reachability and ambiguity refusals, so `Monthly income` can still resolve
|
|
555
|
+
`Monthly income, 3 items` when no exact candidate exists. `clickAccessibleWithin`,
|
|
556
|
+
`holdAccessibleWithin`, and `traverseAccessibleWithin` share this resolution.
|
|
547
557
|
|
|
548
558
|
`traverseAccessible` resolves before pressing Tab to preserve its refusal voices, then checks each
|
|
549
559
|
landing with `matchesTraversalName` before resolving again. A candidate is accepted only when the
|
|
@@ -964,6 +974,8 @@ A `Shape` cell holds the constant's declared type.
|
|
|
964
974
|
|
|
965
975
|
| API | Kind | Signature | Summary |
|
|
966
976
|
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
977
|
+
| `readLoopClock` | function | `() => number` | Reads the loop clock Node stamps on an armed timer, in whole milliseconds. |
|
|
978
|
+
| `alignLoopClock` | function | `(offset?: number) => void` | Spins synchronously past a loop-clock tick and an optional millisecond offset. |
|
|
967
979
|
| `readCapture` | function | `(path: string) => Promise<string>` | Reads the lowercase hexadecimal SHA-256 digest of a captured file's bytes. |
|
|
968
980
|
| `readInventory` | function | `(root: URL \| string, targets: readonly string[], options?: InventoryOptions) => Readonly<Record<string, string>>` | Reads files from selected targets below a root directory. |
|
|
969
981
|
| `resolveContained` | function | `(root: string, target: string) => string \| undefined` | Resolves a target that stays below a root directory. |
|
|
@@ -1198,12 +1210,17 @@ adopted.release()
|
|
|
1198
1210
|
|
|
1199
1211
|
#### `WebStorageInterface`
|
|
1200
1212
|
|
|
1201
|
-
| Method
|
|
1202
|
-
|
|
|
1203
|
-
| `permit`
|
|
1204
|
-
|
|
1205
|
-
|
|
1206
|
-
`
|
|
1213
|
+
| Method | Returns | Summary |
|
|
1214
|
+
| ------------ | ---------------- | --------------------------------------------------------------------------------------------- |
|
|
1215
|
+
| `permit` | `void` | Grants the reads and the writes the host withheld, and replenishes no quota. |
|
|
1216
|
+
| `clear` | `void` | Removes every stored entry when the host permits writes. |
|
|
1217
|
+
| `getItem` | `string \| null` | Reads a stored value when the host permits reads, or returns `null` for an absent key. |
|
|
1218
|
+
| `key` | `string \| null` | Reads the key at an insertion-order index when permitted, or returns `null` beyond the store. |
|
|
1219
|
+
| `removeItem` | `void` | Removes a stored entry when the host permits writes, consuming no quota. |
|
|
1220
|
+
| `setItem` | `void` | Stores a value when writes are permitted and consumes an accepted write from the quota. |
|
|
1221
|
+
|
|
1222
|
+
The interface extends the platform's `Storage` and explicitly declares the operations the fixture
|
|
1223
|
+
implements. It inherits `length` and the named-property index signature. A store created here answers
|
|
1207
1224
|
through those methods and intercepts no named-property access, so drive a consumer under test
|
|
1208
1225
|
through `getItem` and `setItem`;
|
|
1209
1226
|
[Bounds a shipped helper carries](#bounds-a-shipped-helper-carries) states what the property form
|
|
@@ -2885,13 +2902,13 @@ import { readInventory } from '@orkestrel/test/server'
|
|
|
2885
2902
|
const root = resolveRoot(import.meta)
|
|
2886
2903
|
|
|
2887
2904
|
Object.keys(readInventory(root, ['src/core'], { extensions: ['.ts'] }))
|
|
2888
|
-
// ['src/core/constants.ts', 'src/core/factories.ts', 'src/core/helpers.ts',
|
|
2905
|
+
// ['src/core/Production.ts', 'src/core/Teardown.ts', 'src/core/constants.ts', 'src/core/factories.ts', 'src/core/helpers.ts',
|
|
2889
2906
|
// 'src/core/index.ts', 'src/core/types.ts', 'src/core/validators.ts']
|
|
2890
2907
|
|
|
2891
2908
|
// A named file is included whatever `extensions` says, so one call takes the root files a suite
|
|
2892
2909
|
// needs and the source tree it walks.
|
|
2893
2910
|
Object.keys(readInventory(root, ['package.json', 'src/core'], { extensions: ['.ts'] }))
|
|
2894
|
-
// ['package.json', 'src/core/constants.ts', 'src/core/factories.ts', 'src/core/helpers.ts',
|
|
2911
|
+
// ['package.json', 'src/core/Production.ts', 'src/core/Teardown.ts', 'src/core/constants.ts', 'src/core/factories.ts', 'src/core/helpers.ts',
|
|
2895
2912
|
// 'src/core/index.ts', 'src/core/types.ts', 'src/core/validators.ts']
|
|
2896
2913
|
|
|
2897
2914
|
Object.keys(
|
|
@@ -2900,14 +2917,14 @@ Object.keys(
|
|
|
2900
2917
|
exclude: ['src/core/index.ts'],
|
|
2901
2918
|
}),
|
|
2902
2919
|
)
|
|
2903
|
-
// ['src/core/constants.ts', 'src/core/factories.ts', 'src/core/helpers.ts',
|
|
2920
|
+
// ['src/core/Production.ts', 'src/core/Teardown.ts', 'src/core/constants.ts', 'src/core/factories.ts', 'src/core/helpers.ts',
|
|
2904
2921
|
// 'src/core/types.ts', 'src/core/validators.ts']
|
|
2905
2922
|
|
|
2906
2923
|
// A directory key takes every key below it.
|
|
2907
2924
|
Object.keys(
|
|
2908
2925
|
readInventory(root, ['src'], { extensions: ['.ts'], exclude: ['src/server', 'src/browser'] }),
|
|
2909
2926
|
)
|
|
2910
|
-
// ['src/core/constants.ts', 'src/core/factories.ts', 'src/core/helpers.ts', 'src/core/index.ts',
|
|
2927
|
+
// ['src/core/Production.ts', 'src/core/Teardown.ts', 'src/core/constants.ts', 'src/core/factories.ts', 'src/core/helpers.ts', 'src/core/index.ts',
|
|
2911
2928
|
// 'src/core/types.ts', 'src/core/validators.ts']
|
|
2912
2929
|
|
|
2913
2930
|
// An exclusion also applies to a target you name, so naming one file below an excluded directory
|
|
@@ -3748,6 +3765,7 @@ storage.getItem('theme') // 'dark'
|
|
|
3748
3765
|
storage.setItem('theme', 'light')
|
|
3749
3766
|
// Throws DOMException named QuotaExceededError: No room is left for scale
|
|
3750
3767
|
storage.setItem('scale', '2')
|
|
3768
|
+
storage.removeItem('theme') // a write the quota does not count
|
|
3751
3769
|
|
|
3752
3770
|
buildDenial('length').name // 'SecurityError'
|
|
3753
3771
|
```
|
package/dist/host/guides/tool.md
CHANGED
|
@@ -131,6 +131,9 @@ exception. See [`## Methods`](#methods) for its public call surface.
|
|
|
131
131
|
|
|
132
132
|
### `ToolError`
|
|
133
133
|
|
|
134
|
+
The guard recognizes self-branded errors across package copies and subclasses,
|
|
135
|
+
validates the declared code and optional fault report, and refuses transparent proxies.
|
|
136
|
+
|
|
134
137
|
The error class from [`errors.ts`](../src/core/errors.ts) extends `Error`. Its constructor takes
|
|
135
138
|
`code`, `message`, and optional `context`. Direct tool execution throws an `ARGUMENTS` error with
|
|
136
139
|
the full fault report in `context.faults`; the manager contains it as a message. Use `isToolError`
|
|
@@ -86,6 +86,7 @@ Pure, side-effect-free, exhaustively unit-tested under AGENTS' export-and-test-r
|
|
|
86
86
|
| `extendLineage` | function | Appends one tag to a workflow lineage and returns a frozen copy. |
|
|
87
87
|
| `normalizeLineage` | function | Returns the canonical workflow lineage — validated, copied, and frozen. |
|
|
88
88
|
| `deriveWorkflowDepth` | function | Derives the zero-based workflow nesting depth from a valid lineage. |
|
|
89
|
+
| `resolveWorkflowTarget` | function | Resolves an owned workflow input through the supplied flat or draft contracts. |
|
|
89
90
|
| `completeDraft` | function | Completes a `WorkflowDraft` into a strict `WorkflowDefinition` — synthesizes a missing `id` deterministically and positionally, and defaults a missing `name` to its resolved `id`. |
|
|
90
91
|
| `completePhaseDraft` | function | Completes one `PhaseDraft` into a strict phase definition — the per-phase step of `completeDraft` (phase `index` → `phase-<index>` when its id is omitted). |
|
|
91
92
|
| `completeTaskDraft` | function | Completes one `TaskDraft` into a strict task definition — the per-task leaf step of `completeDraft` (task `index` of phase `<phaseId>` → `<phaseId>-task-<index>` when its id is omitted). |
|
|
@@ -610,8 +611,28 @@ declare const result: Parameters<typeof summarizeWorkflow>[0]
|
|
|
610
611
|
summarizeWorkflow(result) // { status, count, durable?, fault? }
|
|
611
612
|
```
|
|
612
613
|
|
|
614
|
+
Resolve an owned JSON input through the same authoring contracts the workflow tool uses:
|
|
615
|
+
|
|
616
|
+
```ts
|
|
617
|
+
import { createContract } from '@orkestrel/contract'
|
|
618
|
+
import type { ContractInterface } from '@orkestrel/contract'
|
|
619
|
+
import type { WorkflowSteps } from '@orkestrel/toolbox'
|
|
620
|
+
import {
|
|
621
|
+
completeDraft,
|
|
622
|
+
createWorkflowDraftContract,
|
|
623
|
+
resolveWorkflowTarget,
|
|
624
|
+
workflowStepsShape,
|
|
625
|
+
} from '@orkestrel/toolbox'
|
|
626
|
+
|
|
627
|
+
const definition = completeDraft({ phases: [{ tasks: [{}] }] })
|
|
628
|
+
const steps: ContractInterface<WorkflowSteps> = createContract(workflowStepsShape)
|
|
629
|
+
resolveWorkflowTarget({}, definition, steps, createWorkflowDraftContract()) // definition
|
|
630
|
+
```
|
|
631
|
+
|
|
613
632
|
### Recovering a typed `ToolboxError`
|
|
614
633
|
|
|
634
|
+
The guard recognizes the self-brand across installed copies and module formats, including subclasses with a different name. It rejects a transparent proxy and validates the declared code and optional context. Context admits class instances and callable objects.
|
|
635
|
+
|
|
615
636
|
Catch a thrown failure and narrow it with the package's own guard to read its `code`:
|
|
616
637
|
|
|
617
638
|
```ts
|
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
> handshake, the masked and unmasked frame codec, ping and pong, and the close handshake,
|
|
6
6
|
> and surfacing every message on an owned `emitter`.
|
|
7
7
|
|
|
8
|
-
After an HTTP server hands you an upgraded socket, this wrapper turns that raw byte stream into a typed, observable connection, and its
|
|
8
|
+
After an HTTP server hands you an upgraded socket, this wrapper turns that raw byte stream into a typed, observable connection, and its runtime dependencies are `@orkestrel/emitter`, which supplies the typed emitter, and `@orkestrel/contract`, which supplies the guards and the error recognition; [`node:crypto`](https://nodejs.org/api/crypto.html) supplies the one handshake hash. The wrapper has no knowledge of MCP, JSON-RPC, reconnection, heartbeats, or any message schema — those belong to a _message_ transport built one layer up, and this is only the wire. The codec and the boundary guards are pure exported functions, pinned against [RFC 6455](https://datatracker.ietf.org/doc/html/rfc6455)'s worked byte vectors and malformed-input cases, and the [`NodeWebSocket`](#nodewebsocketinterface) class is the thin stateful driver that runs them over a [`node:stream`](https://nodejs.org/api/stream.html) Duplex. Keeping the codec pure and the wrapper minimal is the lean-native-wrapper discipline: a small typed surface over native power, with the hard parts exported as testable units. Source: [`src/server`](../src/server). Surfaced through the `@src/server` barrel.
|
|
9
9
|
|
|
10
10
|
## Surface
|
|
11
11
|
|
|
@@ -147,6 +147,8 @@ These invariants hold across `src/server` ↔ `websocket.md`:
|
|
|
147
147
|
|
|
148
148
|
`WebSocketError` is the one failure type, carrying a stable machine-readable `code`. Narrow a caught value with `isWebSocketError`, then branch on `code`.
|
|
149
149
|
|
|
150
|
+
The guard accepts branded errors from another installed copy and subclasses, regardless of `name`. It requires a global `Error` instance with a derived prototype, an own self-identity brand, a declared code, and an optional object context. It refuses unbranded look-alikes, transparent proxies, and a plain object carrying only the brand.
|
|
151
|
+
|
|
150
152
|
| Code | Raised when |
|
|
151
153
|
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
152
154
|
| `OPTION` | `createNodeWebSocket` refused a `NodeWebSocketOptions` member: `payload`, `timeout`, `key`, `protocol`, or a `protocol` given without a server `key`. |
|
|
@@ -84,6 +84,15 @@ Why this is safe: the definition is the single source of truth. `execute` builds
|
|
|
84
84
|
| `createScheduler` | function | Creates the safe cross-environment cooperative-yield default — a `SchedulerInterface` built on `setTimeout` / `clearTimeout` alone, so it runs unchanged in both the browser and Node. |
|
|
85
85
|
| `createRunner` | function | Creates a thin generic orchestrator that drives declared units — and any they `spawn` — through a bounded-concurrency queue, collecting their results in order and failing the run fast on the first genuine unit failure. |
|
|
86
86
|
|
|
87
|
+
### Copy a progress frame
|
|
88
|
+
|
|
89
|
+
```ts
|
|
90
|
+
import { cloneTaskProgress } from '@orkestrel/workflow'
|
|
91
|
+
|
|
92
|
+
const progress = cloneTaskProgress({ progress: 1, total: 2 })
|
|
93
|
+
Object.isFrozen(progress) // true
|
|
94
|
+
```
|
|
95
|
+
|
|
87
96
|
### The entity tree
|
|
88
97
|
|
|
89
98
|
The live runtime mirror of a definition. Each entity class implements its interface exactly, so the `## Methods` tables following double as its per-instance method surface.
|
|
@@ -131,16 +140,20 @@ Both handles are minted per dispatch from values only the driving engine holds
|
|
|
131
140
|
| `WorkflowPersistence` | class | Coordinates advanced run-local snapshot persistence with one writer and one coalesced most recent obligation, normally composed through `execute({ store })` rather than built directly. |
|
|
132
141
|
| `Runner` | class | Implements a thin generic orchestrator that drives declared units — and any they `spawn` — through a bounded-concurrency `createQueue`, collecting ordered results. |
|
|
133
142
|
| `RunHolder` | class | Holds the active phase `RunnerInterface` for one `WorkflowRunnerInterface.execute` call, for the lifetime of that run. |
|
|
143
|
+
| `HostSchedule` | class | Owns the cancellation and exact failure of one scheduled host operation. |
|
|
144
|
+
| `WorkflowExecution` | class | Owns the bounds, durability, and live phase cursor of one workflow execution. |
|
|
145
|
+
| `TaskAttempt` | class | Holds one handler outcome without moving its invocation or exception boundary. |
|
|
146
|
+
| `PhaseExecution` | class | Owns task launch membership, attempt counts, and active claims for one phase execution. |
|
|
134
147
|
|
|
135
148
|
### Scheduler (pacing)
|
|
136
149
|
|
|
137
|
-
The cooperative host-yield primitive that paces the engine between phases: a loop decides what to do; the scheduler decides when the host regains control. Every backend delegates setup, exact settlement, caller cancellation, and handle cleanup to the exported `
|
|
150
|
+
The cooperative host-yield primitive that paces the engine between phases: a loop decides what to do; the scheduler decides when the host regains control. Every backend delegates setup, exact settlement, caller cancellation, and handle cleanup to the exported `createHostSchedule` lifecycle helper, and every `delay` — plus each macrotask fallback — routes its timer through the one exported `createHostDelay` boundary, so no backend arms a `setTimeout` of its own. It links an owned native composite to the optional caller signal before host work is armed, so patched caller listener methods cannot strand a wait, pre-abort schedules nothing, and the first completion, exact host failure, or exact caller reason settles once. A returned cancellation closure is cleanup only: even if it throws during a later caller abort or host failure, the already-winning exact reason still settles the promise without escaping or hanging.
|
|
138
151
|
|
|
139
152
|
```ts
|
|
140
|
-
import {
|
|
153
|
+
import { createHostSchedule } from '@orkestrel/workflow'
|
|
141
154
|
|
|
142
155
|
const controller = new AbortController()
|
|
143
|
-
await
|
|
156
|
+
await createHostSchedule((complete) => {
|
|
144
157
|
const handle = setTimeout(complete, 0)
|
|
145
158
|
return () => clearTimeout(handle)
|
|
146
159
|
}, controller.signal)
|
|
@@ -152,9 +165,9 @@ await scheduleHost((complete) => {
|
|
|
152
165
|
|
|
153
166
|
### Environment backends
|
|
154
167
|
|
|
155
|
-
Beyond the cross-environment default, each host has a native cooperative-yield primitive a `yield()` can reach for. The backends are standalone `SchedulerInterface` implementations that retain only feature detection and native start/cancel boundaries; `
|
|
168
|
+
Beyond the cross-environment default, each host has a native cooperative-yield primitive a `yield()` can reach for. The backends are standalone `SchedulerInterface` implementations that retain only feature detection and native start/cancel boundaries; `createHostSchedule` is the one shared lifecycle. A pending `yield` / `delay` rejects with `signal.reason` _verbatim_, an already-aborted signal rejects with that same reason before arming, a signal that is not a native `AbortSignal` rejects before arming with a `WorkflowError` carrying the `SCHEDULE` code, caller signal method mutation is harmless, cancellation clears the returned handle once, cancellation-closure failure is contained after the winner is captured, and native composite arbitration prevents late completion, abort, or failure from resettling. Each backend's `delay(ms)` is a real `setTimeout`; only the `yield` primitive differs.
|
|
156
169
|
|
|
157
|
-
The **Node** backend ships in [`src/server`](../src/server), published through `@orkestrel/workflow/server`. `NodeScheduler.yield()` waits on `setImmediate` — the canonical Node "give the event loop a turn", running after the current operation and pending I/O. It deliberately does **not** use `node:timers/promises` (whose `{ signal }` option rejects with a Node `AbortError`, `code: 'ABORT_ERR'`, _not_ the caller's `reason`); its `setImmediate` / `setTimeout` boundaries compose `
|
|
170
|
+
The **Node** backend ships in [`src/server`](../src/server), published through `@orkestrel/workflow/server`. `NodeScheduler.yield()` waits on `setImmediate` — the canonical Node "give the event loop a turn", running after the current operation and pending I/O. It deliberately does **not** use `node:timers/promises` (whose `{ signal }` option rejects with a Node `AbortError`, `code: 'ABORT_ERR'`, _not_ the caller's `reason`); its `setImmediate` / `setTimeout` boundaries compose `createHostSchedule` to preserve the caller reason. `priority` is accepted but a no-op — Node has no priority primitive.
|
|
158
171
|
|
|
159
172
|
The **browser** backends ship in [`src/browser`](../src/browser), published through `@orkestrel/workflow/browser`, one per host-turn strategy. Each browser backend feature-detects its native API through `@orkestrel/contract` guards (`isRecord` / `isFunction`), never an `as`, and fall back to a real macrotask where it is absent:
|
|
160
173
|
|
|
@@ -216,13 +229,15 @@ The additive manager tier, following the `@orkestrel/agent` line's store standar
|
|
|
216
229
|
| `WorkflowError` | class | Represents an error the workflow runtime raises for an operation it refuses — a `WorkflowErrorCode` (`TRANSITION`, `RESTORE`, `MUTATION`, `SCHEDULE`, or `INVARIANT`) beside an optional `context` naming the node or the parameter at fault. |
|
|
217
230
|
| `isWorkflowError` | function | Narrows an unknown caught value to a `WorkflowError`. |
|
|
218
231
|
|
|
219
|
-
Every error this package raises for a refused operation of its own is a `WorkflowError`, narrowable with `isWorkflowError`. These values are deliberately not translated and reach the caller unchanged: a value thrown by a consumer-supplied `WorkflowFunction`, a value thrown or rejected by a consumer-supplied `WorkflowStoreInterface`, a value thrown by the `start` closure a caller hands `
|
|
232
|
+
Every error this package raises for a refused operation of its own is a `WorkflowError`, narrowable with `isWorkflowError`. These values are deliberately not translated and reach the caller unchanged: a value thrown by a consumer-supplied `WorkflowFunction`, a value thrown or rejected by a consumer-supplied `WorkflowStoreInterface`, a value thrown by the `start` closure a caller hands `createHostSchedule` or reported through its `failure` callback, and the `reason` an `AbortSignal` carries — a pending wait rejects with that reason verbatim, which is what makes cancellation identity-preserving. Each is a caller-owned value the package passes through on purpose, not a package fault it failed to wrap.
|
|
233
|
+
|
|
234
|
+
`isWorkflowError` accepts branded errors from separate package copies and subclasses, regardless of `name`. It checks the global `Error` prototype boundary, the own immutable self-brand, the declared code, and the optional object or callable context. Plain errors, unbranded look-alikes, branded plain objects, and transparent proxies over genuine errors are refused. Hostile property access returns `false`.
|
|
220
235
|
|
|
221
236
|
Dependency-owned errors still reach callers untranslated. These are known gaps, not intended pass-throughs: `createRunner` surfaces `@orkestrel/queue`'s `QueueError` for an invalid `concurrency` / `retries` / `timeout`, and `createDatabaseWorkflowStore`'s `get` / `set` / `delete` surface `@orkestrel/database`'s `DatabaseError`. Until they are folded into `WorkflowError`, narrow them with the owning package's own guard rather than `isWorkflowError`.
|
|
222
237
|
|
|
223
238
|
### Helpers & guards
|
|
224
239
|
|
|
225
|
-
Centralized, exhaustively unit-tested helpers and guards. The status derivations are pure and encode the lifecycle truth tables; the lineage / snapshot builders seed the entity tree; `
|
|
240
|
+
Centralized, exhaustively unit-tested helpers and guards. The status derivations are pure and encode the lifecycle truth tables; the lineage / snapshot builders seed the entity tree; `createHostSchedule` owns the scheduler's intentionally effectful host lifecycle.
|
|
226
241
|
|
|
227
242
|
Generic exact-JSON ownership comes directly from [`@orkestrel/contract`](contract.md):
|
|
228
243
|
consumers import its `JSONRecord`, `cloneJSONValue`, and `cloneJSONRecord` from their
|
|
@@ -247,10 +262,11 @@ workflow-specific validation and translate ownership failures into `WorkflowErro
|
|
|
247
262
|
| `canTransitionTask` | function | Tests whether the live W-b task state machine may move directly from one `LifecycleStatus` to another — the legal-transition guard. |
|
|
248
263
|
| `resolveTaskSilence` | function | Resolves a task's runtime silence window against its workflow default, to a host-safe `1..MAX_TIMER_MS` window or to `undefined` where the task disables it. |
|
|
249
264
|
| `cloneTaskActivity` | function | Validates and clones one complete task activity frame. |
|
|
265
|
+
| `cloneTaskProgress` | function | Copies a supplied task progress frame after checking its own keys and prototype. |
|
|
250
266
|
| `isTaskActivityInput` | function | Tests whether an unknown value is a valid whole-frame activity report. |
|
|
251
267
|
| `isTaskActivity` | function | Tests whether an unknown value is valid persisted task activity. |
|
|
252
268
|
| `captureWorkflowOptions` | function | Captures every top-level `WorkflowOptions` value exactly once into an owned plain bag. |
|
|
253
|
-
| `
|
|
269
|
+
| `createHostSchedule` | function | Schedules one cancellable host operation behind an owned settlement signal. |
|
|
254
270
|
| `success` | function | Boxes a value as a `Success` — the graceful outcome half of a `Result`. |
|
|
255
271
|
| `failure` | function | Boxes an error as a `Failure` — the graceful outcome half of a `Result`. |
|
|
256
272
|
| `errorToMessage` | function | Normalizes an unknown thrown value to a non-empty persistence-safe message. |
|
|
@@ -266,14 +282,14 @@ workflow-specific validation and translate ownership failures into `WorkflowErro
|
|
|
266
282
|
| `parkSignal` | function | Parks until `signal` aborts — a promise-parked wait, never a timer or busy-loop, that resolves on the abort event and never rejects. |
|
|
267
283
|
| `insertEntry` | function | Inserts one `[key, value]` entry at a positional index into a readonly entries array — the pure splice-in step behind an insertion-ordered registry's `add`. |
|
|
268
284
|
| `moveEntry` | function | Repositions the entry keyed `key` to a new positional index in a readonly entries array — the pure remove-then-reinsert step behind an insertion-ordered registry's `move`. |
|
|
269
|
-
| `
|
|
285
|
+
| `createHostDelay` | function | Schedules the shared host timer boundary every scheduler backend resumes from. |
|
|
270
286
|
| `isWorkflowInterface` | function | Checks whether an unknown value is a live workflow entity rather than a definition. |
|
|
271
287
|
| `isTaskClaimList` | function | Checks whether an unknown value is a valid list of task activity claims. |
|
|
272
288
|
| `cloneTaskClaims` | function | Validates and owns one list of task activity claims. |
|
|
273
289
|
| `isHalted` | function | Tests whether a driving run must stop giving a workflow — or one forced phase of it — more work. |
|
|
274
290
|
| `isStoppable` | function | Tests whether forcing a workflow `stopped` would still record the cancellation. |
|
|
275
291
|
| `isCompletable` | function | Tests whether a naturally-finished run may force its workflow `completed`. |
|
|
276
|
-
| `
|
|
292
|
+
| `matchesAbortedAttempt` | function | Tests whether a task attempt is aborted rather than merely timed out. |
|
|
277
293
|
| `ownsAttempt` | function | Tests whether one attempt still owns the task it launched. |
|
|
278
294
|
|
|
279
295
|
Every exported `is*` guard is total over every traversed argument. In particular,
|
|
@@ -426,6 +442,11 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
426
442
|
| `TaskControllerInterface` | interface | `{ signal, aborted, input, task, attempt, paused } plus report, pulse, wait, results` | Declares the per-task handle a `WorkflowFunction` receives — the running task's cancellation, its input, its lineage, and read access up the tree to the results already settled. |
|
|
427
443
|
| `AttemptOutcome` | type | `readonly [settled: true, value: JSONValue] \| readonly [settled: false, value: undefined, genuine?: boolean]` | Names how one task attempt left the race between its handler and its cancellation. |
|
|
428
444
|
| `RunHolderInterface` | interface | `{ runner } plus hold` | Holds the phase `RunnerInterface` one `WorkflowRunnerInterface.execute` call is driving, for the lifetime of that run. |
|
|
445
|
+
| `HostScheduleInterface` | interface | `{ promise }` | Exposes the settlement of one owned host operation. |
|
|
446
|
+
| `HostScheduleFunction` | type | `(complete, failure) => cancel` | Arms one host operation and returns its cancellation closure. |
|
|
447
|
+
| `WorkflowExecutionInterface` | interface | `{ cursor, persistence } plus start / advance / clear` | Owns the bounds, durability, and phase cursor of one workflow execution. |
|
|
448
|
+
| `TaskAttemptInterface` | interface | `{ outcome } plus resolve` | Holds the captured outcome of one task handler invocation. |
|
|
449
|
+
| `PhaseExecutionInterface` | interface | `{ launched, attempts, owners } plus add / restore / record / claim / revoke` | Owns task launch membership, attempt counts, and active claims for one phase execution. |
|
|
429
450
|
| `WorkflowResult` | interface | `{ workflow, status, results, durable?, fault? }` | Represents the structured outcome of a `WorkflowRunnerInterface.execute` run — the settled live workflow, its final status, the flattened result tree, and the persistence outcome a supplied store produced. |
|
|
430
451
|
| `WorkflowCheckpoint` | type | `'initial' \| 'attempt' \| 'settlement' \| 'final'` | Names a runner-owned durability boundary. |
|
|
431
452
|
| `WorkflowFault` | interface | `{ checkpoint, message, task?, attempt? }` | Represents a normalized persistence failure surfaced as workflow result data. |
|
|
@@ -634,6 +655,77 @@ The attempt-scoped handle a `WorkflowFunction` receives. `signal` / `aborted` /
|
|
|
634
655
|
| ------ | ------- | ------------------------------------------------------------------------------ |
|
|
635
656
|
| `hold` | `void` | Takes a phase runner for the phase that is starting, or releases the held one. |
|
|
636
657
|
|
|
658
|
+
#### `WorkflowExecutionInterface`
|
|
659
|
+
|
|
660
|
+
The runner creates this owner per execution. Its cursor tracks the next live phase, and its persistence member exposes the durability coordinator after setup.
|
|
661
|
+
|
|
662
|
+
| Method | Returns | Summary |
|
|
663
|
+
| --------- | ------------- | -------------------------------------------------------------------------------- |
|
|
664
|
+
| `start` | `AbortSignal` | Arms the execution bounds and durability before returning the composed signal. |
|
|
665
|
+
| `advance` | `void` | Advances the live phase cursor after one phase has been visited. |
|
|
666
|
+
| `clear` | `void` | Detaches durability, clears the deadline, and removes the cancellation listener. |
|
|
667
|
+
|
|
668
|
+
```ts
|
|
669
|
+
import { createWorkflow, RunHolder, WorkflowExecution } from '@orkestrel/workflow'
|
|
670
|
+
|
|
671
|
+
const workflow = createWorkflow({ id: 'run', name: 'Run', phases: [] })
|
|
672
|
+
const execution = new WorkflowExecution()
|
|
673
|
+
try {
|
|
674
|
+
const signal = execution.start(
|
|
675
|
+
workflow,
|
|
676
|
+
new RunHolder(),
|
|
677
|
+
undefined,
|
|
678
|
+
undefined,
|
|
679
|
+
undefined,
|
|
680
|
+
undefined,
|
|
681
|
+
)
|
|
682
|
+
execution.advance()
|
|
683
|
+
execution.cursor // 1
|
|
684
|
+
signal === workflow.signal // true
|
|
685
|
+
} finally {
|
|
686
|
+
execution.clear()
|
|
687
|
+
}
|
|
688
|
+
```
|
|
689
|
+
|
|
690
|
+
#### `TaskAttemptInterface`
|
|
691
|
+
|
|
692
|
+
The runner captures the handler outcome without changing its invocation or exception boundary.
|
|
693
|
+
|
|
694
|
+
| Method | Returns | Summary |
|
|
695
|
+
| --------- | ------- | ----------------------------------------------------------------- |
|
|
696
|
+
| `resolve` | `void` | Captures the handler outcome at the original invocation boundary. |
|
|
697
|
+
|
|
698
|
+
```ts
|
|
699
|
+
import { TaskAttempt } from '@orkestrel/workflow'
|
|
700
|
+
|
|
701
|
+
const invocation = new TaskAttempt()
|
|
702
|
+
invocation.resolve([true, 'complete'])
|
|
703
|
+
invocation.outcome // [true, 'complete']
|
|
704
|
+
```
|
|
705
|
+
|
|
706
|
+
#### `PhaseExecutionInterface`
|
|
707
|
+
|
|
708
|
+
The runner creates this owner before subscribing to live task additions. Its maps retain invocation counts and active ownership for that phase.
|
|
709
|
+
|
|
710
|
+
| Method | Returns | Summary |
|
|
711
|
+
| --------- | -------- | ------------------------------------------------------------------- |
|
|
712
|
+
| `add` | `void` | Registers a task identifier before dispatch. |
|
|
713
|
+
| `restore` | `void` | Restores the task's persisted attempt count before phase dispatch. |
|
|
714
|
+
| `record` | `number` | Records and returns the task's next invocation number. |
|
|
715
|
+
| `claim` | `void` | Assigns activity ownership to the task's current invocation. |
|
|
716
|
+
| `revoke` | `void` | Releases activity ownership only when the invocation still owns it. |
|
|
717
|
+
|
|
718
|
+
```ts
|
|
719
|
+
import { PhaseExecution } from '@orkestrel/workflow'
|
|
720
|
+
|
|
721
|
+
const execution = new PhaseExecution()
|
|
722
|
+
execution.add(task)
|
|
723
|
+
execution.restore(task)
|
|
724
|
+
const attempt = execution.record(task)
|
|
725
|
+
execution.claim(task, attempt)
|
|
726
|
+
execution.revoke(task.id, attempt)
|
|
727
|
+
```
|
|
728
|
+
|
|
637
729
|
#### `ControllerInterface`
|
|
638
730
|
|
|
639
731
|
`wait` parks until the unit's signal aborts; `spawn` fans out a sibling unit; `abort` cancels this unit. The `id` / `input` / `signal` / `aborted` members are Surface rows.
|
|
@@ -1470,7 +1562,7 @@ A successful run fires `start` → `unit`/`settle` per unit → `finish`. A fail
|
|
|
1470
1562
|
|
|
1471
1563
|
- [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ source bijection across `src/core` (value + type exports), each behavioral interface's `## Methods` ↔ source-method bijection, each implementing-class ↔ interface method parity, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Author a definition and run it` fence against the `@example` block of that title (pinned so the titled pair cannot be retired silently), and the README pitch against this guide's tagline. It also runs the flagship fences and asserts the values their comments claim.
|
|
1472
1564
|
- [`tests/policy.test.ts`](../tests/policy.test.ts) — coding policy rejects private `@src/*` imports in TSDoc examples while accepting legitimate source imports and identical text in ordinary non-TSDoc comments.
|
|
1473
|
-
- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — status/lineage/snapshot helpers, bounded silence inheritance, `
|
|
1565
|
+
- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — status/lineage/snapshot helpers, bounded silence inheritance, `createHostSchedule` setup/cancellation race arbitration with exact falsy failures, hostile caller signal methods, and throwing cancellation closures after caller abort or host failure, plus the snapshot-decode leaves: remaining-budget recovery, established strict halt boundaries, exhausted recovery failures, monotonic stamps, exact-restore separation, and hostile inputs.
|
|
1474
1566
|
- [`tests/src/core/cloners.test.ts`](../tests/src/core/cloners.test.ts) — immutable activity cloning, hostile/revoked proxy containment, one-read getters, no alias retention, stamp-vs-restore `updated` handling, and exact wrong-storage-key `RESTORE` evidence.
|
|
1475
1567
|
- [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) — total activity, task-failure, task-result, and owned-snapshot guards over valid, malformed, cyclic, throwing-proxy/getter/ownKeys, and revoked inputs.
|
|
1476
1568
|
- [`tests/src/core/shapers.test.ts`](../tests/src/core/shapers.test.ts) — the shape descriptors: the `taskShape` / `phaseShape` / `workflowShape` mirroring the hand-written definition interfaces, the per-field `description`s riding the `behavior` string + key fields (Rank 1), `describedLiteral`.
|
|
@@ -519,6 +519,10 @@ change nothing about what a workspace is.
|
|
|
519
519
|
|
|
520
520
|
## Failures
|
|
521
521
|
|
|
522
|
+
The error guard recognizes the error's own identity brand across package copies and
|
|
523
|
+
module formats. It accepts subclasses regardless of their `name` and refuses
|
|
524
|
+
transparent proxies, unbranded look-alikes, and plain branded objects.
|
|
525
|
+
|
|
522
526
|
A code describes every refusal, and `WorkspaceError` carries the code plus the context the
|
|
523
527
|
operation had:
|
|
524
528
|
|