@orkestrel/scaffold 0.0.115 → 0.0.117

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 (70) hide show
  1. package/dist/bin/main.js +138 -16
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +1 -1
  4. package/dist/host/claude/agents/orkestrel.md +2 -2
  5. package/dist/host/claude/rules/names.md +3 -1
  6. package/dist/host/guides/abort.md +17 -17
  7. package/dist/host/guides/agent.md +445 -445
  8. package/dist/host/guides/brief.md +143 -143
  9. package/dist/host/guides/browser.md +731 -731
  10. package/dist/host/guides/budget.md +39 -39
  11. package/dist/host/guides/capture.md +298 -298
  12. package/dist/host/guides/console.md +109 -109
  13. package/dist/host/guides/contract.md +335 -335
  14. package/dist/host/guides/csv.md +30 -30
  15. package/dist/host/guides/database.md +163 -163
  16. package/dist/host/guides/emitter.md +17 -17
  17. package/dist/host/guides/form.md +99 -99
  18. package/dist/host/guides/guide.md +368 -183
  19. package/dist/host/guides/html.md +49 -49
  20. package/dist/host/guides/indexeddb.md +40 -40
  21. package/dist/host/guides/interpret.md +139 -139
  22. package/dist/host/guides/lsp.md +114 -114
  23. package/dist/host/guides/markdown.md +68 -68
  24. package/dist/host/guides/mcp.md +3745 -3745
  25. package/dist/host/guides/middleware.md +170 -170
  26. package/dist/host/guides/msg.md +95 -95
  27. package/dist/host/guides/ndjson.md +8 -8
  28. package/dist/host/guides/ollama.md +56 -56
  29. package/dist/host/guides/pool.md +21 -21
  30. package/dist/host/guides/probe.md +82 -82
  31. package/dist/host/guides/process.md +99 -99
  32. package/dist/host/guides/program.md +98 -96
  33. package/dist/host/guides/qualifier.md +70 -70
  34. package/dist/host/guides/queue.md +37 -37
  35. package/dist/host/guides/rater.md +38 -38
  36. package/dist/host/guides/reason.md +308 -308
  37. package/dist/host/guides/relation.md +50 -50
  38. package/dist/host/guides/router.md +58 -58
  39. package/dist/host/guides/scaffold.md +558 -419
  40. package/dist/host/guides/sea.md +128 -128
  41. package/dist/host/guides/server.md +100 -100
  42. package/dist/host/guides/sqlite.md +28 -28
  43. package/dist/host/guides/sse.md +20 -20
  44. package/dist/host/guides/study.md +444 -444
  45. package/dist/host/guides/table.md +82 -82
  46. package/dist/host/guides/template.md +41 -41
  47. package/dist/host/guides/terminal.md +121 -121
  48. package/dist/host/guides/test.md +273 -273
  49. package/dist/host/guides/timeout.md +18 -18
  50. package/dist/host/guides/tool.md +27 -27
  51. package/dist/host/guides/toolbox.md +166 -166
  52. package/dist/host/guides/websocket.md +54 -54
  53. package/dist/host/guides/worker.md +24 -24
  54. package/dist/host/guides/workflow.md +187 -187
  55. package/dist/host/guides/workspace.md +55 -55
  56. package/dist/host/manifest.json +55 -55
  57. package/dist/host/tests/setupPolicy.ts +5 -3
  58. package/dist/src/core/index.cjs +90 -4
  59. package/dist/src/core/index.cjs.map +1 -1
  60. package/dist/src/core/index.d.cts +229 -144
  61. package/dist/src/core/index.d.ts +229 -144
  62. package/dist/src/core/index.js +88 -5
  63. package/dist/src/core/index.js.map +1 -1
  64. package/dist/src/server/index.cjs +295 -66
  65. package/dist/src/server/index.cjs.map +1 -1
  66. package/dist/src/server/index.d.cts +193 -6
  67. package/dist/src/server/index.d.ts +193 -6
  68. package/dist/src/server/index.js +290 -69
  69. package/dist/src/server/index.js.map +1 -1
  70. package/package.json +5 -4
@@ -51,52 +51,52 @@ const status = await queue.enqueue('https://example.com')
51
51
 
52
52
  ### Factories
53
53
 
