canonicalize-entity

Purpose

Resolve aliases and near-duplicates into canonical entities while preserving provenance and rejecting false merges.

Input contract

required: [raw_entities, entity_schema, alias_evidence]
optional: [synonym_dictionary, organization_relationships, graph_edges, canonicalization_policy]
constraints: [the entity schema is explicit; merge requires semantic identity evidence; preserve provenance and redirect relationships]

Procedure

1. Normalize names, identifiers, and aliases under the caller-supplied entity schema.
2. Search for near-duplicates and compare definitions, identifiers, and provenance.
3. Merge only semantically identical entities into a canonical record and redirect dependent edges.
4. Preserve rejected-merge pairs and rationale, then return the canonicalized register.

If canonical entities are stable enough to compare against the target domain, consider map-coverage-space as the next tactic.

Output contract

produces: [canonical_entities, alias_map, merge_decisions, redirected_edges, rejected_merges]
delta_fields: [findings, evidence_updates, decisions, uncertainties]

Quality gates

• Preserve the source merge-candidates gate: scan at least 10 concepts, or all concepts if fewer than 10 exist; a candidate score >7.0 is a merge flag, not proof.
• Before merging aliases, verify pages refer to the same concept rather than merely related concepts; retain inline links and edge redirects where applicable.
• Assignee normalization preserves parent, subsidiary, and acquired-entity relationships rather than collapsing organizations into one name.

Parameterization

The caller must provide the entity type and schema, canonical naming policy, alias/synonym evidence, merge confidence rule, graph-edge policy, and whether the task concerns concepts, assignees, or another entity class.

Failure and counterexamples

Reject merges without semantic identity evidence, threshold-only matches, or records that lose provenance or dependent edges.

Provenance map

• resolved: knowledge-structuring/merge-candidates
• resolved: knowledge-structuring/alias-resolution
• resolved: knowledge-acquisition/assignee-normalization
• intermediate: Pass3/merge-near-duplicate-concepts
• intermediate: Pass3/normalize-assignee
• intermediate: Pass4/map-field-taxonomy

Verbatim source criteria excerpts

• merge-candidates line 18: If search returns another concept with score > 7.0, flag as merge candidate.
• merge-candidates line 25: Must scan at least 10 concepts (or all concepts if fewer than 10 exist).
• alias-resolution line 29: Before merging, verify the pages truly refer to the same concept (not related but distinct concepts).

Preserved source criteria ledger

source	physical line	kind	source criterion
knowledge-structuring/merge-candidates	22	numeric	Scan at least 10 concepts, or all if fewer than 10; score >7.0 flags a merge candidate.
knowledge-structuring/alias-resolution	28	gate	Verify semantic identity before merging; related-but-distinct concepts must not merge.