@orkestrel/scaffold 0.0.120 → 0.0.121

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/dist/bin/main.js +5 -5
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/claude/agents/orkestrel.md +26 -26
  4. package/dist/host/guides/agent.md +5 -5
  5. package/dist/host/guides/brief.md +7 -15
  6. package/dist/host/guides/browser.md +1 -1
  7. package/dist/host/guides/capture.md +2 -2
  8. package/dist/host/guides/console.md +4 -30
  9. package/dist/host/guides/guide.md +0 -1
  10. package/dist/host/guides/interpret.md +165 -182
  11. package/dist/host/guides/lsp.md +26 -51
  12. package/dist/host/guides/mcp.md +220 -276
  13. package/dist/host/guides/middleware.md +14 -22
  14. package/dist/host/guides/ollama.md +1 -3
  15. package/dist/host/guides/probe.md +71 -80
  16. package/dist/host/guides/program.md +26 -35
  17. package/dist/host/guides/qualifier.md +0 -6
  18. package/dist/host/guides/queue.md +0 -4
  19. package/dist/host/guides/rater.md +6 -12
  20. package/dist/host/guides/relation.md +0 -2
  21. package/dist/host/guides/scaffold.md +12 -8
  22. package/dist/host/guides/sea.md +47 -51
  23. package/dist/host/guides/server.md +15 -19
  24. package/dist/host/guides/terminal.md +0 -26
  25. package/dist/host/guides/toolbox.md +0 -10
  26. package/dist/host/guides/worker.md +57 -57
  27. package/dist/host/guides/workflow.md +13 -26
  28. package/dist/host/guides/workspace.md +15 -21
  29. package/dist/host/manifest.json +28 -448
  30. package/dist/src/core/index.cjs +7 -45
  31. package/dist/src/core/index.cjs.map +1 -1
  32. package/dist/src/core/index.js +7 -45
  33. package/dist/src/core/index.js.map +1 -1
  34. package/dist/src/server/index.cjs +10 -9
  35. package/dist/src/server/index.cjs.map +1 -1
  36. package/dist/src/server/index.d.cts +12 -8
  37. package/dist/src/server/index.d.ts +12 -8
  38. package/dist/src/server/index.js +10 -9
  39. package/dist/src/server/index.js.map +1 -1
  40. package/package.json +5 -5
@@ -2,7 +2,7 @@
2
2
 
3
3
  > A synchronous, deterministic bidirectional bridge between natural language and the
4
4
  > `@orkestrel/reason` engine: a forward pipeline that normalizes raw text, classifies its
5
- > intent, matches an added `Template`, clarifies the fields extraction left open, and
5
+ > intent, matches an added `Recipe`, clarifies the fields extraction left open, and
6
6
  > generates a `Subject` and `Definition` pair ready for `Reason.reason`, plus a reverse
7
7
  > direction that renders a `Definition`, a `Subject`, or a `ReasonResult` to
8
8
  > display-neutral prose through a lexicon-driven `Narrator`.
@@ -11,7 +11,7 @@ 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
- template and mines the raw numbers; `clarify` resolves same-domain carry-over, template
14
+ recipe and mines the raw numbers; `clarify` resolves same-domain carry-over, recipe
15
15
  defaults, and dependency-ordered computed fields. Every discriminant names its axis rather
16
16
  than `kind` or `type`: `stage` splits the pipeline phases, `category` splits provenance, and
17
17
  `code` splits coded errors. Source: [`src/core`](../src/core). Surfaced through the
@@ -19,9 +19,9 @@ than `kind` or `type`: `stage` splits the pipeline phases, `category` splits pro
19
19
 
20
20
  ## Surface
21
21
 
22
- ### Interpret text against an added template
22
+ ### Interpret text against an added recipe
23
23
 
24
- Add a template, interpret text through the normalize, extract, clarify, format, and generate
24
+ Add a recipe, interpret text through the normalize, extract, clarify, format, and generate
25
25
  pipeline, then render the result back to prose:
26
26
 
27
27
  ```ts
@@ -37,7 +37,7 @@ const interpret = createInterpret({
37
37
  actions: { calculate: 'calculate' },
38
38
  domains: { arithmetic: ['arithmetic'] },
39
39
  }),
40
- templates: [
40
+ recipes: [
41
41
  {
42
42
  id: 't1',
43
43
  name: 'Arithmetic',
@@ -64,84 +64,80 @@ interpret.destroy()
64
64
  ```
65
65
 
66
66
  `interpret()` is genuinely synchronous and runs the fixed pipeline
67
- `[normalize, extract, clarify, format, generate]`. A `NO_TEMPLATE` or `LOW_CONFIDENCE`
67
+ `[normalize, extract, clarify, format, generate]`. A `NO_RECIPE` or `LOW_CONFIDENCE`
68
68
  non-match, and a thrown stage, each yield a visible incomplete `Interpretation` rather than
69
- throwing, and never an arbitrary fallback template. An interpretation is complete when
69
+ throwing, and never an arbitrary fallback recipe. An interpretation is complete when
70
70
  `ambiguities` and `failures` are both empty; no stored flag repeats that fact.
71
71
 
72
72
  ### Types
73
73
 