54
- | API | Kind | Summary |
55
- | -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
56
- | `createQueue` | function | Creates a concurrent, cooperative job queue — a bounded-concurrency engine that runs each enqueued input through a handler, with retries and a per-attempt timeout / abort, all over the L1 `Abort` / `Timeout` primitives. |
57
- | `createDatabaseQueueStore` | function | Creates a `DatabaseQueueStore` over any `DriverInterface` — the durable, driver-pluggable backing for a queue's outstanding entries, across a memory, JSON, or SQLite driver. |
58
- | `createMemoryQueueStore` | function | Creates an in-memory `MemoryQueueStore` over a plain `Map` — the zero-plumbing `QueueStoreInterface` a queue takes when its outstanding entries need not outlive the process, and the twin of `DatabaseQueueStore`. |
54
+ | Name | Kind | Signature | Summary |
55
+ | -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
56
+ | `createQueue` | function | `<TInput, TResult>(options: QueueOptions<TInput, TResult>) => QueueInterface<TInput, TResult>` | Creates a concurrent, cooperative job queue — a bounded-concurrency engine that runs each enqueued input through a handler, with retries and a per-attempt timeout / abort, all over the L1 `Abort` / `Timeout` primitives. |
57
+ | `createDatabaseQueueStore` | function | `<TInput extends ContractShape>(input: TInput, driver: DriverInterface) => QueueStoreInterface<Infer<TInput>>` | Creates a `DatabaseQueueStore` over any `DriverInterface` — the durable, driver-pluggable backing for a queue's outstanding entries, across a memory, JSON, or SQLite driver. |
58
+ | `createMemoryQueueStore` | function | `<TInput extends ContractShape>(input: TInput) => QueueStoreInterface<Infer<TInput>>` | Creates an in-memory `MemoryQueueStore` over a plain `Map` — the zero-plumbing `QueueStoreInterface` a queue takes when its outstanding entries need not outlive the process, and the twin of `DatabaseQueueStore`. |
59
59
 
60
60
  ### Classes
61
61
 
62
- | API | Kind | Summary |
63
- | -------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
64
- | `Queue` | class | Represents a concurrent, cooperative FIFO job queue — a wake-park worker loop with retries, a per-attempt timeout, abort, and optional outstanding-work persistence. |
65
- | `QueueError` | class | Represents a queue failure carrying a lowercase machine-readable `code`, optional structured context, and an optional cause. |
66
- | `MemoryQueueStore` | class | Represents an in-memory store of a queue's outstanding entries — a process-lifetime `Map` owning validated, immutable JSON snapshots. |
67
- | `DatabaseQueueStore` | class | Represents the opt-in durable store for a queue's outstanding entries, backed by one table of the `@orkestrel/database` layer — a queue's durable state is a table, so persistence reduces to keyed CRUD over a `TableInterface`. |
62
+ | Name | Kind | Signature | Summary |
63
+ | -------------------- | ----- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
64
+ | `Queue` | class | `new <TInput, TResult>(options: QueueOptions<TInput, TResult>) => QueueInterface<TInput, TResult>` | Represents a concurrent, cooperative FIFO job queue — a wake-park worker loop with retries, a per-attempt timeout, abort, and optional outstanding-work persistence. |
65
+ | `QueueError` | class | `new (message: string, options: QueueErrorOptions) => QueueError` | Represents a queue failure carrying a lowercase machine-readable `code`, optional structured context, and an optional cause. |
66
+ | `MemoryQueueStore` | class | `new <TInput extends ContractShape>(input: TInput) => QueueStoreInterface<Infer<TInput>>` | Represents an in-memory store of a queue's outstanding entries — a process-lifetime `Map` owning validated, immutable JSON snapshots. |
67
+ | `DatabaseQueueStore` | class | `new <TInput>(table: TableInterface<StoredEntry<TInput>>) => QueueStoreInterface<TInput>` | Represents the opt-in durable store for a queue's outstanding entries, backed by one table of the `@orkestrel/database` layer — a queue's durable state is a table, so persistence reduces to keyed CRUD over a `TableInterface`. |
68
68
 
69
69
  ### Types
70
70
 
71
71
  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 `\|`.
72
72
 
