@orkestrel/scaffold 0.0.124 → 0.0.125

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 (46) hide show
  1. package/dist/agents/skills/orkestrel-publish/scripts/steps.js +523 -0
  2. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +70 -11
  3. package/dist/bin/main.js +5 -5
  4. package/dist/bin/main.js.map +1 -1
  5. package/dist/host/agents/orchestration.md +5 -1
  6. package/dist/host/agents/platforms/windows.md +9 -1
  7. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +1 -1
  8. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +1 -0
  9. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +30 -2
  10. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -0
  11. package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +5 -1
  12. package/dist/host/agents/skills/orkestrel-publish/SKILL.md +1 -0
  13. package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
  14. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +23 -6
  15. package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +654 -0
  16. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +79 -14
  17. package/dist/host/claude/agents/orkestrel.md +21 -21
  18. package/dist/host/claude/rules/patterns.md +1 -1
  19. package/dist/host/claude/rules/portability.md +2 -0
  20. package/dist/host/claude/rules/quality.md +3 -1
  21. package/dist/host/claude/rules/tests.md +3 -1
  22. package/dist/host/guides/agent.md +349 -244
  23. package/dist/host/guides/brief.md +52 -48
  24. package/dist/host/guides/browser.md +2 -2
  25. package/dist/host/guides/interpret.md +531 -155
  26. package/dist/host/guides/mcp.md +183 -61
  27. package/dist/host/guides/ollama.md +123 -66
  28. package/dist/host/guides/program.md +117 -39
  29. package/dist/host/guides/qualifier.md +110 -59
  30. package/dist/host/guides/rater.md +85 -32
  31. package/dist/host/guides/scaffold.md +13 -5
  32. package/dist/host/guides/study.md +580 -483
  33. package/dist/host/guides/toolbox.md +159 -80
  34. package/dist/host/guides/workflow.md +44 -25
  35. package/dist/host/manifest.json +36 -30
  36. package/dist/src/core/index.cjs +4 -4
  37. package/dist/src/core/index.cjs.map +1 -1
  38. package/dist/src/core/index.js +4 -4
  39. package/dist/src/core/index.js.map +1 -1
  40. package/dist/src/server/index.cjs +23 -11
  41. package/dist/src/server/index.cjs.map +1 -1
  42. package/dist/src/server/index.d.cts +10 -6
  43. package/dist/src/server/index.d.ts +10 -6
  44. package/dist/src/server/index.js +23 -11
  45. package/dist/src/server/index.js.map +1 -1
  46. package/package.json +4 -4
@@ -18,7 +18,7 @@ selects next, so an excluded scope is never evaluated merely to discard its outc
18
18
  `Qualifier` either receives an injected `ReasonInterface`, which it never destroys, or
19
19
  builds and owns its own engine (`bail: false`), destroyed in `destroy()`. An injected
20
20
  engine must be able to dispatch both quantitative and logical definitions — one it
21
- cannot dispatch surfaces `QualifierError('ENGINE')` wrapping the engine's throw. Every
21
+ cannot dispatch fails validation as `QualifierError('DEFINITION')`, and with `validate: false` surfaces `QualifierError('ENGINE')` wrapping the engine's throw. Every
22
22
  `qualify` call fires through `Qualifier`'s typed `emitter`. Source:
23
23
  [`src/core`](../src/core). Surfaced through the `@src/core` barrel.
24
24
 
@@ -70,13 +70,13 @@ per subject.
70
70
  | `QualificationProjection` | type | `number \| boolean \| Readonly<Record<string, unknown>>` | Represents one pass's internal working projection. |
71
71
  | `QualificationContext` | type | `Readonly<Record<string, QualificationProjection>>` | Represents the internal projection record stored under `QUALIFICATION_KEY`. |
72
72
  | `RulingInput` | interface | `{ scope?, message? }` | Carries the optional fields `createRuling` accepts. |
73
- | `QualificationInput` | interface | `{ description?, rulings?, metadata? }` | Carries the optional fields `createQualificationDefinition` accepts. |
73
+ | `QualificationInput` | interface | `{ description?, rulings?, metadata?, shape? }` | Carries the optional fields `createQualificationDefinition` accepts. |
74
74
  | `Ruling` | interface | `{ id, pass, rule, effect, scope?, message? }` | Represents an authored consequence for one rule in one logical pass. |
75
- | `Premise` | interface | `{ field?, label?, description?, comparison?, expected?, actual?, met? }` | Represents display-neutral evidence for one condition, authored as a checked or a described premise. |
76
- | `Finding` | interface | `{ id, pass, rule, effect, scope?, applied, message?, premises }` | Represents one resolved ruling. |
75
+ | `Premise` | interface | `{ field?, label?, description?, comparison?, expected?, actual?, state? }` | Represents display-neutral evidence for one condition, authored as a checked or a described premise. |
76
+ | `Finding` | interface | `{ id, pass, rule, effect, scope?, state, message?, premises }` | Represents one resolved ruling. |
77
77
  | `Derivation` | interface | `{ id, value, success, trace, errors }` | Represents one quantitative pass's audit result. |
78
- | `QualificationDefinition` | interface | `{ id, name, description?, passes, rulings?, metadata? }` | Represents a pure authored qualification definition. |
79
- | `QualificationResult` | interface | `{ id, name, eligibility, scopes, findings, derivations, success, trace, errors }` | Represents one subject's complete qualification outcome. |
78
+ | `QualificationDefinition` | interface | `{ id, name, description?, passes, rulings?, metadata?, shape? }` | Represents a pure authored qualification definition. |
79
+ | `QualificationResult` | interface | `{ id, name, eligibility, scopes, findings, derivations, success, trace, errors, faults, repairs, defaulted }` | Represents one subject's complete qualification outcome. |
80
80
  | `QualifierErrorCode` | type | `'DEFINITION' \| 'MISMATCH' \| 'DESTROYED' \| 'ENGINE'` | Represents a coded `QualifierError` programmer-error code. |
81
81
  | `QualifierErrorContext` | interface | `{ pass?, definition?, cause? }` | Represents the structured payload a `QualifierError` carries. |
