Skip to content
Bahman Shadmehr Independent AI Systems & Automation Engineer
On this pattern

System Pattern 08 / Identity, Data & History

Two records. One company. Maybe.

Entity Resolution with Reversible Canonicalization

Different records can describe the same real-world entity. Similar records can describe different entities. This pattern makes that decision inspectable, reversible, and safe to escalate.

Maturity
Reference design / Specified
Critical uncertainty
Similarity is evidence, not identity. Consequential merges require sufficient evidence and a reversible decision trail.
Human boundary
Resolve authorized ambiguous cases and reverse prior decisions
Applications
Marketplace listings · CRM records · Support incidents · Content provenance
Marketplace, CRM, support, and content records converge into nine reversible entity-resolution layers and branch to same entity, different entities, or needs review.

Problem shape

The problem beneath them

Preserve source records, compare plausible candidates with consequence-aware evidence, and make every canonical identity decision attributable and reversible.

Identifiers are rarely complete across system boundaries. Names vary, addresses age, phone numbers are reassigned, and records are copied. Exact equality is therefore too strict, while fuzzy similarity alone is too permissive. The cost is asymmetric: a false merge can contaminate history, permissions, balances, or communication; a missed match may create duplicate work but remain easier to repair.

Entity resolution should preserve three distinctions. A source record is what a system observed. A resolved entity is a current decision about which observations belong together. A canonical representation is a selected or synthesized view used downstream. Collapsing these into one mutable row destroys the ability to explain or reverse a decision.

The mechanism combines deterministic exclusions, exact identifiers, candidate generation, multi-signal comparison, consequence-aware thresholds, and explicit human authority. It also treats “needs review” as a valid controlled outcome. A forced binary choice is not more decisive when the available evidence cannot support it.

Similarity is evidence, not identity. Consequential merges require sufficient evidence and a reversible decision trail.

This pattern can organize identity evidence; it cannot prove real-world identity where authoritative evidence is unavailable. Canonicalization must not erase source records, transfer permissions by implication, or turn a probabilistic score into legal identity.

Different problems, same shape

The surface changes. The decision structure persists.

01 / Marketplace

Are these listings the same product?

Names overlap while sellers, variants, and identifiers differ.

02 / CRM

Are these records the same company?

Domains, legal names, addresses, and contacts only partially agree.

03 / Support

Are these tickets about the same incident?

Symptoms and timing align, but affected accounts differ.

04 / Content

Are these articles copies of the same source?

Text is similar while publication dates and attribution conflict.

All four questions converge into Entity Resolution with Reversible Canonicalization.

Exploded pattern

Open the mechanism at every decision boundary.

  1. 01

    Preserve original records

    Question
    What exactly did each source assert before resolution?
    Responsibility
    Store source payload, source identity, observation time, and ingestion provenance without destructive merging.
    Input
    Raw records and trustworthy source metadata.
    Output
    Immutable source observations with stable record identifiers.
    Stops when
    Every comparison can refer back to intact source evidence.
  2. 02

    Normalize without destroying provenance

    Question
    Which superficial differences can be made comparable?
    Responsibility
    Produce normalized names, domains, addresses, dates, and identifiers alongside—not over—the originals.
    Input
    Preserved source fields and versioned normalization rules.
    Output
    Comparable derived fields linked to their source values.
    Stops when
    Transformations are reproducible and original meaning remains available.
  3. 03

    Generate plausible candidates

    Question
    Which record pairs deserve comparison without scanning everything?
    Responsibility
    Use blocking keys, search indexes, or locality methods to retrieve plausible matches with acceptable recall.
    Input
    Normalized attributes, entity scope, and candidate policy.
    Output
    Candidate pairs with retrieval reasons.
    Stops when
    The bounded candidate set and excluded scopes are recorded.
  4. 04

    Apply exact rules

    Question
    Do authoritative matches or contradictions settle the pair?
    Responsibility
    Apply hard exclusions, scoped unique identifiers, and deterministic equivalence rules before probabilistic comparison.
    Input
    Candidate pair and verified identifiers.
    Output
    Same, different, or unresolved rule disposition.
    Stops when
    A sufficient rule settles the pair or passes it onward.
  5. 05

    Measure multi-signal similarity

    Question
    How strongly do independent attributes support or oppose one entity?
    Responsibility
    Compare names, identifiers, location, chronology, relationships, and domain-specific signals without hiding contradictions.
    Input
    Candidate records and comparable features.
    Output
    Per-signal evidence, conflicts, missingness, and an aggregate assessment.
    Stops when
    Material positive and negative evidence is exposed for decision.
  6. 06

    Consider confidence and consequence

    Question
    Is the evidence sufficient for the harm profile of this decision?
    Responsibility
    Apply calibrated thresholds and stricter requirements for irreversible, financial, access, or compliance effects.
    Input
    Evidence assessment, proposed action, reversibility, and false-decision costs.
    Output
    Auto-link eligibility, keep-separate decision, or review requirement.
    Stops when
    The route reflects both confidence and consequence.
  7. 07

    Route uncertainty

    Question
    Who can resolve ambiguity, and what must they see?
    Responsibility
    Create a review packet with source records, signals, contradictions, and permitted actions.
    Input
    Unresolved pair, evidence, policy, and review capacity.
    Output
    Prioritized review item or deliberate unresolved state.
    Stops when
    An authorized owner accepts the item or policy permits deferral.
  8. 08

    Canonicalize or keep separate

    Question
    What grouping and representative view should downstream systems use?
    Responsibility
    Link records to an entity, retain separate entities, and select canonical attributes under field-level provenance rules.
    Input
    Authorized disposition and source observations.
    Output
    Entity membership and canonical view without deleting sources.
    Stops when
    The disposition is applied consistently and downstream scope is explicit.
  9. 09

    Record and reverse

    Question
    Can the decision be reconstructed and safely undone?
    Responsibility
    Version membership, rationale, actor, evidence, affected dependents, and reversal operations.
    Input
    Prior entity graph, new disposition, and decision evidence.
    Output
    Append-only decision event and compensating reversal path.
    Stops when
    Both forward impact and reversal requirements are known.

