@orkestrel/scaffold 0.0.112 → 0.0.114

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/dist/agents/skills/orkestrel-harden/scripts/titles.js +3 -3
  2. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +120 -21
  3. package/dist/bin/main.js +71 -23
  4. package/dist/bin/main.js.map +1 -1
  5. package/dist/host/agents/platforms/windows.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +3 -3
  7. package/dist/host/agents/skills/orkestrel-publish/SKILL.md +7 -7
  8. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +25 -8
  9. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +187 -54
  10. package/dist/host/claude/agents/orkestrel.md +53 -53
  11. package/dist/host/claude/rules/architecture.md +4 -3
  12. package/dist/host/claude/rules/tests.md +24 -7
  13. package/dist/host/claude/rules/typescript.md +11 -2
  14. package/dist/host/claude/rules/workspace.md +32 -28
  15. package/dist/host/configs/policy.ts +49 -0
  16. package/dist/host/dotfiles/gitignore +1 -0
  17. package/dist/host/dotfiles/oxlintrc.json +6 -0
  18. package/dist/host/guides/agent.md +13 -13
  19. package/dist/host/guides/brief.md +4 -0
  20. package/dist/host/guides/browser.md +162 -44
  21. package/dist/host/guides/budget.md +1 -1
  22. package/dist/host/guides/capture.md +4 -0
  23. package/dist/host/guides/console.md +13 -0
  24. package/dist/host/guides/contract.md +38 -3
  25. package/dist/host/guides/csv.md +5 -0
  26. package/dist/host/guides/database.md +58 -8
  27. package/dist/host/guides/form.md +17 -0
  28. package/dist/host/guides/guide.md +36 -33
  29. package/dist/host/guides/html.md +72 -44
  30. package/dist/host/guides/indexeddb.md +4 -0
  31. package/dist/host/guides/lsp.md +49 -8
  32. package/dist/host/guides/markdown.md +146 -1
  33. package/dist/host/guides/mcp.md +117 -22
  34. package/dist/host/guides/middleware.md +194 -26
  35. package/dist/host/guides/msg.md +9 -5
  36. package/dist/host/guides/pool.md +8 -1
  37. package/dist/host/guides/probe.md +13 -1
  38. package/dist/host/guides/process.md +102 -90
  39. package/dist/host/guides/program.md +4 -0
  40. package/dist/host/guides/qualifier.md +4 -0
  41. package/dist/host/guides/rater.md +4 -0
  42. package/dist/host/guides/reason.md +6 -4
  43. package/dist/host/guides/relation.md +4 -0
  44. package/dist/host/guides/scaffold.md +32 -14
  45. package/dist/host/guides/server.md +29 -13
  46. package/dist/host/guides/sqlite.md +6 -0
  47. package/dist/host/guides/sse.md +6 -0
  48. package/dist/host/guides/study.md +473 -473
  49. package/dist/host/guides/table.md +3 -0
  50. package/dist/host/guides/template.md +3 -0
  51. package/dist/host/guides/test.md +38 -20
  52. package/dist/host/guides/tool.md +3 -0
  53. package/dist/host/guides/toolbox.md +21 -0
  54. package/dist/host/guides/websocket.md +3 -1
  55. package/dist/host/guides/workflow.md +103 -11
  56. package/dist/host/guides/workspace.md +4 -0
  57. package/dist/host/manifest.json +56 -56
  58. package/dist/host/tests/config.test.ts +72 -16
  59. package/dist/host/tests/policy.test.ts +21 -7
  60. package/dist/host/tests/setupPolicy.ts +147 -12
  61. package/dist/src/core/index.cjs +22 -28
  62. package/dist/src/core/index.cjs.map +1 -1
  63. package/dist/src/core/index.d.cts +8 -8
  64. package/dist/src/core/index.d.ts +8 -8
  65. package/dist/src/core/index.js +22 -28
  66. package/dist/src/core/index.js.map +1 -1
  67. 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. |
@@ -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
- `clickAccessibleWithin` matches the region's name exactly and the control's name loosely. That
538
- combination is what a person does with a repeated short verb such as `Add`, or with a line whose
539
- rendered status completes its accessible name: the region supplies the context, and the name only
540
- has to be recognisable inside it. The loose match reads a computed name that includes the hidden
541
- subtrees, so a glyph joins the text rather than displacing it and the control is still recognisable
542
- under the words beside it. That verb owns one refusal for a control it cannot reach, absent or
543
- hidden, so it needs no second pass to tell the two apart. `resolveAccessibleWithin` is that
544
- resolution on its own, and `holdAccessibleWithin` and `traverseAccessibleWithin` drive the control it
545
- resolves the way `holdAccessible` and `traverseAccessible` drive a document-wide one, so a twin of
546
- the same name in another region is left alone.
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 | Returns | Summary |
1202
- | -------- | ------- | ---------------------------------------------------------------------------- |
1203
- | `permit` | `void` | Grants the reads and the writes the host withheld, and replenishes no quota. |
1204
-
1205
- The rest of the surface is the platform's: `length`, `key`, `getItem`, `setItem`, `removeItem`, and
1206
- `clear` are declared by the host `Storage` interface this one extends. A store created here answers
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
  ```
@@ -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 only runtime dependency is `@orkestrel/emitter`, which supplies the typed emitter; [`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.
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 `scheduleHost` lifecycle helper, and every `delay` — plus each macrotask fallback — routes its timer through the one exported `delayHost` 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.
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 { scheduleHost } from '@orkestrel/workflow'
153
+ import { createHostSchedule } from '@orkestrel/workflow'
141
154
 
142
155
  const controller = new AbortController()
143
- await scheduleHost((complete) => {
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; `scheduleHost` 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.
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 `scheduleHost` to preserve the caller reason. `priority` is accepted but a no-op — Node has no priority primitive.
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 `scheduleHost` 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.
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; `scheduleHost` owns the scheduler's intentionally effectful host lifecycle.
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
- | `scheduleHost` | function | Schedules one cancellable host operation behind an owned settlement signal. |
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
- | `delayHost` | function | Schedules the shared host timer boundary every scheduler backend resumes from. |
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
- | `isSkipping` | function | Tests whether a task attempt is being genuinely cancelled rather than merely timed out. |
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, `scheduleHost` 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.
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