@orkestrel/scaffold 0.0.119 → 0.0.121

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 (73) hide show
  1. package/dist/bin/main.js +19 -19
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
  4. package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
  5. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
  6. package/dist/host/claude/agents/orkestrel.md +52 -51
  7. package/dist/host/claude/rules/tests.md +2 -2
  8. package/dist/host/claude/rules/typescript.md +2 -3
  9. package/dist/host/guides/abort.md +0 -4
  10. package/dist/host/guides/agent.md +5 -5
  11. package/dist/host/guides/brief.md +7 -15
  12. package/dist/host/guides/browser.md +1 -1
  13. package/dist/host/guides/budget.md +1 -5
  14. package/dist/host/guides/capture.md +2 -2
  15. package/dist/host/guides/codec.md +18 -3
  16. package/dist/host/guides/console.md +4 -30
  17. package/dist/host/guides/contract.md +23 -44
  18. package/dist/host/guides/csv.md +86 -93
  19. package/dist/host/guides/database.md +0 -4
  20. package/dist/host/guides/emitter.md +0 -2
  21. package/dist/host/guides/form.md +26 -47
  22. package/dist/host/guides/guide.md +0 -1
  23. package/dist/host/guides/html.md +3 -7
  24. package/dist/host/guides/indexeddb.md +28 -32
  25. package/dist/host/guides/interpret.md +165 -182
  26. package/dist/host/guides/jsonrpc.md +187 -0
  27. package/dist/host/guides/lsp.md +26 -51
  28. package/dist/host/guides/markdown.md +132 -141
  29. package/dist/host/guides/mcp.md +220 -276
  30. package/dist/host/guides/middleware.md +14 -22
  31. package/dist/host/guides/msg.md +47 -63
  32. package/dist/host/guides/ndjson.md +0 -4
  33. package/dist/host/guides/ollama.md +1 -3
  34. package/dist/host/guides/pool.md +0 -4
  35. package/dist/host/guides/probe.md +71 -80
  36. package/dist/host/guides/process.md +71 -79
  37. package/dist/host/guides/program.md +26 -35
  38. package/dist/host/guides/qualifier.md +0 -6
  39. package/dist/host/guides/queue.md +0 -4
  40. package/dist/host/guides/rater.md +6 -12
  41. package/dist/host/guides/reason.md +30 -36
  42. package/dist/host/guides/relation.md +0 -2
  43. package/dist/host/guides/router.md +11 -18
  44. package/dist/host/guides/scaffold.md +148 -144
  45. package/dist/host/guides/sea.md +47 -51
  46. package/dist/host/guides/server.md +15 -19
  47. package/dist/host/guides/sqlite.md +0 -4
  48. package/dist/host/guides/sse.md +6 -10
  49. package/dist/host/guides/table.md +481 -493
  50. package/dist/host/guides/template.md +0 -4
  51. package/dist/host/guides/terminal.md +0 -26
  52. package/dist/host/guides/test.md +46 -66
  53. package/dist/host/guides/timeout.md +0 -6
  54. package/dist/host/guides/tool.md +2 -6
  55. package/dist/host/guides/toolbox.md +0 -10
  56. package/dist/host/guides/websocket.md +0 -4
  57. package/dist/host/guides/worker.md +57 -57
  58. package/dist/host/guides/workflow.md +13 -26
  59. package/dist/host/guides/workspace.md +15 -21
  60. package/dist/host/manifest.json +64 -909
  61. package/dist/src/core/index.cjs +128 -181
  62. package/dist/src/core/index.cjs.map +1 -1
  63. package/dist/src/core/index.d.cts +213 -213
  64. package/dist/src/core/index.d.ts +213 -213
  65. package/dist/src/core/index.js +117 -170
  66. package/dist/src/core/index.js.map +1 -1
  67. package/dist/src/server/index.cjs +35 -34
  68. package/dist/src/server/index.cjs.map +1 -1
  69. package/dist/src/server/index.d.cts +62 -58
  70. package/dist/src/server/index.d.ts +62 -58
  71. package/dist/src/server/index.js +36 -35
  72. package/dist/src/server/index.js.map +1 -1
  73. package/package.json +13 -13
@@ -191,14 +191,10 @@ The **browser** backends ship in [`src/browser`](../src/browser), published thro
191
191
 
