Conflict Policy Contract¶

Status: CONTRACT

Purpose¶

The Conflict Policy contract defines how identity conflicts are detected, classified and exposed to the resolver.

It provides a common mechanism for every vertical while keeping product-specific rules outside the Domain Core.

The policy does not resolve an identity by itself. It evaluates incompatibilities and returns explicit evidence that the resolver can use.

Position in the decision flow¶

Normalized evidence
        ↓
Candidates
        ↓
Conflict Policy
        ↓
Conflict assessment
        ↓
Identity Resolver
        ↓
Resolution decision

The resolver remains the owner of the final identity status.

Input contract¶

A Conflict Policy receives an immutable evaluation context containing, as applicable:

the candidates being compared;
normalized identifiers;
product-level attributes;
variant-level attributes;
source evidence and provenance;
confidence values;
vertical-specific signals supplied through a contract;
previously detected incompatibilities.

The policy must not fetch missing business data implicitly or read mutable runtime state.

Output contract¶

A policy returns an explicit conflict assessment containing:

a canonical conflict state;
a severity;
stable reason codes;
the evidence supporting each reason;
the affected scope: product, variant or attribute;
optional confidence information;
optional review requirements.

The result must be serializable, deterministic and suitable for audits.

Canonical states¶

The common states are:

State	Meaning
`none`	No material incompatibility was found.
`ambiguous`	Several interpretations remain plausible and cannot be ranked safely.
`conflict`	Evidence is materially incompatible and blocks resolution.
`unknown`	Evidence is insufficient to classify the situation.

The resolver maps this assessment to its own resolution status. Policies must not invent resolver-specific terminal states.

Conflict families¶

A policy may classify conflicts into stable families such as:

brand conflict;
product-family conflict;
model conflict;
generation conflict;
product-type conflict;
variant conflict;
identifier conflict;
attribute conflict;
source contradiction;
insufficient evidence.

Vertical Modules may add domain-specific reason codes, but they must map them to a common family and severity.

Severity¶

Severity expresses the operational impact of the incompatibility.

Recommended levels:

info: compatible enrichment or harmless representational difference;
review: ambiguity that requires additional evidence or manual review;
blocking: incompatibility that prevents a safe resolution.

A lower-level signal must never suppress a blocking conflict from a stronger source without an explicit, tested policy rule.

Responsibilities¶

The Conflict Policy is responsible for:

comparing relevant evidence;
distinguishing absence, ambiguity and contradiction;
classifying incompatibilities;
assigning stable severity;
exposing reason codes and supporting evidence;
preserving product-versus-variant boundaries;
remaining deterministic and explainable.

It is not responsible for:

selecting the winning candidate;
creating a Canonical Identity;
computing the overall quality score;
mutating an offer, projection or source record;
writing to SQL or WordPress state;
rendering CLI, HTTP or frontend output.

Vertical Modules¶

The common contract does not know concepts such as Pro Max, lens mount, panel technology or game edition.

Vertical Modules provide these domain-specific comparison rules through explicit contracts. They may enrich:

the evidence set;
comparison predicates;
conflict reason codes;
severity mapping;
review thresholds.

They must not replace the generic conflict mechanism or bypass the resolver.

Evaluation order¶

Conflict evaluation should process the strongest identity boundaries first:

brand
  ↓
product type / family
  ↓
model / generation
  ↓
variant
  ↓
secondary attributes

This order prevents weak attribute similarities from hiding a fundamental product conflict.

Evidence rules¶

Every conflict reason must reference the evidence that produced it.

A valid reason therefore identifies:

the compared fields or identifiers;
their normalized values;
their provenance;
the comparison rule;
the resulting family and severity.

Missing evidence is not a conflict. It produces unknown unless another explicit contradiction exists.

Multiple plausible candidates without contradiction produce ambiguous, not a forced resolution.

Media Quality boundary¶

Media Quality may report contradictions between a projected image and product evidence, for example color or model signals.

These observations are quality evidence. They do not modify identity truth and do not clear image_norm implicitly.

The default Media Quality posture is audit-first:

collect evidence;
classify the result;
expose diagnostics and metrics;
recommend a replacement only when confidence is sufficient;
perform no mutation unless a separate, explicit Write Service is enabled.

A media mismatch must not be converted into an identity conflict unless an explicit product-identity rule proves that the evidence belongs to different products.

Determinism¶

For identical candidates, evidence, rules and configuration, the policy must return the same assessment and reason ordering.

Determinism requires:

stable normalization;
stable rule priority;
stable tie-breaking;
no dependency on current time or unordered iteration;
explicit versioning when rules change materially.

Observability¶

Audits and operators should be able to report at least:

evaluated comparisons;
none assessments;
unknown assessments;
ambiguous assessments;
blocking conflicts;
counts by reason family;
counts by vertical and source;
review-required counts.

Aggregate totals must reconcile with the evaluated population.

Guardrails¶

A Conflict Policy must never:

hide a brand or product-family contradiction;
treat missing information as positive compatibility;
force a winner because only one candidate has richer text;
promote a merchant-specific convention into a global rule;
mix product identity and variant identity;
mutate persistent state;
bypass the resolver;
use Media Quality as a destructive correction path.

Tests¶

Each policy implementation should include tests for:

deterministic output;
stable reason codes;
product and variant boundary handling;
missing evidence producing unknown;
multiple plausible candidates producing ambiguous;
blocking brand, family and model conflicts;
compatible enrichment remaining non-blocking;
vertical rule isolation;
serialization of the assessment;
absence of SQL, WordPress and runtime dependencies;
Media Quality audit-first behavior where applicable.

Invariants¶

The policy classifies; the resolver decides.
Missing evidence is distinct from contradictory evidence.
Ambiguity is preserved rather than forced into a result.
Every conflict is supported by explicit evidence and stable reason codes.
Vertical-specific rules remain outside the generic Domain Core mechanism.
Policy evaluation is deterministic, side-effect free and read-only.
Quality observations do not mutate identity or projections implicitly.