docs/decisions/0010-shared-normalization-contract.md

0010 Shared Normalization Contract

Date: 2026-07-13

Status

Accepted

Context

Interpreter, Scribe scoring, training scoring, and both lexical retrievers carried local normalization implementations. Their names overlapped, but their contracts differed: the Interpreter normalizes units, Vietnamese number words, and relative dates; scoring compares case-insensitively without semantic conversion; lexical retrieval additionally folds diacritics and punctuation.

Decision

Create the installable shared/carepath_shared package. Move the Interpreter normalizer there unchanged as normalize_text, and make every former local normalizer a direct import from this package. Keep the existing scoring and retrieval semantics as the separately named normalize_for_metrics and normalize_for_match functions, rather than silently changing metric scores or term matching.

Consequences

• Normalization algorithms have one owner and one characterization suite.
• Existing module import paths remain compatible.
• A future semantic consolidation must explicitly revise the characterization suite and evaluation baseline; it is not part of this restructure.