Identifier First¶

Status¶

Normative Architecture Principle

Purpose¶

Identifier First defines how CMonChoix Platform establishes product identity from heterogeneous and imperfect source data.

The Platform never assumes that one identifier is sufficient, globally authoritative or permanently reliable.

Identity is resolved from a deterministic body of evidence composed of identifiers, normalized observations, contextual signals and explicit conflict rules.

Scope¶

This principle applies to:

merchant observations;
normalized identifiers;
candidate generation;
identity resolution;
conflict detection;
canonical identity;
audit and simulation services;
projection inputs derived from a resolved identity.

It does not authorize projection, quality or frontend components to redefine identity.

Problem Statement¶

Merchant feeds expose heterogeneous signals such as:

EAN or GTIN;
manufacturer part number;
merchant SKU;
merchant product identifier;
brand reference;
model name;
normalized title attributes;
vertical-specific evidence.

These signals may be missing, malformed, duplicated, reused, unstable, merchant-specific or mutually contradictory.

A system that treats one identifier as absolute truth will eventually merge distinct products or split equivalent products.

Principle¶

An identifier is evidence, not truth.

Canonical identity is established by evaluating all relevant evidence through deterministic rules.

The resolver must be able to:

collect normalized evidence;
build identity candidates;
classify agreement, ambiguity and conflict;
choose a candidate only when the evidence threshold is satisfied;
expose the decision and its reasons;
refuse resolution when evidence is insufficient or contradictory.

The same normalized inputs, rule version and context must always produce the same result.

Evidence Model¶

Evidence may include:

identifier type and normalized value;
source and merchant context;
brand and product-family signals;
model and variant attributes;
vertical-specific observations;
confidence or reliability metadata;
positive matches;
negative or conflicting signals.

Evidence must remain traceable to its origin.

Derived signals must not silently replace raw observations.

Canonical Resolution States¶

Identity resolution must expose an explicit state.

State	Meaning
`resolved`	One identity is supported by sufficient compatible evidence
`unknown`	Evidence is insufficient to produce a defensible candidate
`ambiguous`	Several plausible candidates remain without a safe winner
`conflict`	Strong incompatible evidence prevents resolution

A downstream component must never reinterpret unknown, ambiguous or conflict as resolved.

Architectural Consequences¶

Identifier First implies that:

multiple identifiers may coexist for one observation;
no identifier type is universally authoritative;
canonical identity is independent from merchant identifiers;
candidates and decisions remain auditable;
conflict is a first-class result;
matching rules are versioned and deterministic;
vertical knowledge enriches evidence without entering the Domain Core;
projections consume resolution results but do not perform identity matching;
frontend code never reconstructs identity from feed fields.

Layer Responsibilities¶

Pipeline¶

The Pipeline extracts and normalizes observations and identifiers.

It does not declare canonical identity by itself.

Domain Core and Resolver¶

The Domain Core defines generic identity concepts.

The Resolver evaluates evidence, candidates and conflicts according to stable contracts.

Vertical Modules¶

Vertical Modules provide domain-specific evidence and conflict rules.

They never redefine the generic resolution lifecycle and never depend on another vertical.

Read Services¶

Read Services audit, simulate and compare resolution behavior without writing business data.

Write Services¶

Write Services persist a validated resolution or rebuild result through an explicit, auditable boundary.

Projection and Frontend¶

Projection consumes resolved identity and prepares stable read models.

Frontend consumes projections only.

Relationship with Quality¶

Identity quality and media quality are separate concerns.

A Media Quality rule may use an already resolved identity or normalized attributes as evidence, but it must not change identity resolution.

Media Quality remains audit-first and non-destructive by default. Any corrective mutation must cross an explicit write-service boundary after validation.

Invariants¶

The following rules must always remain true:

an identifier never defines a product by itself;
canonical identity is not a merchant identifier;
every resolution state is explicit;
conflicts are never silently discarded;
identical inputs and rule versions produce identical decisions;
every decision exposes reasons or evidence references;
unresolved observations remain unresolved until new evidence or rules justify a change;
Read Services never write;
projection and frontend layers never resolve identity;
vertical-specific rules never leak into the generic Core.

Prohibited Practices¶

The following practices are forbidden:

treating EAN, MPN, SKU or title as universally authoritative;
forcing a candidate when evidence is ambiguous;
merging products despite a blocking brand, family, model or variant conflict;
hiding unresolved cases through fallback labels;
resolving identity inside SQL projection writers or frontend templates;
mutating production data during an audit or simulation;
introducing non-deterministic rules without an explicit, documented dependency.

Validation Expectations¶

Any change to identifier normalization or resolution rules must provide:

representative fixtures;
deterministic unit tests;
conflict and ambiguity cases;
before-and-after audit metrics;
sampled decision reasons;
regression checks on previously resolved identities;
an explicit rollback or compatibility strategy when persisted results change.

Useful metrics include:

observations scanned;
candidates generated;
resolved, unknown, ambiguous and conflict counts;
resolution rate by source and vertical;
conflict reasons;
identity changes between rule versions.

Non Goals¶

Identifier First does not define:

one universal matching algorithm;
vertical-specific business attributes;
quality scoring policies;
catalog projection formats;
pricing or promotion logic;
frontend behavior;
an implicit production repair mechanism.

These concerns belong to their dedicated layers and contracts.

Future Evolution¶

New identifier types, evidence sources and vertical-specific rules may be introduced without changing this principle.

They must preserve determinism, traceability, explicit unresolved states and the separation between evidence collection, identity resolution, persistence and projection.