74
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
75
-
76
- | Name | Kind | Signature | Summary |
77
- | ---------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
78
- | `ProvenanceCategory` | type | `'extracted' \| 'carried' \| 'default' \| 'computed' \| 'subject'` | Names how one `FieldMapping` or `Entity` value was obtained. |
79
- | `InterpretStage` | type | `'normalize' \| 'extract' \| 'clarify' \| 'format' \| 'generate'` | Names the fixed pipeline phases an `InterpretInterface#interpret` run produces one `StageRecord` for, in order. |
80
- | `InterpretErrorCode` | type | `'NORMALIZE_FAILED' \| 'EXTRACT_FAILED' \| 'CLARIFY_FAILED' \| 'FORMAT_FAILED' \| 'GENERATE_FAILED' \| 'NO_TEMPLATE' \| 'LOW_CONFIDENCE' \| 'DESTROYED'` | Names the coded misuse or failure conditions thrown as an `InterpretError` or carried on a `StageFailure`. |
81
- | `EntityMapping` | interface | `{ entity, aliases, field, required? }` | Represents one entity-extraction rule inside a `Template`: which literal alias phrases identify a value, and which subject field it lands on. |
82
- | `FieldDefault` | interface | `{ field, value }` | Represents a fallback value a `Template` fills onto a field left unresolved by extraction. |
83
- | `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`. |
84
- | `Template` | interface | `{ id, name, domain, intents, mappings, defaults, computations, definition }` | Represents a named, versionable interpretation template: 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. |
85
- | `Provenance` | interface | `{ category, detail? }` | Describes how one value landed — its origin category plus an optional strategy detail. |
86
- | `Intent` | interface | `{ action?, domain?, confidence }` | Represents the classified action + domain for one interpretation, with a combined confidence. |
87
- | `Entity` | interface | `{ name, value, provenance, confidence }` | Represents one value assigned to a template's entity mapping, with its provenance and confidence. |
88
- | `Ambiguity` | interface | `{ field, question, candidates, required }` | Represents an unresolved field surfaced as a human-readable question, never bare prose. |
89
- | `FieldMapping` | interface | `{ field, entity?, value, provenance, confidence }` | Represents one audited field of the built subject — its resolved value, provenance, and confidence. |
90
- | `TextChange` | interface | `{ from, to }` | Represents one normalization substitution applied to the raw text. |
91
- | `StageRecord` | interface | `{ stage, input, output, failed, error? }` | Represents a structured input/output snapshot of one pipeline phase. |
92
- | `StageFailure` | interface | `{ stage, code, message }` | Represents a visible marker for a stage that threw, carrying its coded reason. |
93
- | `NormalizeResult` | interface | `{ text, changes }` | Represents the `Normalizer` stage's output: the cleaned text plus every substitution applied. |
94
- | `ExtractResult` | interface | `{ intent, numbers }` | Represents the `Extractor` stage's output: intent classification plus raw numbers. |
95
- | `ClarifyResult` | interface | `{ entities, ambiguities }` | Represents the `Clarifier` stage's output: resolved entities plus any remaining ambiguities. |
96
- | `FormatResult` | interface | `{ prompt }` | Represents the `Formatter` stage's output: the refined natural-language prompt. |
97
- | `GenerateResult` | interface | `{ subject, definition, mappings, confidence }` | Represents the `Generator` stage's output: the built subject/definition pair plus its full field audit. |
98
- | `Interpretation` | interface | `{ text, normalized, intent, entities, subject?, definition?, mappings, ambiguities, prompt, stages, failures, confidence, digest }` | Represents the full, replayable outcome of one `interpret()` call. |
99
- | `TemplateRecord` | interface | `{ id, template, version, hash }` | Represents a versioned, content-hashed `Template` as held by a `TemplateManagerInterface`. |
100
- | `SubjectRecord` | interface | `{ id, subject, version, hash }` | Represents a versioned, content-hashed `Subject` as held by a `SubjectManagerInterface`. |
101
- | `DefinitionRecord` | interface | `{ id, definition, version, hash }` | Represents a versioned, content-hashed `Definition` as held by a `DefinitionManagerInterface`. |
102
- | `InterpretEventMap` | type | `{ readonly interpret: readonly [result: Interpretation]; readonly add: readonly [templateId: string]; readonly error: readonly [error: unknown]; readonly destroy: readonly []; }` | Represents the push observation surface of an `InterpretInterface`. |
103
- | `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`). |
104
- | `TemplateManagerEventMap` | type | `RecordEventMap` | Represents the push observation surface of a `TemplateManagerInterface`. |
105
- | `SubjectManagerEventMap` | type | `RecordEventMap` | Represents the push observation surface of a `SubjectManagerInterface`, whose `add` carries the own-minted record id. |
106
- | `DefinitionManagerEventMap` | type | `RecordEventMap` | Represents the push observation surface of a `DefinitionManagerInterface`. |
107
- | `InterpretContextEventMap` | type | `{ readonly add: readonly [digest: string]; readonly clear: readonly []; readonly destroy: readonly []; }` | Represents the push observation surface of an `InterpretContextInterface`. |
108
- | `NarratorFormatter` | type | `(value: unknown) => string` | Represents a pure formatting function for one lexicon `value()` unit. |
109
- | `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. |
110
- | `NarratorOptions` | interface | `{ lexicon?, formatters? }` | Represents the options for `createNarrator` and the `Narrator` constructor. |
111
- | `NormalizerOptions` | interface | `{ contractions?, abbreviations?, corrections? }` | Represents the options for `createNormalizer` and the `Normalizer` constructor. |
112
- | `ExtractorOptions` | interface | `{ actions?, domains? }` | Represents the options for `createExtractor` and the `Extractor` constructor. |
113
- | `ClarifierOptions` | interface | `{ floor?, narrator? }` | Represents the options for `createClarifier` and the `Clarifier` constructor. |
114
- | `FormatterOptions` | interface | `{ verbs?, narrator? }` | Represents the options for `createFormatter` and the `Formatter` constructor. |
115
- | `TemplateManagerOptions` | interface | `{ templates?, on?, error? }` | Represents the options for `createTemplateManager` and the `TemplateManager` constructor — the initial seed collection. |
116
- | `SubjectManagerOptions` | interface | `{ subjects?, on?, error? }` | Represents the options for `createSubjectManager` and the `SubjectManager` constructor — the initial seed collection. |
117
- | `DefinitionManagerOptions` | interface | `{ definitions?, on?, error? }` | Represents the options for `createDefinitionManager` and the `DefinitionManager` constructor — the initial seed collection. |
118
- | `RecordStamp` | interface | `{ id, version, hash }` | Represents the identity, version, and content hash a `RecordManagerInterface` derives for one record before its concrete shape is built. |
119
- | `RecordFunction` | type | `(stamp: RecordStamp, value: TValue) => TRecord` | Builds one concrete record from the `RecordStamp` its registry derived and the value that record holds. |
120
- | `RecordManagerOptions` | interface | `{ entity, on?, error? }` | Represents the options for the `RecordManager` constructor. |
121
- | `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. |
122
- | `RecordOptions` | interface | `{ id? }` | Represents the per-call options for the record a manager's `add` mints. |
123
- | `InterpretContextOptions` | interface | `{ session?, history?, on?, error? }` | Represents the options for `createInterpretContext` and the `InterpretContext` constructor. |
124
- | `InterpretOptions` | interface | `{ templates?, context?, normalizer?, extractor?, clarifier?, formatter?, generator?, similarity?, floor?, history?, narrator?, on?, error? }` | Represents the options for `createInterpret` and the `Interpret` constructor. |
125
- | `NormalizerInterface` | interface | `{ normalize() }` | Represents the `Normalizer` stage contract: raw text in, cleaned text + applied changes out. |
126
- | `ExtractorInterface` | interface | `{ extract() }` | Represents the `Extractor` stage contract: template-agnostic intent classification + raw number mining. |
127
- | `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. |
128
- | `FormatterInterface` | interface | `{ format() }` | Represents the `Formatter` stage contract: render the refined natural-language prompt for a matched template. |
129
- | `GeneratorInterface` | interface | `{ generate() }` | Represents the `Generator` stage contract: build the final subject/definition pair plus its field audit. |
130
- | `NarratorInterface` | interface | `{ phrase(), label(), line(), value(), describe(), narrate() }` | Represents the `Narrator` contract — a stateless, total, lexicon-driven rendering engine for the reverse direction. |
131
- | `TemplateManagerInterface` | interface | `{ emitter, count, has(), template(), templates(), add(), remove(), destroy() }` | Represents the template registry — a self-owning, versioned/hashed record-holder with the singular/plural accessor pair and the batch `remove` overloads. |
132
- | `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). |
133
- | `DefinitionManagerInterface` | interface | `{ emitter, count, has(), definition(), definitions(), add(), remove(), destroy() }` | Represents the definition registry — a self-owning, versioned/hashed record-holder. |
134
- | `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. |
135
- | `InterpretInterface` | interface | `{ emitter, interpret(), add(), remove(), template(), templates(), describe(), narrate(), destroy() }` | Represents the interpretation orchestrator — the sole public entry point, mirroring `reasons`' `Reason` orchestrator shape. |
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. |
136
134
 
137
135
  ### Constants
138
136
 
139
- A `Shape` cell holds the constant's declared type.
140
-
141
137
  | Name | Kind | Signature | Summary |
142
138
  | ------------------------------ | ----- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
143
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. |
144
- | `DEFAULT_INTERPRET_FLOOR` | const | `0.3` | Names the default `floor` for `createInterpret` and `matchTemplate`, 0.3 — the minimum intent confidence a template match, or the classified intent itself, must clear. |
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. |
145
141
  | `DEFAULT_INTERPRET_HISTORY` | const | `16` | Names the default `history` cap for an `InterpretContext`'s `previous()` ring buffer, 16. |
146
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`. |
147
143
  | `INTERPRET_STAGES` | const | `readonly InterpretStage[]` | Lists every `InterpretStage` literal in pipeline order, frozen — the one home the result guards check the union from. |