82
82
  | `QualifierEventMap` | type | `{ readonly derive: readonly [derivation: Derivation]; readonly finding: readonly [finding: Finding]; readonly qualify: readonly [result: QualificationResult]; readonly destroy: readonly []; }` | Represents the push observation surface of a `QualifierInterface`. |
@@ -94,8 +94,11 @@ types.
94
94
 
95
95
  | Name | Kind | Signature | Summary |
96
96
  | ---------------------------- | ----- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
97
+ | `QUALIFICATION_EFFECTS` | const | `readonly ['restriction', 'referral', 'condition']` | Lists the effects a ruling can carry. |
98
+ | `ELIGIBILITIES` | const | `readonly ['eligible', 'ineligible', 'referral']` | Lists the eligibility outcomes. |
97
99
  | `DEFAULT_QUALIFIER_VALIDATE` | const | `true` | Holds the default definition validation policy for `createQualifier` and `Qualifier.qualify`, `true`. |
98
100
  | `QUALIFICATION_KEY` | const | `"qualification"` | Names `'qualification'`, the reserved internal projection namespace a pass's working projection is written under. |
101
+ | `MESSAGE_TOKEN` | const | `RegExp` | Matches each `{{dotted.path}}` token of a message template, with the path as its one group. |
99
102
  | `ELIGIBILITY_PRECEDENCE` | const | `readonly Eligibility[]` | Lists the eligibility severities most to least severe: `ineligible`, `referral`, `eligible`. |
100
103
  | `EFFECT_ELIGIBILITIES` | const | `Readonly<Record<QualificationEffect, Eligibility>>` | Maps each `QualificationEffect` to its eligibility impact — `restriction` to `ineligible`, `referral` to `referral`, and `condition` to `eligible`. |
101
104
 
@@ -111,7 +114,7 @@ its subject, so a conditional ruling contributes evidence without changing eligi
111
114
 
112
115
  `context` is a `QualifierErrorContext` or `undefined`, so a caught error's payload
113
116
  needs no narrowing of its own. `ENGINE` marks an underlying reason engine throw that
114
- fits no other code (for example, a missing reasoner) — `context.pass` names the pass
117
+ fits no other code (for example, a missing reasoner with `validate: false`) — `context.pass` names the pass
115
118
  and `context.cause` preserves the original throw. A `DEFINITION`/`INVALID` or
116
119
  `DESTROYED` engine throw maps to the matching code instead, and a `DEFINITION` throw
117
120
  raised by `qualify`'s own validation carries `context.definition`.
@@ -149,6 +152,7 @@ that package.
149
152
 
150
153
  | Name | Kind | Signature | Summary |
151
154
  | --------------------------- | -------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
155
+ | `isDefinitionMetadata` | const | `import("@orkestrel/contract").Guard<Record<string, unknown>>` | Determines whether a value is a definition's `metadata`: a record of JSON values. |
152
156
  | `isEligibility` | const | `import("@orkestrel/contract").Guard<"eligible" \| "ineligible" \| "referral">` | Determines whether a value is an `Eligibility` literal. |
153
157
  | `isQualificationEffect` | const | `import("@orkestrel/contract").Guard<"condition" \| "referral" \| "restriction">` | Determines whether a value is a `QualificationEffect` literal. |
154
158
  | `isEligibilityRecord` | function | `(value: unknown) => value is Readonly<Record<string, Eligibility>>` | Determines whether a value is an open string-keyed record of `Eligibility` values. |
@@ -178,13 +182,13 @@ import { createLogicalDefinition } from '@orkestrel/reason'
178
182
  isEligibility('referral') // true
179
183
  isQualificationEffect('condition') // true
180
184
  isEligibilityRecord({ wind: 'ineligible' }) // true
181
- isPremise({ field: 'age', comparison: 'above', actual: 30, met: true }) // true
185
+ isPremise({ field: 'age', comparison: 'above', actual: 30, state: 'met' }) // true
182
186
  isFinding({
183
187
  id: 'f',
184
188
  pass: 'gates',
185
189
  rule: 'adult',
186
190
  effect: 'condition',
187
- applied: true,
191
+ state: 'met',
188
192
  premises: [],
189
193
  }) // true
190
194
  isDerivation({ id: 'cap', value: Number.NaN, success: true, trace: [], errors: [] }) // true