73
- | Type | Kind | Shape | Summary |
74
- | --------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
75
- | `QueueContext` | interface | `{ id, signal }` | Represents the per-attempt context a queue handler receives. |
76
- | `QueueHandler` | type | `(input: TInput, context: QueueContext) => Promise<TResult> \| TResult` | Runs one queued entry's work; a rejection triggers a retry while attempts remain. |
77
- | `QueueEntryOptions` | interface | `{ id?, retries?, timeout?, signal? }` | Represents the per-entry options for `enqueue`. |
78
- | `QueueOptions` | interface | `{ on?, error?, handler, concurrency?, retries?, timeout?, store? }` | Represents the options for `createQueue`. |
79
- | `QueueInterface` | interface | `{ emitter, count, active, paused, stopped } plus enqueue, restore, start, stop, pause, resume, abort, clear, destroy` | Represents the contract a queue consumer holds — the readings of its live work, the typed observation surface, and the calls that submit, restore, and wind it down. |
80
- | `QueueEventMap` | type | `{ enqueue, start, retry, success, failure, abort, drain }` | Represents the push observation surface of a `QueueInterface` — the lifecycle moments a fire-and-forget observer (logging, metrics, tracing) subscribes to, beside the per-entry `enqueue` promise. |
81
- | `QueueCode` | type | `'invalid' \| 'duplicate' \| 'stopped' \| 'aborted' \| 'destroyed' \| 'cleared' \| 'timeout' \| 'store' \| 'cleanup'` | Represents the machine-readable queue failure categories. |
82
- | `QueueOption` | type | `'id' \| 'concurrency' \| 'retries' \| 'timeout' \| 'signal'` | Represents the construction and per-entry option keys a queue validates. |
83
- | `QueueErrorContext` | interface | `{ id?, option?, operation?, value? }` | Represents the structured context carried by a `QueueError`. |
84
- | `QueueErrorOptions` | interface | `{ code, context?, cause? }` | Represents the construction options for a `QueueError`. |
85
- | `StoredEntry` | interface | `{ id, input, attempts }` | Represents a durably persisted, still-outstanding queue entry — re-run after a restart. |
86
- | `QueueStoreInterface` | interface | `{} plus save, remove, load, clear` | Represents the durable backing for a queue's outstanding entries — the small keyed surface a restart resumes from. |
73
+ | Name | Kind | Signature | Summary |
74
+ | --------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
75
+ | `QueueContext` | interface | `{ id, signal }` | Represents the per-attempt context a queue handler receives. |
76
+ | `QueueHandler` | type | `(input: TInput, context: QueueContext) => Promise<TResult> \| TResult` | Runs one queued entry's work; a rejection triggers a retry while attempts remain. |
77
+ | `QueueEntryOptions` | interface | `{ id?, retries?, timeout?, signal? }` | Represents the per-entry options for `enqueue`. |
78
+ | `QueueOptions` | interface | `{ on?, error?, handler, concurrency?, retries?, timeout?, store? }` | Represents the options for `createQueue`. |
79
+ | `QueueInterface` | interface | `{ emitter, count, active, paused, stopped, enqueue(), restore(), start(), stop(), pause(), resume(), abort(), clear(), destroy() }` | Represents the contract a queue consumer holds — the readings of its live work, the typed observation surface, and the calls that submit, restore, and wind it down. |
80
+ | `QueueEventMap` | type | `{ readonly enqueue: readonly [id: string]; readonly start: readonly [id: string]; readonly retry: readonly [id: string, attempt: number]; readonly success: readonly [id: string, result: TResult]; readonly failure: readonly [id: string, error: unknown]; readonly abort: readonly [reason: unknown]; readonly drain: readonly []; }` | Represents the push observation surface of a `QueueInterface` — the lifecycle moments a fire-and-forget observer (logging, metrics, tracing) subscribes to, beside the per-entry `enqueue` promise. |
81
+ | `QueueCode` | type | `'invalid' \| 'duplicate' \| 'stopped' \| 'aborted' \| 'destroyed' \| 'cleared' \| 'timeout' \| 'store' \| 'cleanup'` | Represents the machine-readable queue failure categories. |
82
+ | `QueueOption` | type | `'id' \| 'concurrency' \| 'retries' \| 'timeout' \| 'signal'` | Represents the construction and per-entry option keys a queue validates. |
83
+ | `QueueErrorContext` | interface | `{ id?, option?, operation?, value? }` | Represents the structured context carried by a `QueueError`. |
84
+ | `QueueErrorOptions` | interface | `{ code, context?, cause? }` | Represents the construction options for a `QueueError`. |
85
+ | `StoredEntry` | interface | `{ id, input, attempts }` | Represents a durably persisted, still-outstanding queue entry — re-run after a restart. |
86
+ | `QueueStoreInterface` | interface | `{ save(), remove(), load(), clear() }` | Represents the durable backing for a queue's outstanding entries — the small keyed surface a restart resumes from. |
87
87
 
