Detecting Silent Schema Changes Before They Break Risk Models

Yesterday, payment_status = 1 meant SETTLED and 2 meant REVERSED. Today, the producer reuses 1 for AUTHORISED, 2 for SETTLED and adds 3 for REVERSED. The field remains INTEGER. Parsing succeeds. SettledPaymentCount_30d now counts authorisations.

A complete contract governs structure and economic interpretation

type SemanticContract = {
  field: string;
  meaning: string;
  unit?: string;
  timeBasis?: string;
  owner: string;
  version: string;
};

Ask what status=1 means, whether amount is gross or net, whether time is UTC or local, whether balance includes pending and whether payment date means initiated or settled. Schema validation cannot answer these questions.

Silent drift has six forms that demand different evidence

Unknown enums must not silently become OTHER when distinctions affect models. Date rounding can leak same-day information; join-key formatting such as 001234 → 1234 can collapse identity coverage without breaking a type.

The registry gives every critical source technical and domain ownership

type DataContract = {
  source: string;
  object: string;
  version: string;
  schema: SchemaDefinition;
  semantics: SemanticDefinition[];
  owner: string;
};

The producer declares schema version, semantic version and change type where possible. Consumers declare exactly which fields and interpretations they depend on. Technical owners understand format; domain owners establish economic meaning.

Use meaningful schemaVersion and semanticVersion; do not over-version irrelevant metadata. Compatibility is a producer/consumer matrix, not a label attached only to the producer.

Field-to-decision lineage turns a source change into a measurable blast radius

Each feature value records its source-contract version, canonical mapping version and feature-definition version. Training dataset manifests retain contract versions; otherwise historical reproduction silently uses today's semantics.

Versioned adapters absorb source churn without hiding real semantic change

A source rename should require only an adapter change while canonical output stays stable. If economic meaning truly changes, version the canonical contract rather than conceal it inside mapping logic.

type SourceChangeManifest = {
  source: string;
  changeVersion: string;
  expectedChanges: string[];
  effectiveAt: Date;
};

During a transition window, process explicit message versions; do not infer them from payload guesses. An unsupported version is quarantined or fails controlled for decision-critical data. Keep the prior adapter available for rollback without deleting received raw events.

Shadow and canary validation must reach the decision layer

Small feature changes can cross policy boundaries, so feature stability does not guarantee decision stability. Before release: contract tests pass, canonical and feature diffs are understood, decision impact is reviewed and rollback is executable. Canary a controlled sample before full cutover.

Runtime sentinels catch unannounced source changes

Use domain-valid ranges and economic invariants such as reversal amount ≤ original amount or Available = Limit − Drawn − Pending under defined semantics. Distribution shifts are signals, not automatic proof: compare change context and borrower behaviour.

Historical data must retain the semantics effective at the time

A contract change needs effective_from. To rebuild an old feature or decision, load the historical source/canonical interpretation; applying today's adapter to old raw data can rewrite meaning.

Golden semantic cases and mutation tests attack meaning, not only shape

Run old and new adapters through the full feature and decision pipeline. Only changes declared in the change manifest should differ.

Semantic incidents require end-to-end scope and decision revalidation

Determine the interval from semantic change to detection, then use dependency lineage to identify affected raw records, canonical events, features, scores, decisions and actions.

Reconstruct corrected features/state and compare actual with corrected decisions. Preserve historical outcomes and route remediation through governance rather than overwriting them automatically.

Monitor contracts in economic units and decision outcomes

Also monitor payment totals, exposure, utilisation, reversal ratios and DPD transitions. These business measures reveal failures that parser success, schema registries and infrastructure uptime cannot.

The Entimema architecture gates source change by decision impact

A Data Contract & Semantic Drift Agent can trace silent change without approving it

A controlled agent can monitor versions, unknown fields and enums, null/cardinality/unit anomalies, compare contract versions, trace source fields to affected models, run feature comparisons, quantify decision impact and identify historical decisions affected by semantic defects.

Continue with Backpressure and Failure Recovery, From Batch ETL to Event-Driven Credit Risk Architecture, Building a Credit Risk Feature Store, Point-in-Time Correct Features, Streaming Behavioural Features, Decision Engine Monitoring and The Hidden Infrastructure Debt of Modern Lending. Infrastructure feature drift and decision-system observability remain future research directions—not fabricated routes.