@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
@@ -11,8 +11,12 @@ Nothing here is an LLM, a provider, or an agent: the `prompt` a result carries i
11
11
  an external model and is never consumed internally, and the reverse direction complements the
12
12
  raters' `describe*` family rather than duplicating it. `normalize` applies contraction,
13
13
  abbreviation, and correction substitutions; `extract` classifies intent without ever seeing a
14
- recipe and mines the raw numbers; `clarify` resolves same-domain carry-over, recipe
15
- defaults, and dependency-ordered computed fields. Every discriminant names its axis rather
14
+ recipe and reads exact numeric values; `clarify` resolves same-domain carry-over and
15
+ dependency-ordered computed fields, then admits the subject they build through the recipe's
16
+ `shape`, which says what is required, what is optional, and what an optional field defaults
17
+ to. A subject the door refuses is no subject: `subject` stays absent and each refusal is an
18
+ `Ambiguity` carrying its fault, with the question from the shape's `description`. Every
19
+ discriminant names its axis rather
16
20
  than `kind` or `type`: `stage` splits the pipeline phases, `category` splits provenance, and
17
21
  `code` splits coded errors. Source: [`src/core`](../src/core). Surfaced through the
18
22
  `@src/core` barrel.
@@ -25,6 +29,7 @@ Add a recipe, interpret text through the normalize, extract, clarify, format, an
25
29
  pipeline, then render the result back to prose:
26
30
 