88
88
  ### Guards
89
89
 
90
90
  In a guard table a `Shape` cell holds the type the guard narrows to.
91
91
 
92
- | API | Kind | Shape | Summary |
93
- | -------------------- | -------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
94
- | `isQueueError` | function | `QueueError` | Determines whether an unknown value is a `QueueError`, staying total for a hostile value. |
95
- | `isQueueConcurrency` | function | `number` | Determines whether a value is a valid queue concurrency — a positive safe integer. |
96
- | `isQueueRetries` | function | `number` | Determines whether a value is a valid queue retry count — a nonnegative safe integer. |
97
- | `isQueueTimeout` | function | `number` | Determines whether a value is a valid queue timeout — an integer count of milliseconds inside the native timer range. |
98
- | `isQueueSignal` | function | `AbortSignal` | Determines whether a value is a native abort signal usable by the queue, testing the native brand rather than the shape. |
99
- | `isStoredEntry` | function | `StoredEntry<unknown>` | Determines whether a value is a valid stored queue entry — a record holding a string `id`, an `input`, and a nonnegative safe-integer `attempts`. |
92
+ | Name | Kind | Signature | Summary |
93
+ | -------------------- | -------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
94
+ | `isQueueError` | function | `(value: unknown) => value is QueueError` | Determines whether an unknown value is a `QueueError`, staying total for a hostile value. |
95
+ | `isQueueConcurrency` | function | `(value: unknown) => value is number` | Determines whether a value is a valid queue concurrency — a positive safe integer. |
96
+ | `isQueueRetries` | function | `(value: unknown) => value is number` | Determines whether a value is a valid queue retry count — a nonnegative safe integer. |
97
+ | `isQueueTimeout` | function | `(value: unknown) => value is number` | Determines whether a value is a valid queue timeout — an integer count of milliseconds inside the native timer range. |
98
+ | `isQueueSignal` | function | `(value: unknown) => value is AbortSignal` | Determines whether a value is a native abort signal usable by the queue, testing the native brand rather than the shape. |
99
+ | `isStoredEntry` | function | `(value: unknown) => value is StoredEntry<unknown>` | Determines whether a value is a valid stored queue entry — a record holding a string `id`, an `input`, and a nonnegative safe-integer `attempts`. |
100
100
 
101
101
  Call each guard on a sample value to see what it accepts and what it refuses:
102
102
 
@@ -120,10 +120,10 @@ isStoredEntry({ id: 'job-1', input: 'task', attempts: 0 }) // true
120
120
 
121
121
  `readOption` and `validateOption` back the queue's option handling. `enqueue` reads every entry option through `readOption`, because a caller's `QueueEntryOptions` is foreign; `enqueue` and the constructor then check what they read through `validateOption`.
122
122
 
123
- | API | Kind | Summary |
124
- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
125
- | `readOption` | function | Reads one named option from a caller-supplied entry options object exactly once, containing a throwing getter as a coded failure. |
126
- | `validateOption` | function | Validates one already-read queue option against its guard, and throws the coded invalid failure carrying the option and the refused value when the guard refuses it. |
123
+ | Name | Kind | Signature | Summary |
124
+ | ---------------- | -------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
125
+ | `readOption` | function | `(options: QueueEntryOptions \| undefined, option: keyof QueueEntryOptions, message: string) => unknown` | Reads one named option from a caller-supplied entry options object exactly once, containing a throwing getter as a coded failure. |
126
+ | `validateOption` | function | `<TValue>(value: unknown, guard: Guard<TValue>, option: QueueOption, message: string) => TValue` | Validates one already-read queue option against its guard, and throws the coded invalid failure carrying the option and the refused value when the guard refuses it. |
127
127
 
