canonicalize-entity
Purpose
Resolve aliases and near-duplicates into canonical entities while preserving provenance and rejecting false merges.
Input contract
yamlrequired: [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
- Normalize names, identifiers, and aliases under the caller-supplied entity schema.
- Search for near-duplicates and compare definitions, identifiers, and provenance.
- Merge only semantically identical entities into a canonical record and redirect dependent edges.
- 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
yamlproduces: [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-candidatesline 18: If search returns another concept with score > 7.0, flag as merge candidate.merge-candidatesline 25: Must scan at least 10 concepts (or all concepts if fewer than 10 exist).alias-resolutionline 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. |