27
31
  ```ts
32
+ import { numberShape, objectShape } from '@orkestrel/contract'
28
33
  import { createExtractor, createInterpret } from '@orkestrel/interpret'
29
34
  import {
30
35
  createFactorGroup,
@@ -44,7 +49,7 @@ const interpret = createInterpret({
44
49
  domain: 'arithmetic',
45
50
  intents: ['calculate'],
46
51
  mappings: [{ entity: 'value', aliases: [], field: 'value' }],
47
- defaults: [],
52
+ shape: objectShape({ value: numberShape() }),
48
53
  computations: [],
49
54
  definition: createQuantitativeDefinition('t1', 'Arithmetic', [
50
55
  createFactorGroup('total', 'sum', [createFieldFactor('value', 'value')]),
@@ -53,7 +58,7 @@ const interpret = createInterpret({
53
58
  ],
54
59
  })
55
60
 
56
- const result = interpret.interpret('calculate arithmetic 42')
61
+ const result = interpret.interpret('calculate arithmetic value 42')
57
62
  result.subject // { value: 42 }
58
63
  result.ambiguities // []
59
64
  result.failures // []
@@ -69,89 +74,391 @@ non-match, and a thrown stage, each yield a visible incomplete `Interpretation`
69
74
  throwing, and never an arbitrary fallback recipe. An interpretation is complete when
70
75
  `ambiguities` and `failures` are both empty; no stored flag repeats that fact.
71
76
 
77
+ ### Reading a recipe's shape
78
+
79
+ `Recipe.shape` is the generated subject's shape, read at the door after clarify and
80
+ computations. A required field absent is a question; an optional field with a default is
81
+ filled, and `defaulted` lists what the door filled; a lossless repair, a number on a string
82
+ field for one, is accepted and listed in `repairs`; anything else the door refuses is a
83
+ question too, and it blocks whether or not the field is required. A question carries the
84
+ `fault` it came from.
85
+
86
+ ```ts
87
+ import { numberShape, objectShape, optionalShape } from '@orkestrel/contract'
88
+ import { createExtractor, createInterpret } from '@orkestrel/interpret'
89
+ import { createLogicalDefinition } from '@orkestrel/reason'
90
+
91
+ const interpret = createInterpret({
92
+ extractor: createExtractor({
93
+ actions: { check: 'check' },
94
+ domains: { loans: ['loan'] },
95
+ }),
96
+ recipes: [
97
+ {
98
+ id: 'r',
99
+ name: 'Loan',
100
+ domain: 'loans',
101
+ intents: ['check'],
102
+ mappings: [{ entity: 'age', aliases: [], field: 'age' }],
103
+ computations: [],
104
+ definition: createLogicalDefinition('r', 'Loan', []),
105
+ shape: objectShape({
106
+ age: numberShape({ description: 'How old are you?' }),
107
+ term: optionalShape(numberShape(), { default: 12 }),
108
+ }),
109
+ },
110
+ ],
111
+ })
112
+
113
+ const asked = interpret.interpret('check loan')
114
+ asked.subject // undefined
115
+ asked.ambiguities[0]?.question // 'How old are you?'
116
+ asked.ambiguities[0]?.fault // { reason: 'missing', path: ['age'], expected: 'number' }
117
+
118
+ const read = interpret.interpret('check loan age 30')
119
+ read.subject // { age: 30, term: 12 }
120
+ read.defaulted // [['term']]
121
+ interpret.destroy()
122
+ ```
123
+
124
+ A computation may read a default, and a computed value stands over one. A computed field is
125
+ trusted no more than the least of what it read.
126
+
127
+ Choosing a recipe asks rather than picks: a text naming two domains or two actions names
128
+ neither, a recipe needs its own domain named, because an action alone names no recipe, and a tie
129
+ for the best score matches nothing. Each of these reaches the `NO_RECIPE` question. A result names
130
+ the recipe it matched in `recipe` and `version`.
131
+
132
+ A number fills a field only through an anchor: the mapping's entity name or an alias, matched
133
+ exactly against a token or an in-order sequence of tokens in the same clause. Fuzzy aliases claim nothing.
134
+ For single-value assignment, conflict detection groups all mappings by their target field.
135
+ Each mapping's selected anchor always counts as a mention. Among overlapping entity and alias
136
+ spans, it keeps the later start, then the longer span at equal starts. If the kept span links
137
+ no number, the overlapping span it displaced speaks instead; a silent span hides nothing.
138
+ A span wholly inside another field's longer declared anchor contributes no mention unless
139
+ it is a selected anchor. That ownership applies only when the longer anchor lies within one
140
+ clause. A declared phrase owns its words: `training hours` does not contribute an `hours`
141
+ mention to another field when that field selects the later `hours` in `training hours 30. hours 40`.
142
+ Every nearest linked number is a candidate, including every number in a tie. A negated clause
143
+ or an unlinked span contributes none. Each numeric occurrence counts once, even when several
144
+ spans reach it. Equal readable values count as one value; an occurrence without a value
145
+ differs from every other occurrence, never from itself.
146
+ Distinct values withhold every mapping on that field and record `anchor-conflict` with the field.
147
+ First-reason-wins still applies: an earlier refusal keeps its reason, and correction-marked
148
+ candidates keep `correction` under an explicit correction cue. Otherwise the last anchor
149
+ remains selected, even when it has no number; an earlier occurrence supplies no fallback.
150
+ A lone array mapping is exempt even without a claim. A non-lone array mapping still receives
151
+ one anchored value and participates in conflict detection. Another field can claim a refused
152
+ candidate through its own anchor; the withheld mapping still participates in rivalry.
153
+ This deliberately costs a question on a revision such as `hours 30. now hours 40`, which
154
+ supplies no value instead of choosing the revision. Only whitespace,
155
+ `is`, `of`, `at`, `to`, `=`, and `:` may link the spans; an article also links when the number
156
+ follows the anchor. A preceding `$125,000 a year` therefore supplies no value for `year`.
157
+ Negation anywhere in the clause blocks its claims. No other number may sit as close, and no
158
+ other anchor may sit closer. Other intervening words and distance across clauses are guesses, so
159
+ they fill nothing. A value read below the floor asks, whether or not the field is required,
160
+ because it is evidence a value was stated. A mapped field left to a default or a prior turn
161
+ asks too while a number nobody claimed could be its value, with those numbers as `candidates`.
162
+ A number `scanNumbers` marks foreign still participates in anchor-conflict detection; excluding
163
+ it would guess its intended role. The clarifier otherwise sets unclaimed foreign numbers aside.
164
+ A host may supply an entity with provenance `proposed` after checking a reader's proposal.
165
+ The clarifier treats it as stated, like `extracted` and `computed`, so an unclaimed number
166
+ does not by itself cast doubt on that field. Confidence and shape checks still apply.
167
+ A `default` value still asks when an unclaimed number could be its value. This package
168
+ does not produce `proposed` entities itself.
169
+ Every one of these blocks the subject, and what a blocked turn read stays in `entities`, so the
170
+ next turn can carry it when history is enabled: only what was stated carries, because a computed or defaulted value is
171
+ worked out again, and only within one recipe. Only a mapping whose field's shape is an array collects many numbers, and collection requires
172
+ an anchor. An unreadable occurrence asks instead of supplying digit fragments or an empty array.
173
+
174
+ A tied anchor still contests both adjacent numbers, so another anchor cannot take one
175
+ merely because the tied anchor could not choose. A number's next neighbor must be the end
176
+ of the text, an attached sentence end (`.`, `!`, `?`, or `;`), a whole declared anchor, or a
177
+ conditional link. Sentence punctuation must touch the number and precede whitespace or the
178
+ text's end: `years 3.` and `years 3. Next` claim, while `amount 3 . 000 . 000` asks.
179
+ A newline alone does not end a sentence. Every other neighbor asks, including words in any script, punctuation,
180
+ and adjacent numbers. This applies to scalar claims and array collection.
181
+ The links `is`, `of`, `at`, `to`, `a`, `an`, `the`, `and`, and `with` all require a declared
182
+ anchor next, allowing one article (`a`, `an`, or `the`) between. An alias must match its
183
+ whole token sequence: `monthly payments` does not stand for `monthly income`. A token also matches
184
+ a declared word with its trailing periods removed, for a field's anchor and for an intent's action or
185
+ domain keyword: `for 2 nights.` binds nights, and `I need a table.` names the domain `table` names.
186
+ A word declared with its own period, such as `st.`, still matches itself, and `St.` ties a domain
187
+ holding `st.` with one holding `st`. This admits a word and leaves sentences as written, so
188
+ `for 2 nights. 3 people` binds both, where `for 2 nights 3 people` ties. A numeric target asks,
189
+ whether written in digits or words: `amount 5 of 3000000`, `amount 3 and 5`,
190
+ `amount 50000 and 60000`, `years 3 and 6 months`, and `amount 50000 with a 20000 deposit`
191
+ hold no value for that field. `3 and a half` remains one numeric form, so it meets no link check.
192
+ Array collection follows the same rule: `value 10 and 20 and 30` asks, while
193
+ `value 10 and value 20 and value 30` collects when `value` is the declared array anchor.
194
+ Thus `amount 50000 and income 120000` holds both fields, while `amount 50000 and up`
195
+ asks for amount and retains no amount value. `amount 50000 income 120000` asks for both
196
+ fields with no entity: the unchanged tie rule records `anchor-tie` for each occurrence.
197
+
198
+ Both sides are read when a number precedes its anchor. A preceding lone punctuation token,
199
+ another number, or the reader's existing `hedged` flag refuses that backward claim with
200
+ `preceding-word` and the immediate predecessor in `word`. Thus `1 – 3 years`, `150 90000 amount`,
201
+ and `under 2 years` ask without holding a value for that field. The preceding-number check
202
+ stops at trailing sentence punctuation: `income 120000, 3 years` keeps years 3.
203
+ `3 years`, `for 3 years`, and `have 3 years` also keep 3. No hedge vocabulary is added.
204
+ An anchor's trailing colon permits only a forward claim. Consequently
205
+ `amount: 50000 income: 120000 years: 3` holds those three values, including when written
206
+ on separate lines before normalization. Its comma-separated form reads the same.
207
+ The glued `amount:50000` remains an undeclared numeric token.
208
+
209
+ A comma admits unless a number follows it: `value 25, now` and
210
+ `amount 50000, income 120000` still claim, whereas `amount 3, 000, 000` asks.
211
+ Known limits retained by the comma admission: `years 3, months` holds 3 and
212
+ `amount 50000, and up` holds 50000.
213
+
214
+ Every maximal nonspace run holding a digit, less trailing sentence punctuation, must match
215
+ a declared numeric form whole. The forms are unsigned digits or comma groups, optionally
216
+ with a decimal fraction, or a leading-dot decimal; an optional dollar prefix (`$`, `US$`,
217
+ or `USD`, allowing one space); and an optional `%`, `k`, `mil`, `mill`, `million`, `thousand`,
218
+ `grand`, or `ish` suffix. With a dollar prefix, `m`, `mm`, `b`, and `bn` also admit.
219
+ Letters match without case. A currency prefix can include its one separating space.
220
+ That prefix must pass the same admission even inside an earlier token: `amount:€ 50000`
221
+ and `amount=€ 50000` refuse the currency-prefixed number.
222
+ Other digit-holding forms, including `3_000_000`, `3+`, `~3`, ordinals, numeric dates,
223
+ times, and hyphenated phone numbers, carry `unreadable: 'undeclared'` with no `value`.
224
+ Their span and `raw` cover the whole rejected token. `401k` is the declared `k` suffix and
225
+ reads 401000; the reader no longer exempts that token as a plan number.
226
+
227
+ Whole-token admission precedes exact reading: ambiguous grouping such as `3.000` and
228
+ space-grouped `3 000 000`, ranges, and inexact arithmetic still refuse. Word forms retain
229
+ their existing grammar, including separated scales such as `3 mn`. An unsupported scale
230
+ word is left after the numeric span and refuses assignment by neighbor admission; it needs
231
+ no scale refusal list. `WHOLE_NUMBER_FORMS` in `tests/setup.ts` pins exact readings and
232
+ refusals, beside seeded tables of admitted tokens, undeclared tokens, and neighbors.
233
+ `3 and a half` reads exactly 3.5, and `six and a half` reads exactly 6.5.
234
+ A fraction joins only a plain number. `3 million and a half`, `$3m and a half`,
235
+ `three million and a half`, `3 million and a quarter`, and `3k and a half` are unreadable.
236
+ The numeric phrase in `3 and a half months` still reads 3.5. In `years 3 and a half months`,
237
+ the following-word test refuses the assignment because `months` is neither an anchor nor a link.
238
+
239
+ An explicit correction in the text makes occurrences marked `suspect` or `changed` ask:
240
+ `sorry` (except `sorry to/for`), `hang on`, `used to be`, `was/were going to be`, and `wait` (except `wait to`).
241
+ Assignment never substitutes a rival value. Ordinary `now` statements do not trigger this
242
+ correction refusal; they can still trigger `anchor-conflict` when the same field names distinct
243
+ values. An array collection refuses when any occurrence meets the correction rule.
244
+
245
+ `add` and the `recipes` option refuse with `InterpretError('DEFINITION')` a recipe that is malformed,
246
+ whose shape does not compile, stand, or declare a field it maps or computes, with a required field
247
+ nothing fills, or with a computation reading a variable nothing fills.
248
+
249
+ An `Interpretation` crosses a boundary as `projectInterpretation`, which
250
+ `interpretationContract` admits. A recipe crosses on `createRecipeContract().is`, never `parse`. `is` reads a nested `shape` as any
251
+ JSON value and the guard reads it as a shape, so `shape: 42` passes `is` and `isRecipe` refuses it:
252
+ a recipe crossing a boundary goes through the guard as well.
253
+
254
+ ### Reading numbers
255
+
256
+ `scanNumbers` reads every number in a text exactly, or says why it cannot, with its span and what
257
+ the words around it say. `extractNumbers` reads digits only; this also reads shorthand and word
258
+ forms. It never assigns a number to a field, so read it beside a recipe, for a check that a
259
+ proposed value appears in the text, or to set aside a number that belongs to no quantity.
260
+
261
+ ```ts
262
+ import { scanNumbers } from '@orkestrel/interpret'
263
+
264
+ scanNumbers('$75k at 6%').map((number) => number.value) // [75000, 6]
265
+ scanNumbers('three hundred thousand dollars')[0]?.money // true
266
+ scanNumbers('twelve fifty')[0]?.unreadable // 'spoken'
267
+ scanNumbers('12 to 18')[0]?.unreadable // 'range'
268
+ scanNumbers('call 555-0142')[0]?.unreadable // 'undeclared'
269
+ scanNumbers('in 2019')[0]?.foreign // 'year'
270
+ scanNumbers('about 40 hours')[0]?.hedged // true
271
+ scanNumbers('about 40 hours')[0]?.unit // 'hour'
272
+ ```
273
+
274
+ A value is present when the digits or words read to a number. Read it with `unreadable`, which
275
+ says the reading is not exact, and `foreign`, which says it is no quantity. A value past what a
276
+ number holds exactly reads as `unreadable: 'overflow'`, with no value. `readNumbersContract` is
277
+ the contract of what it returns. Exponent notation is unreadable shorthand, unsupported scale
278
+ compositions are unreadable joins, and a scaled value changed by six-decimal rounding carries
279
+ `unreadable: 'precision'`. Scaling retains its unrounded product.
280
+
281
+ ### Refusal evidence
282
+
283
+ `compileEntities` is the composition entry for assignment with evidence. `assignEntities`
284
+ returns only its entities. `Interpretation.refusals` carries the same optional record:
285
+ at most `NUMBER_REFUSAL_LIMIT` (32) items, with the remaining count in `omitted`.
286
+ It is absent when no occurrence was refused. Records follow occurrence order, retain
287
+ the first decision for each occurrence, and exclude every occurrence eventually claimed.
288
+ Only retained records render their `text` and following `word` through the contract's
289
+ bounded `preview`; strings therefore include quotes.
290
+
291
+ Positions are UTF-16 offsets into `Interpretation.normalized`, start inclusive and end
292
+ exclusive. Stage compositions obtain that text from `createNormalizer().normalize(text).text`
293
+ and pass it to both `scanNumbers` and `compileEntities`. No original-input offset map is
294
+ provided. The compiler produces ordered spans. The shape and guard validate nonnegative
295
+ integer positions structurally and accept reversed pairs.
296
+
297
+ The reasons record existing decisions: `preceding-word` for a backward claim refused by
298
+ preceding punctuation, another number, or a hedge flag; `following-word` for a failed following-word
299
+ anchor/link check; `unreadable` for a selected occurrence without an exact value or with
300
+ an unreadable mark; `anchor-tie` for equally near numbers or competing nearest anchors;
301
+ `anchor-conflict` for distinct values linked to a field's retained anchor spans, ties included;
302
+ `correction` for a suspect or changed occurrence under an explicit correction cue;
303
+ `negation` for occurrences in a negated anchor clause; `unanchored` when compilation
304
+ ends with neither a claim nor an earlier refusal; and `collection` for the other members
305
+ of a sole array mapping withheld after one member fails. The unreadable check carries
306
+ its existing `unreadable` detail; both neighbor checks carry `word`.
307
+ A decision carries `field` only when its mapping is available. Competing anchors and
308
+ unanchored occurrences have no unique field. No intended field or deeper linguistic
309
+ explanation is inferred.
310
+
311
+ Refusals do not change entities, questions, subjects, or the digest. The digest excludes
312
+ the record, so two results may share a digest while their refusal records differ.
313
+ The extraction stage now returns exact reader values, including word forms, and omits
314
+ unreadable occurrences: `3 000 000` contributes no fragments. This also changes direct
315
+ `Extractor.extract` callers. The separately published `extractNumbers` remains digit-only.
316
+
317
+ | Name | Kind | Signature | Summary |
318
+ | ------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
319
+ | `NumberRefusalReason` | type | `'preceding-word' \| 'following-word' \| 'unreadable' \| 'anchor-tie' \| 'anchor-conflict' \| 'correction' \| 'negation' \| 'unanchored' \| 'collection'` | Names the decision that first prevented a numeric occurrence from being assigned. |
320
+ | `NumberRefusal` | interface | `{ text, reason, unreadable?, word?, field? }` | Represents one refused numeric occurrence, its normalized position, and its first decision. |
321
+ | `NumberRefusals` | interface | `{ items, omitted }` | Represents bounded refusal records and the count omitted after the published cap. |
322
+ | `EntityCompilation` | interface | `{ entities, refusals? }` | Represents assigned entities and any bounded evidence of refused numeric occurrences. |
323
+ | `NumberRefusalDecision` | interface | `{ reason, word?, field? }` | Represents the first refusal decision retained before bounded record construction. |
324
+ | `AnchorRefusalHandler` | type | `(index: number, reason: 'negation' \| 'anchor-tie') => void` | Observes the input occurrence index and the refusal decided by an anchor check. |
325
+ | `NUMBER_REFUSAL_LIMIT` | const | `32` | Limits the refusal records carried by one compilation or interpretation to 32. |
326
+ | `NUMBER_REFUSAL_REASONS` | const | `readonly NumberRefusalReason[]` | Lists the frozen vocabulary of first refusal decisions described by `NumberRefusalReason`. |
327
+ | `compileEntities` | function | `(numbers: readonly ReadNumber[], mappings: readonly EntityMapping[], text: string, shape: ContractShape) => EntityCompilation` | Compiles exact reader occurrences into entities and bounded refusal evidence. |
328
+ | `isNumberRefusal` | function | `(value: unknown) => value is NumberRefusal` | Determines whether a value is a structurally valid refusal record. |
329
+ | `isNumberRefusals` | function | `(value: unknown) => value is NumberRefusals` | Determines whether a value holds bounded refusal items and a valid omitted count. |
330
+ | `numberRefusalShape` | const | `ContractShape` | Describes one refusal record with structurally valid, unordered nonnegative integer positions. |
331
+ | `numberRefusalsShape` | const | `ContractShape` | Describes bounded refusal items and a nonnegative integer omitted count. |
332
+
333
+ ```ts
334
+ import { numberShape, objectShape } from '@orkestrel/contract'
335
+ import { compileEntities, createNormalizer, scanNumbers } from '@orkestrel/interpret'
336
+
337
+ const text = createNormalizer().normalize('years 3 months').text
338
+ const result = compileEntities(
339
+ scanNumbers(text),
340
+ [{ entity: 'years', aliases: [], field: 'years' }],
341
+ text,
342
+ objectShape({ years: numberShape() }),
343
+ )
344
+ result.entities // []
345
+ result.refusals?.items[0]?.reason // 'following-word'
346
+ result.refusals?.items[0]?.start // 6
347
+
348
+ const range = '1 – 3 years'
349
+ const refused = compileEntities(
350
+ scanNumbers(range),
351
+ [{ entity: 'years', aliases: [], field: 'years' }],
352
+ range,
353
+ objectShape({ years: numberShape() }),
354
+ )
355
+ refused.entities // []
356
+ refused.refusals?.items[1]?.reason // 'preceding-word'
357
+ refused.refusals?.items[1]?.word // '"–"'
358
+ ```
359
+
72
360
  ### Types
73
361
 
74
- | Name | Kind | Signature | Summary |
75
- | ---------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
76
- | `ProvenanceCategory` | type | `'extracted' \| 'carried' \| 'default' \| 'computed' \| 'subject'` | Names how one `FieldMapping` or `Entity` value was obtained. |
77
- | `InterpretStage` | type | `'normalize' \| 'extract' \| 'clarify' \| 'format' \| 'generate'` | Names the fixed pipeline phases an `InterpretInterface#interpret` run produces one `StageRecord` for, in order. |
78
- | `InterpretErrorCode` | type | `'NORMALIZE_FAILED' \| 'EXTRACT_FAILED' \| 'CLARIFY_FAILED' \| 'FORMAT_FAILED' \| 'GENERATE_FAILED' \| 'NO_RECIPE' \| 'LOW_CONFIDENCE' \| 'DESTROYED'` | Names the coded misuse or failure conditions thrown as an `InterpretError` or carried on a `StageFailure`. |
79
- | `EntityMapping` | interface | `{ entity, aliases, field, required? }` | Represents one entity-extraction rule inside a `Recipe`: which literal alias phrases identify a value, and which subject field it lands on. |
80
- | `FieldDefault` | interface | `{ field, value }` | Represents a fallback value a `Recipe` fills onto a field left unresolved by extraction. |
81
- | `ComputedField` | interface | `{ field, expression }` | Represents a declaratively computed field: evaluate `expression` against the entities already resolved for this interpretation, and land the result on `field`. |
82
- | `Recipe` | interface | `{ id, name, domain, intents, mappings, defaults, computations, definition }` | Represents a named, versionable interpretation recipe: which intents it answers, how to mine entities for it, its fallback data, its computed fields, and the reasons `Definition` it ultimately produces a `Subject` for. |
83
- | `Provenance` | interface | `{ category, detail? }` | Describes how one value landed — its origin category plus an optional strategy detail. |
84
- | `Intent` | interface | `{ action?, domain?, confidence }` | Represents the classified action + domain for one interpretation, with a combined confidence. |
85
- | `Entity` | interface | `{ name, value, provenance, confidence }` | Represents one value assigned to a recipe's entity mapping, with its provenance and confidence. |
86
- | `Ambiguity` | interface | `{ field, question, candidates, required }` | Represents an unresolved field surfaced as a human-readable question, never bare prose. |
87
- | `FieldMapping` | interface | `{ field, entity?, value, provenance, confidence }` | Represents one audited field of the built subject — its resolved value, provenance, and confidence. |
88
- | `TextChange` | interface | `{ from, to }` | Represents one normalization substitution applied to the raw text. |
89
- | `StageRecord` | interface | `{ stage, input, output, failed, error? }` | Represents a structured input/output snapshot of one pipeline phase. |
90
- | `StageFailure` | interface | `{ stage, code, message }` | Represents a visible marker for a stage that threw, carrying its coded reason. |
91
- | `NormalizeResult` | interface | `{ text, changes }` | Represents the `Normalizer` stage's output: the cleaned text plus every substitution applied. |
92
- | `ExtractResult` | interface | `{ intent, numbers }` | Represents the `Extractor` stage's output: intent classification plus raw numbers. |
93
- | `ClarifyResult` | interface | `{ entities, ambiguities }` | Represents the `Clarifier` stage's output: resolved entities plus any remaining ambiguities. |
94
- | `FormatResult` | interface | `{ prompt }` | Represents the `Formatter` stage's output: the refined natural-language prompt. |
95
- | `GenerateResult` | interface | `{ subject, definition, mappings, confidence }` | Represents the `Generator` stage's output: the built subject/definition pair plus its full field audit. |
96
- | `Interpretation` | interface | `{ text, normalized, intent, entities, subject?, definition?, mappings, ambiguities, prompt, stages, failures, confidence, digest }` | Represents the full, replayable outcome of one `interpret()` call. |
97
- | `RecipeRecord` | interface | `{ id, recipe, version, hash }` | Represents a versioned, content-hashed `Recipe` as held by a `RecipeManagerInterface`. |
98
- | `SubjectRecord` | interface | `{ id, subject, version, hash }` | Represents a versioned, content-hashed `Subject` as held by a `SubjectManagerInterface`. |
99
- | `DefinitionRecord` | interface | `{ id, definition, version, hash }` | Represents a versioned, content-hashed `Definition` as held by a `DefinitionManagerInterface`. |
100
- | `InterpretEventMap` | type | `{ readonly interpret: readonly [result: Interpretation]; readonly add: readonly [recipeId: string]; readonly error: readonly [error: unknown]; readonly destroy: readonly []; }` | Represents the push observation surface of an `InterpretInterface`. |
101
- | `RecordEventMap` | type | `{ readonly add: readonly [id: string]; readonly remove: readonly [id: string]; readonly destroy: readonly []; }` | Represents the push observation surface shared by every record registry — an id-keyed collection, so `add` and `remove` are the events (never ordered-list `append`/`prepend`). |
102
- | `RecipeManagerEventMap` | type | `RecordEventMap` | Represents the push observation surface of a `RecipeManagerInterface`. |
103
- | `SubjectManagerEventMap` | type | `RecordEventMap` | Represents the push observation surface of a `SubjectManagerInterface`, whose `add` carries the own-minted record id. |
104
- | `DefinitionManagerEventMap` | type | `RecordEventMap` | Represents the push observation surface of a `DefinitionManagerInterface`. |
105
- | `InterpretContextEventMap` | type | `{ readonly add: readonly [digest: string]; readonly clear: readonly []; readonly destroy: readonly []; }` | Represents the push observation surface of an `InterpretContextInterface`. |
106
- | `NarratorFormatter` | type | `(value: unknown) => string` | Represents a pure formatting function for one lexicon `value()` unit. |
107
- | `Lexicon` | interface | `{ phrases?, labels?, templates? }` | Represents caller-injected wording data for the reverse direction — mechanism, never policy. Every phrase, label, and template string a `Narrator` renders is data supplied here, never a core literal. |
108
- | `NarratorOptions` | interface | `{ lexicon?, formatters? }` | Represents the options for `createNarrator` and the `Narrator` constructor. |
109
- | `NormalizerOptions` | interface | `{ contractions?, abbreviations?, corrections? }` | Represents the options for `createNormalizer` and the `Normalizer` constructor. |
110
- | `ExtractorOptions` | interface | `{ actions?, domains? }` | Represents the options for `createExtractor` and the `Extractor` constructor. |
111
- | `ClarifierOptions` | interface | `{ floor?, narrator? }` | Represents the options for `createClarifier` and the `Clarifier` constructor. |
112
- | `FormatterOptions` | interface | `{ verbs?, narrator? }` | Represents the options for `createFormatter` and the `Formatter` constructor. |
113
- | `RecipeManagerOptions` | interface | `{ recipes?, on?, error? }` | Represents the options for `createRecipeManager` and the `RecipeManager` constructor — the initial seed collection. |
114
- | `SubjectManagerOptions` | interface | `{ subjects?, on?, error? }` | Represents the options for `createSubjectManager` and the `SubjectManager` constructor — the initial seed collection. |
115
- | `DefinitionManagerOptions` | interface | `{ definitions?, on?, error? }` | Represents the options for `createDefinitionManager` and the `DefinitionManager` constructor — the initial seed collection. |
116
- | `RecordStamp` | interface | `{ id, version, hash }` | Represents the identity, version, and content hash a `RecordManagerInterface` derives for one record before its concrete shape is built. |
117
- | `RecordFunction` | type | `(stamp: RecordStamp, value: TValue) => TRecord` | Builds one concrete record from the `RecordStamp` its registry derived and the value that record holds. |
118
- | `RecordManagerOptions` | interface | `{ entity, on?, error? }` | Represents the options for the `RecordManager` constructor. |
119
- | `RecordManagerInterface` | interface | `{ emitter, count, has(), record(), records(), add(), remove(), destroy() }` | Represents the shared registry engine every record manager composes — the `Map`, the content-hash and version rule, the batch `remove` overloads, and teardown. |
120
- | `RecordOptions` | interface | `{ id? }` | Represents the per-call options for the record a manager's `add` mints. |
121
- | `InterpretContextOptions` | interface | `{ session?, history?, on?, error? }` | Represents the options for `createInterpretContext` and the `InterpretContext` constructor. |
122
- | `InterpretOptions` | interface | `{ recipes?, context?, normalizer?, extractor?, clarifier?, formatter?, generator?, similarity?, floor?, history?, narrator?, on?, error? }` | Represents the options for `createInterpret` and the `Interpret` constructor. |
123
- | `NormalizerInterface` | interface | `{ normalize() }` | Represents the `Normalizer` stage contract: raw text in, cleaned text + applied changes out. |
124
- | `ExtractorInterface` | interface | `{ extract() }` | Represents the `Extractor` stage contract: recipe-agnostic intent classification + raw number mining. |
125
- | `ClarifierInterface` | interface | `{ clarify() }` | Represents the `Clarifier` stage contract: resolve carry-over, defaults, and computed fields against a set of already-assigned entities, surfacing ambiguities for anything required that stays unresolved. |
126
- | `FormatterInterface` | interface | `{ format() }` | Represents the `Formatter` stage contract: render the refined natural-language prompt for a matched recipe. |
127
- | `GeneratorInterface` | interface | `{ generate() }` | Represents the `Generator` stage contract: build the final subject/definition pair plus its field audit. |
128
- | `NarratorInterface` | interface | `{ phrase(), label(), line(), value(), describe(), narrate() }` | Represents the `Narrator` contract — a stateless, total, lexicon-driven rendering engine for the reverse direction. |
129
- | `RecipeManagerInterface` | interface | `{ emitter, count, has(), recipe(), recipes(), add(), remove(), destroy() }` | Represents the recipe registry — a self-owning, versioned/hashed record-holder with the singular/plural accessor pair and the batch `remove` overloads. |
130
- | `SubjectManagerInterface` | interface | `{ emitter, count, has(), subject(), subjects(), add(), remove(), destroy() }` | Represents the subject registry — a self-owning, versioned/hashed record-holder that mints its own record ids (a `Subject` carries none). |
131
- | `DefinitionManagerInterface` | interface | `{ emitter, count, has(), definition(), definitions(), add(), remove(), destroy() }` | Represents the definition registry — a self-owning, versioned/hashed record-holder. |
132
- | `InterpretContextInterface` | interface | `{ emitter, session, subjects, definitions, previous(), entities(), add(), clear(), destroy() }` | Represents the cross-turn interpretation context: a capped, replayable history plus the subject/definition registries carry-over reads from. |
133
- | `InterpretInterface` | interface | `{ emitter, interpret(), add(), remove(), recipe(), recipes(), describe(), narrate(), destroy() }` | Represents the interpretation orchestrator — the sole public entry point, mirroring `reasons`' `Reason` orchestrator shape. |
362
+ | Name | Kind | Signature | Summary |
363
+ | ---------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
364
+ | `ReaderTokenInterface` | interface | `{ form, raw, lower, canon, start, marks, mark() }` | Declares one scanned token the number reader's passes mark as they walk a sentence. |
365
+ | `WordNumberResult` | interface | `{ token, next }` | Represents a written-out number, as the token it reads to and where the walk resumes. |
366
+ | `CardinalResult` | interface | `{ value, part, next, last, unreadable?, money }` | Represents a written-out cardinal as far as it has been read. |
367
+ | `ReaderMarks` | interface | `{ index, glued? }` | Represents what the number reader's passes have marked on one token so far. |
368
+ | `ReaderTokenForm` | type | `'number' \| 'word' \| 'mark'` | Names what one scanned token is to `NumberReader`: a number, a word, or a mark. |
369
+ | `ReadNumber` | interface | `{ raw, value?, unreadable?, foreign?, money?, percent?, scaled?, word?, hedged?, suspect?, changed?, composite?, loose?, magnitude?, weak?, tail?, yearish?, phone?, reference?, unit?, sentence, segment }` | Represents one number read from a text, with its span and what the words around it say. |
370
+ | `NumberForeign` | type | `'plan' \| 'phone' \| 'date' \| 'time' \| 'identifier' \| 'ordinal' \| 'list' \| 'age' \| 'past' \| 'period' \| 'reference' \| 'zip' \| 'address' \| 'year'` | Names what a number that belongs to no quantity is: a year, a date, a time, a reference, and so on. |
371
+ | `NumberUnreadable` | type | `'undeclared' \| 'fraction' \| 'foreign currency' \| 'grouping' \| 'signed' \| 'shorthand' \| 'spoken' \| 'joined' \| 'frequency' \| 'loose' \| 'range' \| 'dimensions' \| 'overflow' \| 'precision'` | Names why a number's value cannot be read exactly. |
372
+ | `TextSpan` | interface | `{ start, end }` | Represents where something sits in a text: `start` inclusive, `end` exclusive. |
373
+ | `AnchorPosition` | interface | `{ index }` | Represents a numeric span's input position in a prepared anchor lookup. |
374
+ | `AnchorCandidate` | interface | `{ index, gap }` | Represents a linked number and its distance from an anchor. |
375
+ | `AnchorLookup` | interface | `{ text, numbers, starts, ends, breaks, negations }` | Holds clause boundaries and ordered numeric spans for one compilation. |
376
+ | `AnchorProbe` | interface | `{ clause, negated, candidates }` | Represents a span's clause and nearest linked candidates, including ties. |
377
+ | `EntityAnchor` | interface | `{ mapping, position, end, confidence, detail, anchors }` | Holds a mapping's occurrences and its selected assignment anchor. |
378
+ | `ShapeDefault` | interface | `{ field, value }` | Represents one default a `Recipe`'s `shape` holds, by the field it fills. |
379
+ | `ProvenanceCategory` | type | `'extracted' \| 'proposed' \| 'carried' \| 'default' \| 'computed' \| 'subject'` | Names how one `FieldMapping` or `Entity` value was obtained. |
380
+ | `InterpretStage` | type | `'normalize' \| 'extract' \| 'clarify' \| 'format' \| 'generate'` | Names the fixed pipeline phases an `InterpretInterface#interpret` run produces one `StageRecord` for, in order. |
381
+ | `InterpretErrorCode` | type | `'TEXT_LIMIT' \| 'NORMALIZE_FAILED' \| 'EXTRACT_FAILED' \| 'CLARIFY_FAILED' \| 'FORMAT_FAILED' \| 'GENERATE_FAILED' \| 'NO_RECIPE' \| 'LOW_CONFIDENCE' \| 'DEFINITION' \| 'DESTROYED'` | Names the coded misuse or failure conditions thrown as an `InterpretError` or carried on a `StageFailure`. |
382
+ | `EntityMapping` | interface | `{ entity, aliases, field }` | Represents one entity-extraction rule inside a `Recipe`: which literal aliases identify a value, and which subject field it lands on. |
383
+ | `ComputedField` | interface | `{ field, expression }` | Represents a declaratively computed field: evaluate `expression` against the entities already resolved for this interpretation, and land the result on `field`. |
384
+ | `Recipe` | interface | `{ id, name, domain, intents, mappings, computations, definition, shape }` | Represents a named, versionable interpretation recipe: which intents it answers, how to mine entities for it, its computed fields, the shape of what it produces, and the reasons `Definition` it ultimately produces a `Subject` for. |
385
+ | `Provenance` | interface | `{ category, detail? }` | Describes how one value landed — its origin category plus an optional strategy detail. |
386
+ | `Intent` | interface | `{ action?, domain?, confidence }` | Represents the classified action + domain for one interpretation, with a combined confidence. |
387
+ | `Entity` | interface | `{ name, field?, value, provenance, confidence }` | Represents one value assigned to a recipe's entity mapping, with its provenance and confidence. |
388
+ | `Ambiguity` | interface | `{ field, question, candidates, required, fault? }` | Represents an unresolved field surfaced as a human-readable question, never bare prose. |
389
+ | `FieldMapping` | interface | `{ field, entity?, value, provenance, confidence }` | Represents one audited field of the built subject — its resolved value, provenance, and confidence. |
390
+ | `TextChange` | interface | `{ from, to }` | Represents one normalization substitution applied to the raw text. |
391
+ | `StageRecord` | interface | `{ stage, input, output, failed, error? }` | Represents a structured input/output snapshot of one pipeline phase. |
392
+ | `StageFailure` | interface | `{ stage, code, message }` | Represents a visible marker for a stage that threw, carrying its coded reason. |
393
+ | `NormalizeResult` | interface | `{ text, changes }` | Represents the `Normalizer` stage's output: the cleaned text plus every substitution applied. |
394
+ | `ExtractResult` | interface | `{ intent, numbers }` | Represents the `Extractor` stage's output: intent classification plus exact reader values. |
395
+ | `ClarifyResult` | interface | `{ entities, ambiguities, repairs, defaulted }` | Represents the `Clarifier` stage's output: resolved entities plus any remaining ambiguities. |
396
+ | `FormatResult` | interface | `{ prompt }` | Represents the `Formatter` stage's output: the refined natural-language prompt. |
397
+ | `GenerateResult` | interface | `{ subject, definition, mappings, confidence }` | Represents the `Generator` stage's output: the built subject/definition pair plus its full field audit. |
398
+ | `Interpretation` | interface | `{ refusals?, text, normalized, intent, recipe?, version?, entities, subject?, definition?, mappings, ambiguities, repairs, defaulted, prompt, stages, failures, confidence, digest }` | Represents the full, replayable outcome of one `interpret()` call. |
399
+ | `RecipeRecord` | interface | `{ id, recipe, version, hash }` | Represents a versioned, content-hashed `Recipe` as held by a `RecipeManagerInterface`. |
400
+ | `SubjectRecord` | interface | `{ id, subject, version, hash }` | Represents a versioned, content-hashed `Subject` as held by a `SubjectManagerInterface`. |
401
+ | `DefinitionRecord` | interface | `{ id, definition, version, hash }` | Represents a versioned, content-hashed `Definition` as held by a `DefinitionManagerInterface`. |
402
+ | `InterpretEventMap` | type | `{ readonly interpret: readonly [result: Interpretation]; readonly add: readonly [recipeId: string]; readonly error: readonly [error: unknown]; readonly destroy: readonly []; }` | Represents the push observation surface of an `InterpretInterface`. |
403
+ | `RecordEventMap` | type | `{ readonly add: readonly [id: string]; readonly remove: readonly [id: string]; readonly destroy: readonly []; }` | Represents the push observation surface shared by every record registry — an id-keyed collection, so `add` and `remove` are the events (never ordered-list `append`/`prepend`). |
404
+ | `RecipeManagerEventMap` | type | `RecordEventMap` | Represents the push observation surface of a `RecipeManagerInterface`. |
405
+ | `SubjectManagerEventMap` | type | `RecordEventMap` | Represents the push observation surface of a `SubjectManagerInterface`, whose `add` carries the own-minted record id. |
406
+ | `DefinitionManagerEventMap` | type | `RecordEventMap` | Represents the push observation surface of a `DefinitionManagerInterface`. |
407
+ | `InterpretContextEventMap` | type | `{ readonly add: readonly [digest: string]; readonly clear: readonly []; readonly destroy: readonly []; }` | Represents the push observation surface of an `InterpretContextInterface`. |
408
+ | `NarratorFormatter` | type | `(value: unknown) => string` | Represents a pure formatting function for one lexicon `value()` unit. |
409
+ | `Lexicon` | interface | `{ phrases?, labels?, templates? }` | Represents caller-injected wording data for the reverse direction — mechanism, never policy. Every phrase, label, and template string a `Narrator` renders is data supplied here, never a core literal. |
410
+ | `NarratorOptions` | interface | `{ lexicon?, formatters? }` | Represents the options for `createNarrator` and the `Narrator` constructor. |
411
+ | `NormalizerOptions` | interface | `{ contractions?, abbreviations?, corrections? }` | Represents the options for `createNormalizer` and the `Normalizer` constructor. |
412
+ | `ExtractorOptions` | interface | `{ actions?, domains? }` | Represents the options for `createExtractor` and the `Extractor` constructor. |
413
+ | `ClarifierOptions` | interface | `{ floor?, narrator? }` | Represents the options for `createClarifier` and the `Clarifier` constructor. |
414
+ | `FormatterOptions` | interface | `{ verbs?, narrator? }` | Represents the options for `createFormatter` and the `Formatter` constructor. |
415
+ | `RecipeManagerOptions` | interface | `{ recipes?, on?, error? }` | Represents the options for `createRecipeManager` and the `RecipeManager` constructor — the initial seed collection. |
416
+ | `SubjectManagerOptions` | interface | `{ subjects?, on?, error? }` | Represents the options for `createSubjectManager` and the `SubjectManager` constructor — the initial seed collection. |
417
+ | `DefinitionManagerOptions` | interface | `{ definitions?, on?, error? }` | Represents the options for `createDefinitionManager` and the `DefinitionManager` constructor — the initial seed collection. |
418
+ | `RecordStamp` | interface | `{ id, version, hash }` | Represents the identity, version, and content hash a `RecordManagerInterface` derives for one record before its concrete shape is built. |
419
+ | `RecordFunction` | type | `(stamp: RecordStamp, value: TValue) => TRecord` | Builds one concrete record from the `RecordStamp` its registry derived and the value that record holds. |
420
+ | `RecordManagerOptions` | interface | `{ entity, on?, error? }` | Represents the options for the `RecordManager` constructor. |
421
+ | `RecordManagerInterface` | interface | `{ emitter, count, has(), record(), records(), add(), remove(), destroy() }` | Represents the shared registry engine every record manager composes — the `Map`, the content-hash and version rule, the batch `remove` overloads, and teardown. |
422
+ | `RecordOptions` | interface | `{ id? }` | Represents the per-call options for the record a manager's `add` mints. |
423
+ | `InterpretContextOptions` | interface | `{ session?, history?, on?, error? }` | Represents the options for `createInterpretContext` and the `InterpretContext` constructor. |
424
+ | `InterpretOptions` | interface | `{ recipes?, context?, normalizer?, extractor?, clarifier?, formatter?, generator?, floor?, history?, narrator?, on?, error? }` | Represents the options for `createInterpret` and the `Interpret` constructor. |
425
+ | `NormalizerInterface` | interface | `{ normalize() }` | Represents the `Normalizer` stage contract: raw text in, cleaned text + applied changes out. |
426
+ | `ExtractorInterface` | interface | `{ extract() }` | Represents the `Extractor` stage contract: recipe-agnostic intent classification and exact reader values. |
427
+ | `ClarifierInterface` | interface | `{ clarify() }` | Represents the `Clarifier` stage contract: resolve carry-over and computed fields against a set of already-assigned entities, surfacing ambiguities for anything required that stays unresolved. |
428
+ | `FormatterInterface` | interface | `{ format() }` | Represents the `Formatter` stage contract: render the refined natural-language prompt for a matched recipe. |
429
+ | `GeneratorInterface` | interface | `{ generate() }` | Represents the `Generator` stage contract: build the final subject/definition pair plus its field audit. |
430
+ | `NarratorInterface` | interface | `{ phrase(), label(), line(), value(), describe(), narrate() }` | Represents the `Narrator` contract — a stateless, total, lexicon-driven rendering engine for the reverse direction. |
431
+ | `RecipeManagerInterface` | interface | `{ emitter, count, has(), recipe(), recipes(), add(), remove(), destroy() }` | Represents the recipe registry — a self-owning, versioned/hashed record-holder with the singular/plural accessor pair and the batch `remove` overloads. |
432
+ | `SubjectManagerInterface` | interface | `{ emitter, count, has(), subject(), subjects(), add(), remove(), destroy() }` | Represents the subject registry — a self-owning, versioned/hashed record-holder that mints its own record ids (a `Subject` carries none). |
433
+ | `DefinitionManagerInterface` | interface | `{ emitter, count, has(), definition(), definitions(), add(), remove(), destroy() }` | Represents the definition registry — a self-owning, versioned/hashed record-holder. |
434
+ | `InterpretContextInterface` | interface | `{ emitter, session, subjects, definitions, previous(), entities(), add(), clear(), destroy() }` | Represents the cross-turn interpretation context: a capped, replayable history plus the subject/definition registries carry-over reads from. |
435
+ | `InterpretInterface` | interface | `{ emitter, interpret(), add(), remove(), recipe(), recipes(), describe(), narrate(), destroy() }` | Represents the interpretation orchestrator — the sole public entry point, mirroring `reasons`' `Reason` orchestrator shape. |
134
436
 