128
128
  Read one entry option, then validate what you read — the pair `enqueue` runs for every option a caller supplies:
129
129
 
@@ -68,7 +68,7 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
68
68
  optional member and `plus` introducing its call-signature members, and a type alias's own
69
69
  type literal with a union's arms escaped as `\|`.
70
70
 
71
- | Type | Kind | Shape | Summary |
71
+ | Name | Kind | Signature | Summary |
72
72
  | ------------------ | --------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
73
73
  | `Stage` | type | `'factor' \| 'group' \| 'total'` | Names a worksheet derivation step stage. |
74
74
  | `RaterErrorCode` | type | `'DEFINITION' \| 'MISMATCH' \| 'DESTROYED'` | Names a coded `RaterError` programmer-error code. |
@@ -82,9 +82,9 @@ type literal with a union's arms escaped as `\|`.
82
82
  | `Worksheet` | interface | `{ id, name, aggregation, precision?, value, groups, steps, trace, errors, success }` | Represents a quantitative definition joined to its result — the rating audit trail. |
83
83
  | `LineResult` | interface | `{ id, name, amount?, worksheet }` | Represents one line's rating outcome. |
84
84
  | `RatingResult` | interface | `{ lines, total?, success }` | Represents a rated outcome across every line of one `rate` call. |
85
- | `RaterEventMap` | type | `{ rate }` | Represents the push observation surface of a `RaterInterface`. |
85
+ | `RaterEventMap` | type | `{ readonly rate: readonly [subject: Subject, result: RatingResult]; }` | Represents the push observation surface of a `RaterInterface`. |
86
86
  | `RaterOptions` | interface | `{ on?, error?, engine?, total?, labels? }` | Configures `createRater` and the `Rater` constructor. |
87
- | `RaterInterface` | interface | `{ emitter } plus rate, destroy` | Represents the rating orchestrator over the shared quantitative reasoning engine. |
87
+ | `RaterInterface` | interface | `{ emitter, rate(), destroy() }` | Represents the rating orchestrator over the shared quantitative reasoning engine. |
88
88
 
89
89
  `RaterInterface`'s `emitter` is a `readonly` data member and stays in this table's
90
90
  `Shape` cell; the interface's call-signature members are documented under
@@ -95,10 +95,10 @@ type literal with a union's arms escaped as `\|`.
95
95
  Every `RaterError` carries a `code` — `'DEFINITION'`, `'MISMATCH'`, or `'DESTROYED'` —
96
96
  and an optional `context` record of structured detail beside its message.
97
97
 
98
- | API | Kind | Summary |
99
- | -------------- | -------- | --------------------------------------------------------------- |
100
- | `RaterError` | class | Represents a coded programmer error thrown by the rating layer. |
101
- | `isRaterError` | function | Narrows a caught value to a `RaterError`. |
98
+ | Name | Kind | Signature | Summary |
99
+ | -------------- | -------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
100
+ | `RaterError` | class | `new (code: RaterErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => RaterError` | Represents a coded programmer error thrown by the rating layer. |
101
+ | `isRaterError` | function | `(value: unknown) => value is RaterError` | Narrows a caught value to a `RaterError`. |
102
102
 
103
103
  The `isRaterError` guard narrows a caught value, so a handler reads the `code` member
104
104
  off it:
@@ -131,18 +131,18 @@ plain numbers, strings, or unknown values.
131
131
 
132
132
  In a guard table a `Shape` cell holds the type the guard narrows to.
133
133
 