Decision forks

Every branch states why it exists and when it escalates.

Signals, decisions, reasons, and escalation conditions
Signal Decision Reason Escalates when
Same authoritative identifier in valid scope Treat as same entity Scoped identifier outweighs cosmetic differences Identifier reuse or source authority is disputed
Mutually exclusive verified identifiers Keep separate Contradictory identity evidence blocks merging A source is known to issue duplicates
Strong similarity with no material conflict Auto-link when consequence policy allows Multiple independent signals support the same explanation Merge would transfer consequential state
Sparse records with moderate similarity Needs review or remain unresolved Missing evidence is not positive evidence Delay itself creates material harm
High text similarity but incompatible variant Keep separate Product or content variant is identity-relevant Variant taxonomy is incomplete
Existing canonical entity gains contradictory data Re-open resolution New evidence can invalidate an earlier decision Reversal affects many downstream records
Reviewer lacks authority or evidence Defer, do not force A review click cannot manufacture certainty Service expectations or consequence require specialist action

Operating paths

Clear, ambiguous, and failed work all reach explicit states.

Clear path

Preserve, normalize, generate candidate, satisfy exact or high-sufficiency criteria, canonicalize, and record.

Final state
Same entity or Different entities.
Owner
Resolution system under an approved deterministic policy.
Evidence
Source snapshots, candidate reason, rule version, signal assessment, and decision event.
Recovery
Re-evaluate when source corrections or policy versions materially change.
Ambiguous path

Retain both records, expose supporting and opposing signals, and send an evidence packet to an authorized reviewer.

Final state
Needs review.
Owner
Domain steward or specialist identity reviewer.
Evidence
Originals, normalized values, missing fields, conflicts, confidence, consequence, and reviewer disposition.
Recovery
Gather authoritative evidence, keep unresolved, or apply and record a reversible decision.
Failure path

Stop affected candidate generation or canonicalization, quarantine incomplete work, and preserve prior entity state.

Final state
Needs review.
Owner
Data platform owner until integrity is restored; domain owner for affected decisions.
Evidence
Failed stage, impacted records, rule/model version, last valid graph version, and containment action.
Recovery
Repair, replay from preserved records, compare graph changes, then publish the corrected version.

Authority map

Capability does not grant authority.

RULE

May decide
Enforce exclusions, exact scoped matches, and consequence thresholds
May not decide
Treat an unverified shared attribute as universally unique
Required evidence
Rule/version, source fields, scope, and disposition

MODEL

May decide
Compare unstructured attributes and summarize evidence
May not decide
Merge entities or conceal contradictory evidence on its own
Required evidence
Model/version, feature inputs, per-signal output, and confidence

SYSTEM

May decide
Preserve records, generate candidates, apply authorized links, and version history
May not decide
Delete source provenance or propagate unapproved consequential merges
Required evidence
Candidate trace, transition event, graph version, and affected scope