135
437
  ### Constants
136
438
 
137
- | Name | Kind | Signature | Summary |
138
- | ------------------------------ | ----- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
139
- | `DEFAULT_INTERPRET_SIMILARITY` | const | `0.8` | Names the default `similarity` for `createInterpret` and `matchAlias`, 0.8 — the fuzzy alias-match score threshold, between 0 and 1. |
140
- | `DEFAULT_INTERPRET_FLOOR` | const | `0.3` | Names the default `floor` for `createInterpret` and `matchRecipe`, 0.3 — the minimum intent confidence a recipe match, or the classified intent itself, must clear. |
141
- | `DEFAULT_INTERPRET_HISTORY` | const | `16` | Names the default `history` cap for an `InterpretContext`'s `previous()` ring buffer, 16. |
142
- | `PROVENANCE_CATEGORIES` | const | `readonly ProvenanceCategory[]` | Lists every `ProvenanceCategory` literal, frozen — the one home the result guards check the union from, so a new category added to `types.ts` is added here rather than silently rejected by `isProvenance`. |
143
- | `INTERPRET_STAGES` | const | `readonly InterpretStage[]` | Lists every `InterpretStage` literal in pipeline order, frozen — the one home the result guards check the union from. |
144
- | `INTERPRET_ERROR_CODES` | const | `readonly InterpretErrorCode[]` | Lists every `InterpretErrorCode` literal, frozen — the one home the result guards check the union from. |
145
- | `CONFIDENCE_EXACT` | const | `1` | Names the confidence assigned to an exact keyword-proximity entity match, 1. |
146
- | `CONFIDENCE_ALIAS` | const | `0.9` | Names the confidence assigned to an exact alias-phrase entity match, 0.9. |
147
- | `CONFIDENCE_COLLECT` | const | `0.9` | Names the confidence assigned when a single entity mapping collects every extracted number, 0.9. |
148
- | `CONFIDENCE_POSITIONAL` | const | `0.7` | Names the confidence assigned to a positional (order-based) entity match fallback, 0.7. |
149
- | `CONFIDENCE_CARRIED` | const | `0.7` | Names the confidence assigned to a same-domain carried-over field, 0.7. |
150
- | `CONFIDENCE_DEFAULT` | const | `1` | Names the confidence assigned to a recipe default fill, 1. |
151
- | `CONFIDENCE_COMPUTED` | const | `0.9` | Names the confidence assigned to a successfully resolved computed field, 0.9. |
152
- | `NUMBER_PATTERN` | const | `RegExp` | Holds the numeric-entity extraction pattern shared by `extractNumbers` and `assignEntities` — an optional leading `$`, thousands-comma-grouped digits, an optional decimal fraction, and an optional trailing `%`. |
153
- | `DEFAULT_CONTRACTIONS` | const | `Readonly<Record<string, string>>` | Holds the neutral built-in contraction expansions for `Normalizer` — small on purpose; callers merge their own map over this one. |
154
- | `DEFAULT_LEXICON` | const | `Lexicon` | Holds the neutral default `Lexicon` a `Narrator` merges caller data over. |
439
+ | Name | Kind | Signature | Summary |
440
+ | --------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
441
+ | `NUMBER_FOREIGN_KINDS` | const | `readonly NumberForeign[]` | Lists every `NumberForeign` kind, frozen, for the shape that describes a read number. |
442
+ | `NUMBER_UNREADABLE_REASONS` | const | `readonly NumberUnreadable[]` | Lists every `NumberUnreadable` reason, frozen, for the shape that describes a read number. |
443
+ | `READER_WORDS` | const | `Readonly<{ synonyms: Readonly<Record<string, string>>; per: Readonly<Set<string>>; months: Readonly<Set<string>>; yearCues: Readonly<Set<string>>; references: Readonly<Set<string>>; referenceLinks: Readonly<Set<string>>; streets: Readonly<Set<string>>; generalUnits: Readonly<Set<string>>; timeUnits: Readonly<Set<string>>; calendarPeriods: Readonly<Set<string>>; countedOver: Readonly<Set<string>>; foreignCurrency: Readonly<Set<string>>; dollars: Readonly<Set<string>>; hedgesBefore: Readonly<Set<string>>; hedgesNear: Readonly<Set<string>>; hedgePairs: Readonly<Set<string>>; doubtPairs: Readonly<Set<string>>; hedgesAfter: Readonly<Set<string>>; hedgeAfterPairs: Readonly<Set<string>>; corrections: Readonly<Set<string>>; correctionPairs: Readonly<Set<string>>; suspectBefore: Readonly<Set<string>>; offsetBefore: Readonly<Set<string>>; verbLastBefore: Readonly<Set<string>>; putInBefore: Readonly<Set<string>>; changes: Readonly<Set<string>>; compositeCues: Readonly<Set<string>>; loose: Readonly<Set<string>>; magnitudes: Readonly<Set<string>>; gluedScales: Readonly<Set<string>>; functions: Readonly<Set<string>>; abbreviations: Readonly<Set<string>>; notOneBefore: Readonly<Set<string>>; notOneAfter: Readonly<Set<string>>; workOut: Readonly<Set<string>>; dimensions: Readonly<Set<string>>; alternatives: Readonly<Set<string>>; sentenceEnds: Readonly<Set<string>>; segmentMarks: Readonly<Set<string>>; ageBefore: Readonly<Set<string>>; }>` | Holds the word lists `NumberReader` reads a number's surroundings by. |
444
+ | `READER_SCALES` | const | `Readonly<{ digit: Readonly<Record<string, number>>; word: Readonly<Record<string, number>>; units: Readonly<Record<string, number>>; tens: Readonly<Record<string, number>>; }>` | Holds the values number words and scale words read to. |
445
+ | `READER_SHAPES` | const | `Readonly<{ admitted: RegExp; currency: RegExp; digit: RegExp; word: RegExp; }>` | Holds the shapes `NumberReader` recognizes a number by. |
446
+ | `CLAUSE_BREAK_PATTERN` | const | `RegExp` | Holds what ends a clause: closing punctuation, a comma or dot no digit follows, a newline, and a joining word. A colon stays inside, because "rate: 6" says one thing. |
447
+ | `DEFAULT_INTERPRET_FLOOR` | const | `0.3` | Names the default `floor` for `createInterpret` and `matchRecipe`, 0.3 — the minimum intent confidence a recipe match, or the classified intent itself, must clear. |
448
+ | `DEFAULT_INTERPRET_HISTORY` | const | `0` | Names the default `history` cap for an `InterpretContext`'s `previous()` ring buffer, 0 (carry is opt-in). |
449
+ | `PROVENANCE_CATEGORIES` | const | `readonly ProvenanceCategory[]` | Lists every `ProvenanceCategory` literal, frozen — the one home the result guards check the union from, so a new category added to `types.ts` is added here rather than silently rejected by `isProvenance`. |
450
+ | `INTERPRET_STAGES` | const | `readonly InterpretStage[]` | Lists every `InterpretStage` literal in pipeline order, frozen — the one home the result guards check the union from. |
451
+ | `INTERPRET_TEXT_LIMIT` | const | `65536` | Caps text accepted by the built-in normalizer and number reader at 65,536 UTF-16 units. |
452
+ | `INTERPRET_ERROR_CODES` | const | `readonly InterpretErrorCode[]` | Lists every `InterpretErrorCode` literal, frozen — the one home the result guards check the union from. |
453
+ | `CONFIDENCE_EXACT` | const | `1` | Names the confidence assigned to an exact keyword-proximity entity match, 1. |
454
+ | `CONFIDENCE_ALIAS` | const | `0.9` | Names the confidence assigned to an exact alias-phrase entity match, 0.9. |
455
+ | `CONFIDENCE_COLLECT` | const | `0.9` | Names the confidence assigned when a single entity mapping collects every extracted number, 0.9. |
456
+ | `CONFIDENCE_CARRIED` | const | `0.7` | Names the confidence assigned to a same-domain carried-over field, 0.7. |
457
+ | `CONFIDENCE_DEFAULT` | const | `1` | Names the confidence assigned to a default the door filled, 1. |
458
+ | `CONFIDENCE_COMPUTED` | const | `0.9` | Names the most a computed field may be trusted, 0.9: its inputs can only lower it. |
459
+ | `NUMBER_PATTERN` | const | `RegExp` | Holds the digit-only pattern for `extractNumbers`: an optional currency prefix, grouped digits, an optional decimal fraction, and an optional trailing `%`. |
460
+ | `DEFAULT_CONTRACTIONS` | const | `Readonly<Record<string, string>>` | Holds the neutral built-in contraction expansions for `Normalizer` — small on purpose; callers merge their own map over this one. |
461
+ | `DEFAULT_LEXICON` | const | `Lexicon` | Holds the neutral default `Lexicon` a `Narrator` merges caller data over. |
155
462
 