@@ -151,10 +147,9 @@ A `Shape` cell holds the constant's declared type.
151
147
  | `CONFIDENCE_COLLECT` | const | `0.9` | Names the confidence assigned when a single entity mapping collects every extracted number, 0.9. |
152
148
  | `CONFIDENCE_POSITIONAL` | const | `0.7` | Names the confidence assigned to a positional (order-based) entity match fallback, 0.7. |
153
149
  | `CONFIDENCE_CARRIED` | const | `0.7` | Names the confidence assigned to a same-domain carried-over field, 0.7. |
154
- | `CONFIDENCE_DEFAULT` | const | `1` | Names the confidence assigned to a template default fill, 1. |
150
+ | `CONFIDENCE_DEFAULT` | const | `1` | Names the confidence assigned to a recipe default fill, 1. |
155
151
  | `CONFIDENCE_COMPUTED` | const | `0.9` | Names the confidence assigned to a successfully resolved computed field, 0.9. |
156
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 `%`. |
157
- | `UNSAFE_FIELD_SEGMENTS` | const | `readonly string[]` | Lists the prototype-pollution-unsafe field-path segments, `__proto__`, `prototype`, and `constructor` — `setField` refuses to write any path containing one, and returns its input unchanged. |
158
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. |
159
154
  | `DEFAULT_LEXICON` | const | `Lexicon` | Holds the neutral default `Lexicon` a `Narrator` merges caller data over. |
160
155
 
@@ -173,7 +168,6 @@ import {
173
168
  DEFAULT_INTERPRET_SIMILARITY,
174
169
  DEFAULT_LEXICON,
175
170
  NUMBER_PATTERN,
176
- UNSAFE_FIELD_SEGMENTS,
177
171
  } from '@orkestrel/interpret'
178
172
 
179
173
  DEFAULT_INTERPRET_SIMILARITY // 0.8
@@ -187,7 +181,6 @@ CONFIDENCE_CARRIED // 0.7
187
181
  CONFIDENCE_DEFAULT // 1
188
182
  CONFIDENCE_COMPUTED // 0.9
189
183
  NUMBER_PATTERN.source // the numeric-entity pattern
190
- UNSAFE_FIELD_SEGMENTS // ['__proto__', 'prototype', 'constructor']
191
184
  DEFAULT_CONTRACTIONS["can't"] // 'cannot'
192
185
  DEFAULT_LEXICON.templates?.['subject.empty'] // 'with no fields'
193
186
  DEFAULT_LEXICON.templates?.['prompt.base'] // '{{verb}} {{name}}'
@@ -224,14 +217,12 @@ published member conforms, because a foreign engine's return is not this package
224
217
  `interpret` return with `isInterpretation` before dereferencing `intent`, `entities`, or