192
192
  The browser backends also publish supporting members through `@orkestrel/workflow/browser`: the `POST_TASK_PRIORITY` map `BrowserScheduler` reads to translate a portable `SchedulerPriority` into a `scheduler.postTask` priority level, and the `IdleInterface` shape of the feature-detected `requestIdleCallback` / `cancelIdleCallback` pair `IdleScheduler` narrows to (or resolves to `undefined`, falling back to a macrotask).
193
193
 
194
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
195
-
196
194
  | Name | Kind | Signature | Summary |
197
195
  | --------------- | --------- | --------------------- | ---------------------------------------------------------------------------------------------------------- |
198
196
  | `IdleInterface` | interface | `{ request, cancel }` | Declares the narrowed `requestIdleCallback` / `cancelIdleCallback` pair feature-detected off `globalThis`. |
199
197
 
200
- A `Shape` cell holds the constant's declared type.
201
-
202
198
  | Name | Kind | Signature | Summary |
203
199
  | -------------------- | ----- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
204
200
  | `POST_TASK_PRIORITY` | const | `Readonly<Record<SchedulerPriority, string>>` | Maps each portable `SchedulerPriority` to the browser-native `postTask` priority — `user` to `'user-blocking'`, `normal` to `'user-visible'`, and `background` to `'background'`. |
@@ -242,7 +238,9 @@ Centralized, exhaustively unit-tested helpers and guards. The status derivations
242
238
  Generic exact-JSON ownership comes directly from [`@orkestrel/contract`](contract.md):
243
239
  consumers import its `JSONRecord`, `cloneJSONValue`, and `cloneJSONRecord` from their
244
240
  originating package. Workflow does not re-export them. Its domain cloners below add
245
- workflow-specific validation and translate ownership failures into `WorkflowError`.
241
+ workflow-specific validation and translate ownership failures into `WorkflowError`. The
242
+ `success` and `failure` constructors that box a `Result`, and the `errorToMessage` function
243
+ that renders a thrown value as a failure message, also come from `@orkestrel/contract`.
246
244
 
247
245
  | Name | Kind | Signature | Summary |
248
246
  | --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -267,9 +265,6 @@ workflow-specific validation and translate ownership failures into `WorkflowErro
267
265
  | `isTaskActivity` | function | `(value: unknown) => value is TaskActivity` | Tests whether an unknown value is valid persisted task activity. |
268
266
  | `captureWorkflowOptions` | function | `(options?: WorkflowOptions) => WorkflowOptions` | Captures every top-level `WorkflowOptions` value exactly once into an owned plain bag. |
269
267
  | `createHostSchedule` | function | `(start: HostScheduleFunction, signal?: AbortSignal) => Promise<void>` | Schedules one cancellable host operation behind an owned settlement signal. |
270
- | `success` | function | `<T>(value: T) => Success<T>` | Boxes a value as a `Success` — the graceful outcome half of a `Result`. |
271
- | `failure` | function | `<E>(error: E) => Failure<E>` | Boxes an error as a `Failure` — the graceful outcome half of a `Result`. |
272
- | `errorToMessage` | function | `(error: unknown) => string` | Normalizes an unknown thrown value to a non-empty persistence-safe message. |
273
268
  | `findFailure` | function | `(results: readonly TaskResult[]) => TaskResult \| undefined` | Finds the first `TaskResult` in a positional list whose boxed outcome is a `Failure` — the pure scan shared by a phase's and a workflow's derived-`failed` `fail`-event lookup. |
274
269
  | `buildWorkflowContext` | function | `(node: WorkflowContext) => WorkflowContext` | Builds a `WorkflowContext` — the identity every level inherits — from a node's `id` / `name` / optional `description`. |
275
270
  | `buildPhaseContext` | function | `(workflow: WorkflowContext, node: WorkflowContext) => PhaseContext` | Builds a `PhaseContext` — a phase's own identity plus a back-reference to its workflow — from the parent `WorkflowContext` and the phase node's identity. |
@@ -302,7 +297,6 @@ The exact snapshot boundary is also available as composable public leaves:
302
297
  import {
303
298
  cloneWorkflowSnapshot,
304
299
  createWorkflow,
305
- errorToMessage,
306
300
  hasWorkflowHandlers,
307
301
  isLifecycleStatus,
308
302
  isOwnedWorkflowSnapshot,
@@ -341,7 +335,6 @@ if (phase !== undefined && task !== undefined) {
341
335
  matchesDescription(snapshot.description, workflow.description)
342
336
  hasWorkflowHandlers(snapshot, functions)
343
337
  scanSnapshotContext({ ...snapshot, bail: 'invalid' })
344
- errorToMessage(new Error('provider failed'))
345
338
  recoverWorkflowSnapshot(snapshot)
346
339
  ```
