@orkestrel/interpret 0.0.3 → 0.0.5

package/dist/src/core/index.js

@@ -0,0 +1,2605 @@
+import { arrayOf, isBoolean, isFiniteNumber, isRecord, isString, notOf, parseJSONAs, recordOf, unionOf } from "@orkestrel/contract";
+import { applyOperation, formatField, isDefinition, isFieldPath, isSymbolicExpression } from "@orkestrel/reason";
+import { Emitter } from "@orkestrel/emitter";
+import { fillTemplate } from "@orkestrel/template";
+//#region src/core/constants.ts
+/**
+* Default `similarity` for `createInterpret` / `matchAlias` — the fuzzy
+* alias-match score threshold (0..1).
+*
+* @remarks
+* Domain-qualified (not a bare `DEFAULT_SIMILARITY`) so the name stays free
+* of collision on the shared `@src/core` barrel, mirroring the
+* `DEFAULT_REASON_BAIL` precedent.
+*/
+var DEFAULT_INTERPRET_SIMILARITY = .8;
+/**
+* Default `floor` for `createInterpret` / `matchTemplate` — the minimum
+* intent confidence a template match (or the classified intent itself) must
+* clear.
+*/
+var DEFAULT_INTERPRET_FLOOR = .3;
+/** Default `history` cap for an `InterpretContext`'s `previous()` ring buffer. */
+var DEFAULT_INTERPRET_HISTORY = 16;
+/** Default `id` for an `Interpret` orchestrator. */
+var INTERPRET_ID = "interpret";
+/** Confidence assigned to an exact keyword-proximity entity match. */
+var CONFIDENCE_EXACT = 1;
+/** Confidence assigned to an exact alias-phrase entity match. */
+var CONFIDENCE_ALIAS = .9;
+/** Confidence assigned when a single entity mapping collects every extracted number. */
+var CONFIDENCE_COLLECT = .9;
+/** Confidence assigned to a positional (order-based) entity match fallback. */
+var CONFIDENCE_POSITIONAL = .7;
+/** Confidence assigned to a same-domain carried-over field. */
+var CONFIDENCE_CARRIED = .7;
+/** Confidence assigned to a template default fill. */
+var CONFIDENCE_DEFAULT = 1;
+/** Confidence assigned to a successfully resolved computed field. */
+var CONFIDENCE_COMPUTED = .9;
+/**
+* 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 `%`.
+*
+* @remarks
+* Carries the global flag, so every call site builds a fresh `RegExp` from
+* `.source` / `.flags` (mirrors the core-root `PLACEHOLDER_PATTERN` pattern)
+* rather than sharing this instance's mutable `lastIndex` across scans.
+*/
+var NUMBER_PATTERN = /(?:\$\s*)?(\d+(?:,\d{3})*(?:\.\d+)?)\s*%?/g;
+/**
+* Prototype-pollution-unsafe field-path segments — `setField` refuses to
+* write ANY path containing one, returning its input unchanged.
+*/
+var UNSAFE_FIELD_SEGMENTS = Object.freeze([
+	"__proto__",
+	"prototype",
+	"constructor"
+]);
+/**
+* Neutral built-in contraction expansions for `Normalizer` — small on
+* purpose; callers merge their own map over this one.
+*/
+var DEFAULT_CONTRACTIONS = Object.freeze({
+	"can't": "cannot",
+	"won't": "will not",
+	"it's": "it is",
+	"don't": "do not"
+});
+/** Neutral built-in abbreviation expansions for `Normalizer` — empty by default. */
+var DEFAULT_ABBREVIATIONS = Object.freeze({});
+/** Neutral built-in misspelling corrections for `Normalizer` — empty by default. */
+var DEFAULT_CORRECTIONS = Object.freeze({});
+/** Neutral built-in action-verb vocabulary for `Extractor#extract`'s intent classification — empty by default. */
+var DEFAULT_ACTIONS = Object.freeze({});
+/** Neutral built-in domain-keyword vocabulary for `Extractor#extract`'s intent classification — empty by default. */
+var DEFAULT_DOMAINS = Object.freeze({});
+/** Neutral built-in intent-verb phrasing for `Formatter#format` — empty by default. */
+var DEFAULT_VERBS = Object.freeze({});
+/**
+* The neutral default `Lexicon` a `Narrator` merges caller data over.
+*
+* @remarks
+* `phrases` and `labels` are empty — there is no built-in vocabulary or
+* label overrides (AGENTS §21 mechanism-never-policy). `templates` carries
+* the structural, display-neutral strings the reverse helpers formerly
+* hardcoded, keyed by
+* `{table}.{reasoning}` for the four reasons kinds, `result.quantitative.failed`
+* for the quantitative-result failure suffix, and `subject.fields` /
+* `subject.empty` for `describeSubject`. Every string is a plain
+* @orkestrel/template `fillTemplate` template — `{{name}}`-style placeholders
+* resolved against the caller-supplied `values` record.
+*/
+var DEFAULT_LEXICON = Object.freeze({
+	phrases: Object.freeze({}),
+	labels: Object.freeze({}),
+	templates: Object.freeze({
+		"definition.quantitative": "{{name}}: {{count}} factor group(s)",
+		"definition.logical": "{{name}}: {{count}} rule(s), strategy {{strategy}}",
+		"definition.symbolic": "{{name}}: solve {{count}} equation(s)",
+		"definition.inferential": "{{name}}: {{facts}} fact(s)/{{inferences}} inference(s), {{strategy}}",
+		"result.quantitative": "scored {{value}} across {{count}} group(s)",
+		"result.quantitative.failed": "; failed: {{errors}}",
+		"result.logical": "{{status}}: {{count}} rule(s)",
+		"result.symbolic": "solved {{solved}}",
+		"result.inferential": "derived {{count}} fact(s)",
+		"subject.fields": "with {{fields}}",
+		"subject.empty": "with no fields"
+	})
+});
+//#endregion
+//#region src/core/errors.ts
+/**
+* An error thrown by the interprets layer.
+*
+* @remarks
+* Thrown for: an injected stage implementation throwing during its phase
+* (`NORMALIZE_FAILED` / `EXTRACT_FAILED` / `CLARIFY_FAILED` /
+* `FORMAT_FAILED` / `GENERATE_FAILED`), `createTemplate` handed data that
+* fails `isTemplate` (`INVALID_TEMPLATE`), and any use of a destroyed
+* `Interpret` / manager / context (`DESTROYED`). `NO_TEMPLATE` and
+* `LOW_CONFIDENCE` never throw — they surface as a visible incomplete
+* {@link Interpretation} instead (never an arbitrary fallback template).
+* `context`, when present, carries the offending stage / template id.
+*/
+var InterpretError = class extends Error {
+	code;
+	context;
+	constructor(code, message, context) {
+		super(message);
+		this.name = "InterpretError";
+		this.code = code;
+		this.context = context;
+	}
+};
+/**
+* Narrow an unknown caught value to an {@link InterpretError}.
+*
+* @param value - The value to test (typically a `catch` binding)
+* @returns `true` when `value` is an {@link InterpretError}
+*
+* @example
+* ```ts
+* import { isInterpretError } from '@src/core'
+*
+* try {
+* 	interpret.template('missing')
+* } catch (error) {
+* 	if (isInterpretError(error) && error.code === 'DESTROYED') return
+* }
+* ```
+*/
+function isInterpretError(value) {
+	return value instanceof InterpretError;
+}
+//#endregion
+//#region src/core/validators.ts
+/**
+* Determine whether a value is an {@link EntityMapping} — a literal
+* alias-phrase extraction rule pointing at a subject field.
+*
+* @param value - The value to test
+* @returns `true` when `value` is a well-formed entity mapping
+*
+* @example
+* ```ts
+* import { isEntityMapping } from '@src/core'
+*
+* isEntityMapping({ entity: 'age', aliases: ['years old'], field: 'age' }) // true
+* isEntityMapping({ entity: 'age', aliases: [/\d+/], field: 'age' })      // false — RegExp alias
+* ```
+*/
+function isEntityMapping(value) {
+	return recordOf({
+		entity: isString,
+		aliases: arrayOf(isString),
+		field: isFieldPath,
+		required: isBoolean
+	}, ["required"])(value);
+}
+/**
+* Determine whether a value is a {@link FieldDefault} — a fallback value a
+* {@link Template} fills onto an unresolved field.
+*
+* @remarks
+* `value` is unconstrained (any value, including `null` or `undefined`) as
+* long as the key is present — the trivially-true guard `notOf(unionOf())`
+* mirrors the reasons `Check.value` precedent.
+*
+* @param value - The value to test
+* @returns `true` when `value` is a well-formed field default
+*
+* @example
+* ```ts
+* import { isFieldDefault } from '@src/core'
+*
+* isFieldDefault({ field: 'term', value: 12 })   // true
+* isFieldDefault({ field: 'term' })               // false — value missing
+* ```
+*/
+function isFieldDefault(value) {
+	return recordOf({
+		field: isFieldPath,
+		value: notOf(unionOf())
+	})(value);
+}
+/**
+* Determine whether a value is a {@link ComputedField} — a declaratively
+* computed field carrying a reasons {@link SymbolicExpression} tree.
+*
+* @param value - The value to test
+* @returns `true` when `value` is a well-formed computed field
+*
+* @example
+* ```ts
+* import { constant, operation, variable } from '@orkestrel/reason'
+* import { isComputedField } from '@src/core'
+*
+* isComputedField({
+* 	field: 'monthly',
+* 	expression: operation('divide', variable('deductible'), constant(12)),
+* }) // true
+* isComputedField({ field: 'monthly', expression: { form: 'variable' } }) // false — name missing
+* ```
+*/
+function isComputedField(value) {
+	return recordOf({
+		field: isFieldPath,
+		expression: isSymbolicExpression
+	})(value);
+}
+/**
+* Determine whether a value is a {@link Template} — a named, versionable
+* interpretation template.
+*
+* @remarks
+* `definition` is validated with reasons' `isDefinition` — a `Template`'s
+* definition is already expressed in terrain reasons vocabulary, so no
+* parallel interprets-owned definition guard exists.
+*
+* @param value - The value to test
+* @returns `true` when `value` is a well-formed template
+*
+* @example
+* ```ts
+* import { factorGroup, fieldFactor, quantitativeDefinition } from '@orkestrel/reason'
+* import { isTemplate } from '@src/core'
+*
+* isTemplate({
+* 	id: 't1',
+* 	name: 'Arithmetic',
+* 	domain: 'arithmetic',
+* 	intents: ['calculate'],
+* 	mappings: [],
+* 	defaults: [],
+* 	computations: [],
+* 	definition: quantitativeDefinition('t1', 'Arithmetic', [
+* 		factorGroup('total', 'sum', [fieldFactor('value', 'value')]),
+* 	]),
+* }) // true
+* isTemplate({ id: 't1' }) // false — most fields missing
+* ```
+*/
+function isTemplate(value) {
+	return recordOf({
+		id: isString,
+		name: isString,
+		domain: isString,
+		intents: arrayOf(isString),
+		mappings: arrayOf(isEntityMapping),
+		defaults: arrayOf(isFieldDefault),
+		computations: arrayOf(isComputedField),
+		definition: isDefinition
+	})(value);
+}
+//#endregion
+//#region src/core/helpers.ts
+/**
+* Escape every regex metacharacter in `text` so it matches literally when
+* compiled into a `RegExp`.
+*
+* @param text - The literal text to escape
+* @returns `text` with every regex metacharacter backslash-escaped
+*
+* @example
+* ```ts
+* import { escapeRegExp } from '@src/core'
+*
+* escapeRegExp('a.b*c') // 'a\\.b\\*c'
+* new RegExp(escapeRegExp('a.b*c')).test('a.b*c') // true
+* ```
+*/
+function escapeRegExp(text) {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Copy-on-write write a value at a (possibly nested) field path on a subject.
+*
+* @remarks
+* Never mutates `subject` — every level a `field` array descends through is
+* freshly copied, so the input and every intermediate record stay untouched
+* (AGENTS §11). Prototype-pollution-safe: a `field` containing `__proto__`,
+* `prototype`, or `constructor` at ANY segment (checked against
+* `UNSAFE_FIELD_SEGMENTS`) is refused as a no-op, returning `subject`
+* unchanged. A non-record value already sitting at an intermediate segment is
+* replaced by a fresh record rather than descended into.
+*
+* @param subject - The subject to derive from
+* @param field - The (possibly nested) field path to write
+* @param value - The value to write
+* @returns A fresh subject with `value` written at `field`, or `subject`
+* unchanged when `field` carries an unsafe segment
+*
+* @example
+* ```ts
+* import { setField } from '@src/core'
+*
+* setField({ age: 25 }, 'age', 30)               // { age: 30 }
+* setField({}, ['address', 'city'], 'Reno')      // { address: { city: 'Reno' } }
+* setField({}, ['__proto__', 'polluted'], true)  // {} — refused, unchanged
+* ```
+*/
+/**
+* Derive the sibling field path for a computed aggregate of `field` — the
+* suffix is appended to `field`'s OWN last segment, so the aggregate nests
+* beside the source field rather than flattening past it.
+*
+* @remarks
+* For an array {@link FieldPath} (e.g. `['address', 'amounts']`) with suffix
+* `'Sum'` the result is `['address', 'amountsSum']` — nested beside
+* `address.amounts`. For a plain string field the result stays a flat string
+* (`'amounts'` → `'amountsSum'`), matching the existing single-key behavior.
+*
+* @param field - The source field path
+* @param suffix - The aggregate suffix (`'Sum'`, `'Count'`, `'Average'`, `'Minimum'`, `'Maximum'`)
+* @returns The sibling field path for the aggregate
+*
+* @example
+* ```ts
+* import { deriveAggregateField } from '@src/core'
+*
+* deriveAggregateField(['address', 'amounts'], 'Sum') // ['address', 'amountsSum']
+* deriveAggregateField('amounts', 'Sum')               // 'amountsSum'
+* ```
+*/
+function deriveAggregateField(field, suffix) {
+	if (Array.isArray(field)) {
+		const last = field[field.length - 1];
+		return [...field.slice(0, -1), `${last}${suffix}`];
+	}
+	return `${field}${suffix}`;
+}
+function setField(subject, field, value) {
+	const path = Array.isArray(field) ? field : [field];
+	if (path.length === 0) return subject;
+	if (path.some((segment) => UNSAFE_FIELD_SEGMENTS.includes(segment))) return subject;
+	const [key, ...rest] = path;
+	if (key === void 0) return subject;
+	if (rest.length === 0) return {
+		...subject,
+		[key]: value
+	};
+	const child = subject[key];
+	const nested = isRecord(child) ? child : {};
+	return {
+		...subject,
+		[key]: setField(nested, rest, value)
+	};
+}
+/**
+* Replace every whole-word occurrence of a map's keys with their values.
+*
+* @remarks
+* Word-boundary safe (`in` never matches inside `information`) and
+* case-insensitive; each key is regex-escaped via the core-root
+* `escapeRegExp` before compiling, so a caller-supplied phrase containing
+* regex metacharacters is matched literally. Multiple keys apply in
+* `Object.entries` order — the `Normalizer` stage sequences its three maps
+* (contractions, abbreviations, corrections) with three separate calls.
+*
+* @param text - The text to substitute within
+* @param map - The `{ from: to }` substitution map
+* @returns `text` with every whole-word match replaced
+*
+* @example
+* ```ts
+* import { applyReplacements } from '@src/core'
+*
+* applyReplacements("can't stop", { "can't": 'cannot' }) // 'cannot stop'
+* applyReplacements('information', { in: 'IN' })          // 'information' — word-boundary safe
+* ```
+*/
+function applyReplacements(text, map) {
+	let result = text;
+	for (const [from, to] of Object.entries(map)) {
+		const pattern = new RegExp(`\\b${escapeRegExp(from)}\\b`, "gi");
+		result = result.replace(pattern, to);
+	}
+	return result;
+}
+/**
+* Collapse every run of whitespace to a single space and trim the ends.
+*
+* @param text - The text to collapse
+* @returns The collapsed text
+*
+* @example
+* ```ts
+* import { collapseWhitespace } from '@src/core'
+*
+* collapseWhitespace('  a   b\t c ') // 'a b c'
+* ```
+*/
+function collapseWhitespace(text) {
+	return text.replace(/\s+/g, " ").trim();
+}
+/**
+* Split text into lowercase tokens, stripping punctuation outside a small
+* numeric/currency-safe allowlist.
+*
+* @remarks
+* Shared by `classifyIntent` and `assignEntities` — pure ECMAScript
+* (no locale-aware `Intl` segmentation), so multi-byte / astral text tokenizes
+* on ASCII word boundaries only.
+*
+* @param text - The text to tokenize
+* @returns The lowercase tokens, punctuation-stripped, empty tokens dropped
+*
+* @example
+* ```ts
+* import { tokenize } from '@src/core'
+*
+* tokenize('The rate is 85%.') // ['the', 'rate', 'is', '85%']
+* ```
+*/
+function tokenize(text) {
+	return text.toLowerCase().replace(/[^a-z0-9\s./%$'-]/g, " ").split(/\s+/).filter((token) => token.length > 0);
+}
+/**
+* Mine every numeric literal from text — optional leading `$`, thousands
+* commas, an optional decimal fraction, an optional trailing `%`.
+*
+* @remarks
+* Numbers-only: this is the module's entire extraction contract (AGENTS
+* §21 mechanism-never-policy) — no date, text-entity, or negation parsing.
+*
+* @param text - The text to scan
+* @returns Every extracted number, in left-to-right order
+*
+* @example
+* ```ts
+* import { extractNumbers } from '@src/core'
+*
+* extractNumbers('income was $50,000, age 25') // [50000, 25]
+* ```
+*/
+function extractNumbers(text) {
+	const pattern = new RegExp(NUMBER_PATTERN.source, NUMBER_PATTERN.flags);
+	const numbers = [];
+	let match = pattern.exec(text);
+	while (match !== null) {
+		const raw = match[1];
+		if (raw !== void 0) {
+			const value = Number(raw.replace(/,/g, ""));
+			if (Number.isFinite(value)) numbers.push(value);
+		}
+		match = pattern.exec(text);
+	}
+	return numbers;
+}
+/**
+* Assign already-extracted numbers to a matched template's entity mappings.
+*
+* @remarks
+* Strategy, in order: (1) a SINGLE mapping collects every number (an array
+* when more than one, a scalar otherwise) at `CONFIDENCE_COLLECT`. Otherwise,
+* per mapping, the rightmost token in the text that equals the entity name
+* (`CONFIDENCE_EXACT`), an alias exactly (`CONFIDENCE_ALIAS`), or an alias
+* fuzzily (via `matchAlias`, confidence = its returned score) becomes a
+* keyword anchor; anchors sort left-to-right and each claims its nearest
+* unused number by text position. (3) Any mapping still unfilled claims the
+* next unused number positionally, at `CONFIDENCE_POSITIONAL`. Every entity
+* carries provenance `category: 'extracted'` with `detail` naming the
+* strategy that filled it (`'collect' | 'keyword' | 'alias' | 'positional'`).
+* Runs ONLY after a template has matched (an orchestrator-owned step, never
+* inside `Extractor`, which stays template-agnostic).
+*
+* @param numbers - The numbers already extracted from `text` via `extractNumbers`
+* @param mappings - The matched template's entity mappings
+* @param text - The same text `numbers` was extracted from (for keyword proximity)
+* @param similarity - The fuzzy alias-match score threshold (0..1)
+* @returns The assigned entities, one per filled mapping
+*
+* @example
+* ```ts
+* import { assignEntities } from '@src/core'
+*
+* const mappings = [
+* 	{ entity: 'age', aliases: ['years old'], field: 'age' },
+* 	{ entity: 'score', aliases: ['credit score'], field: 'score' },
+* ]
+* assignEntities([25, 720], mappings, '25 year old with score 720', 0.8)
+* // [{ name: 'age', value: 25, ... }, { name: 'score', value: 720, ... }]
+* ```
+*/
+function assignEntities(numbers, mappings, text, similarity) {
+	if (mappings.length === 0 || numbers.length === 0) return [];
+	if (mappings.length === 1) {
+		const mapping = mappings[0];
+		if (mapping === void 0) return [];
+		return [{
+			name: mapping.entity,
+			value: numbers.length === 1 ? numbers[0] : numbers,
+			provenance: {
+				category: "extracted",
+				detail: "collect"
+			},
+			confidence: CONFIDENCE_COLLECT
+		}];
+	}
+	const tokens = tokenize(text);
+	const lowerText = text.toLowerCase();
+	const positions = [];
+	const positionPattern = new RegExp(NUMBER_PATTERN.source, NUMBER_PATTERN.flags);
+	let positionMatch = positionPattern.exec(text);
+	while (positionMatch !== null) {
+		positions.push(positionMatch.index);
+		positionMatch = positionPattern.exec(text);
+	}
+	const keywordMatches = [];
+	for (const mapping of mappings) {
+		let matchedPosition = -1;
+		let matchedConfidence = 0;
+		let matchedDetail = "keyword";
+		const entityToken = mapping.entity.toLowerCase();
+		for (const token of tokens) {
+			const tokenPosition = lowerText.indexOf(token);
+			if (token === entityToken) {
+				if (tokenPosition > matchedPosition) {
+					matchedPosition = tokenPosition;
+					matchedConfidence = 1;
+					matchedDetail = "keyword";
+				}
+				continue;
+			}
+			if (mapping.aliases.some((alias) => alias.toLowerCase() === token)) {
+				if (tokenPosition > matchedPosition) {
+					matchedPosition = tokenPosition;
+					matchedConfidence = CONFIDENCE_ALIAS;
+					matchedDetail = "alias";
+				}
+				continue;
+			}
+			const fuzzy = matchAlias(token, mapping.aliases, similarity);
+			if (fuzzy > 0 && tokenPosition > matchedPosition) {
+				matchedPosition = tokenPosition;
+				matchedConfidence = fuzzy;
+				matchedDetail = "alias";
+			}
+		}
+		if (matchedPosition >= 0) keywordMatches.push({
+			mapping,
+			position: matchedPosition,
+			confidence: matchedConfidence,
+			detail: matchedDetail
+		});
+	}
+	keywordMatches.sort((a, b) => a.position - b.position);
+	const used = /* @__PURE__ */ new Set();
+	const filled = /* @__PURE__ */ new Set();
+	const entities = [];
+	for (const match of keywordMatches) {
+		let bestIndex = -1;
+		let bestDistance = Number.POSITIVE_INFINITY;
+		for (let index = 0; index < numbers.length; index += 1) {
+			if (used.has(index)) continue;
+			const position = positions[index];
+			if (position === void 0) continue;
+			const distance = Math.abs(position - match.position);
+			if (distance < bestDistance) {
+				bestDistance = distance;
+				bestIndex = index;
+			}
+		}
+		if (bestIndex >= 0) {
+			const value = numbers[bestIndex];
+			if (value !== void 0) {
+				used.add(bestIndex);
+				filled.add(match.mapping.entity);
+				entities.push({
+					name: match.mapping.entity,
+					value,
+					provenance: {
+						category: "extracted",
+						detail: match.detail
+					},
+					confidence: match.confidence
+				});
+			}
+		}
+	}
+	let numberIndex = 0;
+	for (const mapping of mappings) {
+		if (filled.has(mapping.entity)) continue;
+		while (numberIndex < numbers.length && used.has(numberIndex)) numberIndex += 1;
+		if (numberIndex >= numbers.length) break;
+		const value = numbers[numberIndex];
+		if (value !== void 0) {
+			used.add(numberIndex);
+			filled.add(mapping.entity);
+			entities.push({
+				name: mapping.entity,
+				value,
+				provenance: {
+					category: "extracted",
+					detail: "positional"
+				},
+				confidence: CONFIDENCE_POSITIONAL
+			});
+		}
+		numberIndex += 1;
+	}
+	return entities;
+}
+/**
+* Classify the action + domain intent of a text against caller-supplied
+* vocabularies.
+*
+* @remarks
+* `actions` maps a token to an action name — the first matching token in
+* `text` (left to right) wins, at `CONFIDENCE_EXACT`. `domains` maps a domain
+* name to its keyword list — the domain with the most matching tokens wins
+* (ties keep the earliest-declared domain), also at `CONFIDENCE_EXACT`.
+* Combined confidence (PINNED): both fire → their average; exactly one fires
+* → its value times `0.5`; neither → `0`. There is no built-in worldview and
+* no auto-classification from a registered template's own `domain` name — a
+* caller MUST list a template's domain among `domains` for it to classify.
+* No `floor` parameter: the confidence floor gate lives at the orchestrator's
+* `matchTemplate` step, never inside classification itself.
+*
+* @param text - The (normalized) text to classify
+* @param actions - The caller's token → action-name vocabulary
+* @param domains - The caller's domain-name → keyword-list vocabulary
+* @returns The classified intent
+*
+* @example
+* ```ts
+* import { classifyIntent } from '@src/core'
+*
+* classifyIntent('calculate my rate', { calculate: 'compute' }, { rating: ['rate'] })
+* // { action: 'compute', domain: 'rating', confidence: 1 }
+* classifyIntent('hello', {}, {}) // { action: '', domain: '', confidence: 0 }
+* ```
+*/
+function classifyIntent(text, actions, domains) {
+	const tokens = tokenize(text);
+	let action = "";
+	let actionConfidence = 0;
+	for (const token of tokens) {
+		const mapped = actions[token];
+		if (mapped !== void 0) {
+			action = mapped;
+			actionConfidence = 1;
+			break;
+		}
+	}
+	let domain = "";
+	let domainConfidence = 0;
+	let bestMatches = 0;
+	for (const [name, keywords] of Object.entries(domains)) {
+		const lowerKeywords = keywords.map((keyword) => keyword.toLowerCase());
+		let matches = 0;
+		for (const token of tokens) if (lowerKeywords.includes(token)) matches += 1;
+		if (matches > bestMatches) {
+			bestMatches = matches;
+			domain = name;
+			domainConfidence = 1;
+		}
+	}
+	const confidence = actionConfidence > 0 && domainConfidence > 0 ? (actionConfidence + domainConfidence) / 2 : Math.max(actionConfidence, domainConfidence) * .5;
+	return {
+		action,
+		domain,
+		confidence
+	};
+}
+/**
+* Bigram (Dice coefficient) string similarity, case-insensitive.
+*
+* @param a - The first string
+* @param b - The second string
+* @returns A score in `[0, 1]` — `1` for an exact (case-insensitive) match,
+* `0` when either string is shorter than 2 characters and they are not equal
+*
+* @example
+* ```ts
+* import { scoreSimilarity } from '@src/core'
+*
+* scoreSimilarity('rate', 'rate')  // 1
+* scoreSimilarity('rate', 'value') // 0 — no shared bigrams
+* ```
+*/
+function scoreSimilarity(a, b) {
+	const left = a.toLowerCase();
+	const right = b.toLowerCase();
+	if (left === right) return 1;
+	if (left.length < 2 || right.length < 2) return 0;
+	const bigrams = /* @__PURE__ */ new Map();
+	for (let index = 0; index < left.length - 1; index += 1) {
+		const bigram = left.slice(index, index + 2);
+		bigrams.set(bigram, (bigrams.get(bigram) ?? 0) + 1);
+	}
+	let matches = 0;
+	for (let index = 0; index < right.length - 1; index += 1) {
+		const bigram = right.slice(index, index + 2);
+		const count = bigrams.get(bigram);
+		if (count !== void 0 && count > 0) {
+			bigrams.set(bigram, count - 1);
+			matches += 1;
+		}
+	}
+	return 2 * matches / (left.length - 1 + (right.length - 1));
+}
+/**
+* The best `scoreSimilarity` a token achieves against a list of aliases,
+* gated by a threshold.
+*
+* @param token - The token to score
+* @param aliases - The alias phrases to score against
+* @param threshold - The minimum score to report (an explicit no-match below it)
+* @returns The best score when it meets `threshold`, else `0`
+*
+* @example
+* ```ts
+* import { matchAlias } from '@src/core'
+*
+* matchAlias('valu', ['value', 'amount'], 0.6) // ~0.86 — fuzzy hit on 'value'
+* matchAlias('xyz', ['value', 'amount'], 0.6)  // 0 — no alias clears the threshold
+* ```
+*/
+function matchAlias(token, aliases, threshold) {
+	let best = 0;
+	for (const alias of aliases) {
+		const score = scoreSimilarity(token, alias);
+		if (score > best) best = score;
+	}
+	return best >= threshold ? best : 0;
+}
+/**
+* Render a value into a canonical, key-order-stable string — the pre-image
+* of `digestValue`.
+*
+* @remarks
+* Ported from the app's `raters` digest machinery (`app/core/raters/helpers.ts`)
+* — record keys sort before serialization so a re-ordered object canonicalizes
+* identically; arrays keep position order (position is meaningful).
+* Cycle-safe and total (AGENTS §14): `visited` tracks the object ancestors
+* along the CURRENT recursion path (not a global "seen" set, so the same
+* object reachable twice via non-cyclic sibling branches still canonicalizes
+* normally); revisiting an ancestor renders that node as the literal string
+* `'[cycle]'` instead of recursing — deterministic, never throws, never
+* overflows the call stack.
+*
+* @param value - The value to canonicalize
+* @param visited - The object ancestors along the current recursion path (internal; omit at the call site)
+* @returns The canonical string form
+*
+* @example
+* ```ts
+* import { canonicalize } from '@src/core'
+*
+* canonicalize({ b: 1, a: 2 }) === canonicalize({ a: 2, b: 1 }) // true
+* ```
+*/
+function canonicalize(value, visited = /* @__PURE__ */ new Set()) {
+	if (Array.isArray(value)) {
+		if (visited.has(value)) return JSON.stringify("[cycle]");
+		const nextVisited = new Set(visited);
+		nextVisited.add(value);
+		return `[${value.map((entry) => canonicalize(entry, nextVisited)).join(",")}]`;
+	}
+	if (isRecord(value)) {
+		if (visited.has(value)) return JSON.stringify("[cycle]");
+		const nextVisited = new Set(visited);
+		nextVisited.add(value);
+		return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalize(value[key], nextVisited)}`).join(",")}}`;
+	}
+	return JSON.stringify(value) ?? "null";
+}
+/**
+* Compute a canonical structural digest of a pure-JSON value — a key-order-
+* stable FNV-1a hash rendered as an 8-hex-digit string.
+*
+* @remarks
+* Pure ECMAScript, no host crypto (AGENTS §17.7) — the same algorithm as the
+* app's `digest`, ported into core so `Interpretation.digest` and the
+* versioned managers can hash without leaving strict core.
+*
+* @param value - The value to digest
+* @returns The 8-character hex digest
+*
+* @example
+* ```ts
+* import { digestValue } from '@src/core'
+*
+* digestValue({ a: 1 }) === digestValue({ a: 1 }) // true — deterministic
+* ```
+*/
+function digestValue(value) {
+	const canonical = canonicalize(value);
+	let hash = 2166136261;
+	for (let index = 0; index < canonical.length; index += 1) {
+		hash ^= canonical.charCodeAt(index);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(16).padStart(8, "0");
+}
+/**
+* Score how well a classified intent matches one template's domain + action.
+*
+* @param intent - The classified intent
+* @param template - The candidate template
+* @returns A score in `[0, 1]` — the mean of the domain match (`1`/`0`) and
+* the action match (`1`/`0`, `template.intents` containing `intent.action`)
+*
+* @example
+* ```ts
+* import { scoreTemplate } from '@src/core'
+*
+* scoreTemplate(
+* 	{ action: 'compute', domain: 'rating', confidence: 1 },
+* 	{ id: 't1', name: 'T', domain: 'rating', intents: ['compute'], mappings: [], defaults: [], computations: [], definition: { reasoning: 'symbolic', id: 't1', name: 'T', equations: [], variables: {} } },
+* ) // 1
+* ```
+*/
+function scoreTemplate(intent, template) {
+	return ((template.domain.toLowerCase() === intent.domain.toLowerCase() ? 1 : 0) + (template.intents.some((candidate) => candidate.toLowerCase() === intent.action.toLowerCase()) ? 1 : 0)) / 2;
+}
+/**
+* Find the best-scoring registered template for a classified intent, gated
+* by a confidence floor.
+*
+* @remarks
+* Explicit no-match (AGENTS-flagged scsr defect 2 — never an arbitrary
+* `templates[0]` fallback): an empty registry, or a best score strictly below
+* `floor`, both return `undefined`.
+*
+* @param intent - The classified intent
+* @param templates - The registered templates to score
+* @param floor - The minimum score a match must clear
+* @returns The best-scoring template, or `undefined` on no qualifying match
+*
+* @example
+* ```ts
+* import { matchTemplate } from '@src/core'
+*
+* matchTemplate({ action: '', domain: '', confidence: 0 }, [], 0.3) // undefined — empty registry
+* ```
+*/
+function matchTemplate(intent, templates, floor) {
+	let best;
+	let bestScore = -1;
+	for (const template of templates) {
+		const score = scoreTemplate(intent, template);
+		if (score > bestScore) {
+			bestScore = score;
+			best = template;
+		}
+	}
+	return best !== void 0 && bestScore >= floor ? best : void 0;
+}
+/**
+* Collect every variable name referenced by a symbolic expression tree, in
+* first-occurrence order.
+*
+* @param expression - The expression tree to scan
+* @returns The referenced variable names, deduplicated
+*
+* @example
+* ```ts
+* import { constant, operation, variable } from '@orkestrel/reason'
+* import { variablesOf } from '@src/core'
+*
+* variablesOf(operation('divide', variable('deductible'), constant(12))) // ['deductible']
+* ```
+*/
+function variablesOf(expression) {
+	const names = [];
+	const seen = /* @__PURE__ */ new Set();
+	function collect(node) {
+		if (node.form === "variable") {
+			if (!seen.has(node.name)) {
+				seen.add(node.name);
+				names.push(node.name);
+			}
+			return;
+		}
+		if (node.form === "operation") {
+			collect(node.left);
+			if (node.right !== void 0) collect(node.right);
+		}
+	}
+	collect(expression);
+	return names;
+}
+/**
+* Evaluate a symbolic expression tree against resolved bindings.
+*
+* @remarks
+* THE critical leaf (design-pinned, engine-parity semantics): an absent
+* `right` operand on a binary operation defaults to `0` — matching
+* `SymbolicReasoner`'s internal `#evaluate` — and is always passed as an
+* EXPLICIT numeric operand, so the same tree evaluates identically here and
+* inside the engine. Each arithmetic step delegates to the reasons
+* `applyOperation` pure function, mapping the node's `.operator` field onto
+* its `operator` parameter. An unresolved input variable, or a non-finite
+* result (`NaN` from a divide-by-zero, or an overflowing `±Infinity`),
+* becomes a gap — `undefined`, never landing on a subject.
+*
+* @param expression - The expression tree to evaluate
+* @param bindings - The resolved variable bindings
+* @returns The evaluated number, or `undefined` on an unresolved input or a
+* non-finite result
+*
+* @example
+* ```ts
+* import { constant, operation, variable } from '@orkestrel/reason'
+* import { resolveExpression } from '@src/core'
+*
+* resolveExpression(operation('divide', variable('deductible'), constant(12)), { deductible: 6000 }) // 500
+* resolveExpression(operation('divide', constant(1), constant(0)), {}) // undefined — NaN gap
+* resolveExpression(variable('missing'), {}) // undefined — unresolved input
+* ```
+*/
+function resolveExpression(expression, bindings) {
+	if (expression.form === "constant") return expression.value;
+	if (expression.form === "variable") return bindings[expression.name];
+	const left = resolveExpression(expression.left, bindings);
+	if (left === void 0) return void 0;
+	const right = expression.right === void 0 ? 0 : resolveExpression(expression.right, bindings);
+	if (right === void 0) return void 0;
+	const result = applyOperation(expression.operator, left, right);
+	return isFiniteNumber(result) ? result : void 0;
+}
+/**
+* Render a one-line, display-neutral description of a reasons `Subject`,
+* through an injected `Narrator`.
+*
+* @remarks
+* Complements — never duplicates — the raters `describe*` family (which
+* describes RATERS artifacts); this describes REASONS artifacts. Every field
+* renders via `narrator.label` + `narrator.value` (looked up under the
+* `'units'` phrase table, falling back to `'plain'`) — the wording is fully
+* lexicon-driven (AGENTS §21 mechanism-never-policy); `Definition` /
+* `ReasonResult` narration lives on `Narrator#describe` / `Narrator#narrate`
+* directly.
+*
+* @param subject - The subject to describe
+* @param narrator - The lexicon-driven renderer to render field labels/values/lines through
+* @returns A one-line description, the lexicon's `'subject.empty'` line when empty
+*
+* @example
+* ```ts
+* import { createNarrator, describeSubject } from '@src/core'
+*
+* describeSubject({ age: 25, income: 50000 }, createNarrator()) // 'with age: 25, income: 50000'
+* ```
+*/
+function describeSubject(subject, narrator) {
+	const keys = Object.keys(subject).sort();
+	if (keys.length === 0) return narrator.line("subject.empty", {});
+	const parts = keys.map((key) => {
+		const unit = narrator.phrase("units", key, "plain");
+		return `${narrator.label(key)}: ${narrator.value(unit, subject[key])}`;
+	});
+	return narrator.line("subject.fields", { fields: parts.join(", ") });
+}
+/**
+* Parse a JSON string into a `Template`, or `undefined` on invalid JSON or a
+* shape that fails `isTemplate`.
+*
+* @remarks
+* The module's sole JSON boundary (design §4) — an `Interpretation` and the
+* versioned records are produced internally, never deserialized from
+* untrusted JSON; replay re-runs `interpret`, it does not deserialize a
+* stored result.
+*
+* @param value - The JSON text to parse
+* @returns The parsed template, or `undefined`
+*
+* @example
+* ```ts
+* import { parseTemplate } from '@src/core'
+*
+* parseTemplate('not json') // undefined
+* ```
+*/
+function parseTemplate(value) {
+	return parseJSONAs(value, isTemplate);
+}
+//#endregion
+//#region src/core/managers/DefinitionManager.ts
+/**
+* The definition registry — a self-owning, versioned and content-hashed
+* record-holder for the reasons {@link Definition}s an interpretation produces.
+*
+* @remarks
+* Mirrors {@link TemplateManager}: `add` defaults each record id to the
+* definition's own `id`, derives `hash` from the definition CONTENT
+* (id-independent), and bumps `version` ONLY when that hash changes at a reused
+* id — an identical re-add keeps its version. The batch `remove(ids)` form is
+* all-or-nothing; `destroy()` is idempotent and every method afterwards throws
+* `InterpretError('DESTROYED', …)`.
+*
+* @example
+* ```ts
+* import { symbolicDefinition } from '@orkestrel/reason'
+* import { DefinitionManager } from '@src/core'
+*
+* const manager = new DefinitionManager()
+* const record = manager.add(symbolicDefinition('rate', 'Rate', []))
+* record.id // 'rate'
+* manager.add(symbolicDefinition('rate', 'Rate', [])).version // 1 — identical re-add, no bump
+* ```
+*/
+var DefinitionManager = class {
+	#records = /* @__PURE__ */ new Map();
+	#emitter;
+	#destroyed = false;
+	constructor(options) {
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		for (const definition of options?.definitions ?? []) this.add(definition);
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get size() {
+		this.#ensureAlive();
+		return this.#records.size;
+	}
+	has(id) {
+		this.#ensureAlive();
+		return this.#records.has(id);
+	}
+	definition(id) {
+		this.#ensureAlive();
+		return this.#records.get(id);
+	}
+	definitions() {
+		this.#ensureAlive();
+		return [...this.#records.values()];
+	}
+	add(definition, options) {
+		this.#ensureAlive();
+		const id = options?.id ?? definition.id;
+		const hash = digestValue(definition);
+		const existing = this.#records.get(id);
+		const record = {
+			id,
+			definition,
+			version: existing === void 0 ? 1 : existing.hash === hash ? existing.version : existing.version + 1,
+			hash
+		};
+		this.#records.set(id, record);
+		this.#emitter.emit("add", id);
+		return record;
+	}
+	remove(target) {
+		this.#ensureAlive();
+		if (target === void 0) {
+			for (const id of this.#records.keys()) this.#emitter.emit("remove", id);
+			this.#records.clear();
+			return;
+		}
+		if (typeof target === "string") {
+			const removed = this.#records.delete(target);
+			if (removed) this.#emitter.emit("remove", target);
+			return removed;
+		}
+		for (const id of target) if (!this.#records.has(id)) return false;
+		for (const id of target) {
+			this.#records.delete(id);
+			this.#emitter.emit("remove", id);
+		}
+		return true;
+	}
+	destroy() {
+		if (this.#destroyed) return;
+		this.#records.clear();
+		this.#destroyed = true;
+		this.#emitter.emit("destroy");
+		this.#emitter.destroy();
+	}
+	#ensureAlive() {
+		if (this.#destroyed) throw new InterpretError("DESTROYED", "Definition manager has been destroyed");
+	}
+};
+//#endregion
+//#region src/core/managers/SubjectManager.ts
+/**
+* The subject registry — a self-owning, versioned and content-hashed
+* record-holder that mints its OWN record identity for every {@link Subject}
+* (a `Subject` carries no `id` field of its own).
+*
+* @remarks
+* The defect-7 fix: scsr keyed stored subjects by their definition's id, so
+* successive same-domain turns silently overwrote one shared subject. Here each
+* `add` mints a fresh `subject-{n}` id (deterministic per instance, no host
+* randomness — AGENTS §17.7) unless the caller overrides it via
+* `ManagerAddOptions.id`. `hash` is content-derived (id-independent) and
+* `version` bumps ONLY when the hash changes at a reused id. The batch
+* `remove(ids)` form is all-or-nothing; `destroy()` is idempotent and every
+* method afterwards throws `InterpretError('DESTROYED', …)`.
+*
+* @example
+* ```ts
+* import { SubjectManager } from '@src/core'
+*
+* const manager = new SubjectManager()
+* const first = manager.add({ age: 25 })
+* const second = manager.add({ age: 30 })
+* first.id !== second.id // true — each subject gets its own identity
+* ```
+*/
+var SubjectManager = class {
+	#records = /* @__PURE__ */ new Map();
+	#emitter;
+	#counter = 0;
+	#destroyed = false;
+	constructor(options) {
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		for (const subject of options?.subjects ?? []) this.add(subject);
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get size() {
+		this.#ensureAlive();
+		return this.#records.size;
+	}
+	has(id) {
+		this.#ensureAlive();
+		return this.#records.has(id);
+	}
+	subject(id) {
+		this.#ensureAlive();
+		return this.#records.get(id);
+	}
+	subjects() {
+		this.#ensureAlive();
+		return [...this.#records.values()];
+	}
+	add(subject, options) {
+		this.#ensureAlive();
+		let id = options?.id;
+		if (id === void 0) {
+			id = `subject-${this.#counter}`;
+			this.#counter += 1;
+		}
+		const hash = digestValue(subject);
+		const existing = this.#records.get(id);
+		const version = existing === void 0 ? 1 : existing.hash === hash ? existing.version : existing.version + 1;
+		const record = {
+			id,
+			subject,
+			version,
+			hash
+		};
+		this.#records.set(id, record);
+		this.#emitter.emit("add", id);
+		return record;
+	}
+	remove(target) {
+		this.#ensureAlive();
+		if (target === void 0) {
+			for (const id of this.#records.keys()) this.#emitter.emit("remove", id);
+			this.#records.clear();
+			return;
+		}
+		if (typeof target === "string") {
+			const removed = this.#records.delete(target);
+			if (removed) this.#emitter.emit("remove", target);
+			return removed;
+		}
+		for (const id of target) if (!this.#records.has(id)) return false;
+		for (const id of target) {
+			this.#records.delete(id);
+			this.#emitter.emit("remove", id);
+		}
+		return true;
+	}
+	destroy() {
+		if (this.#destroyed) return;
+		this.#records.clear();
+		this.#destroyed = true;
+		this.#emitter.emit("destroy");
+		this.#emitter.destroy();
+	}
+	#ensureAlive() {
+		if (this.#destroyed) throw new InterpretError("DESTROYED", "Subject manager has been destroyed");
+	}
+};
+//#endregion
+//#region src/core/managers/InterpretContext.ts
+/**
+* Cross-turn interpretation context — a capped, replayable history of
+* completed {@link Interpretation}s plus the subject and definition registries
+* carry-over reads from.
+*
+* @remarks
+* `previous()` is a capped ring buffer (newest-last, oldest dropped once the
+* `history` cap is reached — `DEFAULT_INTERPRET_HISTORY` by default, ≥ 3
+* preserves the carry-over pin) rather than scsr's unbounded `previous` array.
+* `entities()` flattens every entity across the buffered history, most recent
+* last — the read a `Clarifier`'s same-domain carry-over consults. `add` pushes
+* one result and trims to the cap; `clear` resets the history and both
+* registries WITHOUT tearing the context down; `destroy()` is idempotent and
+* every method afterwards throws `InterpretError('DESTROYED', …)`.
+*
+* @example
+* ```ts
+* import { InterpretContext } from '@src/core'
+*
+* const context = new InterpretContext({ session: 's1', history: 8 })
+* context.session // 's1'
+* context.previous() // []
+* ```
+*/
+var InterpretContext = class {
+	#session;
+	#subjects;
+	#definitions;
+	#history;
+	#previous = [];
+	#emitter;
+	#destroyed = false;
+	constructor(options) {
+		this.#session = options?.session;
+		this.#history = Math.max(0, options?.history ?? 16);
+		this.#subjects = new SubjectManager();
+		this.#definitions = new DefinitionManager();
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get session() {
+		this.#ensureAlive();
+		return this.#session;
+	}
+	get subjects() {
+		this.#ensureAlive();
+		return this.#subjects;
+	}
+	get definitions() {
+		this.#ensureAlive();
+		return this.#definitions;
+	}
+	previous() {
+		this.#ensureAlive();
+		return [...this.#previous];
+	}
+	entities() {
+		this.#ensureAlive();
+		return this.#previous.flatMap((result) => [...result.entities]);
+	}
+	add(result) {
+		this.#ensureAlive();
+		this.#previous.push(result);
+		while (this.#previous.length > this.#history) this.#previous.shift();
+		this.#emitter.emit("add", result.digest);
+	}
+	clear() {
+		this.#ensureAlive();
+		this.#previous.length = 0;
+		this.#subjects.remove();
+		this.#definitions.remove();
+		this.#emitter.emit("clear");
+	}
+	destroy() {
+		if (this.#destroyed) return;
+		this.#previous.length = 0;
+		this.#subjects.destroy();
+		this.#definitions.destroy();
+		this.#destroyed = true;
+		this.#emitter.emit("destroy");
+		this.#emitter.destroy();
+	}
+	#ensureAlive() {
+		if (this.#destroyed) throw new InterpretError("DESTROYED", "Interpret context has been destroyed");
+	}
+};
+//#endregion
+//#region src/core/managers/TemplateManager.ts
+/**
+* The template registry — a self-owning, versioned and content-hashed
+* record-holder for the {@link Template}s an `Interpret` orchestrator matches
+* against.
+*
+* @remarks
+* `size` (never `count` — the sole tally in scope) plus the AGENTS §9.1
+* singular/plural accessors (`template` / `templates`) and the §9.2 batch
+* `remove` overloads. `add` derives each record's `hash` from the template's
+* CONTENT (id-independent — the same template data hashes identically under
+* any record id) and bumps `version` ONLY when that hash changes: an identical
+* re-add keeps its version (unlike scsr, which bumped on every add). The
+* batch `remove(ids)` form is ALL-OR-NOTHING — any id absent from the registry
+* leaves the collection untouched and returns `false`. `destroy()` is
+* idempotent; every method afterwards throws `InterpretError('DESTROYED', …)`.
+*
+* @example
+* ```ts
+* import { factorGroup, fieldFactor, quantitativeDefinition } from '@orkestrel/reason'
+* import { TemplateManager } from '@src/core'
+*
+* const manager = new TemplateManager()
+* const record = manager.add({
+* 	id: 't1',
+* 	name: 'Arithmetic',
+* 	domain: 'arithmetic',
+* 	intents: ['calculate'],
+* 	mappings: [],
+* 	defaults: [],
+* 	computations: [],
+* 	definition: quantitativeDefinition('t1', 'Arithmetic', [
+* 		factorGroup('total', 'sum', [fieldFactor('value', 'value')]),
+* 	]),
+* })
+* record.version // 1
+* manager.size // 1
+* ```
+*/
+var TemplateManager = class {
+	#records = /* @__PURE__ */ new Map();
+	#emitter;
+	#destroyed = false;
+	constructor(options) {
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		for (const template of options?.templates ?? []) this.add(template);
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get size() {
+		this.#ensureAlive();
+		return this.#records.size;
+	}
+	has(id) {
+		this.#ensureAlive();
+		return this.#records.has(id);
+	}
+	template(id) {
+		this.#ensureAlive();
+		return this.#records.get(id);
+	}
+	templates() {
+		this.#ensureAlive();
+		return [...this.#records.values()];
+	}
+	add(template, options) {
+		this.#ensureAlive();
+		const id = options?.id ?? template.id;
+		const hash = digestValue(template);
+		const existing = this.#records.get(id);
+		const record = {
+			id,
+			template,
+			version: existing === void 0 ? 1 : existing.hash === hash ? existing.version : existing.version + 1,
+			hash
+		};
+		this.#records.set(id, record);
+		this.#emitter.emit("add", id);
+		return record;
+	}
+	remove(target) {
+		this.#ensureAlive();
+		if (target === void 0) {
+			for (const id of this.#records.keys()) this.#emitter.emit("remove", id);
+			this.#records.clear();
+			return;
+		}
+		if (typeof target === "string") {
+			const removed = this.#records.delete(target);
+			if (removed) this.#emitter.emit("remove", target);
+			return removed;
+		}
+		for (const id of target) if (!this.#records.has(id)) return false;
+		for (const id of target) {
+			this.#records.delete(id);
+			this.#emitter.emit("remove", id);
+		}
+		return true;
+	}
+	destroy() {
+		if (this.#destroyed) return;
+		this.#records.clear();
+		this.#destroyed = true;
+		this.#emitter.emit("destroy");
+		this.#emitter.destroy();
+	}
+	#ensureAlive() {
+		if (this.#destroyed) throw new InterpretError("DESTROYED", "Template manager has been destroyed");
+	}
+};
+//#endregion
+//#region src/core/Narrator.ts
+/**
+* A stateless, TOTAL, lexicon-driven rendering engine for the reverse
+* direction — the reverse-direction mirror of the forward `Formatter`'s
+* `verbs` seam (AGENTS §21 mechanism-never-policy).
+*
+* @remarks
+* Every wording decision is DATA — a caller-supplied `Lexicon` merged, per
+* sub-record (`phrases` / `labels` / `templates`), OVER `DEFAULT_LEXICON`.
+* Stateless and holds no resources: no emitter, no `destroy()` (deliberate —
+* there is nothing to release). Every method is total (never throws); a
+* lexicon or formatter miss degrades to its documented fallback rather than
+* a thrown error, and every lookup guards with `Object.hasOwn` so an
+* adversarial key (`toString`, `constructor`, `__proto__`) misses cleanly
+* instead of reading an inherited prototype member.
+*
+* @example
+* ```ts
+* import { Narrator } from '@src/core'
+*
+* const narrator = new Narrator({
+* 	lexicon: { phrases: { comparison: { equals: 'is' } } },
+* 	formatters: { money: (value) => `$${String(value)}` },
+* })
+* narrator.phrase('comparison', 'equals', 'equals') // 'is'
+* narrator.phrase('comparison', 'missing', 'equals') // 'equals' — fallback
+* narrator.value('money', 5) // '$5'
+* ```
+*/
+var Narrator = class {
+	#lexicon;
+	#formatters;
+	constructor(options) {
+		this.#lexicon = {
+			phrases: {
+				...DEFAULT_LEXICON.phrases,
+				...options?.lexicon?.phrases
+			},
+			labels: {
+				...DEFAULT_LEXICON.labels,
+				...options?.lexicon?.labels
+			},
+			templates: {
+				...DEFAULT_LEXICON.templates,
+				...options?.lexicon?.templates
+			}
+		};
+		this.#formatters = { ...options?.formatters };
+	}
+	phrase(table, key, fallback) {
+		if (Object.hasOwn(this.#lexicon.phrases, table)) {
+			const row = this.#lexicon.phrases[table];
+			if (row !== null && row !== void 0 && Object.hasOwn(row, key)) {
+				const value = row[key];
+				if (typeof value === "string") return value;
+			}
+		}
+		return fallback ?? key;
+	}
+	label(field) {
+		const key = formatField(field);
+		if (Object.hasOwn(this.#lexicon.labels, key)) {
+			const value = this.#lexicon.labels[key];
+			if (typeof value === "string") return value;
+		}
+		return key;
+	}
+	line(id, values) {
+		if (!Object.hasOwn(this.#lexicon.templates, id)) return "";
+		const template = this.#lexicon.templates[id];
+		return typeof template === "string" ? fillTemplate(template, values, { missing: "empty" }) : "";
+	}
+	value(unit, raw) {
+		if (Object.hasOwn(this.#formatters, unit)) {
+			const formatter = this.#formatters[unit];
+			if (typeof formatter === "function") try {
+				return formatter(raw);
+			} catch {
+				return String(raw);
+			}
+		}
+		return String(raw);
+	}
+	describe(definition) {
+		switch (definition.reasoning) {
+			case "quantitative": return this.line("definition.quantitative", {
+				name: definition.name,
+				count: definition.groups.length
+			});
+			case "logical": return this.line("definition.logical", {
+				name: definition.name,
+				count: definition.rules.length,
+				strategy: definition.strategy
+			});
+			case "symbolic": return this.line("definition.symbolic", {
+				name: definition.name,
+				count: definition.equations.length
+			});
+			case "inferential": return this.line("definition.inferential", {
+				name: definition.name,
+				facts: definition.facts.length,
+				inferences: definition.inferences.length,
+				strategy: definition.strategy
+			});
+		}
+	}
+	narrate(result) {
+		switch (result.reasoning) {
+			case "quantitative": {
+				const base = this.line("result.quantitative", {
+					value: result.value,
+					count: result.count
+				});
+				if (result.errors.length === 0) return base;
+				return `${base}${this.line("result.quantitative.failed", { errors: result.errors.join(", ") })}`;
+			}
+			case "logical": return this.line("result.logical", {
+				status: result.conclusion ? "met" : "unmet",
+				count: result.count
+			});
+			case "symbolic": {
+				const solved = Object.entries(result.solutions).map(([key, value]) => `${key}=${value}`).join(", ");
+				return this.line("result.symbolic", { solved });
+			}
+			case "inferential": return this.line("result.inferential", { count: result.derived.length });
+		}
+	}
+};
+//#endregion
+//#region src/core/stages/Clarifier.ts
+/**
+* The `Clarifier` stage: resolves same-domain carry-over, template defaults,
+* and declaratively computed fields against an already-assigned entity set,
+* surfacing an {@link Ambiguity} for every required mapping that stays
+* unresolved.
+*
+* @remarks
+* Resolution order: fresh (already-assigned) entities always win; carry-over
+* fills a mapping only from the SAME domain's most recent prior turn (a
+* domain change drops carry-over entirely) and never overwrites a fresh
+* value; template defaults fill any field still unresolved after carry-over;
+* computed fields resolve in dependency (topological) order via
+* `resolveExpression` — an unresolved input, a non-finite result, or a
+* dependency cycle leaves the field a gap, never landing an entity. `floor`
+* (from {@link ClarifierOptions}, never hardcoded — AGENTS-flagged scsr
+* defect 4) gates whether a resolved entity's confidence counts as
+* "resolved enough" when raising ambiguities — a field with a value below
+* `floor` still raises its ambiguity.
+*
+* @example
+* ```ts
+* import { Clarifier } from '@src/core'
+*
+* const clarifier = new Clarifier({ floor: 0.3 })
+* clarifier.clarify(
+* 	[],
+* 	{
+* 		id: 't1',
+* 		name: 'Arithmetic',
+* 		domain: 'arithmetic',
+* 		intents: ['calculate'],
+* 		mappings: [{ entity: 'value', aliases: [], field: 'value', required: true }],
+* 		defaults: [],
+* 		computations: [],
+* 		definition: { reasoning: 'symbolic', id: 't1', name: 'Arithmetic', equations: [], variables: {} },
+* 	},
+* 	undefined,
+* 	{ action: 'calculate', domain: 'arithmetic', confidence: 1 },
+* ) // { entities: [], ambiguities: [{ field: 'value', ... }], complete: false }
+* ```
+*/
+var Clarifier = class {
+	#floor;
+	constructor(options) {
+		this.#floor = options?.floor ?? .3;
+	}
+	clarify(entities, template, context, intent) {
+		const resolved = [...entities];
+		const filledEntityNames = new Set(resolved.map((entity) => entity.name));
+		const filledFields = new Set(resolved.map((entity) => {
+			const mapping = template.mappings.find((candidate) => candidate.entity === entity.name);
+			return mapping === void 0 ? entity.name : formatField(mapping.field);
+		}));
+		this.#carryOver(template, context, intent, filledEntityNames, filledFields, resolved);
+		this.#fillDefaults(template, filledFields, resolved);
+		this.#resolveComputations(template, filledFields, resolved);
+		const ambiguities = this.#collectAmbiguities(template, resolved);
+		return {
+			entities: resolved,
+			ambiguities,
+			complete: ambiguities.length === 0
+		};
+	}
+	#carryOver(template, context, intent, filledEntityNames, filledFields, resolved) {
+		if (context === void 0) return;
+		const sameDomain = context.previous().filter((prior) => prior.intent.domain === intent.domain);
+		for (const mapping of template.mappings) {
+			if (filledEntityNames.has(mapping.entity)) continue;
+			for (let index = sameDomain.length - 1; index >= 0; index -= 1) {
+				const found = sameDomain[index]?.entities.find((entity) => entity.name === mapping.entity);
+				if (found === void 0) continue;
+				resolved.push({
+					name: mapping.entity,
+					value: found.value,
+					provenance: { category: "carried" },
+					confidence: CONFIDENCE_CARRIED
+				});
+				filledEntityNames.add(mapping.entity);
+				filledFields.add(formatField(mapping.field));
+				break;
+			}
+		}
+	}
+	#fillDefaults(template, filledFields, resolved) {
+		for (const fieldDefault of template.defaults) {
+			const key = formatField(fieldDefault.field);
+			if (filledFields.has(key)) continue;
+			const mapping = template.mappings.find((candidate) => formatField(candidate.field) === key);
+			resolved.push({
+				name: mapping?.entity ?? key,
+				value: fieldDefault.value,
+				provenance: { category: "default" },
+				confidence: 1
+			});
+			filledFields.add(key);
+		}
+	}
+	#resolveComputations(template, filledFields, resolved) {
+		const bindings = {};
+		for (const entity of resolved) {
+			const mapping = template.mappings.find((candidate) => candidate.entity === entity.name);
+			const field = mapping === void 0 ? entity.name : formatField(mapping.field);
+			if (isFiniteNumber(entity.value)) bindings[field] = entity.value;
+		}
+		for (const computation of this.#orderComputations(template.computations)) {
+			const key = formatField(computation.field);
+			if (filledFields.has(key)) continue;
+			const value = resolveExpression(computation.expression, bindings);
+			if (value === void 0) continue;
+			const mapping = template.mappings.find((candidate) => formatField(candidate.field) === key);
+			resolved.push({
+				name: mapping?.entity ?? key,
+				value,
+				provenance: { category: "computed" },
+				confidence: CONFIDENCE_COMPUTED
+			});
+			filledFields.add(key);
+			bindings[key] = value;
+		}
+	}
+	#orderComputations(computations) {
+		const byField = /* @__PURE__ */ new Map();
+		for (const computation of computations) byField.set(formatField(computation.field), computation);
+		const dependents = /* @__PURE__ */ new Map();
+		const inDegree = /* @__PURE__ */ new Map();
+		for (const key of byField.keys()) inDegree.set(key, 0);
+		for (const [key, computation] of byField) {
+			const dependencies = variablesOf(computation.expression).filter((name) => byField.has(name));
+			inDegree.set(key, dependencies.length);
+			for (const dependency of dependencies) {
+				const list = dependents.get(dependency) ?? [];
+				list.push(key);
+				dependents.set(dependency, list);
+			}
+		}
+		const queue = [];
+		for (const [key, degree] of inDegree) if (degree === 0) queue.push(key);
+		const ordered = [];
+		let cursor = 0;
+		while (cursor < queue.length) {
+			const key = queue[cursor];
+			cursor += 1;
+			if (key === void 0) continue;
+			const computation = byField.get(key);
+			if (computation !== void 0) ordered.push(computation);
+			for (const dependent of dependents.get(key) ?? []) {
+				const next = (inDegree.get(dependent) ?? 0) - 1;
+				inDegree.set(dependent, next);
+				if (next === 0) queue.push(dependent);
+			}
+		}
+		return ordered;
+	}
+	#collectAmbiguities(template, resolved) {
+		const ambiguities = [];
+		for (const mapping of template.mappings) {
+			if (mapping.required !== true) continue;
+			const entity = resolved.find((candidate) => candidate.name === mapping.entity);
+			if (entity !== void 0 && entity.confidence >= this.#floor) continue;
+			ambiguities.push({
+				field: mapping.field,
+				question: `What is your ${mapping.entity}?`,
+				candidates: [],
+				required: true
+			});
+		}
+		return ambiguities;
+	}
+};
+//#endregion
+//#region src/core/stages/Extractor.ts
+/**
+* The `Extractor` stage: template-agnostic intent classification plus raw
+* numeric-entity mining.
+*
+* @remarks
+* Deliberately never named `Parser` — the `contracts` module already owns
+* `Parser<T>`, so a class of that name would collide in type space (AGENTS
+* §21, design ledger 3). `extract` never sees a `Template`: numbers →
+* entity ASSIGNMENT is a separate orchestrator-owned step that runs only
+* after a template has matched (`assignEntities` in `helpers.ts`), not
+* inside this stage (the defect-3 fix — scsr's parser mined template-shaped
+* entities directly and only worked via an `instanceof` hack).
+*
+* @example
+* ```ts
+* import { Extractor } from '@src/core'
+*
+* const extractor = new Extractor({
+* 	actions: { calculate: 'compute' },
+* 	domains: { rating: ['rate'] },
+* })
+* extractor.extract('calculate my rate at 85')
+* // { intent: { action: 'compute', domain: 'rating', confidence: 1 }, numbers: [85], complete: true }
+* ```
+*/
+var Extractor = class {
+	#actions;
+	#domains;
+	constructor(options) {
+		this.#actions = {
+			...DEFAULT_ACTIONS,
+			...options?.actions
+		};
+		this.#domains = {
+			...DEFAULT_DOMAINS,
+			...options?.domains
+		};
+	}
+	extract(text) {
+		const numbers = extractNumbers(text);
+		const intent = classifyIntent(text, this.#actions, this.#domains);
+		return {
+			intent,
+			numbers,
+			complete: numbers.length > 0 && intent.confidence > 0
+		};
+	}
+};
+//#endregion
+//#region src/core/stages/Formatter.ts
+/**
+* The `Formatter` stage: renders the refined natural-language prompt for a
+* matched template.
+*
+* @remarks
+* Shape: `{verb} {template.name}` + ` with {label}: {value}, …` for every
+* non-default entity (via the core-root `formatField`) + `
+* (defaults: {label}: {value}, …)` for default-provenance entities + `
+* needed: {question} …` for every ambiguity. `verbs` maps `intent.action` to
+* its display verb; an action absent from the map falls back to the action
+* string itself. Every parameter is read — no ignored `context` argument
+* (AGENTS-flagged scsr defect 5).
+*
+* @example
+* ```ts
+* import { Formatter } from '@src/core'
+*
+* const formatter = new Formatter({ verbs: { calculate: 'Calculate' } })
+* formatter.format(
+* 	{ action: 'calculate', domain: 'arithmetic', confidence: 1 },
+* 	{
+* 		id: 't1',
+* 		name: 'Arithmetic',
+* 		domain: 'arithmetic',
+* 		intents: ['calculate'],
+* 		mappings: [],
+* 		defaults: [],
+* 		computations: [],
+* 		definition: { reasoning: 'symbolic', id: 't1', name: 'Arithmetic', equations: [], variables: {} },
+* 	},
+* 	[],
+* 	[],
+* ) // { prompt: 'Calculate Arithmetic' }
+* ```
+*/
+var Formatter = class {
+	#verbs;
+	constructor(options) {
+		this.#verbs = {
+			...DEFAULT_VERBS,
+			...options?.verbs
+		};
+	}
+	format(intent, template, entities, ambiguities) {
+		const verb = this.#verbs[intent.action] ?? intent.action;
+		const render = (list) => list.map((entity) => `${formatField(entity.name)}: ${String(entity.value)}`).join(", ");
+		let prompt = `${verb} ${template.name}`;
+		const resolved = entities.filter((entity) => entity.provenance.category !== "default");
+		if (resolved.length > 0) prompt += ` with ${render(resolved)}`;
+		const defaults = entities.filter((entity) => entity.provenance.category === "default");
+		if (defaults.length > 0) prompt += ` (defaults: ${render(defaults)})`;
+		if (ambiguities.length > 0) prompt += ` needed: ${ambiguities.map((ambiguity) => ambiguity.question).join(" ")}`;
+		return { prompt };
+	}
+};
+//#endregion
+//#region src/core/stages/Generator.ts
+/**
+* The `Generator` stage: builds the final `Subject` from a fully resolved
+* entity set, plus its complete field audit.
+*
+* @remarks
+* `entity → field` via `template.mappings` (an `EntityMapping.entity` name
+* lookup); an entity whose name matches no mapping lands on the field named
+* by its OWN `name` — the shape `Clarifier` uses for its synthesized
+* default/computed entities, so one lookup rule serves both extraction-
+* mapped and template-data-derived fields. A single-element array value
+* unwraps to its scalar; a multi-element, ALL-numeric array value stays an
+* array AND additionally emits five aggregate fields (`Sum` / `Count` /
+* `Average` / `Minimum` / `Maximum`, provenance `computed`), each derived as
+* a SIBLING path beside the source field via `deriveAggregateField` — for an
+* array `FieldPath` (e.g. `['address', 'amounts']`) the aggregates nest
+* (`['address', 'amountsSum']`, ...); for a plain string field they stay
+* flat (`'amountsSum'`), matching the source field's own shape.
+* `confidence` is the mean of the input entities' own confidences (`0` for
+* an empty entity set). A `FieldMapping` is emitted for EVERY field that
+* lands on the subject, including defaults, computed fields, and aggregates
+* — scsr silently omitted defaults/computed from its audit trail; this
+* closes that gap. `GeneratorOptions` is a reserved extension seam — the
+* stage has no knobs yet, so construction takes no arguments until one
+* exists.
+*
+* @example
+* ```ts
+* import { Generator } from '@src/core'
+*
+* const generator = new Generator()
+* generator.generate(
+* 	[
+* 		{
+* 			name: 'value',
+* 			value: 42,
+* 			provenance: { category: 'extracted', detail: 'collect' },
+* 			confidence: 0.9,
+* 		},
+* 	],
+* 	{
+* 		id: 't1',
+* 		name: 'Arithmetic',
+* 		domain: 'arithmetic',
+* 		intents: ['calculate'],
+* 		mappings: [{ entity: 'value', aliases: [], field: 'value' }],
+* 		defaults: [],
+* 		computations: [],
+* 		definition: { reasoning: 'symbolic', id: 't1', name: 'Arithmetic', equations: [], variables: {} },
+* 	},
+* ) // { subject: { value: 42 }, mappings: [...], confidence: 0.9, ... }
+* ```
+*/
+var Generator = class {
+	generate(entities, template) {
+		let subject = {};
+		const mappings = [];
+		for (const entity of entities) {
+			const mapping = template.mappings.find((candidate) => candidate.entity === entity.name);
+			const field = mapping === void 0 ? entity.name : mapping.field;
+			const value = entity.value;
+			if (Array.isArray(value) && value.length === 1) {
+				const scalar = value[0];
+				subject = setField(subject, field, scalar);
+				mappings.push({
+					field,
+					entity: entity.name,
+					value: scalar,
+					provenance: entity.provenance,
+					confidence: entity.confidence
+				});
+				continue;
+			}
+			if (Array.isArray(value) && value.length > 1) {
+				const numeric = [];
+				for (const item of value) {
+					if (!isFiniteNumber(item)) break;
+					numeric.push(item);
+				}
+				if (numeric.length === value.length) {
+					subject = setField(subject, field, value);
+					mappings.push({
+						field,
+						entity: entity.name,
+						value,
+						provenance: entity.provenance,
+						confidence: entity.confidence
+					});
+					const sum = numeric.reduce((total, item) => total + item, 0);
+					const minimum = numeric.reduce((min, item) => item < min ? item : min, numeric[0]);
+					const maximum = numeric.reduce((max, item) => item > max ? item : max, numeric[0]);
+					const aggregates = [
+						[deriveAggregateField(field, "Sum"), sum],
+						[deriveAggregateField(field, "Count"), numeric.length],
+						[deriveAggregateField(field, "Average"), sum / numeric.length],
+						[deriveAggregateField(field, "Minimum"), minimum],
+						[deriveAggregateField(field, "Maximum"), maximum]
+					];
+					for (const [aggregateField, aggregateValue] of aggregates) {
+						subject = setField(subject, aggregateField, aggregateValue);
+						mappings.push({
+							field: aggregateField,
+							value: aggregateValue,
+							provenance: { category: "computed" },
+							confidence: CONFIDENCE_COMPUTED
+						});
+					}
+					continue;
+				}
+			}
+			subject = setField(subject, field, value);
+			mappings.push({
+				field,
+				entity: entity.name,
+				value,
+				provenance: entity.provenance,
+				confidence: entity.confidence
+			});
+		}
+		const confidence = entities.length === 0 ? 0 : entities.reduce((total, entity) => total + entity.confidence, 0) / entities.length;
+		return {
+			subject,
+			definition: template.definition,
+			mappings,
+			confidence
+		};
+	}
+};
+//#endregion
+//#region src/core/stages/Normalizer.ts
+/**
+* The `Normalizer` stage: applies contraction, abbreviation, and correction
+* substitutions in order, then collapses whitespace.
+*
+* @remarks
+* Each caller map is merged OVER the neutral built-in default for its slot —
+* `text` is never mutated (AGENTS §11). Every substitution actually applied
+* (one entry per matching map KEY, not per occurrence) is recorded on the
+* result's `changes`, in `contractions → abbreviations → corrections` order,
+* so the audit trail explains every character difference between `text` and
+* `NormalizeResult.text` (the final whitespace collapse carries no entry of
+* its own — it is structural cleanup, not a substitution).
+*
+* @example
+* ```ts
+* import { Normalizer } from '@src/core'
+*
+* const normalizer = new Normalizer({ contractions: { "can't": 'cannot' } })
+* normalizer.normalize("can't   stop")
+* // { text: 'cannot stop', changes: [{ from: "can't", to: 'cannot' }] }
+* ```
+*/
+var Normalizer = class {
+	#contractions;
+	#abbreviations;
+	#corrections;
+	constructor(options) {
+		this.#contractions = {
+			...DEFAULT_CONTRACTIONS,
+			...options?.contractions
+		};
+		this.#abbreviations = {
+			...DEFAULT_ABBREVIATIONS,
+			...options?.abbreviations
+		};
+		this.#corrections = {
+			...DEFAULT_CORRECTIONS,
+			...options?.corrections
+		};
+	}
+	normalize(text) {
+		const changes = [];
+		let working = text;
+		for (const map of [
+			this.#contractions,
+			this.#abbreviations,
+			this.#corrections
+		]) {
+			const applied = this.#applyStage(working, map);
+			working = applied.text;
+			changes.push(...applied.changes);
+		}
+		return {
+			text: collapseWhitespace(working),
+			changes
+		};
+	}
+	#applyStage(text, map) {
+		let working = text;
+		const changes = [];
+		for (const [from, to] of Object.entries(map)) if (new RegExp(`\\b${escapeRegExp(from)}\\b`, "i").test(working)) {
+			working = applyReplacements(working, { [from]: to });
+			changes.push({
+				from,
+				to
+			});
+		}
+		return {
+			text: working,
+			changes
+		};
+	}
+};
+//#endregion
+//#region src/core/Interpret.ts
+/**
+* The interpretation orchestrator — the sole public entry point of the
+* `interprets` module, mirroring the reasons `Reason` orchestrator shape.
+*
+* @remarks
+* `interpret()` is genuinely SYNCHRONOUS (scsr's was fake-async with zero
+* `await`s) and runs a fixed five-stage pipeline —
+* `[normalize, extract, clarify, format, generate]` — each producing one
+* {@link StageRecord}. Between `extract` and `clarify` the orchestrator matches
+* the classified {@link Intent} against its registered {@link Template}s and,
+* on a match, assigns the extracted numbers to that template's mappings
+* (`assignEntities`) — a template-owned step, not a sixth stage. No match, or a
+* matched template whose intent confidence falls below the configured `floor`,
+* yields an explicit, auditable INCOMPLETE result (a `field: 'intent'`
+* ambiguity, absent subject/definition) rather than scsr's arbitrary
+* `templates[0]` fallback. A stage THROW is caught, marked on its record AND on
+* `failures`, emitted as `error`, and still yields a visible incomplete result
+* — never a silent fallback. Every result carries a `digest` over its original
+* text plus the matched template id/version and the built subject/definition,
+* so re-running the same text against the same template version reproduces the
+* same digest (the replay contract). `describe` / `narrate` are the reverse
+* direction (structure → prose). `destroy()` is idempotent, tears down the
+* registry and context, then destroys the emitter LAST (AGENTS §13); every
+* method afterwards except the {@link emitter} getter throws
+* `InterpretError('DESTROYED', …)`.
+*
+* @example
+* ```ts
+* import { factorGroup, fieldFactor, quantitativeDefinition } from '@orkestrel/reason'
+* import { Interpret, Extractor } from '@src/core'
+*
+* const interpret = new Interpret({
+* 	extractor: new Extractor({ actions: { calculate: 'calculate' }, domains: { arithmetic: ['arithmetic'] } }),
+* 	templates: [
+* 		{
+* 			id: 't1',
+* 			name: 'Arithmetic',
+* 			domain: 'arithmetic',
+* 			intents: ['calculate'],
+* 			mappings: [{ entity: 'value', aliases: [], field: 'value' }],
+* 			defaults: [],
+* 			computations: [],
+* 			definition: quantitativeDefinition('t1', 'Arithmetic', [
+* 				factorGroup('total', 'sum', [fieldFactor('value', 'value')]),
+* 			]),
+* 		},
+* 	],
+* })
+* interpret.interpret('calculate arithmetic 42').subject // { value: 42 }
+* ```
+*/
+var Interpret = class {
+	#templates;
+	#context;
+	#normalizer;
+	#extractor;
+	#clarifier;
+	#formatter;
+	#generator;
+	#similarity;
+	#floor;
+	#narrator;
+	#emitter;
+	#destroyed = false;
+	constructor(options) {
+		this.#similarity = options?.similarity ?? .8;
+		this.#floor = options?.floor ?? .3;
+		this.#templates = new TemplateManager({ templates: options?.templates });
+		this.#context = options?.context ?? new InterpretContext({ history: options?.history });
+		this.#normalizer = options?.normalizer ?? new Normalizer();
+		this.#extractor = options?.extractor ?? new Extractor();
+		this.#clarifier = options?.clarifier ?? new Clarifier({ floor: this.#floor });
+		this.#formatter = options?.formatter ?? new Formatter();
+		this.#generator = options?.generator ?? new Generator();
+		this.#narrator = new Narrator({
+			lexicon: options?.lexicon,
+			formatters: options?.formatters
+		});
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	interpret(text) {
+		this.#ensureAlive();
+		const stages = [];
+		let normalized;
+		try {
+			normalized = this.#normalizer.normalize(text);
+		} catch (error) {
+			return this.#abort(text, text, {
+				action: "",
+				domain: "",
+				confidence: 0
+			}, [], [], stages, "normalize", "NORMALIZE_FAILED", text, error, [
+				"extract",
+				"clarify",
+				"format",
+				"generate"
+			], void 0, void 0);
+		}
+		stages.push({
+			stage: "normalize",
+			input: text,
+			output: normalized,
+			failed: false
+		});
+		let extract;
+		try {
+			extract = this.#extractor.extract(normalized.text);
+		} catch (error) {
+			return this.#abort(text, normalized.text, {
+				action: "",
+				domain: "",
+				confidence: 0
+			}, [], [], stages, "extract", "EXTRACT_FAILED", normalized.text, error, [
+				"clarify",
+				"format",
+				"generate"
+			], void 0, void 0);
+		}
+		stages.push({
+			stage: "extract",
+			input: normalized.text,
+			output: extract,
+			failed: false
+		});
+		const intent = extract.intent;
+		const matched = matchTemplate(intent, this.#templates.templates().map((record) => record.template), this.#floor);
+		if (matched === void 0) return this.#gate(text, normalized.text, intent, [], stages, "NO_TEMPLATE", void 0, void 0);
+		const assigned = assignEntities(extract.numbers, matched.mappings, normalized.text, this.#similarity);
+		const version = this.#templates.template(matched.id)?.version;
+		if (intent.confidence < this.#floor) return this.#gate(text, normalized.text, intent, assigned, stages, "LOW_CONFIDENCE", matched.id, version);
+		let clarified;
+		try {
+			clarified = this.#clarifier.clarify(assigned, matched, this.#context, intent);
+		} catch (error) {
+			return this.#abort(text, normalized.text, intent, assigned, [], stages, "clarify", "CLARIFY_FAILED", assigned, error, ["format", "generate"], matched.id, version);
+		}
+		stages.push({
+			stage: "clarify",
+			input: assigned,
+			output: clarified,
+			failed: false
+		});
+		const formatInput = {
+			intent,
+			entities: clarified.entities,
+			ambiguities: clarified.ambiguities
+		};
+		let formatted;
+		try {
+			formatted = this.#formatter.format(intent, matched, clarified.entities, clarified.ambiguities);
+		} catch (error) {
+			return this.#abort(text, normalized.text, intent, clarified.entities, clarified.ambiguities, stages, "format", "FORMAT_FAILED", formatInput, error, ["generate"], matched.id, version);
+		}
+		stages.push({
+			stage: "format",
+			input: formatInput,
+			output: formatted,
+			failed: false
+		});
+		let generated;
+		try {
+			generated = this.#generator.generate(clarified.entities, matched);
+		} catch (error) {
+			return this.#abort(text, normalized.text, intent, clarified.entities, clarified.ambiguities, stages, "generate", "GENERATE_FAILED", clarified.entities, error, [], matched.id, version);
+		}
+		stages.push({
+			stage: "generate",
+			input: clarified.entities,
+			output: generated,
+			failed: false
+		});
+		const digest = digestValue({
+			text,
+			templateId: matched.id,
+			templateVersion: version,
+			subject: generated.subject,
+			definition: generated.definition
+		});
+		const result = {
+			text,
+			normalized: normalized.text,
+			intent,
+			entities: clarified.entities,
+			subject: generated.subject,
+			definition: generated.definition,
+			mappings: generated.mappings,
+			ambiguities: clarified.ambiguities,
+			prompt: formatted.prompt,
+			stages,
+			failures: [],
+			complete: clarified.complete,
+			confidence: generated.confidence,
+			digest
+		};
+		this.#context.subjects.add(generated.subject);
+		this.#context.definitions.add(generated.definition, { id: generated.definition.id });
+		this.#context.add(result);
+		this.#emitter.emit("interpret", result);
+		return result;
+	}
+	register(template) {
+		this.#ensureAlive();
+		this.#templates.add(template, { id: template.id });
+		this.#emitter.emit("register", template.id);
+	}
+	unregister(id) {
+		this.#ensureAlive();
+		return this.#templates.remove(id);
+	}
+	template(id) {
+		this.#ensureAlive();
+		return this.#templates.template(id)?.template;
+	}
+	templates() {
+		this.#ensureAlive();
+		return this.#templates.templates().map((record) => record.template);
+	}
+	describe(definition) {
+		this.#ensureAlive();
+		return this.#narrator.describe(definition);
+	}
+	narrate(result) {
+		this.#ensureAlive();
+		return this.#narrator.narrate(result);
+	}
+	destroy() {
+		if (this.#destroyed) return;
+		this.#templates.destroy();
+		this.#context.destroy();
+		this.#destroyed = true;
+		this.#emitter.emit("destroy");
+		this.#emitter.destroy();
+	}
+	#gate(text, normalized, intent, entities, stages, code, templateId, templateVersion) {
+		const domains = [...new Set(this.#templates.templates().map((record) => record.template.domain))];
+		const ambiguity = {
+			field: "intent",
+			question: code === "NO_TEMPLATE" ? "Which domain and action did you mean?" : "Which did you mean? The intent was too weak to act on.",
+			candidates: domains,
+			required: true
+		};
+		const failure = {
+			stage: "clarify",
+			code,
+			message: code === "NO_TEMPLATE" ? "No registered template matched the classified intent" : "Classified intent confidence fell below the configured floor"
+		};
+		return this.#assemble(text, normalized, intent, entities, [ambiguity], stages, [failure], [
+			"clarify",
+			"format",
+			"generate"
+		], templateId, templateVersion);
+	}
+	#abort(text, normalized, intent, entities, ambiguities, stages, stage, code, input, error, remaining, templateId, templateVersion) {
+		const message = error instanceof Error ? error.message : String(error);
+		stages.push({
+			stage,
+			input,
+			output: void 0,
+			failed: true,
+			error: message
+		});
+		this.#emitter.emit("error", error);
+		return this.#assemble(text, normalized, intent, entities, ambiguities, stages, [{
+			stage,
+			code,
+			message
+		}], remaining, templateId, templateVersion);
+	}
+	#assemble(text, normalized, intent, entities, ambiguities, stages, failures, remaining, templateId, templateVersion) {
+		for (const stage of remaining) stages.push({
+			stage,
+			input: void 0,
+			output: void 0,
+			failed: false
+		});
+		const digest = digestValue({
+			text,
+			templateId,
+			templateVersion,
+			subject: void 0,
+			definition: void 0
+		});
+		const result = {
+			text,
+			normalized,
+			intent,
+			entities,
+			mappings: [],
+			ambiguities,
+			prompt: "",
+			stages,
+			failures: [...failures],
+			complete: false,
+			confidence: 0,
+			digest
+		};
+		this.#context.add(result);
+		this.#emitter.emit("interpret", result);
+		return result;
+	}
+	#ensureAlive() {
+		if (this.#destroyed) throw new InterpretError("DESTROYED", "Interpret has been destroyed");
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* Create an interpretation orchestrator.
+*
+* @remarks
+* `interpret()` is genuinely synchronous and runs the fixed five-stage
+* pipeline `[normalize, extract, clarify, format, generate]`. Every stage
+* slot (`normalizer` / `extractor` / `clarifier` / `formatter` / `generator`)
+* is bring-your-own — a supplied implementation is used as-is, else the
+* built-in stage is constructed from the matching per-stage options.
+*
+* @param options - Optional templates, context, stage implementations, the
+*   `similarity` / `floor` axes, and emitter hooks
+* @returns A working {@link InterpretInterface}
+*
+* @example
+* ```ts
+* import { factorGroup, fieldFactor, quantitativeDefinition } from '@orkestrel/reason'
+* import { createInterpret } from '@src/core'
+*
+* const interpret = createInterpret({
+* 	extractor: { extract: () => ({ intent: { action: 'calculate', domain: 'arithmetic', confidence: 1 }, numbers: [42], complete: true }) },
+* 	templates: [
+* 		{
+* 			id: 't1',
+* 			name: 'Arithmetic',
+* 			domain: 'arithmetic',
+* 			intents: ['calculate'],
+* 			mappings: [{ entity: 'value', aliases: [], field: 'value' }],
+* 			defaults: [],
+* 			computations: [],
+* 			definition: quantitativeDefinition('t1', 'Arithmetic', [
+* 				factorGroup('total', 'sum', [fieldFactor('value', 'value')]),
+* 			]),
+* 		},
+* 	],
+* })
+* interpret.interpret('calculate arithmetic 42').subject // { value: 42 }
+* ```
+*/
+function createInterpret(options) {
+	return new Interpret(options);
+}
+/**
+* Create a text normalizer.
+*
+* @param options - Optional contraction / abbreviation / correction maps,
+*   merged over the neutral built-in defaults
+* @returns A stateless {@link NormalizerInterface}
+*
+* @example
+* ```ts
+* import { createNormalizer } from '@src/core'
+*
+* createNormalizer().normalize("it's  cold") // { text: 'it is cold', changes: [{ from: "it's", to: 'it is' }] }
+* ```
+*/
+function createNormalizer(options) {
+	return new Normalizer(options);
+}
+/**
+* Create a template-agnostic intent classifier and number extractor.
+*
+* @param options - Optional caller `actions` / `domains` vocabularies
+* @returns A stateless {@link ExtractorInterface}
+*
+* @example
+* ```ts
+* import { createExtractor } from '@src/core'
+*
+* const extractor = createExtractor({
+* 	actions: { calculate: 'calculate' },
+* 	domains: { arithmetic: ['arithmetic'] },
+* })
+* extractor.extract('calculate arithmetic 42').numbers // [42]
+* ```
+*/
+function createExtractor(options) {
+	return new Extractor(options);
+}
+/**
+* Create a clarifier — carry-over, defaults, and computed-field resolution
+* against an assigned entity set.
+*
+* @param options - Optional confidence `floor` for raised ambiguities
+* @returns A stateless {@link ClarifierInterface}
+*
+* @example
+* ```ts
+* import { createClarifier } from '@src/core'
+*
+* const clarifier = createClarifier({ floor: 0.5 })
+* ```
+*/
+function createClarifier(options) {
+	return new Clarifier(options);
+}
+/**
+* Create a prompt formatter.
+*
+* @param options - Optional caller intent-verb phrasing map
+* @returns A stateless {@link FormatterInterface}
+*
+* @example
+* ```ts
+* import { createFormatter } from '@src/core'
+*
+* const formatter = createFormatter({ verbs: { calculate: 'Calculate' } })
+* ```
+*/
+function createFormatter(options) {
+	return new Formatter(options);
+}
+/**
+* Create a subject/definition generator.
+*
+* @param options - Currently an empty extension seam
+* @returns A stateless {@link GeneratorInterface}
+*
+* @example
+* ```ts
+* import { createGenerator } from '@src/core'
+*
+* const generator = createGenerator()
+* ```
+*/
+function createGenerator(_options) {
+	return new Generator();
+}
+/**
+* Create a template registry.
+*
+* @param options - Optional initial seed collection
+* @returns A working {@link TemplateManagerInterface}
+*
+* @example
+* ```ts
+* import { factorGroup, fieldFactor, quantitativeDefinition } from '@orkestrel/reason'
+* import { createTemplate, createTemplateManager } from '@src/core'
+*
+* const template = createTemplate({
+* 	id: 't1', name: 'Arithmetic', domain: 'arithmetic', intents: ['calculate'],
+* 	mappings: [{ entity: 'value', aliases: [], field: 'value' }], defaults: [], computations: [],
+* 	definition: quantitativeDefinition('t1', 'Arithmetic', [factorGroup('total', 'sum', [fieldFactor('value', 'value')])]),
+* })
+* const templates = createTemplateManager({ templates: [template] })
+* templates.size // 1
+* ```
+*/
+function createTemplateManager(options) {
+	return new TemplateManager(options);
+}
+/**
+* Create a subject registry.
+*
+* @remarks
+* Mints its own record ids on `add` when none is supplied — a `Subject`
+* carries no `id` field of its own.
+*
+* @param options - Optional initial seed collection
+* @returns A working {@link SubjectManagerInterface}
+*
+* @example
+* ```ts
+* import { createSubjectManager } from '@src/core'
+*
+* const subjects = createSubjectManager({ subjects: [{ value: 1 }] })
+* subjects.size // 1
+* ```
+*/
+function createSubjectManager(options) {
+	return new SubjectManager(options);
+}
+/**
+* Create a definition registry.
+*
+* @param options - Optional initial seed collection
+* @returns A working {@link DefinitionManagerInterface}
+*
+* @example
+* ```ts
+* import { factorGroup, fieldFactor, quantitativeDefinition } from '@orkestrel/reason'
+* import { createDefinitionManager } from '@src/core'
+*
+* const definitions = createDefinitionManager({
+* 	definitions: [quantitativeDefinition('d1', 'D1', [factorGroup('total', 'sum', [fieldFactor('value', 'value')])])],
+* })
+* definitions.size // 1
+* ```
+*/
+function createDefinitionManager(options) {
+	return new DefinitionManager(options);
+}
+/**
+* Create a cross-turn interpretation context.
+*
+* @param options - Optional `session` label and `history` ring-buffer cap
+* @returns A working {@link InterpretContextInterface}
+*
+* @example
+* ```ts
+* import { createInterpretContext } from '@src/core'
+*
+* const context = createInterpretContext({ session: 'turn-1', history: 4 })
+* context.previous() // []
+* ```
+*/
+function createInterpretContext(options) {
+	return new InterpretContext(options);
+}
+/**
+* Build and validate one interpretation template from plain data.
+*
+* @remarks
+* The factory/coercer pair for template intake (AGENTS §4.6.1): this throws
+* on malformed data, while `parseTemplate` returns `undefined`. Data failing
+* {@link isTemplate} throws `InterpretError('INVALID_TEMPLATE', …)`.
+*
+* @param data - The candidate template data
+* @returns The same data, now known to satisfy {@link Template}
+* @throws {@link InterpretError} `INVALID_TEMPLATE` when `data` fails validation
+*
+* @example
+* ```ts
+* import { factorGroup, fieldFactor, quantitativeDefinition } from '@orkestrel/reason'
+* import { createTemplate } from '@src/core'
+*
+* const template = createTemplate({
+* 	id: 't1', name: 'Arithmetic', domain: 'arithmetic', intents: ['calculate'],
+* 	mappings: [{ entity: 'value', aliases: [], field: 'value' }], defaults: [], computations: [],
+* 	definition: quantitativeDefinition('t1', 'Arithmetic', [factorGroup('total', 'sum', [fieldFactor('value', 'value')])]),
+* })
+* template.id // 't1'
+* ```
+*/
+function createTemplate(data) {
+	if (!isTemplate(data)) throw new InterpretError("INVALID_TEMPLATE", "Template data failed validation");
+	return data;
+}
+/**
+* Create a lexicon-driven reverse-direction rendering engine.
+*
+* @remarks
+* Stateless — `phrase` / `label` / `line` / `value` are total lookups into a
+* caller `Lexicon` merged over `DEFAULT_LEXICON`, and `describe` / `narrate`
+* compose them over a reasons `Definition` / `ReasonResult`.
+*
+* @param options - Optional `lexicon` and `formatters` map
+* @returns A stateless {@link NarratorInterface}
+*
+* @example
+* ```ts
+* import { createNarrator } from '@src/core'
+*
+* const narrator = createNarrator({ lexicon: { templates: { 'subject.empty': 'nothing here' } } })
+* narrator.line('subject.empty', {}) // 'nothing here'
+* ```
+*/
+function createNarrator(options) {
+	return new Narrator(options);
+}
+//#endregion
+export { CONFIDENCE_ALIAS, CONFIDENCE_CARRIED, CONFIDENCE_COLLECT, CONFIDENCE_COMPUTED, CONFIDENCE_DEFAULT, CONFIDENCE_EXACT, CONFIDENCE_POSITIONAL, Clarifier, DEFAULT_ABBREVIATIONS, DEFAULT_ACTIONS, DEFAULT_CONTRACTIONS, DEFAULT_CORRECTIONS, DEFAULT_DOMAINS, DEFAULT_INTERPRET_FLOOR, DEFAULT_INTERPRET_HISTORY, DEFAULT_INTERPRET_SIMILARITY, DEFAULT_LEXICON, DEFAULT_VERBS, DefinitionManager, Extractor, Formatter, Generator, INTERPRET_ID, Interpret, InterpretContext, InterpretError, NUMBER_PATTERN, Narrator, Normalizer, SubjectManager, TemplateManager, UNSAFE_FIELD_SEGMENTS, applyReplacements, assignEntities, canonicalize, classifyIntent, collapseWhitespace, createClarifier, createDefinitionManager, createExtractor, createFormatter, createGenerator, createInterpret, createInterpretContext, createNarrator, createNormalizer, createSubjectManager, createTemplate, createTemplateManager, deriveAggregateField, describeSubject, digestValue, escapeRegExp, extractNumbers, isComputedField, isEntityMapping, isFieldDefault, isInterpretError, isTemplate, matchAlias, matchTemplate, parseTemplate, resolveExpression, scoreSimilarity, scoreTemplate, setField, tokenize, variablesOf };
+
+//# sourceMappingURL=index.js.map