225
218
  `ambiguities`. Each row's `Summary` names the posture its guard takes.
226
219
 
227
- In a guard table a `Shape` cell holds the type the guard narrows to.
228
-
229
220
  | Name | Kind | Signature | Summary |
230
221
  | ------------------ | -------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
231
222
  | `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. |
232
- | `isFieldDefault` | function | `(value: unknown) => value is FieldDefault` | Determines whether a value is an exact `FieldDefault` input record — a fallback value a `Template` fills onto an unresolved 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. |
233
224
  | `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. |
234
- | `isTemplate` | function | `(value: unknown) => value is Template` | Determines whether a value is an exact `Template` input record — a named, versionable interpretation template. |
225
+ | `isRecipe` | function | `(value: unknown) => value is Recipe` | Determines whether a value is an exact `Recipe` input record — a named, versionable interpretation recipe. |
235
226
  | `isProvenance` | function | `(value: unknown) => value is Provenance` | Determines whether a value is an open `Provenance` result record. |
236
227
  | `isIntent` | function | `(value: unknown) => value is Intent` | Determines whether a value is an open `Intent` result record. |
237
228
  | `isEntity` | function | `(value: unknown) => value is Entity` | Determines whether a value is an open `Entity` result record. |
@@ -255,7 +246,7 @@ import {
255
246
  isProvenance,
256
247
  isStageFailure,
257
248
  isStageRecord,
258
- isTemplate,
249
+ isRecipe,
259
250
  } from '@orkestrel/interpret'
260
251
  import {
261
252
  createFactorGroup,
@@ -274,7 +265,7 @@ isComputedField({
274
265
  right: { form: 'constant', value: 12 },
275
266
  },
276
267
  }) // true