347
340
 
@@ -365,20 +358,16 @@ resolveTaskSilence(0, 30_000) // undefined: the task explicitly disables inherit
365
358
 
366
359
  `createWorkflowContract` derives its lockstep JSON Schema, guard, parser, and generator from these shape values. They agree with the hand-written definition interfaces (the source of truth); a round-trip parity test (`generate → is → parse`) guards against drift.
367
360
 
368
- A `Shape` cell holds the constant's declared type.
369
-
370
- | Name | Kind | Signature | Summary |
371
- | ------------------ | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
372
- | `taskShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; behavior: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; retries: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>` | Describes the shape of a `TaskDefinition` — identity plus an optional `behavior` behavior reference (a plain registry-key string, min length 1). `description` is optional prose. |
373
- | `phaseShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; tasks: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; behavior: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; retries: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a `PhaseDefinition` — identity, its ordered `taskShape` tasks, and an optional positive-integer `concurrency` throttle (max tasks in flight; omitted ⇒ unbounded). |
374
- | `workflowShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; phases: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; tasks: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; behavior: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; retries: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a `WorkflowDefinition` — the contract root: identity, its ordered `phaseShape` phases, and the optional `bail` boolean failure policy (the literal pair `true`/`false`, the runtime mirror of the boolean toggle; omitted ⇒ the graceful default). |
375
- | `taskUpdateShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; }, false>` | Describes the shape of a `TaskUpdate` — a partial edit to a `pending` task's `name` / `description`, both optional. |
376
- | `phaseUpdateShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a `PhaseUpdate` — a partial edit to a `pending` phase's `name` / `description` / `concurrency` / `bail`, all optional. |
361
+ | Name | Kind | Signature | Summary |
362
+ | --------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
363
+ | `taskDefinitionShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; behavior: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; retries: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>` | Describes the shape of a `TaskDefinition` — identity plus an optional `behavior` behavior reference (a plain registry-key string, min length 1). `description` is optional prose. |
364
+ | `phaseShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; tasks: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; behavior: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; retries: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a `PhaseDefinition` — identity, its ordered `taskDefinitionShape` tasks, and an optional positive-integer `concurrency` throttle (max tasks in flight; omitted ⇒ unbounded). |
365
+ | `workflowShape` | const | `import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; phases: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; tasks: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ id: import("@orkestrel/contract").StringShape; name: import("@orkestrel/contract").StringShape; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; behavior: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; retries: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, false>>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a `WorkflowDefinition` — the contract root: identity, its ordered `phaseShape` phases, and the optional `bail` boolean failure policy (the literal pair `true`/`false`, the runtime mirror of the boolean toggle; omitted ⇒ the graceful default). |
366
+ | `taskUpdateShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; }, false>` | Describes the shape of a `TaskUpdate` — a partial edit to a `pending` task's `name` / `description`, both optional. |
367
+ | `phaseUpdateShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; description: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; concurrency: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bail: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").LiteralShape<readonly [true, false]>>; }, false>` | Describes the shape of a `PhaseUpdate` — a partial edit to a `pending` phase's `name` / `description` / `concurrency` / `bail`, all optional. |
377
368
 
378
369
  ### Constants
379
370
 
380
- A `Shape` cell holds the constant's declared type.
381
-
382
371
  | Name | Kind | Signature | Summary |
383
372
  | --------------------------- | ----- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
384
373
  | `DEFAULT_BAIL` | const | `false` | Names the default `WorkflowDefinition.bail`, `false` — the graceful policy that records a leaf failure and finishes every phase. |
@@ -392,8 +381,6 @@ A `Shape` cell holds the constant's declared type.
392
381
 
393
382
  ### Types