156
463
  ```ts
157
464
  import {
@@ -161,22 +468,18 @@ import {
161
468
  CONFIDENCE_COMPUTED,
162
469
  CONFIDENCE_DEFAULT,
163
470
  CONFIDENCE_EXACT,
164
- CONFIDENCE_POSITIONAL,
165
471
  DEFAULT_CONTRACTIONS,
166
472
  DEFAULT_INTERPRET_FLOOR,
167
473
  DEFAULT_INTERPRET_HISTORY,
168
- DEFAULT_INTERPRET_SIMILARITY,
169
474
  DEFAULT_LEXICON,
170
475
  NUMBER_PATTERN,
171
476
  } from '@orkestrel/interpret'
172
477
 
173
- DEFAULT_INTERPRET_SIMILARITY // 0.8
174
478
  DEFAULT_INTERPRET_FLOOR // 0.3
175
- DEFAULT_INTERPRET_HISTORY // 16
479
+ DEFAULT_INTERPRET_HISTORY // 0
176
480
  CONFIDENCE_EXACT // 1
177
481
  CONFIDENCE_ALIAS // 0.9
178
482
  CONFIDENCE_COLLECT // 0.9
179
- CONFIDENCE_POSITIONAL // 0.7
180
483
  CONFIDENCE_CARRIED // 0.7
181
484
  CONFIDENCE_DEFAULT // 1
182
485
  CONFIDENCE_COMPUTED // 0.9
@@ -220,7 +523,6 @@ published member conforms, because a foreign engine's return is not this package
220
523
  | Name | Kind | Signature | Summary |
221
524
  | ------------------ | -------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
222
525
  | `isEntityMapping` | function | `(value: unknown) => value is EntityMapping` | Determines whether a value is an exact `EntityMapping` input record — a literal alias-phrase extraction rule pointing at a subject field. |
223
- | `isFieldDefault` | function | `(value: unknown) => value is FieldDefault` | Determines whether a value is an exact `FieldDefault` input record — a fallback value a `Recipe` fills onto an unresolved field. |
224
526
  | `isComputedField` | function | `(value: unknown) => value is ComputedField` | Determines whether a value is an exact `ComputedField` input record — a declaratively computed field carrying a reasons `SymbolicExpression` tree. |
225
527
  | `isRecipe` | function | `(value: unknown) => value is Recipe` | Determines whether a value is an exact `Recipe` input record — a named, versionable interpretation recipe. |
226
528
  | `isProvenance` | function | `(value: unknown) => value is Provenance` | Determines whether a value is an open `Provenance` result record. |
@@ -233,13 +535,13 @@ published member conforms, because a foreign engine's return is not this package
233
535
  | `isInterpretation` | function | `(value: unknown) => value is Interpretation` | Determines whether a value is an open `Interpretation` result record. |
234
536
 
235
537
  ```ts