277
- isTemplate({
268
+ isRecipe({
278
269
  id: 't1',
279
270
  name: 'Arithmetic',
280
271
  domain: 'arithmetic',
@@ -306,35 +297,27 @@ behind the `Interpret` orchestrator and its stages.
306
297
 
307
298
  | Name | Kind | Signature | Summary |
308
299
  | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
309
- | `escapeRegExp` | function | `(text: string) => string` | Escapes every regex metacharacter in `text` so it matches literally when compiled into a `RegExp`. |
310
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. |
311
301
  | `applyReplacements` | function | `(text: string, map: Readonly<Record<string, string>>) => string` | Replaces every whole-word occurrence of a map's keys with their values. |
312
302
  | `collapseWhitespace` | function | `(text: string) => string` | Collapses every run of whitespace to a single space and trims the ends. |
313
303
  | `tokenize` | function | `(text: string) => readonly string[]` | Splits text into lowercase tokens, stripping punctuation outside a small numeric/currency-safe allowlist. |
314
304
  | `extractNumbers` | function | `(text: string) => readonly number[]` | Mines every numeric literal from text — optional leading `$`, thousands commas, an optional decimal fraction, an optional trailing `%`. |
315
- | `assignEntities` | function | `(numbers: readonly number[], mappings: readonly EntityMapping[], text: string, similarity: number) => readonly Entity[]` | Assigns already-extracted numbers to a matched template's entity mappings. |
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. |
316
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. |
317
307
  | `scoreSimilarity` | function | `(a: string, b: string) => number` | Measures bigram (Dice coefficient) string similarity, case-insensitive. |
318
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. |
319
309
  | `canonicalize` | function | `(value: unknown) => string` | Renders a value into a canonical, key-order-stable string — the pre-image of `digestValue`. |
320
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. |
321
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. |
322
- | `scoreTemplate` | function | `(intent: Intent, template: Template) => number` | Scores how well a classified intent matches one template's domain + action. |
323
- | `matchTemplate` | function | `(intent: Intent, templates: readonly Template[], floor: number) => Template \| undefined` | Finds the best-scoring added template for a classified intent, gated by a confidence floor. |
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. |
324
314
  | `variablesOf` | function | `(expression: SymbolicExpression) => readonly string[]` | Collects every variable name referenced by a symbolic expression tree, in first-occurrence order. |
325
315
  | `resolveExpression` | function | `(expression: SymbolicExpression, bindings: Readonly<Record<string, number>>) => number \| undefined` | Evaluates a symbolic expression tree against resolved bindings. |
326
316
  | `renderSubject` | function | `(subject: Subject, narrator: NarratorInterface) => string` | Renders a one-line, display-neutral description of a reasons `Subject`, through an injected `Narrator`. |
327
317
 
328
318
  ```ts
329
- import {
330
- applyReplacements,
331
- collapseWhitespace,
332
- escapeRegExp,
333
- setField,
334
- tokenize,
335
- } from '@orkestrel/interpret'
319
+ import { applyReplacements, collapseWhitespace, setField, tokenize } from '@orkestrel/interpret'
336
320
 
337
- escapeRegExp('a.b*c') // 'a\\.b\\*c'
338
321
  setField({ age: 25 }, 'age', 30) // { age: 30 }
339
322
  setField({}, ['address', 'city'], 'Reno') // { address: { city: 'Reno' } }
340
323
  applyReplacements("can't stop", { "can't": 'cannot' }) // 'cannot stop'
@@ -343,7 +326,7 @@ tokenize('The rate is 85%.') // ['the', 'rate', 'is', '85%.']
343
326
  ```
344
327
 
345
328
  Extraction, classification, and fuzzy matching — the leaves behind
346
- `Extractor#extract` and template entity assignment:
329
+ `Extractor#extract` and recipe entity assignment:
347
330
 
348
331
  ```ts
349
332
  import {
@@ -365,27 +348,27 @@ scoreSimilarity('rate', 'rate') // 1
365
348
  matchAlias('valu', ['value', 'amount'], 0.6) // ~0.86 — fuzzy hit on 'value'
366
349
  ```
367
350
 
368
- Digest, template matching, computed-field resolution, and the reverse
351
+ Digest, recipe matching, computed-field resolution, and the reverse
369
352
  direction:
370
353
 
371
354
  ```ts
372
- import type { Template } from '@orkestrel/interpret'
355
+ import type { Recipe } from '@orkestrel/interpret'
373
356
  import {
374
357
  canonicalize,
375
358
  canonicalizeNode,
376
359
  createNarrator,
377
360
  digestValue,
378
- matchTemplate,
361
+ matchRecipe,
379
362
  renderSubject,
380
363
  resolveExpression,
381
- scoreTemplate,
364
+ scoreRecipe,
382
365
  variablesOf,
383
366
  } from '@orkestrel/interpret'
384
367
 
385
368
  canonicalize({ b: 1, a: 2 }) === canonicalize({ a: 2, b: 1 }) // true
386
369
  canonicalizeNode({ b: 1, a: 2 }, new Set()) // '{"a":2,"b":1}'
387
370
  digestValue({ a: 1 }) === digestValue({ a: 1 }) // true — deterministic
388
- matchTemplate({ confidence: 0 }, [], 0.3) // undefined — empty registry
371
+ matchRecipe({ confidence: 0 }, [], 0.3) // undefined — empty registry
389
372
  variablesOf({
390
373
  form: 'operation',
391
374
  operator: 'divide',
@@ -404,7 +387,7 @@ resolveExpression(
404
387
  renderSubject({ age: 25, income: 50000 }, createNarrator()) // 'with age: 25, income: 50000'
405
388
 
406
389
  const gate = { action: 'compute', domain: 'rating', confidence: 1 }
407
- const template: Template = {
390
+ const recipe: Recipe = {
408
391
  id: 't1',
409
392
  name: 'T',
410
393
  domain: 'rating',
@@ -414,23 +397,23 @@ const template: Template = {
414
397
  computations: [],
415
398
  definition: { reasoning: 'symbolic', id: 't1', name: 'T', equations: [], variables: {} },
416
399
  }
417
- scoreTemplate(gate, template) // 1
400
+ scoreRecipe(gate, recipe) // 1
418
401
  ```
419
402
 
420
403
  ### Parsers
421
404
 
422
405
  Coercers — each returns its type or `undefined` off-shape, and never throws.
423
- Template intake is total: an off-shape template returns `undefined`, and a
406
+ Recipe intake is total: an off-shape recipe returns `undefined`, and a
424
407
  caller who wants a throw raises its own error from that `undefined`.
425
408
 
426
- | Name | Kind | Signature | Summary |
427
- | --------------- | -------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
428
- | `parseTemplate` | function | `(value: string) => Template \| undefined` | Parses a JSON string into a `Template`, or `undefined` on invalid JSON or a shape that fails `isTemplate`. |
409
+ | Name | Kind | Signature | Summary |
410
+ | ------------- | -------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------ |
411
+ | `parseRecipe` | function | `(value: string) => Recipe \| undefined` | Parses a JSON string into a `Recipe`, or `undefined` on invalid JSON or a shape that fails `isRecipe`. |
429
412
 
430
413
  ```ts
431
- import { parseTemplate } from '@orkestrel/interpret'
414
+ import { parseRecipe } from '@orkestrel/interpret'
432
415
 
433
- parseTemplate('not json') // undefined
416
+ parseRecipe('not json') // undefined
434
417
  ```
435
418
 
436
419
  ### Factories
@@ -439,11 +422,11 @@ parseTemplate('not json') // undefined
439
422
  | ------------------------- | -------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
440
423
  | `createInterpret` | function | `(options?: InterpretOptions) => InterpretInterface` | Creates an interpretation orchestrator, returning an `InterpretInterface` seeded from `InterpretOptions`. |
441
424
  | `createNormalizer` | function | `(options?: NormalizerOptions) => NormalizerInterface` | Creates a text normalizer, returning a stateless `NormalizerInterface`. |
442
- | `createExtractor` | function | `(options?: ExtractorOptions) => ExtractorInterface` | Creates a template-agnostic intent classifier and number extractor, returning a stateless `ExtractorInterface`. |
425
+ | `createExtractor` | function | `(options?: ExtractorOptions) => ExtractorInterface` | Creates a recipe-agnostic intent classifier and number extractor, returning a stateless `ExtractorInterface`. |
443
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`. |
444
427
  | `createFormatter` | function | `(options?: FormatterOptions) => FormatterInterface` | Creates a prompt formatter, returning a stateless `FormatterInterface`. |
445
428
  | `createGenerator` | function | `() => GeneratorInterface` | Creates a subject and definition generator, returning a stateless `GeneratorInterface`. |
446
- | `createTemplateManager` | function | `(options?: TemplateManagerOptions) => TemplateManagerInterface` | Creates a template registry, returning a working `TemplateManagerInterface`. |
429
+ | `createRecipeManager` | function | `(options?: RecipeManagerOptions) => RecipeManagerInterface` | Creates a recipe registry, returning a working `RecipeManagerInterface`. |
447
430
  | `createSubjectManager` | function | `(options?: SubjectManagerOptions) => SubjectManagerInterface` | Creates a subject registry, returning a working `SubjectManagerInterface`. |
448
431
  | `createDefinitionManager` | function | `(options?: DefinitionManagerOptions) => DefinitionManagerInterface` | Creates a definition registry, returning a working `DefinitionManagerInterface`. |
449
432
  | `createInterpretContext` | function | `(options?: InterpretContextOptions) => InterpretContextInterface` | Creates a cross-turn interpretation context, returning a working `InterpretContextInterface`. |
@@ -461,7 +444,7 @@ import {
461
444
  createNarrator,
462
445
  createNormalizer,
463
446
  createSubjectManager,
464
- createTemplateManager,
447
+ createRecipeManager,
465
448
  } from '@orkestrel/interpret'
466
449
  import {
467
450
  createFactorGroup,
@@ -480,8 +463,8 @@ createGenerator()
480
463
  createInterpretContext({ session: 'turn-1', history: 4 })
481
464
  createNarrator({ lexicon: { templates: { 'subject.empty': 'nothing here' } } })
482
465
 
483
- const templates = createTemplateManager({
484
- templates: [
466
+ const recipes = createRecipeManager({
467
+ recipes: [
485
468
  {
486
469
  id: 't1',
487
470
  name: 'Arithmetic',
@@ -496,8 +479,8 @@ const templates = createTemplateManager({
496
479
  },
497
480
  ],
498
481
  })
499
- templates.count // 1
500
- templates.destroy()
482
+ recipes.count // 1
483
+ recipes.destroy()
501
484
 
502
485
  createSubjectManager({ subjects: [{ value: 1 }] }).count // 1
503
486
  createDefinitionManager({
@@ -511,20 +494,20 @@ createDefinitionManager({
511
494
 
512
495
  ### Classes
513
496
 
514
- | Name | Kind | Signature | Summary |
515
- | ------------------- | ----- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
516
- | `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 template registry and the context, and exposes the reverse direction. |
517
- | `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. |
518
- | `Normalizer` | class | `new (options?: NormalizerOptions) => NormalizerInterface` | Implements the normalize stage: applies contraction, abbreviation, and correction substitutions in order, then collapses whitespace. |
519
- | `Extractor` | class | `new (options?: ExtractorOptions) => ExtractorInterface` | Implements the extract stage: template-agnostic intent classification plus raw numeric-entity mining. |
520
- | `Clarifier` | class | `new (options?: ClarifierOptions) => ClarifierInterface` | Implements the clarify stage: resolves same-domain carry-over, template defaults, and declaratively computed fields against an already-assigned entity set, surfacing an `Ambiguity` for every required mapping that stays unresolved. |
521
- | `Formatter` | class | `new (options?: FormatterOptions) => FormatterInterface` | Implements the format stage: renders the refined natural-language prompt for a matched template. |
522
- | `Generator` | class | `new () => GeneratorInterface` | Implements the generate stage: builds the final `Subject` from a fully resolved entity set, plus its complete field audit. |
523
- | `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. |
524
- | `TemplateManager` | class | `new (options?: TemplateManagerOptions) => TemplateManagerInterface` | Implements the template registry — a self-owning, versioned and content-hashed record-holder for the `Template`s an `Interpret` orchestrator matches against. |
525
- | `SubjectManager` | class | `new (options?: SubjectManagerOptions) => SubjectManagerInterface` | Implements the subject registry — a self-owning, versioned and content-hashed record-holder that mints its own record identity for every `Subject` (a `Subject` carries no `id` field of its own). |
526
- | `DefinitionManager` | class | `new (options?: DefinitionManagerOptions) => DefinitionManagerInterface` | Implements the definition registry — a self-owning, versioned and content-hashed record-holder for the reasons `Definition`s an interpretation produces. |
527
- | `InterpretContext` | class | `new (options?: InterpretContextOptions) => InterpretContextInterface` | Implements the cross-turn interpretation context — a capped, replayable history of completed `Interpretation`s plus the subject and definition registries carry-over reads from. |
497
+ | Name | Kind | Signature | Summary |
498
+ | ------------------- | ----- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
499
+ | `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
+ | `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
+ | `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. |
504
+ | `Formatter` | class | `new (options?: FormatterOptions) => FormatterInterface` | Implements the format stage: renders the refined natural-language prompt for a matched recipe. |
505
+ | `Generator` | class | `new () => GeneratorInterface` | Implements the generate stage: builds the final `Subject` from a fully resolved entity set, plus its complete field audit. |
506
+ | `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. |
507
+ | `RecipeManager` | class | `new (options?: RecipeManagerOptions) => RecipeManagerInterface` | Implements the recipe registry — a self-owning, versioned and content-hashed record-holder for the `Recipe`s an `Interpret` orchestrator matches against. |
508
+ | `SubjectManager` | class | `new (options?: SubjectManagerOptions) => SubjectManagerInterface` | Implements the subject registry — a self-owning, versioned and content-hashed record-holder that mints its own record identity for every `Subject` (a `Subject` carries no `id` field of its own). |
509
+ | `DefinitionManager` | class | `new (options?: DefinitionManagerOptions) => DefinitionManagerInterface` | Implements the definition registry — a self-owning, versioned and content-hashed record-holder for the reasons `Definition`s an interpretation produces. |
510
+ | `InterpretContext` | class | `new (options?: InterpretContextOptions) => InterpretContextInterface` | Implements the cross-turn interpretation context — a capped, replayable history of completed `Interpretation`s plus the subject and definition registries carry-over reads from. |
528
511
 
529
512
  ## Methods
530
513
 
@@ -568,9 +551,9 @@ extractor.extract('calculate my rate at 85')
568
551
 
569
552
  #### `ClarifierInterface`
570
553
 
571
- | Method | Returns | Summary |
572
- | --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
573
- | `clarify` | `ClarifyResult` | Resolves carry-over, template defaults, and computed fields, and surfaces an `Ambiguity` for every unresolved required field, worded through the narrator's `ambiguity.entity` line. |
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. |
574
557
 
575
558
  ```ts
576
559
  import { createClarifier } from '@orkestrel/interpret'
@@ -600,7 +583,7 @@ clarifier.clarify(
600
583
  ```
601
584
 
602
585
  A computation addresses one numeric element of an array-valued field as
603
- `{field}.{index}`, so a template whose collection has a known length declares an
586
+ `{field}.{index}`, so a recipe whose collection has a known length declares an
604
587
  aggregate over it:
605
588
 
606
589
  ```ts
@@ -610,7 +593,7 @@ import { createOperation, createVariable } from '@orkestrel/reason'
610
593
  // `value.0` and `value.1` name the first two elements of the array-valued
611
594
  // `value` field. A collection whose length varies per turn has no declarable
612
595
  // aggregate: `resolveExpression` returns `undefined` for an unbound variable,
613
- // so a template naming `value.2` against a two-element array lands no `total`
596
+ // so a recipe naming `value.2` against a two-element array lands no `total`
614
597
  // at all.
615
598
  const clarifier = createClarifier({ floor: 0.3 })
616
599
  clarifier.clarify(
@@ -643,9 +626,9 @@ clarifier.clarify(
643
626
 
644
627
  #### `FormatterInterface`
645
628
 
646
- | Method | Returns | Summary |
647
- | -------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
648
- | `format` | `FormatResult` | Renders the refined natural-language prompt for a matched template, clause by clause through the narrator's `prompt.*` lines. |
629
+ | Method | Returns | Summary |
630
+ | -------- | -------------- | --------------------------------------------------------------------------------------------------------------------------- |
631
+ | `format` | `FormatResult` | Renders the refined natural-language prompt for a matched recipe, clause by clause through the narrator's `prompt.*` lines. |
649
632
 
650
633
  ```ts
651
634
  import { createFormatter } from '@orkestrel/interpret'
@@ -676,9 +659,9 @@ formatter.format(
676
659
 
677
660
  #### `GeneratorInterface`
678
661
 
679
- | Method | Returns | Summary |
680
- | ---------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
681
- | `generate` | `GenerateResult` | Builds the final subject and definition pair plus its complete field audit, deriving no field the template did not declare. |
662
+ | Method | Returns | Summary |
663
+ | ---------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
664
+ | `generate` | `GenerateResult` | Builds the final subject and definition pair plus its complete field audit, deriving no field the recipe did not declare. |
682
665
 
683
666
  ```ts
684
667
  import { createGenerator } from '@orkestrel/interpret'
@@ -794,31 +777,31 @@ notes.remove('n1') // true
794
777
  notes.destroy()
795
778
  ```
796
779
 
797
- #### `TemplateManagerInterface`
780
+ #### `RecipeManagerInterface`
798
781
 
799
- The self-owning, ordered registry over templates. `add` derives each record's `hash` from the
800
- template's content and bumps `version` only when that hash changes. `remove`'s array form is
782
+ The self-owning, ordered registry over recipes. `add` derives each record's `hash` from the
783
+ recipe's content and bumps `version` only when that hash changes. `remove`'s array form is
801
784
  all-or-nothing. A call after `destroy()` throws `InterpretError('DESTROYED', …)`.
802
785
 
803
- | Method | Returns | Summary |
804
- | ----------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
805
- | `has` | `boolean` | Reports whether a template with the given id has been added. |
806
- | `template` | `TemplateRecord \| undefined` | Looks up one added template record by id — the singular accessor. |
807
- | `templates` | `readonly TemplateRecord[]` | Lists every added template record — the plural accessor. |
808
- | `add` | `TemplateRecord` | Adds, or re-adds, one template from its data, and emits `add`. |
809
- | `remove` | `boolean` (or `void`) | Removes the listed templates by id, one template by id, or every template, and emits `remove` per removed id. |
810
- | `destroy` | `void` | Tears the template registry down idempotently — clears the collection, emits `destroy`, then destroys the emitter last. |
786
+ | Method | Returns | Summary |
787
+ | --------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
788
+ | `has` | `boolean` | Reports whether a recipe with the given id has been added. |
789
+ | `recipe` | `RecipeRecord \| undefined` | Looks up one added recipe record by id — the singular accessor. |
790
+ | `recipes` | `readonly RecipeRecord[]` | Lists every added recipe record — the plural accessor. |
791
+ | `add` | `RecipeRecord` | Adds, or re-adds, one recipe from its data, and emits `add`. |
792
+ | `remove` | `boolean` (or `void`) | Removes the listed recipes by id, one recipe by id, or every recipe, and emits `remove` per removed id. |
793
+ | `destroy` | `void` | Tears the recipe registry down idempotently — clears the collection, emits `destroy`, then destroys the emitter last. |
811
794
 
812
795
  ```ts
813
- import { createTemplateManager } from '@orkestrel/interpret'
796
+ import { createRecipeManager } from '@orkestrel/interpret'
814
797
  import {
815
798
  createFactorGroup,
816
799
  createFieldFactor,
817
800
  createQuantitativeDefinition,
818
801
  } from '@orkestrel/reason'
819
802
 
820
- const templates = createTemplateManager()
821
- const record = templates.add({
803
+ const recipes = createRecipeManager()
804
+ const record = recipes.add({
822
805
  id: 't1',
823
806
  name: 'Arithmetic',
824
807
  domain: 'arithmetic',
@@ -831,17 +814,17 @@ const record = templates.add({
831
814
  ]),
832
815
  })
833
816
  record.version // 1
834
- templates.count // 1
835
- templates.has('t1') // true
836
- templates.template('t1') // the TemplateRecord, or undefined
837
- templates.templates() // every added record
838
- templates.remove('t1') // true
839
- templates.destroy()
817
+ recipes.count // 1
818
+ recipes.has('t1') // true
819
+ recipes.recipe('t1') // the RecipeRecord, or undefined
820
+ recipes.recipes() // every added record
821
+ recipes.remove('t1') // true
822
+ recipes.destroy()
840
823
  ```
841
824
 
842
825
  #### `SubjectManagerInterface`
843
826
 
844
- Mirrors `TemplateManagerInterface`, minting its own record ids (a `Subject`
827
+ Mirrors `RecipeManagerInterface`, minting its own record ids (a `Subject`
845
828
  carries no `id` field of its own) unless the caller overrides through
846
829
  `RecordOptions.id`.
847
830
 
@@ -869,7 +852,7 @@ subjects.destroy()
869
852
 
870
853
  #### `DefinitionManagerInterface`
871
854
 
872
- Mirrors `TemplateManagerInterface`, defaulting each record id to the
855
+ Mirrors `RecipeManagerInterface`, defaulting each record id to the
873
856
  definition's own `id`.
874
857
 
875
858
  | Method | Returns | Summary |
@@ -943,8 +926,8 @@ context.destroy()
943
926
 
944
927
  #### `InterpretInterface`
945
928
 
946
- `interpret` is genuinely synchronous. `add`, `remove`, `template`, and `templates` name the
947
- same acts as the internal `TemplateManagerInterface` they delegate to, and `add` returns
929
+ `interpret` is genuinely synchronous. `add`, `remove`, `recipe`, and `recipes` name the
930
+ same acts as the internal `RecipeManagerInterface` they delegate to, and `add` returns
948
931
  `void` where the manager returns the record it minted. `describe` and `narrate` are the
949
932
  reverse direction. After `destroy()` every method except the `emitter` getter and `destroy`
950
933
  itself throws `InterpretError('DESTROYED', …)`; `destroy()` is idempotent, leaves a `context`
@@ -953,16 +936,16 @@ supplied-context half of that rule: `InterpretInterface` publishes no context ac
953
936
  nothing outside reads the state of a context the orchestrator constructed itself or
954
937
  subscribes to its emitter.
955
938
 
956
- | Method | Returns | Summary |
957
- | ----------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
958
- | `interpret` | `Interpretation` | Runs the `[normalize, extract, clarify, format, generate]` pipeline over raw text, returning a complete or a visibly incomplete result. |
959
- | `add` | `void` | Adds one template, and emits `add`. |
960
- | `remove` | `boolean` (or `void`) | Removes the listed templates by id, one template by id, or every template. |
961
- | `template` | `Template \| undefined` | Looks up one added template's plain data by id. |
962
- | `templates` | `readonly Template[]` | Lists every added template's plain data. |
963
- | `describe` | `string` | Renders a reasons `Definition` to a one-line, display-neutral description. |
964
- | `narrate` | `string` | Renders a reasons `ReasonResult` to a one-line, display-neutral description. |
965
- | `destroy` | `void` | Tears the orchestrator down idempotently — the template registry, the context it constructed itself, then the emitter last. |
939
+ | Method | Returns | Summary |
940
+ | ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
941
+ | `interpret` | `Interpretation` | Runs the `[normalize, extract, clarify, format, generate]` pipeline over raw text, returning a complete or a visibly incomplete result. |
942
+ | `add` | `void` | Adds one recipe, and emits `add`. |
943
+ | `remove` | `boolean` (or `void`) | Removes the listed recipes by id, one recipe by id, or every recipe. |
944
+ | `recipe` | `Recipe \| undefined` | Looks up one added recipe's plain data by id. |
945
+ | `recipes` | `readonly Recipe[]` | Lists every added recipe's plain data. |
946
+ | `describe` | `string` | Renders a reasons `Definition` to a one-line, display-neutral description. |
947
+ | `narrate` | `string` | Renders a reasons `ReasonResult` to a one-line, display-neutral description. |
948
+ | `destroy` | `void` | Tears the orchestrator down idempotently — the recipe registry, the context it constructed itself, then the emitter last. |
966
949
 
967
950
  ```ts
968
951
  import { createExtractor, createInterpret } from '@orkestrel/interpret'
@@ -992,8 +975,8 @@ interpret.add({
992
975
  })
993
976
  const result = interpret.interpret('calculate arithmetic 42')
994
977
  result.subject // { value: 42 }
995
- interpret.template('t1') // the plain Template data
996
- interpret.templates() // every added template
978
+ interpret.recipe('t1') // the plain Recipe data
979
+ interpret.recipes() // every added recipe
997
980
  interpret.describe(createQuantitativeDefinition('t1', 'Arithmetic', []))
998
981
  interpret.narrate({
999
982
  reasoning: 'symbolic',
@@ -1009,21 +992,21 @@ interpret.destroy()
1009
992
 
1010
993
  ## Tests
1011
994
 
1012
- - [`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 template` 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.
1013
- - [`tests/src/core/Interpret.test.ts`](../tests/src/core/Interpret.test.ts) — the orchestrator: the fixed pipeline and its per-stage records, the `NO_TEMPLATE` and `LOW_CONFIDENCE` incomplete results, a thrown stage marked on its record and on `failures`, the replay digest, the emitter surface, and teardown.
995
+ - [`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.
996
+ - [`tests/src/core/Interpret.test.ts`](../tests/src/core/Interpret.test.ts) — the orchestrator: the fixed pipeline and its per-stage records, the `NO_RECIPE` and `LOW_CONFIDENCE` incomplete results, a thrown stage marked on its record and on `failures`, the replay digest, the emitter surface, and teardown.
1014
997
  - [`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.
1015
998
  - [`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.
1016
999
  - [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — each factory returns a working entity, and honors the options it declares.
1017
- - [`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, template scoring and matching, expression variables and resolution, and subject rendering.
1018
- - [`tests/src/core/parsers.test.ts`](../tests/src/core/parsers.test.ts) — `parseTemplate` returns a template, or `undefined` on invalid JSON and on a shape that fails `isTemplate`.
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.
1001
+ - [`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`.
1019
1002
  - [`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.
1020
1003
  - [`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.
1021
- - [`tests/src/core/stages/Extractor.test.ts`](../tests/src/core/stages/Extractor.test.ts) — intent classification against caller vocabularies, and numeric mining, with no template in sight.
1004
+ - [`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.
1022
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.
1023
1006
  - [`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.
1024
1007
  - [`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.
1025
1008
  - [`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.
1026
- - [`tests/src/core/managers/TemplateManager.test.ts`](../tests/src/core/managers/TemplateManager.test.ts) — the template accessors, the record id defaulting to `template.id`, and re-add versioning.
1009
+ - [`tests/src/core/managers/RecipeManager.test.ts`](../tests/src/core/managers/RecipeManager.test.ts) — the recipe accessors, the record id defaulting to `recipe.id`, and re-add versioning.
1027
1010
  - [`tests/src/core/managers/SubjectManager.test.ts`](../tests/src/core/managers/SubjectManager.test.ts) — the minted record identity, the caller override, and the subject accessors.
1028
1011
  - [`tests/src/core/managers/DefinitionManager.test.ts`](../tests/src/core/managers/DefinitionManager.test.ts) — the definition accessors and the record id defaulting to the definition's own `id`.
1029
1012
  - [`tests/src/core/integration.test.ts`](../tests/src/core/integration.test.ts) — the forward and reverse directions driven together over a real corpus, through the public API.