HUMAN

May decide
Resolve authorized ambiguous cases and reverse prior decisions
May not decide
Assert legal identity beyond their remit or edit history silently
Required evidence
Identity, evidence reviewed, rationale, action, and timestamp

EXCEPTION

May decide
Hold unresolved or integrity-affected records safely
May not decide
Become an invisible catch-all or imply records are different
Required evidence
Trigger, owner, evidence gaps, age, and next permitted action

Failure modes and recovery

A failed path remains owned, evidenced, and recoverable.

Failures, detection, containment, recovery, and owners
Failure Detection Containment Recovery Owner
Over-broad blocking key floods candidates Candidate volume and low relevance shift sharply Disable affected key and preserve queued records Refine scope and replay candidate generation Data platform
Normalizer strips identity-bearing detail Audits show collisions or missing qualifiers Stop decisions using affected feature version Restore originals, version fix, re-evaluate impacted pairs Resolution owner
False merge contaminates canonical history Contradiction, complaint, or authoritative identifier mismatch Freeze further propagation and mark entity disputed Split membership, compensate dependents, record reversal Domain steward
Duplicate entity remains undetected New authoritative link or repeated operational conflict Link cases without overwriting sources Re-run candidates and merge only with sufficient evidence Domain steward
Model version changes scores silently Reproducibility check differs for same evidence Pin version and halt thresholded automation Calibrate, compare, approve, and version route policy Model owner
Review backlog removes practical escalation Queue age or consequence exceeds policy Tighten automation scope rather than threshold Add capacity, prioritize risk, or leave unresolved explicitly Operations owner

Invariants and guarantees

Properties the structure is designed to preserve.

  • Original source observations and provenance are never destroyed by canonicalization.
  • Deterministic contradictions remain visible even when other signals strongly agree.
  • “Needs review” is a first-class outcome with an owner, not a hidden low score.
  • Thresholds account for consequence and reversibility, not confidence alone.
  • Every membership change identifies the evidence, rule or model version, and actor.
  • Reversal creates compensating history and evaluates downstream impact.
  • A canonical view never retroactively changes what a source originally asserted.

What changes between implementations

The constraints determine the final mechanism.

Identity scope is domain-specific: a legal company, account, location, product variant, incident, and source article have different boundaries. Candidate methods depend on volume and available identifiers. Signal weights and hard exclusions depend on data quality and semantics. Thresholds depend on false-merge cost, missed-match cost, reversibility, and review capacity.

Canonical fields may select the most authoritative source, preserve several values, or derive a view. Some systems need real-time resolution; others can batch and compare graph versions. Privacy rules may forbid cross-tenant comparison even when it would improve recall. The stable structure is preservation, evidence-aware decision, explicit uncertainty, and reversible history.

Evidence chain

Follow the pattern into systems and software.

Architecture and controls specified; no production results published.

lead-operations relates to company and contact records arriving through multiple channels. invoice-intake relates where supplier identities and document records require cautious association. incident-triage relates where multiple reports may or may not describe one incident. These are reference-design relationships only; they do not claim this exact mechanism was implemented or evaluated in those cases.

Durable execution preserves resolution attempts and guarded graph updates. Evidence-bounded inference provides a complementary discipline when unstructured evidence supports an identity decision.

This document is a REFERENCE DESIGN with specified controls. No production results are published. No open-source implementation is linked. No evaluation fixture, test, or benchmark is linked. The case-study links identify plausible composition points, not implementation, testing, or measurement evidence.

Known boundaries

Limitations and non-fit

Resolution cannot recover identifiers that were never observed or distinguish entities that are genuinely indistinguishable under permitted data. Biometric, legal-person, sanctions, access-control, and other high-consequence identity decisions require domain-specific authority and may prohibit probabilistic auto-linking entirely. A reversible database link does not guarantee that downstream emails, payments, or disclosures can be reversed.

The pattern is unnecessary where a complete authoritative identifier is enforced end to end and its scope never changes. It is also unsafe when source records cannot be retained long enough to explain decisions, reviewers lack legitimate authority, or downstream systems cannot tolerate correction.

Related patterns

Continue through the adjacent decision structures.

Entity resolution is a governed claim about records, not a cleanup operation. Preserving observations, exposing contradictions, and recording reversible decisions lets a system use canonical identities without pretending ambiguity has disappeared.

Adapt the pattern

Bring the problem, the boundary, and the consequence of being wrong.

Let's build something real