/canonicalize-entity

name: canonicalize-entity
description: "Resolve aliases and near-duplicates into canonical entities while preserving provenance and rejecting false merges; entity schema is configurable."

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. |