@@ -195,6 +199,9 @@ isQualificationResult({
195
199
  scopes: {},
196
200
  findings: [],
197
201
  derivations: [],
202
+ faults: [],
203
+ repairs: [],
204
+ defaulted: [],
198
205
  success: true,
199
206
  trace: [],
200
207
  errors: [],
@@ -209,29 +216,37 @@ isQualificationDefinition({ id: 'd', name: 'D', passes: [] }) // true
209
216
  Pure exported helpers form the functional core. `Qualifier` retains only the ordered
210
217
  orchestration and ownership lifecycle.
211
218
 
212
- | Name | Kind | Signature | Summary |
213
- | -------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
214
- | `interpolateMessage` | function | `(template: string, subject: Readonly<Record<string, unknown>>) => string` | Interpolates `{{dotted.path}}` tokens in a message template against a subject. |
215
- | `renderComparison` | function | `(comparison: NonNullable<Premise['comparison']>) => string` | Renders a `Premise` comparison as a display-neutral verb phrase. |
216
- | `renderValue` | function | `(value: unknown) => string` | Renders a structured or scalar expected value display-neutrally. |
217
- | `renderPremise` | function | `(entry: Premise, labels?: Readonly<Record<string, string>>) => string` | Renders one `Premise` into a display-neutral sentence. |
218
- | `checkToPremise` | function | `(check: Check, result: CheckResult, labels?: Readonly<Record<string, string>>) => Premise` | Builds a `Premise` from an authored `Check` and its evaluated `CheckResult`. |
219
- | `ruleToPremises` | function | `(rule: Rule, working: Subject, evaluator: EvaluatorInterface, labels?: Readonly<Record<string, string>>) => readonly Premise[]` | Builds rich premises for one fired `Rule` by walking its premise atoms and re-evaluating each against the working subject. |
220
- | `findRule` | function | `(definition: LogicalDefinition, id: string) => Rule \| undefined` | Locates an authored `Rule` by id. |
221
- | `reasonResultToProjection` | function | `(definition: QualificationPass, result: ReasonResult) => QualificationProjection` | Projects one reason result into the internal qualification namespace. |
222
- | `quantitativeResultToDerivation` | function | `(id: string, result: QuantitativeResult) => Derivation` | Projects a quantitative result into a `Derivation` audit record. |
223
- | `qualificationToRecord` | function | `(context: QualificationContext) => Readonly<Record<string, QualificationContext>>` | Wraps a `QualificationContext` under `QUALIFICATION_KEY`. |
224
- | `mergeQualificationContext` | function | `(context: QualificationContext, id: string, projection: QualificationProjection) => QualificationContext` | Merges one pass projection into the context, copy-on-write. |
225
- | `rulingToFinding` | function | `(ruling: Ruling, pass: QualificationPass, result: LogicalResult, subject: Subject, evaluator: EvaluatorInterface, labels?: Readonly<Record<string, string>>) => Finding` | Joins a ruling, its logical rule result, the pass, the pre-projection subject, and an evaluator into a `Finding`. |
226
- | `deriveFindingEligibility` | function | `(findings: readonly Finding[], failed?: boolean) => Eligibility` | Derives global eligibility from applied, unscoped findings. |
227
- | `combineEligibilities` | function | `(eligibilities: readonly Eligibility[]) => Eligibility` | Returns the most severe `Eligibility` in a list. |
228
- | `deriveScopeEligibilities` | function | `(findings: readonly Finding[]) => Readonly<Record<string, Eligibility>>` | Derives one eligibility per finding scope. |
229
- | `describeMissingReferences` | function | `(definition: QualificationDefinition) => readonly string[]` | Describes each ruling whose pass or rule does not exist or whose pass is not logical, and each pass id shadowing the reserved `QUALIFICATION_KEY`. |
230
- | `hasReservedKey` | function | `(subject: Subject) => boolean` | Determines whether a subject already owns the reserved `QUALIFICATION_KEY`. |
231
- | `assertSubject` | function | `(value: unknown) => asserts value is Subject` | Asserts a value is a valid qualification `Subject`, narrowing it in place. |
232
- | `mapEngineError` | function | `(error: unknown, pass: string) => QualifierError` | Maps an engine throw caught while running one pass to a typed `QualifierError`. |
233
- | `describeEmptyLogicalPasses` | function | `(definition: QualificationDefinition) => readonly string[]` | Describes each logical pass carrying no rulings. |
234
- | `describeUnreadDerivations` | function | `(definition: QualificationDefinition) => readonly string[]` | Describes each quantitative pass never read by a later pass. |
219
+ | Name | Kind | Signature | Summary |
220
+ | -------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
221
+ | `hasUnreadRule` | function | `(result: ReasonResult) => boolean` | Determines whether a logical result holds a rule left unread. |
222
+ | `describeReservedConclusions` | function | `(definition: QualificationDefinition) => readonly string[]` | Describes each rule concluding `conclusion`, which a pass's projection reserves for itself. |
223
+ | `findMessageTokens` | function | `(template: string) => readonly string[]` | Finds the `{{dotted.path}}` tokens a message template reads. |
224
+ | `readsProjection` | function | `(field: FieldPath, projections?: readonly string[]) => boolean` | Determines whether a field reads a pass's projection under `qualification`, or a key the host projects. |
225
+ | `scanDefinitionShape` | function | `(definition: QualificationDefinition, projections?: readonly string[]) => ShapeScan` | Describes what the definition's shape cannot stand for: a read of a field it does not declare, and the reserved `qualification` key, which a default could otherwise fill. |
226
+ | `projectQualificationResult` | function | `(result: QualificationResult) => JSONValue \| undefined` | Projects a result to the JSON its contract reads. |
227
+ | `describeUnknownTokens` | function | `(definition: QualificationDefinition) => readonly string[]` | Describes each message token no field of the definition's shape answers. |
228
+ | `expandPassFaults` | function | `(faults: readonly AuditFault[], unread: ReadonlyMap<string, readonly AuditFault[]>) => readonly AuditFault[]` | Replaces a read of an unread pass's projection with what that pass could not read. |
229
+ | `interpolateMessage` | function | `(template: string, subject: Readonly<Record<string, unknown>>) => string` | Interpolates `{{dotted.path}}` tokens in a message template against a subject. |
230
+ | `renderComparison` | function | `(comparison: NonNullable<Premise['comparison']>) => string` | Renders a `Premise` comparison as a display-neutral verb phrase. |
231
+ | `renderValue` | function | `(value: unknown) => string` | Renders a structured or scalar expected value display-neutrally. |
232
+ | `renderPremise` | function | `(entry: Premise, labels?: Readonly<Record<string, string>>) => string` | Renders one `Premise` into a display-neutral sentence. |
233
+ | `checkToPremise` | function | `(check: Check, result: CheckResult, labels?: Readonly<Record<string, string>>) => Premise` | Builds a `Premise` from an authored `Check` and its evaluated `CheckResult`. |
234
+ | `ruleToPremises` | function | `(rule: Rule, resolved: RuleResult \| undefined, labels?: Readonly<Record<string, string>>) => readonly Premise[]` | Builds rich premises for one fired `Rule` by walking its premise atoms and reading each from what the rule read. |
235
+ | `findRule` | function | `(definition: LogicalDefinition, id: string) => Rule \| undefined` | Locates an authored `Rule` by id. |
236
+ | `reasonResultToProjection` | function | `(definition: QualificationPass, result: ReasonResult) => QualificationProjection` | Projects one reason result into the internal qualification namespace. |
237
+ | `quantitativeResultToDerivation` | function | `(id: string, result: QuantitativeResult) => Derivation` | Projects a quantitative result into a `Derivation` audit record. |
238
+ | `qualificationToRecord` | function | `(context: QualificationContext) => Readonly<Record<string, QualificationContext>>` | Wraps a `QualificationContext` under `QUALIFICATION_KEY`. |
239
+ | `mergeQualificationContext` | function | `(context: QualificationContext, id: string, projection: QualificationProjection) => QualificationContext` | Merges one pass projection into the context, copy-on-write. |
240
+ | `rulingToFinding` | function | `(ruling: Ruling, pass: QualificationPass, result: LogicalResult, subject: Subject, labels?: Readonly<Record<string, string>>) => Finding` | Joins a ruling, its logical rule result, the pass, and the pre-projection subject into a `Finding`. |
241
+ | `deriveFindingEligibility` | function | `(findings: readonly Finding[], failed?: boolean) => Eligibility` | Derives global eligibility from unscoped findings whose rule is met. |
242
+ | `combineEligibilities` | function | `(eligibilities: readonly Eligibility[]) => Eligibility` | Returns the most severe `Eligibility` in a list. |
243
+ | `deriveScopeEligibilities` | function | `(findings: readonly Finding[]) => Readonly<Record<string, Eligibility>>` | Derives one eligibility per finding scope. |
244
+ | `describeMissingReferences` | function | `(definition: QualificationDefinition) => readonly string[]` | Describes each ruling whose pass or rule does not exist or whose pass is not logical, and each pass id shadowing the reserved `QUALIFICATION_KEY`. |
245
+ | `hasReservedKey` | function | `(subject: Subject) => boolean` | Determines whether a subject already owns the reserved `QUALIFICATION_KEY`. |
246
+ | `assertSubject` | function | `(value: unknown) => asserts value is Subject` | Asserts a value is a valid qualification `Subject`, narrowing it in place. |
247
+ | `mapEngineError` | function | `(error: unknown, pass: string) => QualifierError` | Maps an engine throw caught while running one pass to a typed `QualifierError`. |
248
+ | `describeEmptyLogicalPasses` | function | `(definition: QualificationDefinition) => readonly string[]` | Describes each logical pass carrying no rulings. |
249
+ | `describeUnreadDerivations` | function | `(definition: QualificationDefinition) => readonly string[]` | Describes each quantitative pass never read by a later pass. |
235
250
 
236
251
  Every helper carries a worked `@example` in source and is composed by `Qualifier`
237
252
  rather than reimplemented by it.
@@ -252,7 +267,6 @@ import {
252
267
  } from '@orkestrel/qualifier'
253
268
  import {
254
269
  createAtom,
255
- createEvaluator,
256
270
  createFactorGroup,
257
271
  createLogicalDefinition,
258
272
  createLogicalReasoner,
@@ -267,7 +281,6 @@ const engine = createReason({
267
281
  reasoners: [createQuantitativeReasoner(), createLogicalReasoner()],
268
282
  bail: false,
269
283
  })
270
- const evaluator = createEvaluator()
271
284
 
272
285
  const cap = createQuantitativeDefinition('cap', 'TIV cap', [
273
286
  createFactorGroup('limit', 'sum', [createStaticFactor('base', 500_000)]),
@@ -294,7 +307,7 @@ if (capResult.reasoning === 'quantitative') {
294
307
  const gatesResult = engine.reason(subject, gates)
295
308
  if (gatesResult.reasoning === 'logical') {
296
309
  const ruling = createRuling('license', 'gates', 'licensed', 'restriction')
297
- const finding = rulingToFinding(ruling, gates, gatesResult, subject, evaluator)
310
+ const finding = rulingToFinding(ruling, gates, gatesResult, subject)
298
311
  deriveFindingEligibility([finding]) // 'ineligible'
299
312
  deriveScopeEligibilities([finding]) // {} — the finding is unscoped
300
313
  }
@@ -333,11 +346,12 @@ assertSubject({ id: 's1' }) // narrows to Subject; throws QualifierError('MISMAT
333
346
 
334
347
  ### Factories
335
348
 
336
- | Name | Kind | Signature | Summary |
337
- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
338
- | `createQualifier` | function | `(options?: QualifierOptions) => QualifierInterface` | Creates one `QualifierInterface` over a reason engine. |
339
- | `createQualificationDefinition` | function | `(id: string, name: string, passes: readonly QualificationPass[], input?: QualificationInput) => QualificationDefinition` | Creates a fresh `QualificationDefinition`, omitting every absent optional key. |
340
- | `createRuling` | function | `(id: string, pass: string, rule: string, effect: QualificationEffect, input?: RulingInput) => Ruling` | Creates a fresh `Ruling` from the rule it reacts to and the effect it applies. |
349
+ | Name | Kind | Signature | Summary |
350
+ | --------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
351
+ | `createQualificationDefinitionContract` | function | `() => ContractInterface<unknown>` | Creates the contract of a `QualificationDefinition`, its `schema` for an LLM, a tool, or MCP. |
352
+ | `createQualifier` | function | `(options?: QualifierOptions) => QualifierInterface` | Creates one `QualifierInterface` over a reason engine. |
353
+ | `createQualificationDefinition` | function | `(id: string, name: string, passes: readonly QualificationPass[], input?: QualificationInput) => QualificationDefinition` | Creates a fresh `QualificationDefinition`, omitting every absent optional key. |
354
+ | `createRuling` | function | `(id: string, pass: string, rule: string, effect: QualificationEffect, input?: RulingInput) => Ruling` | Creates a fresh `Ruling` from the rule it reacts to and the effect it applies. |
341
355
 
342
356
  #### Create a qualifier
343
357
 
@@ -380,6 +394,27 @@ qualifier.destroy()
380
394
 
381
395
  Every factory returns a fresh value and omits absent optional keys.
382
396
 
397
+ ### Shapes
398
+
399
+ The definition and result as `ContractShape` values.
400
+
401
+ | Name | Kind | Signature | Summary |
402
+ | ------------------------------------ | -------- | --------------------- | ------------------------------------------------------------------------------------- |
403
+ | `qualificationResultShape` | const | `ContractShape` | Describes a `QualificationResult` in its JSON projection. |
404
+ | `derivationShape` | const | `ContractShape` | Describes a `Derivation` in its JSON projection, where a non-finite number is `null`. |
405
+ | `findingShape` | const | `ContractShape` | Describes a `Finding` in its JSON projection. |
406
+ | `premiseShape` | const | `ContractShape` | Describes a `Premise` in its JSON projection. |
407
+ | `createQualificationDefinitionShape` | function | `() => ContractShape` | Creates the shape of a `QualificationDefinition`. |
408
+ | `rulingShape` | const | `ContractShape` | Describes a `Ruling`. |
409
+
410
+ ### Contracts
411
+
412
+ The compiled contract of what is flat enough to compile at import.
413
+
414
+ | Name | Kind | Signature | Summary |
415
+ | ----------------------------- | ----- | ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
416
+ | `qualificationResultContract` | const | `ContractInterface<unknown>` | Publishes a `QualificationResult`'s JSON projection as a contract, read through `projectQualificationResult`. |
417
+
383
418
  ### Classes
384
419
 
385
420
  | Name | Kind | Signature | Summary |
@@ -429,14 +464,15 @@ qualifier.destroy()
429
464
 
430
465
  Pass order is load-bearing.
431
466
 
432
- 1. Begin with a fresh working subject copied from the caller's subject.
433
- 2. Run the first pass through the shared reason engine.
434
- 3. Resolve rulings against the exact subject snapshot the pass evaluated.
435
- 4. Project the result under `qualification[pass.id]`.
436
- 5. Rebuild the working subject copy-on-write for later passes.
437
- 6. Continue with the next pass.
438
- 7. Derive global eligibility, scoped eligibility, and success.
439
- 8. Return a fresh result and discard the working subject.
467
+ 1. Admit the subject through the definition's `shape`, when it carries one. A refusal returns a `referral` result naming each fault, and no pass runs.
468
+ 2. Begin with a fresh working subject copied from what the door admitted.
469
+ 3. Run the first pass through the shared reason engine.
470
+ 4. Resolve rulings against what each rule read: a premise comes from the rule's own `checks`, so a key derived in the same pass reads as the rule saw it.
471
+ 5. Project a settled pass under `qualification[pass.id]`. A pass left unread projects nothing.
472
+ 6. Rebuild the working subject copy-on-write for later passes.
473
+ 7. Continue with the next pass, unless an error no fault can say or an unscoped restriction stopped the run.
474
+ 8. Derive global eligibility, scoped eligibility, and success.
475
+ 9. Return a fresh result and discard the working subject.
440
476
 
441
477
  A quantitative pass exposes its numeric value directly:
442
478
 
@@ -444,7 +480,7 @@ A quantitative pass exposes its numeric value directly:
444
480
  qualification.cap // 500000
445
481
  ```
446
482
 
447
- A logical pass exposes a record containing `conclusion` and applied conclusion fields:
483
+ A logical pass exposes a record containing `conclusion` and its conclusion fields: a fired rule's values, and `false` for a key only unfired rules conclude, so a later read of it settles. `conclusion` is the pass's own, so `validate` refuses a rule concluding it:
448
484
 
449
485
  ```ts
450
486
  qualification.gates // { conclusion: true, blocked: true }
@@ -462,7 +498,7 @@ A dotted string remains one literal field key and is not equivalent.
462
498
 
463
499
  ### Eligibility
464
500
 
465
- Global eligibility is derived only from **unscoped** applied findings:
501
+ Global eligibility is derived only from **unscoped** findings whose rule is `met`:
466
502
 
467
503
  | Effect | Eligibility |
468
504
  | ------------- | ------------ |
@@ -474,6 +510,13 @@ A failed pass adds a synthetic referral impact. Operational failure is therefore
474
510
  fail-closed: a subject with incomplete eligibility evidence must not proceed to
475
511
  any downstream decision step.
476
512
 
513
+ A pass left `unread` is that failure too, and it does not stop the run, because a later
514
+ restriction can still outrank its referral. `faults` names each input the run could not read,
515
+ and a later pass reading the unread pass's projection reports what that pass could not read,
516
+ so a caller asks one question per missing input. A finding on an `unread` rule carries
517
+ `state: 'unread'`, and its premises show which reads were missing. An error no fault can say,
518
+ such as an ordering on a conclusion no rule derived, stops the run.
519
+
477
520
  Severity is deterministic:
478
521
 
479
522
  ```text
@@ -510,6 +553,10 @@ step. It does not evaluate the wind scope and then suppress its outcome.
510
553
  A missing scope entry means `eligible`. A scoped `condition` leaves the scope
511
554
  eligible and contributes evidence a later consumer may act on.
512
555
 
556
+ ### Publishing definitions and results
557
+
558
+ `createQualificationDefinitionContract()` publishes a definition, its `schema` for an LLM, a tool, or MCP. Cross a definition on `is`, never `parse`, and hold the result, because building it walks the recursive expressions of its logical passes. `is` reads a nested `shape` as any JSON value and the guard reads it as a shape, so `shape: 42` passes `is` and `isQualificationDefinition` refuses it: a definition crossing a boundary goes through the guard as well. A result crosses as `projectQualificationResult`, which `qualificationResultContract` admits, because a premise's `actual` holds whatever the subject held and a derivation's `value` may be `NaN`.
559
+
513
560
  ### Validation
514
561
 
515
562
  Structural validation and semantic validation remain separate.
@@ -525,14 +572,20 @@ Structural validation and semantic validation remain separate.
525
572
  - every ruling references a logical pass
526
573
  - every ruling references an existing rule in that pass
527
574
  - no pass id equals `QUALIFICATION_KEY`
575
+ - the engine's own deep validation of each pass, whose errors and warnings carry the pass id
576
+ - no pass carries a `shape`, because the subject a pass reads holds `qualification` too
577
+ - no rule concludes `conclusion`, which a pass's projection reserves for itself
578
+ - a `shape` on the definition can stand, does not declare `qualification`, declares every field a pass reads outside `qualification`, and declares every token a ruling's message reads
579
+ - `metadata` is a record of JSON values
528
580
  - warnings for definitions with no passes
529
581
  - warnings for logical passes with no rulings
530
582
  - warnings for quantitative derivations never read by a later pass
531
583
 
532
584
  `qualify` throws `QualifierError('DEFINITION')` for a semantically invalid authored
533
- definition when `validate` is enabled. A malformed reason result is an operational
585
+ definition when `validate` is enabled, and remembers a valid definition by identity, so one
586
+ edited in place is not validated again. A pass whose reasoning the engine has no reasoner for fails that validation, so `qualify` throws `DEFINITION`, and with `validate: false` the same pass throws `ENGINE` when it runs. A malformed reason result is an operational
534
587
  qualification failure and returns a referral result instead of throwing. A
535
- definition with no passes is valid (a warning only) — every subject qualifies
588
+ definition with no passes is valid (a warning only) — every subject the door admits qualifies
536
589
  vacuously eligible against it.
537
590
 
538
591
  ## Patterns
@@ -645,7 +698,7 @@ const condition = createRuling('vacant', 'gates', 'vacant', 'condition', {
645
698
  })
646
699
  ```
647
700
 
648
- An applied condition produces:
701
+ A condition whose rule is `met` produces:
649
702
 
650
703
  ```ts
651
704
  result.scopes.exWind // 'eligible'
@@ -665,7 +718,7 @@ const referral = createRuling('roof', 'gates', 'roof', 'referral', {
665
718
  })
666
719
  ```
667
720
 
668
- An unscoped applied referral returns `eligibility: 'referral'`. A caller that runs
721
+ An unscoped referral whose rule is `met` returns `eligibility: 'referral'`. A caller that runs
669
722
  qualification ahead of a downstream step must treat that outcome as terminal and
670
723
  skip that step.
671
724
 
@@ -691,10 +744,8 @@ qualifier.destroy() // does not destroy the injected engine
691
744
  engine.destroy()
692
745
  ```
693
746
 
694
- Premise evidence is rendered through an internal, stateless `@orkestrel/reason`
695
- evaluator (`createEvaluator()`). Because that evaluator is deterministic and holds no
696
- state, a finding can never disagree with the pass that produced it, whether the engine
697
- is owned or injected — so there is no separate `evaluator` option to keep in sync.
747
+ Premise evidence comes from the `checks` each rule result carries, so a finding can never
748
+ disagree with the pass that produced it, whether the engine is owned or injected.
698
749
 
699
750
  The `labels` option overrides the display name a premise field renders under. Key it by
700
751
  the dot-joined field path — `age`, `qualification.cap` — and the override wins over the
@@ -840,7 +891,7 @@ Tests mirror the source structure and drive real reasoners.
840
891
  ## Practices
841
892
 
842
893
  - Qualify before any downstream work or decision step.
843
- - Treat `success: false` as terminal and fail closed to referral.
894
+ - Treat `success: false` as terminal and fail closed to referral, and ask for what `faults` names.
844
895
  - Use unscoped rulings for global eligibility and scoped rulings for per-scope selection.
845
896
  - Keep quantitative derivations under `qualification`; never flatten them onto the caller's subject.
846
897
  - Pass the original subject to downstream consumers — never the working projection.
@@ -53,34 +53,37 @@ plain line list resolves to that form; a `RatingDefinition` resolves the same wa
53
53
  through its own `lines`. Each overload rates exactly one subject — there is no batch
54
54
  overload, and the subject must be a plain record or `rate` throws `RaterError`
55
55
  `'MISMATCH'`; an input that is neither an array of lines nor a `RatingDefinition`
56
- throws `RaterError` `'DEFINITION'`. A line that fails to resolve (a missing lookup
57
- entry, a failed required factor) is a rating failure reported on its own `LineResult`
58
- (`worksheet.success: false`, no `amount`, a populated `worksheet.errors`) — the caller decides
56
+ throws `RaterError` `'DEFINITION'`, and so does a line definition the engine's `validate` refuses. A line that cannot resolve (a missing field, a lookup miss with no `fallback`, a failed required factor) is a rating failure reported on its own `LineResult`
57
+ (`worksheet.success: false`, no `amount`, a populated `worksheet.errors`, and `worksheet.faults` when an input is what it could not read) — the caller decides
59
58
  what to do with a failed line, and `Rater` reports exactly what each line resolved
60
59
  to. `total` is derived from every line's `amount` by a `TotalHandler` (default
61
- `sumAmounts`, overridable through `RaterOptions.total`). A `LineResult` carries an
60
+ `sumAmounts`, overridable through `RaterOptions.total`), only when every line rated, because a total over a line that refused would read as an answer for the whole subject. A `LineResult` carries an
62
61
  `amount` only when its `worksheet.success` is `true`, and a `RatingResult`'s `success`
63
- is `true` only when every line's `worksheet.success` is `true`.
62
+ is `true` only when every line's `worksheet.success` is `true`. A `RatingResult` names what stopped it: `faults` lists each input no line could read, once per field, and `errors` holds one string per fault plus what no fault can say, carrying the line id.
63
+
64
+ A `RatingDefinition` may carry a `shape`, which admits the subject through `reason`'s door before any line reads it. A refusal rates no line and names each fault, and `repairs` and `defaulted` report what the door changed. The shape is checked once per definition against what its lines read, and a shape that cannot stand or misses a field throws `RaterError` `'DEFINITION'`. A plain line list has no door.
65
+
66
+ A definition crosses a boundary on `ratingDefinitionContract.is`, never `parse`. The contract checks nested shapes structurally, so `shape: 42` fails both the contract and `isRatingDefinition`. A result crosses as `projectRatingResult`, which `ratingResultContract` admits, because an evidence row's `actual` holds whatever the subject held and a worksheet's numbers may be `NaN`.
64
67
 
65
68
  ### Types
66
69
 
67
- | Name | Kind | Signature | Summary |
68
- | ------------------ | --------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
69
- | `WorksheetStage` | type | `'factor' \| 'group' \| 'total'` | Names a worksheet derivation step stage. |
70
- | `RaterErrorCode` | type | `'DEFINITION' \| 'MISMATCH' \| 'DESTROYED'` | Names a coded `RaterError` programmer-error code. |
71
- | `TotalHandler` | type | `(lines: readonly LineResult[]) => number \| undefined` | Represents a pure total port over resolved lines. |
72
- | `LineDefinition` | interface | `{ id, name, description?, rate, metadata? }` | Represents one rateable line — a quantitative definition joined to display metadata. |
73
- | `RatingDefinition` | interface | `{ id, name, description?, lines, metadata? }` | Represents a pure authored rating — a named, ordered set of lines. |
74
- | `Evidence` | interface | `{ field?, label?, comparison?, expected?, actual?, met? }` | Represents a checked-evidence row rendered into a display-neutral sentence. |
75
- | `WorksheetFactor` | interface | `{ id, name?, description?, applied, value?, evidence }` | Represents a resolved quantitative factor, joined to its authored metadata. |
76
- | `WorksheetGroup` | interface | `{ id, name?, description?, applied, value, factors }` | Represents a resolved quantitative group, joined to its authored metadata. |
77
- | `Step` | interface | `{ stage, id?, name?, value, expression? }` | Represents a display-neutral worksheet derivation step. |
78
- | `Worksheet` | interface | `{ id, name, aggregation, precision?, value, groups, steps, trace, errors, success }` | Represents a quantitative definition joined to its result — the rating audit trail. |
79
- | `LineResult` | interface | `{ id, name, amount?, worksheet }` | Represents one line's rating outcome. |
80
- | `RatingResult` | interface | `{ lines, total?, success }` | Represents a rated outcome across every line of one `rate` call. |
81
- | `RaterEventMap` | type | `{ readonly rate: readonly [subject: Subject, result: RatingResult]; }` | Represents the push observation surface of a `RaterInterface`. |
82
- | `RaterOptions` | interface | `{ on?, error?, engine?, total?, labels? }` | Configures `createRater` and the `Rater` constructor. |
83
- | `RaterInterface` | interface | `{ emitter, rate(), destroy() }` | Represents the rating orchestrator over the shared quantitative reasoning engine. |
70
+ | Name | Kind | Signature | Summary |
71
+ | ------------------ | --------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
72
+ | `WorksheetStage` | type | `'factor' \| 'group' \| 'total'` | Names a worksheet derivation step stage. |
73
+ | `RaterErrorCode` | type | `'DEFINITION' \| 'MISMATCH' \| 'DESTROYED'` | Names a coded `RaterError` programmer-error code. |
74
+ | `TotalHandler` | type | `(lines: readonly LineResult[]) => number \| undefined` | Represents a pure total port over resolved lines. |
75
+ | `LineDefinition` | interface | `{ id, name, description?, rate, metadata? }` | Represents one rateable line — a quantitative definition joined to display metadata. |
76
+ | `RatingDefinition` | interface | `{ id, name, description?, lines, metadata?, shape? }` | Represents a pure authored rating — a named, ordered set of lines. |
77
+ | `Evidence` | interface | `{ field?, label?, comparison?, expected?, actual?, state? }` | Represents a checked-evidence row rendered into a display-neutral sentence. |
78
+ | `WorksheetFactor` | interface | `{ id, name?, description?, applied, value?, evidence }` | Represents a resolved quantitative factor, joined to its authored metadata. |
79
+ | `WorksheetGroup` | interface | `{ id, name?, description?, applied, value, factors }` | Represents a resolved quantitative group, joined to its authored metadata. |
80
+ | `Step` | interface | `{ stage, id?, name?, value, expression? }` | Represents a display-neutral worksheet derivation step. |
81
+ | `Worksheet` | interface | `{ id, name, aggregation, precision?, value, groups, steps, trace, errors, success, faults, repairs, defaulted }` | Represents a quantitative definition joined to its result — the rating audit trail. |
82
+ | `LineResult` | interface | `{ id, name, amount?, worksheet }` | Represents one line's rating outcome. |
83
+ | `RatingResult` | interface | `{ lines, total?, success, errors, faults, repairs, defaulted }` | Represents a rated outcome across every line of one `rate` call. |
84
+ | `RaterEventMap` | type | `{ readonly rate: readonly [subject: Subject, result: RatingResult]; }` | Represents the push observation surface of a `RaterInterface`. |
85
+ | `RaterOptions` | interface | `{ on?, error?, engine?, total?, labels? }` | Configures `createRater` and the `Rater` constructor. |
86
+ | `RaterInterface` | interface | `{ emitter, rate(), destroy() }` | Represents the rating orchestrator over the shared quantitative reasoning engine. |
84
87
 
85
88
  `RaterInterface`'s `emitter` is a `readonly` data member and stays in this table's
86
89
  `Signature` cell; the interface's call-signature members are documented under
@@ -142,13 +145,19 @@ Each guard answers `true` for a value of its own shape:
142
145
 
143
146
  ```ts
144
147
  import { isLineDefinition, isRatingDefinition, isWorksheetStage } from '@orkestrel/rater'
145
- import { createQuantitativeDefinition } from '@orkestrel/reason'
148
+ import {
149
+ createFactorGroup,
150
+ createQuantitativeDefinition,
151
+ createStaticFactor,
152
+ } from '@orkestrel/reason'
146
153
 
147
154
  isWorksheetStage('group') // true
148
155
  isLineDefinition({
149
156
  id: 'base',
150
157
  name: 'Base Amount',
151
- rate: createQuantitativeDefinition('base', 'Base', []),
158
+ rate: createQuantitativeDefinition('base', 'Base', [
159
+ createFactorGroup('amount', 'sum', [createStaticFactor('flat', 100)]),
160
+ ]),
152
161
  }) // true
153
162
  isRatingDefinition({ id: 'r1', name: 'Rating', lines: [] }) // true
154
163
  ```
@@ -160,9 +169,10 @@ and the worksheet-joining behind `Rater`'s `rate` projection.
160
169
 
161
170
  | Name | Kind | Signature | Summary |
162
171
  | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
172
+ | `projectRatingResult` | function | `(result: RatingResult) => JSONValue \| undefined` | Projects a result to the JSON its contract reads. |
163
173
  | `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. |
164
174
  | `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. |
165
- | `buildEvidence` | function | `(check: Check, actual: unknown, met: boolean \| undefined, labels?: Readonly<Record<string, string>>) => Evidence` | Builds an `Evidence` row from an evaluated `Check`. |
175
+ | `buildEvidence` | function | `(check: Check, actual: unknown, state: CheckState \| undefined, labels?: Readonly<Record<string, string>>) => Evidence` | Builds an `Evidence` row from an evaluated `Check`. |
166
176
  | `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. |
167
177
  | `buildWorksheetFactor` | function | `(definition: Factor, results: readonly FactorResult[], labels?: Readonly<Record<string, string>>) => WorksheetFactor` | Joins one authored quantitative factor to its evaluated `FactorResult`. |
168
178
  | `buildWorksheetGroup` | function | `(definition: QuantitativeDefinition['groups'][number], results: readonly GroupResult[], labels?: Readonly<Record<string, string>>) => WorksheetGroup` | Joins one authored quantitative group to its evaluated `GroupResult`. |
@@ -177,12 +187,18 @@ entirely:
177
187
 
178
188
  ```ts
179
189
  import { buildLineDefinition, buildRatingDefinition } from '@orkestrel/rater'
180
- import { createQuantitativeDefinition } from '@orkestrel/reason'
190
+ import {
191
+ createFactorGroup,
192
+ createQuantitativeDefinition,
193
+ createStaticFactor,
194
+ } from '@orkestrel/reason'
181
195
 
182
196
  const base = buildLineDefinition(
183
197
  'base',
184
198
  'Base Amount',
185
- createQuantitativeDefinition('base', 'Base', []),
199
+ createQuantitativeDefinition('base', 'Base', [
200
+ createFactorGroup('amount', 'sum', [createStaticFactor('flat', 100)]),
201
+ ]),
186
202
  )
187
203
  buildRatingDefinition('r1', 'Rating', [base])
188
204
  buildRatingDefinition('r1', 'Rating', [base], { description: 'A rating' }) // overrides merged over the defaults
@@ -197,9 +213,9 @@ import { buildEvidence, buildEvidenceRows } from '@orkestrel/rater'
197
213
  import { createCheck } from '@orkestrel/reason'
198
214
 
199
215
  const evaluated = createCheck('age', 'above', 18)
200
- buildEvidence(evaluated, 25, true) // { field: 'age', comparison: 'above', expected: 18, actual: 25, met: true }
201
- buildEvidence(evaluated, 25, true, { age: 'Age' }) // labels override → adds { label: 'Age' }
202
- buildEvidenceRows([evaluated], [{ field: 'age', met: true, actual: 25 }])
216
+ buildEvidence(evaluated, 25, 'met') // { field: 'age', comparison: 'above', expected: 18, actual: 25, state: 'met' }
217
+ buildEvidence(evaluated, 25, 'met', { age: 'Age' }) // labels override → adds { label: 'Age' }
218
+ buildEvidenceRows([evaluated], [{ field: 'age', state: 'met', actual: 25 }])
203
219
  ```
204
220
 
205
221
  Worksheet joining and line assembly — one authored quantitative definition and its
@@ -274,6 +290,37 @@ const rater = createRater()
274
290
  rater.destroy()
275
291
  ```
276
292
 
293
+ ### Shapes
294
+
295
+ The definition and result as `ContractShape` values.
296
+
297
+ | Name | Kind | Signature | Summary |
298
+ | ----------------------- | ----- | --------------- | ----------------------------------------------------- |
299
+ | `ratingResultShape` | const | `ContractShape` | Describes a `RatingResult` in its JSON projection. |
300
+ | `lineResultShape` | const | `ContractShape` | Describes a `LineResult` in its JSON projection. |
301
+ | `worksheetShape` | const | `ContractShape` | Describes a `Worksheet` in its JSON projection. |
302
+ | `worksheetStepShape` | const | `ContractShape` | Describes a `Step` in its JSON projection. |
303
+ | `worksheetGroupShape` | const | `ContractShape` | Describes a `WorksheetGroup` in its JSON projection. |
304
+ | `worksheetFactorShape` | const | `ContractShape` | Describes a `WorksheetFactor` in its JSON projection. |
305
+ | `evidenceShape` | const | `ContractShape` | Describes an `Evidence` row in its JSON projection. |
306
+ | `ratingDefinitionShape` | const | `ContractShape` | Describes a `RatingDefinition`. |
307
+ | `lineDefinitionShape` | const | `ContractShape` | Describes a `LineDefinition`. |
308
+
309
+ ### Contracts
310
+
311
+ The compiled contracts. Cross a definition on `is`, never `parse`, and a result as `projectRatingResult`.
312
+
313
+ | Name | Kind | Signature | Summary |
314
+ | -------------------------- | ----- | ---------------------------- | ----------------------------------------------------------------------------------------------- |
315
+ | `ratingResultContract` | const | `ContractInterface<unknown>` | Publishes a `RatingResult`'s JSON projection as a contract, read through `projectRatingResult`. |
316
+ | `ratingDefinitionContract` | const | `ContractInterface<unknown>` | Publishes a `RatingDefinition` as a contract. Cross it on `is`, never `parse`. |
317
+
318
+ ### Constants
319
+
320
+ | Name | Kind | Signature | Summary |
321
+ | ------------------ | ----- | --------------------------------------- | ----------------------------------------------------------- |
322
+ | `WORKSHEET_STAGES` | const | `readonly ['factor', 'group', 'total']` | Lists the stages a worksheet derivation step can belong to. |
323
+
277
324
  ### Classes
278
325
 
279
326
  | Name | Kind | Signature | Summary |
@@ -304,13 +351,19 @@ return equal results for the same lines:
304
351
 
305
352
  ```ts
306
353
  import { buildLineDefinition, createRater } from '@orkestrel/rater'
307
- import { createQuantitativeDefinition } from '@orkestrel/reason'
354
+ import {
355
+ createFactorGroup,
356
+ createQuantitativeDefinition,
357
+ createStaticFactor,
358
+ } from '@orkestrel/reason'
308
359
 
309
360
  const rater = createRater()
310
361
  const base = buildLineDefinition(
311
362
  'base',
312
363
  'Base Amount',
313
- createQuantitativeDefinition('base', 'Base', []),
364
+ createQuantitativeDefinition('base', 'Base', [
365
+ createFactorGroup('amount', 'sum', [createStaticFactor('flat', 100)]),
366
+ ]),
314
367
  )
315
368
 
316
369
  rater.rate([base], { id: 'subject-1' }) // the array-of-lines overload