394
383
 
395
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
396
-
397
384
  | Name | Kind | Signature | Summary |
398
385
  | ------------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
399
386
  | `TaskDefinition` | interface | `{ id, name, description?, behavior?, retries?, timeout? }` | Represents the serializable definition of one task — its identity, an optional reference to the behavior it runs, and its optional per-task `retries` and `timeout` overrides. |
@@ -406,8 +393,8 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
406
393
  | `PhaseInput` | type | `Partial<PhaseContext>` | Represents the minimal data to create a phase context — a partial `PhaseContext`. |
407
394
  | `TaskInput` | interface | `{ metadata? }` | Represents the minimal data to create a task context — a partial `TaskContext` plus the open `metadata` bag the task stores and snapshots without interpreting it. |
408
395
  | `TaskProgress` | interface | `{ progress, total?, message? }` | Represents the aggregate progress most recently reported by a running task. |
409
- | `TaskClaim` | interface | `{ id, name, started }` | Represents one identified thing a running task claims active, with the moment the claim began — the shape `TaskOperation` and `TaskConstraint` share. |
410
- | `TaskOperation` | interface | `{}` | Represents one operation claimed active when a running task's complete frame was accepted. |
396
+ | `TaskClaim` | interface | `{ id, name, started }` | Represents one identified thing a running task claims active, with the moment the claim began — the shape `TaskActivityOperation` and `TaskConstraint` share. |
397
+ | `TaskActivityOperation` | interface | `{}` | Represents one operation claimed active when a running task's complete frame was accepted. |
411
398
  | `TaskConstraint` | interface | `{}` | Represents one constraint claimed active when a running task's complete frame was accepted. |
412
399
  | `TaskActivityInput` | interface | `{ note?, progress?, operations?, constraints? }` | Represents one complete replacement of a running task's observable activity, an omitted collection meaning an empty one. |
413
400
  | `TaskActivity` | interface | `{ note?, progress?, operations, constraints, updated }` | Represents the bounded, JSON-serializable activity most recently accepted from a task reporter. |