134
- | API | Kind | Shape | Summary |
135
- | -------------------- | -------- | ------------------ | ---------------------------------------------------------------------- |
136
- | `isStage` | const | `Stage` | Determines whether a value is a `Stage` literal. |
137
- | `isLineDefinition` | function | `LineDefinition` | Determines whether a value is an exact `LineDefinition` record. |
138
- | `isRatingDefinition` | function | `RatingDefinition` | Determines whether a value is an exact `RatingDefinition` record. |
139
- | `isEvidence` | function | `Evidence` | Determines whether a value is an open result-side `Evidence` object. |
140
- | `isWorksheetFactor` | function | `WorksheetFactor` | Determines whether a value is an open `WorksheetFactor` result object. |
141
- | `isWorksheetGroup` | function | `WorksheetGroup` | Determines whether a value is an open `WorksheetGroup` result object. |
142
- | `isStep` | function | `Step` | Determines whether a value is an open `Step` result object. |
143
- | `isWorksheet` | function | `Worksheet` | Determines whether a value is an open `Worksheet` result object. |
144
- | `isLineResult` | function | `LineResult` | Determines whether a value is an open `LineResult` object. |
145
- | `isRatingResult` | function | `RatingResult` | Determines whether a value is an open `RatingResult` object. |
134
+ | Name | Kind | Signature | Summary |
135
+ | -------------------- | -------- | ----------------------------------------------- | ---------------------------------------------------------------------- |
136
+ | `isStage` | const | `Guard<Stage>` | Determines whether a value is a `Stage` literal. |
137
+ | `isLineDefinition` | function | `(value: unknown) => value is LineDefinition` | Determines whether a value is an exact `LineDefinition` record. |
138
+ | `isRatingDefinition` | function | `(value: unknown) => value is RatingDefinition` | Determines whether a value is an exact `RatingDefinition` record. |
139
+ | `isEvidence` | function | `(value: unknown) => value is Evidence` | Determines whether a value is an open result-side `Evidence` object. |
140
+ | `isWorksheetFactor` | function | `(value: unknown) => value is WorksheetFactor` | Determines whether a value is an open `WorksheetFactor` result object. |
141
+ | `isWorksheetGroup` | function | `(value: unknown) => value is WorksheetGroup` | Determines whether a value is an open `WorksheetGroup` result object. |
142
+ | `isStep` | function | `(value: unknown) => value is Step` | Determines whether a value is an open `Step` result object. |
143
+ | `isWorksheet` | function | `(value: unknown) => value is Worksheet` | Determines whether a value is an open `Worksheet` result object. |
144
+ | `isLineResult` | function | `(value: unknown) => value is LineResult` | Determines whether a value is an open `LineResult` object. |
145
+ | `isRatingResult` | function | `(value: unknown) => value is RatingResult` | Determines whether a value is an open `RatingResult` object. |
146
146
 
147
147
  Each guard answers `true` for a value of its own shape:
148
148
 
@@ -164,19 +164,19 @@ isRatingDefinition({ id: 'r1', name: 'Rating', lines: [] }) // true
164
164
  Pure, exported utility functions — the definition builders, the evidence construction,
165
165
  and the worksheet-joining behind `Rater`'s `rate` projection.
166
166
 
