@orkestrel/interpret 0.0.1 → 0.0.3

package/dist/src/core/index.js

@@ -1,2636 +0,0 @@
-import { arrayOf, isBoolean, isFiniteNumber, isRecord, isString, notOf, parseJSONAs, recordOf, resolveField, unionOf } from "@orkestrel/contract";
-import { applyOperation, formatField, isDefinition, isFieldPath, isSymbolicExpression } from "@orkestrel/reason";
-import { Emitter } from "@orkestrel/emitter";
-//#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
-* `interpolateMessage` 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)
-	};
-}
-/**
-* Interpolate `{{dotted.path}}` tokens in a message template against a record.
-*
-* @remarks
-* Each token is split on `.` into a {@link FieldPath} array and resolved with
-* the contracts `resolveField` (a plain string field is ONE key, never
-* dot-split — the split here is the token-to-path bridge). A finite number
-* renders with `en-US` thousand grouping (`5010` → `5,010`); any other
-* resolved value String-coerces. An UNRESOLVED path (the resolved value is
-* `undefined`) renders as the empty string — the deterministic "nothing to
-* show" rule.
-*
-* @param template - The message template carrying `{{dotted.path}}` tokens
-* @param record - The record tokens resolve against
-* @returns The template with every token replaced
-*
-* @example
-* ```ts
-* import { interpolateMessage } from '@src/core'
-*
-* interpolateMessage('Limit is {{limit}}', { limit: 5010 }) // 'Limit is 5,010'
-* interpolateMessage('Missing {{gone}}', {})                // 'Missing '
-* ```
-*/
-function interpolateMessage(template, record) {
-	return template.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_match, path) => {
-		const value = resolveField(record, path.split("."));
-		if (value === void 0) return "";
-		if (isFiniteNumber(value)) return value.toLocaleString("en-US");
-		return String(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" ? interpolateMessage(template, values) : "";
-	}
-	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, interpolateMessage, isComputedField, isEntityMapping, isFieldDefault, isInterpretError, isTemplate, matchAlias, matchTemplate, parseTemplate, resolveExpression, scoreSimilarity, scoreTemplate, setField, tokenize, variablesOf };
-
-//# sourceMappingURL=index.js.map