@@ -1565,7 +1552,7 @@ A successful run fires `start` → `unit`/`settle` per unit → `finish`. A fail
1565
1552
  - [`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.
1566
1553
  - [`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.
1567
1554
  - [`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.
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`.
1555
+ - [`tests/src/core/shapers.test.ts`](../tests/src/core/shapers.test.ts) — the shape descriptors: the `taskDefinitionShape` / `phaseShape` / `workflowShape` mirroring the hand-written definition interfaces, the per-field `description`s riding the `behavior` string + key fields (Rank 1), `describedLiteral`.
1569
1556
  - [`tests/src/core/tasks/Task.test.ts`](../tests/src/core/tasks/Task.test.ts) — lifecycle plus whole-frame activity, validation/immutability, pulse, repeatable silence rearming, task signal, terminal cleanup, and cooperative pause.
1570
1557
  - [`tests/src/core/phases/Phase.test.ts`](../tests/src/core/phases/Phase.test.ts) — the derived middle tier: child-transition cascade, `skip` / `stop` override, results, snapshot/restore, and isolated lifecycle emission including idempotent pause/resume.
1571
1558
  - [`tests/src/core/Workflow.test.ts`](../tests/src/core/Workflow.test.ts) — the derived root: bail-aware cascade, result tree, override, snapshot/restore, teardown, and isolated lifecycle emission including idempotent pause/resume.
@@ -33,8 +33,6 @@ documented under [`## Methods`](#methods), and its readonly data members stay he
33
33
  `emitter`, and `count` on `WorkspaceInterface`, `count` and `active` on
34
34
  `WorkspaceManagerInterface`, and none on `WorkspaceStoreInterface`.
35
35
 
36
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
37
-
38
36
  | Name | Kind | Signature | Summary |
39
37
  | --------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
40
38
  | `BinaryMIME` | type | `'image/png' \| 'image/jpeg' \| 'image/gif' \| 'image/webp'` | Names the MIME labels a binary `FileContent` arm supports. |
@@ -44,7 +42,7 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
44
42
  | `FileState` | type | `'created' \| 'modified'` | Names the edit state of an immutable file value: `created` for the first write to a path and `modified` for every later edit of that path. |
45
43
  | `FileInput` | interface | `{ path, content, state? }` | Carries the caller-supplied values used to create an immutable file. The byte size and the line count are derived rather than supplied. |
46
44
  | `FileInterface` | interface | `{ path, content, state, size, lines }` | Represents an immutable path-addressed file with derived byte and line counts. |
47
- | `Position` | interface | `{ line, column }` | Locates a 1-based caret inside text. |
45
+ | `Caret` | interface | `{ line, column }` | Locates a 1-based caret inside text. |
48
46
  | `Range` | interface | `{ start, end }` | Represents a half-open text span whose start is inclusive and end is exclusive. |
49
47
  | `ReadResult` | interface | `{ content, range }` | Carries the content and clamped span returned by a ranged read. |
50
48
  | `SearchOptions` | interface | `{ regex?, sensitive?, limit? }` | Configures search and replacement behavior. |
@@ -62,8 +60,6 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
62
60
 
63
61
  ### Constants
64
62
 
65
- A `Shape` cell holds the constant's declared type.
66
-
67
63
  | Name | Kind | Signature | Summary |
68
64
  | --------------------- | ----- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
69
65
  | `EXTENSION_LANGUAGES` | const | `Readonly<Record<string, string>>` | Maps file extensions to language tags for text content. The table is frozen, and an extension it does not list falls back to `text` in `inferLanguage`. |
@@ -86,27 +82,24 @@ on its own, and the classes compose them rather than hiding them.
86
82
  | Name | Kind | Signature | Summary |
87
83
  | -------------------- | -------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
88
84
  | `inferLanguage` | function | `(path: string) => string` | Infers a language tag from the final file extension. |
89
- | `isText` | function | `(content: FileContent) => content is TextContent` | Determines whether content is the text arm. |
85
+ | `isTextContent` | function | `(content: FileContent) => content is TextContent` | Determines whether content is the text arm. |
90
86
  | `isBinary` | function | `(content: FileContent) => content is BinaryContent` | Determines whether content is the binary arm. |
91
87
  | `computeSize` | function | `(content: FileContent) => number` | Computes the byte size of file content. |
92
88
  | `countLines` | function | `(content: FileContent) => number` | Counts the lines in file content. |
93
89
  | `computeDecodedSize` | function | `(base64: string) => number` | Computes the decoded byte length of a base64 string, arithmetically rather than by decoding it. |
94
90
  | `isValidRange` | function | `(range: Range) => boolean` | Determines whether a 1-based range is structurally valid. |
95
- | `clampPosition` | function | `(text: string, position: Position) => Position` | Clamps a position to text bounds. |
96
- | `clampRange` | function | `(text: string, range: Range) => Range` | Clamps both positions in a range to text bounds. |
97
- | `offsetAt` | function | `(text: string, position: Position) => number` | Converts a 1-based position to a zero-based string offset. |
91
+ | `clampCaret` | function | `(text: string, caret: Caret) => Caret` | Clamps a caret to text bounds. |
92
+ | `clampRange` | function | `(text: string, range: Range) => Range` | Clamps both carets in a range to text bounds. |
93
+ | `offsetAt` | function | `(text: string, caret: Caret) => number` | Converts a 1-based caret to a zero-based string offset. |
98
94
  | `sliceRange` | function | `(text: string, range: Range) => string` | Slices a clamped half-open text range. |
99
95
  | `spliceRange` | function | `(text: string, range: Range, replacement: string) => string` | Replaces a clamped half-open text range. |
100
96
  | `rangeOf` | function | `(fromLine: number, fromColumn: number, toLine: number, toColumn: number) => Range` | Assembles a nested range from four 1-based coordinates. |
101
- | `escapeRegExp` | function | `(value: string) => string` | Escapes regular-expression metacharacters for literal matching. |
102
97
 
103
98
  ### Validators
104
99
 
105
100
  The total guards, from [`validators.ts`](../src/core/validators.ts). Each narrows an `unknown`
106
101
  value arriving from outside the process without throwing on a hostile property access.
107
102
 
108
- In a guard table a `Shape` cell holds the type the guard narrows to.
109
-
110
103
  | Name | Kind | Signature | Summary |
111
104
  | --------------------- | -------- | ------------------------------------------------ | ----------------------------------------------------- |
112
105
  | `isFile` | function | `(value: unknown) => value is FileInterface` | Narrows an unknown value to an immutable file record. |
@@ -244,7 +237,7 @@ import {
244
237
  createTextContent,
245
238
  inferLanguage,
246
239
  isBinary,
247
- isText,
240
+ isTextContent,
248
241
  } from '@orkestrel/workspace'
249
242
 
250
243
  const note = createFile({
@@ -255,7 +248,7 @@ const note = createFile({
255
248
  note.size // 12 — UTF-8 bytes, through computeSize
256
249
  note.lines // 2 — through countLines
257
250
  note.state // 'created'
258
- isText(note.content) // true
251
+ isTextContent(note.content) // true
259
252
 
260
253
  const icon = createFile({ path: 'icon.png', content: createBinaryContent('AAAA', 'image/png') })
261
254
  isBinary(icon.content) // true
@@ -305,11 +298,11 @@ path with `Cannot splice a range of a binary file: <path>` under `MODALITY`. A s
305
298
  impossible range — inverted, or with a coordinate below one — throws `RANGE`. A range that is merely too
306
299
  large is not an error: both endpoints clamp to the text's bounds, so `rangeOf(1, 2, 9, 9)` over
307
300
  `'abc'` addresses everything from the second column onward. The pure functions behind that
308
- behavior are exported and usable on their own: `isValidRange`, `clampPosition`, `clampRange`,
301
+ behavior are exported and usable on their own: `isValidRange`, `clampCaret`, `clampRange`,
309
302
  `offsetAt`, `sliceRange`, and `spliceRange`.
310
303
 
311
304
  Ranges are half-open and 1-based. `rangeOf(1, 1, 1, 6)` covers the first five columns of line one,
312
- which is the convention every editor position in this package follows.
305
+ which is the convention every caret in this package follows.
313
306
 
314
307
  ## Reading and searching
315
308
 
@@ -317,7 +310,7 @@ Reads are shaped by what the caller asked for, and binary content is quietly abs
317
310
  that promise text:
318
311
 
319
312
  ```ts
320
- import { createWorkspace, escapeRegExp, rangeOf } from '@orkestrel/workspace'
313
+ import { createWorkspace, rangeOf } from '@orkestrel/workspace'
321
314
 
322
315
  const workspace = createWorkspace()
323
316
  workspace.write({ 'a.ts': 'const x = 1\nconst y = 2', 'b.ts': 'const z = 3' })
@@ -335,9 +328,9 @@ workspace.has(['missing.ts', 'b.ts']) // false — a batch answers true only whe
335
328
 
336
329
  workspace.search('const') // three matches, a.ts before b.ts, line order within each
337
330
  workspace.search('[a-z]\\d', { regex: true }) // pattern source instead of literal text
331
+ workspace.search('const.') // [] — a literal query reads '.' as a dot, not as any character
338
332
  workspace.search('CONST', { sensitive: false, limit: 2 })
339
333
  workspace.replace('const', 'let') // { occurrences: 3, files: 2 }
340
- escapeRegExp('a.b') // 'a\\.b' — what a literal search does for you
341
334
  ```
342
335
 
343
336
  A plain read of a binary path returns `undefined`, exactly as an absent path does; a batch read
@@ -345,9 +338,10 @@ omits both. A ranged read of binary content is the one that throws `MODALITY`, b
345
338
  named coordinates that cannot exist. Search and replace skip binary content entirely, so base64
346
339
  that happens to spell a query is never a hit.
347
340
 
348
- A query is literal by default — `escapeRegExp` neutralizes its metacharacters — and `regex: true`
349
- passes it through as pattern source instead. `limit` caps hits for `search` and replacements for
350
- `replace`, counted across files in insertion order. A pattern that will not compile throws
341
+ A query is literal by default — the `escapeRegExp` function from `@orkestrel/contract` neutralizes
342
+ its metacharacters — and `regex: true` passes it through as pattern source instead. `limit` caps
343
+ hits for `search` and replacements for `replace`, counted across files in insertion order. A
344
+ pattern that will not compile throws
351
345
  `PATTERN` rather than silently matching nothing. A zero-width pattern such as `a*` terminates: the
352
346
  scan advances past an empty match instead of re-matching the same column.
353
347