538
+ import { objectShape } from '@orkestrel/contract'
236
539
  import {
237
540
  createInterpret,
238
541
  isAmbiguity,
239
542
  isComputedField,
240
543
  isEntity,
241
544
  isEntityMapping,
242
- isFieldDefault,
243
545
  isFieldMapping,
244
546
  isIntent,
245
547
  isInterpretation,
@@ -255,7 +557,6 @@ import {
255
557
  } from '@orkestrel/reason'
256
558
 
257
559
  isEntityMapping({ entity: 'age', aliases: ['years old'], field: 'age' }) // true
258
- isFieldDefault({ field: 'term', value: 12 }) // true
259
560
  isComputedField({
260
561
  field: 'monthly',
261
562
  expression: {
@@ -271,7 +572,7 @@ isRecipe({
271
572
  domain: 'arithmetic',
272
573
  intents: ['calculate'],
273
574
  mappings: [],
274
- defaults: [],
575
+ shape: objectShape({}),
275
576
  computations: [],
276
577
  definition: createQuantitativeDefinition('t1', 'Arithmetic', [
277
578
  createFactorGroup('total', 'sum', [createFieldFactor('value', 'value')]),
@@ -295,25 +596,39 @@ guardEngine.destroy()
295
596
  Pure, exported utility functions — the referentially-transparent leaves
296
597
  behind the `Interpret` orchestrator and its stages.
297
598
 
298
- | Name | Kind | Signature | Summary |
299
- | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
300
- | `setField` | function | `(subject: Subject, field: FieldPath, value: unknown) => Subject` | Writes a value at a (possibly nested) field path on a subject, copy-on-write. |
301
- | `applyReplacements` | function | `(text: string, map: Readonly<Record<string, string>>) => string` | Replaces every whole-word occurrence of a map's keys with their values. |
302
- | `collapseWhitespace` | function | `(text: string) => string` | Collapses every run of whitespace to a single space and trims the ends. |
303
- | `tokenize` | function | `(text: string) => readonly string[]` | Splits text into lowercase tokens, stripping punctuation outside a small numeric/currency-safe allowlist. |
304
- | `extractNumbers` | function | `(text: string) => readonly number[]` | Mines every numeric literal from text — optional leading `$`, thousands commas, an optional decimal fraction, an optional trailing `%`. |
305
- | `assignEntities` | function | `(numbers: readonly number[], mappings: readonly EntityMapping[], text: string, similarity: number) => readonly Entity[]` | Assigns already-extracted numbers to a matched recipe's entity mappings. |
306
- | `classifyIntent` | function | `(text: string, actions: Readonly<Record<string, string>>, domains: Readonly<Record<string, readonly string[]>>) => Intent` | Classifies the action + domain intent of a text against caller-supplied vocabularies. |
307
- | `scoreSimilarity` | function | `(a: string, b: string) => number` | Measures bigram (Dice coefficient) string similarity, case-insensitive. |
308
- | `matchAlias` | function | `(token: string, aliases: readonly string[], threshold: number) => number` | Returns the best `scoreSimilarity` a token achieves against a list of aliases, gated by a threshold. |
309
- | `canonicalize` | function | `(value: unknown) => string` | Renders a value into a canonical, key-order-stable string — the pre-image of `digestValue`. |
310
- | `canonicalizeNode` | function | `(value: unknown, ancestors: ReadonlySet<object>) => string` | Renders one node of a value into its canonical, key-order-stable string, against the object ancestors already on the recursion path. |
311
- | `digestValue` | function | `(value: unknown) => string` | Computes a canonical structural digest of a pure-JSON value — a key-order-stable FNV-1a hash rendered as an 8-hex-digit string. |
312
- | `scoreRecipe` | function | `(intent: Intent, recipe: Recipe) => number` | Scores how well a classified intent matches one recipe's domain + action. |
313
- | `matchRecipe` | function | `(intent: Intent, recipes: readonly Recipe[], floor: number) => Recipe \| undefined` | Finds the best-scoring added recipe for a classified intent, gated by a confidence floor. |
314
- | `variablesOf` | function | `(expression: SymbolicExpression) => readonly string[]` | Collects every variable name referenced by a symbolic expression tree, in first-occurrence order. |
315
- | `resolveExpression` | function | `(expression: SymbolicExpression, bindings: Readonly<Record<string, number>>) => number \| undefined` | Evaluates a symbolic expression tree against resolved bindings. |
316
- | `renderSubject` | function | `(subject: Subject, narrator: NarratorInterface) => string` | Renders a one-line, display-neutral description of a reasons `Subject`, through an injected `Narrator`. |
599
+ | Name | Kind | Signature | Summary |
600
+ | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
601
+ | `matchesFilledField` | function | `(field: string, filled: readonly string[]) => boolean` | Determines whether a field is filled by one of the given fields: itself, one above it, or one inside it. |
602
+ | `collectRequiredFields` | function | `(shape: ContractShape, path?: readonly string[]) => readonly string[]` | Lists the fields a shape requires, each as its dot-joined path. |
603
+ | `scanNumbers` | function | `(text: string) => readonly ReadNumber[]` | Reads every number in a text exactly, or says why it cannot. |
604
+ | `findUnclaimedNumbers` | function | `(numbers: readonly ReadNumber[], entities: readonly Entity[]) => ReadonlyArray<number \| string>` | Finds the numbers no entity claimed. |
605
+ | `findAnchoredNumber` | function | `(text: string, anchor: TextSpan, numbers: readonly TextSpan[], refused?: AnchorRefusalHandler) => { readonly index: number; readonly gap: number; } \| undefined` | Finds the nearest directly linked number in an unnegated clause, refusing ties. |
606
+ | `findSpanOffset` | function | `(spans: readonly TextSpan[], position: number, edge?: 'start' \| 'end', lower?: number, upper?: number) => number` | Finds the first span whose selected edge is at or beyond a position. |
607
+ | `findLinkedNumbers` | function | `(text: string, anchor: TextSpan, numbers: readonly TextSpan[], clause: TextSpan) => readonly AnchorCandidate[]` | Finds directly linked numeric spans ordered by distance within a supplied clause. |
608
+ | `projectInterpretation` | function | `(result: Interpretation) => JSONValue \| undefined` | Projects an interpretation to JSON, so it can cross a boundary. |
609
+ | `assertRecipe` | function | `(recipe: unknown) => asserts recipe is Recipe` | Asserts a value is a recipe that stands. |
610
+ | `scanRecipeShape` | function | `(recipe: Recipe) => readonly string[]` | Describes what is wrong with a recipe's shape, against the recipe itself. |
611
+ | `settleEntities` | function | `(entities: readonly Entity[], mappings: readonly EntityMapping[], admission: SubjectAdmission) => readonly Entity[]` | Settles entities against what the door admitted. |
612
+ | `collectShapeDefaults` | function | `(shape: ContractShape, subject?: unknown, path?: readonly string[]) => readonly ShapeDefault[]` | Collects each default a shape holds, keyed by its field. |
613
+ | `findFieldDescription` | function | `(shape: ContractShape, field: FieldPath) => string \| undefined` | Finds the description a shape gives a field, which words the question for it. |
614
+ | `matchesArrayField` | function | `(shape: ContractShape, field: FieldPath) => boolean` | Determines whether a shape's field holds an array, so a mapping onto it collects many. |
615
+ | `buildSubject` | function | `(entities: readonly Entity[], mappings: readonly EntityMapping[]) => Subject` | Builds a subject from entities, each on the field it lands on. |
616
+ | `findEntityField` | function | `(entity: Entity, mappings: readonly EntityMapping[]) => FieldPath` | Finds the field an entity lands on. |
617
+ | `setField` | function | `(subject: Subject, field: FieldPath, value: unknown) => Subject` | Writes a value at a (possibly nested) field path on a subject, copy-on-write. |
618
+ | `applyReplacements` | function | `(text: string, map: Readonly<Record<string, string>>) => string` | Replaces every whole-word occurrence of a map's keys with their values. |
619
+ | `collapseWhitespace` | function | `(text: string) => string` | Collapses every run of whitespace to a single space and trims the ends. |
620
+ | `tokenize` | function | `(text: string) => readonly string[]` | Splits text into lowercase tokens, stripping punctuation outside a small numeric/currency-safe allowlist. |
621
+ | `extractNumbers` | function | `(text: string) => readonly number[]` | Mines every numeric literal from text — optional leading `$`, thousands commas, an optional decimal fraction, an optional trailing `%`. |
622
+ | `assignEntities` | function | `(numbers: readonly ReadNumber[], mappings: readonly EntityMapping[], text: string, shape: ContractShape) => readonly Entity[]` | Assigns exact reader occurrences to a matched recipe's entity mappings. |
623
+ | `classifyIntent` | function | `(text: string, actions: Readonly<Record<string, string>>, domains: Readonly<Record<string, readonly string[]>>) => Intent` | Classifies the action + domain intent of a text against caller-supplied vocabularies. |
624
+ | `canonicalize` | function | `(value: unknown) => string` | Renders a value into a canonical, key-order-stable string — the pre-image of `digestValue`. |
625
+ | `canonicalizeNode` | function | `(value: unknown, ancestors: ReadonlySet<object>) => string` | Renders one node of a value into its canonical, key-order-stable string, against the object ancestors already on the recursion path. |
626
+ | `digestValue` | function | `(value: unknown) => string` | Computes a canonical structural digest of a pure-JSON value — a key-order-stable FNV-1a hash rendered as an 8-hex-digit string. |
627
+ | `scoreRecipe` | function | `(intent: Intent, recipe: Recipe) => number` | Scores how well a classified intent matches one recipe's domain + action. |
628
+ | `matchRecipe` | function | `(intent: Intent, recipes: readonly Recipe[], floor: number) => Recipe \| undefined` | Finds the best-scoring added recipe for a classified intent, gated by a confidence floor. |
629
+ | `variablesOf` | function | `(expression: SymbolicExpression) => readonly string[]` | Collects every variable name referenced by a symbolic expression tree, in first-occurrence order. |
630
+ | `resolveExpression` | function | `(expression: SymbolicExpression, bindings: Readonly<Record<string, number>>) => number \| undefined` | Evaluates a symbolic expression tree against resolved bindings. |
631
+ | `renderSubject` | function | `(subject: Subject, narrator: NarratorInterface) => string` | Renders a one-line, display-neutral description of a reasons `Subject`, through an injected `Narrator`. |
317
632
 
318
633
  ```ts
319
634
  import { applyReplacements, collapseWhitespace, setField, tokenize } from '@orkestrel/interpret'
@@ -325,33 +640,29 @@ collapseWhitespace(' a b\t c ') // 'a b c'
325
640
  tokenize('The rate is 85%.') // ['the', 'rate', 'is', '85%.']
326
641
  ```
327
642
 
328
- Extraction, classification, and fuzzy matching — the leaves behind
643
+ Extraction, classification, and assignment — the leaves behind
329
644
  `Extractor#extract` and recipe entity assignment:
330
645
 
331
646
  ```ts
332
- import {
333
- assignEntities,
334
- classifyIntent,
335
- extractNumbers,
336
- matchAlias,
337
- scoreSimilarity,
338
- } from '@orkestrel/interpret'
647
+ import { numberShape, objectShape } from '@orkestrel/contract'
648
+ import { assignEntities, classifyIntent, extractNumbers, scanNumbers } from '@orkestrel/interpret'
339
649
 
340
650
  extractNumbers('income was $50,000, age 25') // [50000, 25]
341
651
  const mappings = [
342
652
  { entity: 'age', aliases: ['years old'], field: 'age' },
343
653
  { entity: 'score', aliases: ['credit score'], field: 'score' },
344
654
  ]
345
- assignEntities([25, 720], mappings, '25 year old with score 720', 0.8)
655
+ const shape = objectShape({ age: numberShape(), score: numberShape() })
656
+ assignEntities(scanNumbers('age 25 with score 720'), mappings, 'age 25 with score 720', shape)
657
+ // Both values are assigned; `with` keeps age because the declared score anchor follows it.
346
658
  classifyIntent('calculate my rate', { calculate: 'compute' }, { rating: ['rate'] })
347
- scoreSimilarity('rate', 'rate') // 1
348
- matchAlias('valu', ['value', 'amount'], 0.6) // ~0.86 — fuzzy hit on 'value'
349
659
  ```
350
660
 
351
661
  Digest, recipe matching, computed-field resolution, and the reverse
352
662
  direction:
353
663
 
354
664
  ```ts
665
+ import { objectShape } from '@orkestrel/contract'
355
666
  import type { Recipe } from '@orkestrel/interpret'
356
667
  import {
357
668
  canonicalize,
@@ -393,7 +704,7 @@ const recipe: Recipe = {
393
704
  domain: 'rating',
394
705
  intents: ['compute'],
395
706
  mappings: [],
396
- defaults: [],
707
+ shape: objectShape({}),
397
708
  computations: [],
398
709
  definition: { reasoning: 'symbolic', id: 't1', name: 'T', equations: [], variables: {} },
399
710
  }
@@ -418,21 +729,22 @@ parseRecipe('not json') // undefined
418
729
 
419
730
  ### Factories
420
731
 
421
- | Name | Kind | Signature | Summary |
422
- | ------------------------- | -------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
423
- | `createInterpret` | function | `(options?: InterpretOptions) => InterpretInterface` | Creates an interpretation orchestrator, returning an `InterpretInterface` seeded from `InterpretOptions`. |
424
- | `createNormalizer` | function | `(options?: NormalizerOptions) => NormalizerInterface` | Creates a text normalizer, returning a stateless `NormalizerInterface`. |
425
- | `createExtractor` | function | `(options?: ExtractorOptions) => ExtractorInterface` | Creates a recipe-agnostic intent classifier and number extractor, returning a stateless `ExtractorInterface`. |
426
- | `createClarifier` | function | `(options?: ClarifierOptions) => ClarifierInterface` | Creates a clarifier — carry-over, defaults, and computed-field resolution against an assigned entity set — returning a stateless `ClarifierInterface`. |
427
- | `createFormatter` | function | `(options?: FormatterOptions) => FormatterInterface` | Creates a prompt formatter, returning a stateless `FormatterInterface`. |
428
- | `createGenerator` | function | `() => GeneratorInterface` | Creates a subject and definition generator, returning a stateless `GeneratorInterface`. |
429
- | `createRecipeManager` | function | `(options?: RecipeManagerOptions) => RecipeManagerInterface` | Creates a recipe registry, returning a working `RecipeManagerInterface`. |
430
- | `createSubjectManager` | function | `(options?: SubjectManagerOptions) => SubjectManagerInterface` | Creates a subject registry, returning a working `SubjectManagerInterface`. |
431
- | `createDefinitionManager` | function | `(options?: DefinitionManagerOptions) => DefinitionManagerInterface` | Creates a definition registry, returning a working `DefinitionManagerInterface`. |
432
- | `createInterpretContext` | function | `(options?: InterpretContextOptions) => InterpretContextInterface` | Creates a cross-turn interpretation context, returning a working `InterpretContextInterface`. |
433
- | `createNarrator` | function | `(options?: NarratorOptions) => NarratorInterface` | Creates a lexicon-driven reverse-direction rendering engine, returning a stateless `NarratorInterface`. |
732
+ | Name | Kind | Signature | Summary |
733
+ | ------------------------- | -------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
734
+ | `createInterpret` | function | `(options?: InterpretOptions) => InterpretInterface` | Creates an interpretation orchestrator, returning an `InterpretInterface` seeded from `InterpretOptions`. |
735
+ | `createNormalizer` | function | `(options?: NormalizerOptions) => NormalizerInterface` | Creates a text normalizer, returning a stateless `NormalizerInterface`. |
736
+ | `createExtractor` | function | `(options?: ExtractorOptions) => ExtractorInterface` | Creates a recipe-agnostic intent classifier and number extractor, returning a stateless `ExtractorInterface`. |
737
+ | `createClarifier` | function | `(options?: ClarifierOptions) => ClarifierInterface` | Creates a clarifier — carry-over, computed-field resolution, and the door's reading of the recipe's shape against an assigned entity set — returning a `ClarifierInterface`. |
738
+ | `createFormatter` | function | `(options?: FormatterOptions) => FormatterInterface` | Creates a prompt formatter, returning a stateless `FormatterInterface`. |
739
+ | `createGenerator` | function | `() => GeneratorInterface` | Creates a subject and definition generator, returning a stateless `GeneratorInterface`. |
740
+ | `createRecipeManager` | function | `(options?: RecipeManagerOptions) => RecipeManagerInterface` | Creates a recipe registry, returning a working `RecipeManagerInterface`. |
741
+ | `createSubjectManager` | function | `(options?: SubjectManagerOptions) => SubjectManagerInterface` | Creates a subject registry, returning a working `SubjectManagerInterface`. |
742
+ | `createDefinitionManager` | function | `(options?: DefinitionManagerOptions) => DefinitionManagerInterface` | Creates a definition registry, returning a working `DefinitionManagerInterface`. |
743
+ | `createInterpretContext` | function | `(options?: InterpretContextOptions) => InterpretContextInterface` | Creates a cross-turn interpretation context, returning a working `InterpretContextInterface`. |
744
+ | `createNarrator` | function | `(options?: NarratorOptions) => NarratorInterface` | Creates a lexicon-driven reverse-direction rendering engine, returning a stateless `NarratorInterface`. |
434
745
 
435
746
  ```ts
747
+ import { numberShape, objectShape } from '@orkestrel/contract'
436
748
  import {
437
749
  createClarifier,
438
750
  createDefinitionManager,
@@ -471,7 +783,7 @@ const recipes = createRecipeManager({
471
783
  domain: 'arithmetic',
472
784
  intents: ['calculate'],
473
785
  mappings: [{ entity: 'value', aliases: [], field: 'value' }],
474
- defaults: [],
786
+ shape: objectShape({ value: numberShape() }),
475
787
  computations: [],
476
788
  definition: createQuantitativeDefinition('t1', 'Arithmetic', [
477
789
  createFactorGroup('total', 'sum', [createFieldFactor('value', 'value')]),
@@ -492,6 +804,34 @@ createDefinitionManager({
492
804
  }).count // 1
493
805
  ```
494
806
 
807
+ ### Shapes
808
+
809
+ The definition and result as `ContractShape` values.
810
+
811
+ | Name | Kind | Signature | Summary |
812
+ | --------------------- | -------- | --------------------- | ----------------------------------------------------- |
813
+ | `readNumberShape` | const | `ContractShape` | Describes a number `scanNumbers` read. |
814
+ | `interpretationShape` | const | `ContractShape` | Describes an `Interpretation` in its JSON projection. |
815
+ | `stageFailureShape` | const | `ContractShape` | Describes a `StageFailure`. |
816
+ | `stageRecordShape` | const | `ContractShape` | Describes a `StageRecord` in its JSON projection. |
817
+ | `fieldMappingShape` | const | `ContractShape` | Describes a `FieldMapping` in its JSON projection. |
818
+ | `ambiguityShape` | const | `ContractShape` | Describes an `Ambiguity`. |
819
+ | `entityShape` | const | `ContractShape` | Describes an `Entity` in its JSON projection. |
820
+ | `intentShape` | const | `ContractShape` | Describes an `Intent`. |
821
+ | `provenanceShape` | const | `ContractShape` | Describes a `Provenance`. |
822
+ | `createRecipeShape` | function | `() => ContractShape` | Creates the shape of a `Recipe`. |
823
+ | `entityMappingShape` | const | `ContractShape` | Describes an `EntityMapping`. |
824
+
825
+ ### Contracts
826
+
827
+ The compiled contract of what is flat enough to compile at import.
828
+
829
+ | Name | Kind | Signature | Summary |
830
+ | ------------------------ | -------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------- |
831
+ | `readNumbersContract` | const | `ContractInterface<unknown>` | Publishes what `scanNumbers` returns as a contract. |
832
+ | `interpretationContract` | const | `ContractInterface<unknown>` | Publishes an `Interpretation`'s JSON projection as a contract, read through `projectInterpretation`. |
833
+ | `createRecipeContract` | function | `() => ContractInterface<unknown>` | Creates a `Recipe` as a contract. Cross it on `is`, never `parse`. |
834
+
495
835
  ### Classes
496
836
 
497
837
  | Name | Kind | Signature | Summary |
@@ -499,8 +839,8 @@ createDefinitionManager({
499
839
  | `Interpret` | class | `new (options?: InterpretOptions) => InterpretInterface` | Implements the interpretation orchestrator — the sole public entry point of the `interprets` module, mirroring the reasons `Reason` orchestrator shape: it runs the `[normalize, extract, clarify, format, generate]` pipeline, owns the recipe registry and the context, and exposes the reverse direction. |
500
840
  | `Narrator` | class | `new (options?: NarratorOptions) => NarratorInterface` | Implements a stateless, total, lexicon-driven rendering engine for the reverse direction — the reverse-direction mirror of the forward `Formatter`'s `verbs` seam, supplying mechanism rather than wording policy. |
501
841
  | `Normalizer` | class | `new (options?: NormalizerOptions) => NormalizerInterface` | Implements the normalize stage: applies contraction, abbreviation, and correction substitutions in order, then collapses whitespace. |
502
- | `Extractor` | class | `new (options?: ExtractorOptions) => ExtractorInterface` | Implements the extract stage: recipe-agnostic intent classification plus raw numeric-entity mining. |
503
- | `Clarifier` | class | `new (options?: ClarifierOptions) => ClarifierInterface` | Implements the clarify stage: resolves same-domain carry-over, recipe defaults, and declaratively computed fields against an already-assigned entity set, surfacing an `Ambiguity` for every required mapping that stays unresolved. |
842
+ | `Extractor` | class | `new (options?: ExtractorOptions) => ExtractorInterface` | Implements the extract stage: recipe-agnostic intent classification plus exact reader values. |
843
+ | `Clarifier` | class | `new (options?: ClarifierOptions) => ClarifierInterface` | Implements the clarify stage: resolves same-domain carry-over and declaratively computed fields against an already-assigned entity set, admits the subject they build through the recipe's shape, and surfaces an `Ambiguity` for everything the door refused. |
504
844
  | `Formatter` | class | `new (options?: FormatterOptions) => FormatterInterface` | Implements the format stage: renders the refined natural-language prompt for a matched recipe. |
505
845
  | `Generator` | class | `new () => GeneratorInterface` | Implements the generate stage: builds the final `Subject` from a fully resolved entity set, plus its complete field audit. |
506
846
  | `RecordManager` | class | `new <TValue, TRecord extends RecordStamp>(options: RecordManagerOptions) => RecordManagerInterface<TValue, TRecord>` | Implements the shared registry engine behind every record manager in this module — it owns the `Map`, the content-hash and version rule, the batch `remove` overloads, and teardown. |
@@ -534,9 +874,9 @@ normalizer.normalize("can't stop") // { text: 'cannot stop', changes: [{ from:
534
874
 
535
875
  #### `ExtractorInterface`
536
876
 
537
- | Method | Returns | Summary |
538
- | --------- | --------------- | -------------------------------------------------------------------- |
539
- | `extract` | `ExtractResult` | Classifies the intent and mines every numeric literal from the text. |
877
+ | Method | Returns | Summary |
878
+ | --------- | --------------- | ---------------------------------------------------------------------- |
879
+ | `extract` | `ExtractResult` | Classifies the intent and returns exact values from the number reader. |
540
880
 
541
881
  ```ts
542
882
  import { createExtractor } from '@orkestrel/interpret'
@@ -551,11 +891,12 @@ extractor.extract('calculate my rate at 85')
551
891
 
552
892
  #### `ClarifierInterface`
553
893
 
554
- | Method | Returns | Summary |
555
- | --------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
556
- | `clarify` | `ClarifyResult` | Resolves carry-over, recipe defaults, and computed fields, and surfaces an `Ambiguity` for every unresolved required field, worded through the narrator's `ambiguity.entity` line. |
894
+ | Method | Returns | Summary |
895
+ | --------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
896
+ | `clarify` | `ClarifyResult` | Resolves carry-over and computed fields, admits the result through the recipe's shape, and surfaces an `Ambiguity` for everything the door refused, every value read below the floor, and every mapped field left to a default or a prior turn while a number nobody claimed could be its value, with its question from the shape's `description` or the narrator's `ambiguity.entity` line. |
557
897
 
558
898
  ```ts
899
+ import { numberShape, objectShape } from '@orkestrel/contract'
559
900
  import { createClarifier } from '@orkestrel/interpret'
560
901
 
561
902
  const clarifier = createClarifier({ floor: 0.3 })
@@ -566,8 +907,8 @@ clarifier.clarify(
566
907
  name: 'Arithmetic',
567
908
  domain: 'arithmetic',
568
909
  intents: ['calculate'],
569
- mappings: [{ entity: 'value', aliases: [], field: 'value', required: true }],
570
- defaults: [],
910
+ mappings: [{ entity: 'value', aliases: [], field: 'value' }],
911
+ shape: objectShape({ value: numberShape() }),
571
912
  computations: [],
572
913
  definition: {
573
914
  reasoning: 'symbolic',
@@ -587,6 +928,7 @@ A computation addresses one numeric element of an array-valued field as
587
928
  aggregate over it:
588
929
 
589
930
  ```ts
931
+ import { arrayShape, numberShape, objectShape } from '@orkestrel/contract'
590
932
  import { createClarifier } from '@orkestrel/interpret'
591
933
  import { createOperation, createVariable } from '@orkestrel/reason'
592
934
 
@@ -604,7 +946,7 @@ clarifier.clarify(
604
946
  domain: 'arithmetic',
605
947
  intents: ['calculate'],
606
948
  mappings: [{ entity: 'value', aliases: [], field: 'value' }],
607
- defaults: [],
949
+ shape: objectShape({ value: arrayShape(numberShape()), total: numberShape() }),
608
950
  computations: [
609
951
  {
610
952
  field: 'total',
@@ -626,11 +968,16 @@ clarifier.clarify(
626
968
 
627
969
  #### `FormatterInterface`
628
970
 
971
+ Primitive strings retain their text. Other values use the contract package's total
972
+ `preview` renderer. Objects and arrays, including the door's null-prototype defaults,
973
+ render as `object` and `array` without coercion or traversal.
974
+
629
975
  | Method | Returns | Summary |
630
976
  | -------- | -------------- | --------------------------------------------------------------------------------------------------------------------------- |
631
977
  | `format` | `FormatResult` | Renders the refined natural-language prompt for a matched recipe, clause by clause through the narrator's `prompt.*` lines. |
632
978
 
633
979
  ```ts
980
+ import { objectShape } from '@orkestrel/contract'
634
981
  import { createFormatter } from '@orkestrel/interpret'
635
982
 
636
983
  const formatter = createFormatter({ verbs: { calculate: 'Calculate' } })
@@ -642,7 +989,7 @@ formatter.format(
642
989
  domain: 'arithmetic',
643
990
  intents: ['calculate'],
644
991
  mappings: [],
645
- defaults: [],
992
+ shape: objectShape({}),
646
993
  computations: [],
647
994
  definition: {
648
995
  reasoning: 'symbolic',
@@ -664,6 +1011,7 @@ formatter.format(
664
1011
  | `generate` | `GenerateResult` | Builds the final subject and definition pair plus its complete field audit, deriving no field the recipe did not declare. |
665
1012
 
666
1013
  ```ts
1014
+ import { numberShape, objectShape } from '@orkestrel/contract'
667
1015
  import { createGenerator } from '@orkestrel/interpret'
668
1016
 
669
1017
  const generator = createGenerator()
@@ -682,7 +1030,7 @@ generator.generate(
682
1030
  domain: 'arithmetic',
683
1031
  intents: ['calculate'],
684
1032
  mappings: [{ entity: 'value', aliases: [], field: 'value' }],
685
- defaults: [],
1033
+ shape: objectShape({ value: numberShape() }),
686
1034
  computations: [],
687
1035
  definition: {
688
1036
  reasoning: 'symbolic',
@@ -793,6 +1141,7 @@ all-or-nothing. A call after `destroy()` throws `InterpretError('DESTROYED', …
793
1141
  | `destroy` | `void` | Tears the recipe registry down idempotently — clears the collection, emits `destroy`, then destroys the emitter last. |
794
1142
 
795
1143
  ```ts
1144
+ import { objectShape } from '@orkestrel/contract'
796
1145
  import { createRecipeManager } from '@orkestrel/interpret'
797
1146
  import {
798
1147
  createFactorGroup,
@@ -807,7 +1156,7 @@ const record = recipes.add({
807
1156
  domain: 'arithmetic',
808
1157
  intents: ['calculate'],
809
1158
  mappings: [],
810
- defaults: [],
1159
+ shape: objectShape({}),
811
1160
  computations: [],
812
1161
  definition: createQuantitativeDefinition('t1', 'Arithmetic', [
813
1162
  createFactorGroup('total', 'sum', [createFieldFactor('value', 'value')]),
@@ -889,7 +1238,7 @@ definitions.destroy()
889
1238
  #### `InterpretContextInterface`
890
1239
 
891
1240
  `previous()` returns the ring buffer newest-last, capped at the configured
892
- `history`. `entities()` flattens every entity across the buffered history,
1241
+ `history` (default 0). `entities()` flattens every entity across the buffered history,
893
1242
  most recent last. `clear()` resets the history, the subject registry, and the
894
1243
  definition registry without tearing the context down.
895
1244
 
@@ -948,6 +1297,7 @@ subscribes to its emitter.
948
1297
  | `destroy` | `void` | Tears the orchestrator down idempotently — the recipe registry, the context it constructed itself, then the emitter last. |
949
1298
 
950
1299
  ```ts
1300
+ import { numberShape, objectShape } from '@orkestrel/contract'
951
1301
  import { createExtractor, createInterpret } from '@orkestrel/interpret'
952
1302
  import {
953
1303
  createFactorGroup,
@@ -967,13 +1317,13 @@ interpret.add({
967
1317
  domain: 'arithmetic',
968
1318
  intents: ['calculate'],
969
1319
  mappings: [{ entity: 'value', aliases: [], field: 'value' }],
970
- defaults: [],
1320
+ shape: objectShape({ value: numberShape() }),
971
1321
  computations: [],
972
1322
  definition: createQuantitativeDefinition('t1', 'Arithmetic', [
973
1323
  createFactorGroup('total', 'sum', [createFieldFactor('value', 'value')]),
974
1324
  ]),
975
1325
  })
976
- const result = interpret.interpret('calculate arithmetic 42')
1326
+ const result = interpret.interpret('calculate arithmetic value 42')
977
1327
  result.subject // { value: 42 }
978
1328
  interpret.recipe('t1') // the plain Recipe data
979
1329
  interpret.recipes() // every added recipe
@@ -990,6 +1340,32 @@ interpret.remove('t1') // true
990
1340
  interpret.destroy()
991
1341
  ```
992
1342
 
1343
+ ## Migration: text length is bounded
1344
+
1345
+ `INTERPRET_TEXT_LIMIT` is 65,536 UTF-16 units, measured by the raw string's `length`.
1346
+ The built-in `Normalizer.normalize` throws `InterpretError('TEXT_LIMIT')` above that
1347
+ limit, before substitutions or whitespace cleanup. `scanNumbers` and direct
1348
+ `Extractor.extract` calls meet the same limit. There is no option to raise it.
1349
+ Custom normalizer implementations must honor the same input bound.
1350
+
1351
+ `Interpret.interpret` captures this refusal as a `TEXT_LIMIT` stage failure, emits the
1352
+ original error, and returns an incomplete interpretation with no subject. A direct stage
1353
+ caller catches the coded error. Callers that previously sent larger messages must shorten
1354
+ them or divide them into independently meaningful requests before calling the reader.
1355
+
1356
+ ## Migration: carrying is opt-in
1357
+
1358
+ A reused `Interpret` no longer carries values between messages by default.
1359
+ `DEFAULT_INTERPRET_HISTORY` is 0. This prevents one person's unstated fields
1360
+ from being filled by another person's earlier request.
1361
+
1362
+ For turns belonging to one person, set `history: 16` on `createInterpret` or
1363
+ `Interpret` to retain the previous window. When supplying a shared `context`,
1364
+ set `history` on that context instead. Any positive cap enables history;
1365
+ there is no minimum of three. With the default, `previous()` and `entities()`
1366
+ are empty even after a result is added. Subject and definition registries
1367
+ remain separate and are still populated for generated results.
1368
+
993
1369
  ## Tests
994
1370
 
995
1371
  - [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` bijection (value and type exports), each behavioral interface ↔ its implementing class method bijection, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Interpret text against an added recipe` fence against the `@example` block of that title (pinned so the titled pair cannot be retired silently), and the README pitch against this guide's tagline. It also runs the flagship fences and asserts the values their comments claim.
@@ -997,12 +1373,12 @@ interpret.destroy()
997
1373
  - [`tests/src/core/InterpretContext.test.ts`](../tests/src/core/InterpretContext.test.ts) — the capped ring buffer, the flattened entity read carry-over consults, `clear` against `destroy`, and the emitted events.
998
1374
  - [`tests/src/core/Narrator.test.ts`](../tests/src/core/Narrator.test.ts) — every lookup total against an adversarial key, the documented fallback of each primitive, and the composed `describe` and `narrate` renderings.
999
1375
  - [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — each factory returns a working entity, and honors the options it declares.
1000
- - [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — the pure leaves: escaping, copy-on-write field writes and their prototype-pollution refusal, replacement and whitespace collapse, tokenizing, numeric mining, entity assignment, intent classification, similarity and alias matching, canonicalization and digesting, recipe scoring and matching, expression variables and resolution, and subject rendering.
1376
+ - [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — the pure leaves: escaping, copy-on-write field writes and their prototype-pollution refusal, replacement and whitespace collapse, tokenizing, numeric mining, entity assignment, intent classification, canonicalization and digesting, recipe scoring and matching, expression variables and resolution, and subject rendering.
1001
1377
  - [`tests/src/core/parsers.test.ts`](../tests/src/core/parsers.test.ts) — `parseRecipe` returns a recipe, or `undefined` on invalid JSON and on a shape that fails `isRecipe`.
1002
1378
  - [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) — every guard stays total against junk, cycles, and hostile prototypes, with the exact posture for an input record and the open posture for a result record.
1003
1379
  - [`tests/src/core/stages/Normalizer.test.ts`](../tests/src/core/stages/Normalizer.test.ts) — the substitution order, the recorded changes, and the final whitespace collapse.
1004
1380
  - [`tests/src/core/stages/Extractor.test.ts`](../tests/src/core/stages/Extractor.test.ts) — intent classification against caller vocabularies, and numeric mining, with no recipe in sight.
1005
- - [`tests/src/core/stages/Clarifier.test.ts`](../tests/src/core/stages/Clarifier.test.ts) — resolution order across fresh entities, same-domain carry-over, defaults, and dependency-ordered computed fields, plus the ambiguity every unresolved required mapping raises.
1381
+ - [`tests/src/core/stages/Clarifier.test.ts`](../tests/src/core/stages/Clarifier.test.ts) — resolution order across fresh entities, same-domain carry-over, what the door fills, repairs, and refuses, and dependency-ordered computed fields, plus the ambiguity every refusal and every below-floor required mapping raises.
1006
1382
  - [`tests/src/core/stages/Formatter.test.ts`](../tests/src/core/stages/Formatter.test.ts) — the clause assembly through the narrator's `prompt.*` lines, and the verb fallback.
1007
1383
  - [`tests/src/core/stages/Generator.test.ts`](../tests/src/core/stages/Generator.test.ts) — the entity-to-field rule, the single-element unwrap, the mean confidence, and the field audit.
1008
1384
  - [`tests/src/core/managers/RecordManager.test.ts`](../tests/src/core/managers/RecordManager.test.ts) — the content hash and version rule, the all-or-nothing batch `remove`, the emitted events, and idempotent teardown.