167
- | API | Kind | Summary |
168
- | ----------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
169
- | `buildLineDefinition` | function | Builds a fresh `LineDefinition` from a line id, a display name, and the line's quantitative rating definition, with `overrides` merged over those defaults. |
170
- | `buildRatingDefinition` | function | Builds a fresh `RatingDefinition` from a rating id, a display name, and the rating's ordered lines, with `overrides` merged over those defaults. |
171
- | `buildEvidence` | function | Builds an `Evidence` row from an evaluated `Check`. |
172
- | `buildEvidenceRows` | function | Builds one evidence row per authored check of a quantitative factor, joined to that check's evaluated result. |
173
- | `buildWorksheetFactor` | function | Joins one authored quantitative factor to its evaluated `FactorResult`. |
174
- | `buildWorksheetGroup` | function | Joins one authored quantitative group to its evaluated `GroupResult`. |
175
- | `buildWorksheetStep` | function | Builds one display-neutral `Step` row. |
176
- | `buildWorksheetSteps` | function | Builds the ordered `Step` rows for a resolved `Worksheet`. |
177
- | `buildWorksheet` | function | Joins a `QuantitativeDefinition` and its `QuantitativeResult` into a `Worksheet` — the rating audit trail. |
178
- | `buildLineResult` | function | Builds a rated `LineResult` from a line's evaluated `QuantitativeResult`. |
179
- | `sumAmounts` | function | Sums defined line amounts. |
167
+ | Name | Kind | Signature | Summary |
168
+ | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
169
+ | `buildLineDefinition` | function | `(id: string, name: string, rate: QuantitativeDefinition, overrides?: Partial<Omit<LineDefinition, 'id' \| 'name' \| 'rate'>>) => LineDefinition` | Builds a fresh `LineDefinition` from a line id, a display name, and the line's quantitative rating definition, with `overrides` merged over those defaults. |
170
+ | `buildRatingDefinition` | function | `(id: string, name: string, lines: readonly LineDefinition[], overrides?: Partial<Omit<RatingDefinition, 'id' \| 'name' \| 'lines'>>) => RatingDefinition` | Builds a fresh `RatingDefinition` from a rating id, a display name, and the rating's ordered lines, with `overrides` merged over those defaults. |
171
+ | `buildEvidence` | function | `(check: Check, actual: unknown, met: boolean \| undefined, labels?: Readonly<Record<string, string>>) => Evidence` | Builds an `Evidence` row from an evaluated `Check`. |
172
+ | `buildEvidenceRows` | function | `(checks: readonly Check[] \| undefined, results: readonly CheckResult[] \| undefined, labels?: Readonly<Record<string, string>>) => readonly Evidence[]` | Builds one evidence row per authored check of a quantitative factor, joined to that check's evaluated result. |
173
+ | `buildWorksheetFactor` | function | `(definition: Factor, results: readonly FactorResult[], labels?: Readonly<Record<string, string>>) => WorksheetFactor` | Joins one authored quantitative factor to its evaluated `FactorResult`. |
174
+ | `buildWorksheetGroup` | function | `(definition: QuantitativeDefinition['groups'][number], results: readonly GroupResult[], labels?: Readonly<Record<string, string>>) => WorksheetGroup` | Joins one authored quantitative group to its evaluated `GroupResult`. |
175
+ | `buildWorksheetStep` | function | `(stage: Stage, id: string \| undefined, name: string \| undefined, value: number, expression: string) => Step` | Builds one display-neutral `Step` row. |
176
+ | `buildWorksheetSteps` | function | `(definition: QuantitativeDefinition, result: QuantitativeResult, groups: readonly WorksheetGroup[]) => readonly Step[]` | Builds the ordered `Step` rows for a resolved `Worksheet`. |
177
+ | `buildWorksheet` | function | `(definition: QuantitativeDefinition, result: QuantitativeResult, labels?: Readonly<Record<string, string>>) => Worksheet` | Joins a `QuantitativeDefinition` and its `QuantitativeResult` into a `Worksheet` — the rating audit trail. |
178
+ | `buildLineResult` | function | `(definition: LineDefinition, result: QuantitativeResult, labels?: Readonly<Record<string, string>>) => LineResult` | Builds a rated `LineResult` from a line's evaluated `QuantitativeResult`. |
179
+ | `sumAmounts` | function | `(lines: readonly LineResult[]) => number \| undefined` | Sums defined line amounts. |
180
180
 
181
181
  Each definition builder returns a fresh object and omits an absent optional key
182
182
  entirely:
@@ -262,9 +262,9 @@ sumAmounts([]) // undefined — no line carries an amount
262
262
 
263
263
  ### Factories
264
264
 
265
- | API | Kind | Summary |
266
- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
267
- | `createRater` | function | Creates a rating orchestrator over the shared quantitative engine, seeded from `RaterOptions` and returning a `RaterInterface`. |
265
+ | Name | Kind | Signature | Summary |
266
+ | ------------- | -------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
267
+ | `createRater` | function | `(options?: RaterOptions) => RaterInterface` | Creates a rating orchestrator over the shared quantitative engine, seeded from `RaterOptions` and returning a `RaterInterface`. |
268
268
 
269
269
  `createRater` returns a live entity that owns an engine unless one is injected, so every
270
270
  rater is destroyed when its work is done.
@@ -282,9 +282,9 @@ rater.destroy()
282
282
 
283
283
  ### Classes
284
284
 
285
- | API | Kind | Summary |
286
- | ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------- |
287
- | `Rater` | class | Orchestrates rating — owns (or receives) the shared quantitative reasoning engine and projects results into the rating domain vocabulary. |
285
+ | Name | Kind | Signature | Summary |
286
+ | ------- | ----- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
287
+ | `Rater` | class | `new (options?: RaterOptions) => RaterInterface` | Orchestrates rating — owns (or receives) the shared quantitative reasoning engine and projects results into the rating domain vocabulary. |
288
288
 
289
289
  ## Methods
290
290