Aller au contenu

Candidate

Status: CURRENT

Purpose

A Candidate is an explicit identity hypothesis built from available evidence before any final resolution.

It is not product truth, not a projection and not a persistence record. It exists so the resolver can compare several plausible interpretations without collapsing uncertainty too early.

Observed values
      ↓
Normalized evidence
      ↓
Candidates
      ↓
Resolver decision
      ↓
Canonical Identity or explicit unresolved state

Responsibilities

A Candidate may:

  • aggregate identifiers and normalized attributes;
  • retain the source and strength of each piece of evidence;
  • expose an identity hypothesis in a stable structure;
  • carry reasons, confidence signals and conflicts;
  • be compared with competing candidates;
  • be rejected without mutating source data.

A Candidate must not:

  • decide the final identity;
  • silently merge contradictory evidence;
  • write to SQL or WordPress state;
  • build a catalog projection;
  • contain presentation logic;
  • convert missing evidence into a positive match.

Evidence model

Candidate construction is evidence-first.

Each relevant signal should preserve, when available:

  • normalized value;
  • original value;
  • evidence type;
  • source feed or merchant;
  • rule or extractor that produced it;
  • confidence;
  • reason code;
  • ambiguity or conflict state.

Typical evidence includes:

  • EAN, GTIN, UPC or another trusted identifier;
  • MPN or manufacturer reference;
  • merchant product identifiers;
  • brand, family, series and model;
  • variant attributes such as storage, color, size or network;
  • vertical-specific technical attributes;
  • consistency or contradiction signals.

No single weak signal should be promoted to truth merely because stronger evidence is absent.

Candidate states

A Candidate is an hypothesis, not a boolean match. Its evaluation may contribute to one of the following resolver outcomes:

  • resolved: one candidate is sufficiently supported;
  • unknown: evidence is insufficient;
  • ambiguous: several candidates remain plausible;
  • conflict: evidence is materially contradictory.

These states must remain distinguishable in metrics and diagnostics.

Candidate identity versus variant identity

Candidate construction must separate product-level and variant-level evidence.

Product-level examples:

  • brand;
  • family;
  • series;
  • model;
  • generation;
  • product type.

Variant-level examples:

  • storage;
  • color;
  • screen size;
  • connectivity;
  • edition;
  • capacity.

A variant difference must not automatically create a different canonical product when the domain model treats it as a variant. Conversely, a product-level contradiction must not be hidden as a harmless variant difference.

Vertical Modules

Vertical Modules may provide:

  • additional candidate factories;
  • vertical-specific evidence extractors;
  • value normalization rules;
  • compatibility checks;
  • candidate comparison criteria.

They may not:

  • bypass the resolver;
  • mutate canonical identity directly;
  • introduce WordPress, SQL or frontend dependencies into the Domain Core;
  • redefine generic candidate semantics.

Scoring and ranking

A candidate score is advisory evidence for the resolver. It must remain explainable.

A useful evaluation result should expose:

  • total score or confidence;
  • contributing evidence;
  • penalties;
  • conflicts;
  • reason codes;
  • threshold or decision policy used.

Scores from different contexts must not be compared unless they share the same contract and scale.

A high score must never erase a hard contradiction.

Media Quality boundary

Media Quality may produce evidence about the consistency of an offer image with normalized product attributes, for example a color agreement, mismatch, ambiguity or unknown actual color.

That evidence may enrich diagnostics or quality evaluation, but it must not:

  • become a canonical identity identifier;
  • resolve product identity on its own;
  • clear an image implicitly;
  • mutate an offer during candidate construction.

The current policy is audit-first and non-destructive by default.

Determinism

For identical normalized inputs, configuration and rule versions, candidate construction must produce the same candidates in the same canonical order.

Candidate identifiers should be derived from stable business inputs or a deterministic serialization. They must not depend on process memory, timestamps or random values.

Traceability

Every candidate used in a decision must be explainable from source evidence.

An audit should be able to answer:

  • which inputs created the candidate;
  • which rules were applied;
  • which evidence increased confidence;
  • which evidence introduced ambiguity or conflict;
  • why the candidate was retained or rejected.

Tests

Candidate tests should cover at least:

  • deterministic construction;
  • stable ordering;
  • product versus variant separation;
  • missing evidence;
  • ambiguous evidence;
  • contradictory evidence;
  • vertical enrichment without Core coupling;
  • immutability during evaluation;
  • absence of persistence and transport dependencies;
  • serialization of evidence and reason codes.

Invariants

  1. A Candidate is an hypothesis, never truth.
  2. Candidate construction is deterministic.
  3. Evidence remains traceable to its source.
  4. Missing evidence never becomes a positive match.
  5. Contradictions remain explicit.
  6. Product and variant evidence remain separated.
  7. The resolver owns the final decision.
  8. Candidate construction performs no persistent write.
  9. Vertical Modules extend the model without bypassing the Core.
  10. Media Quality remains advisory and non-destructive by default.

See also