Project: link incident mentions to a versioned service catalog

Last updated: 6 Oct 20265 min read

project

Resolve service names in incident notes to authorized catalog IDs, leave unseen names unresolved and stage catalog migrations for review.

Define the linking contract

The incident team searches notes about services with overlapping nicknames. The system detects mention spans and proposes catalog records within the incident’s tenant and time scope. It must offer NIL when no record fits. Output mention offsets, candidate evidence, chosen ID or reject reason, catalog revision and source note revision. A linked mention does not grant access to the record; authorization remains a separate check.

Construct hard examples

Collect ambiguous aliases, renamed services, canary deployments and names shared across tenants. Add never-seen services to test NIL, and notes that mention two services in one sentence. Reviewers label the correct record or NIL under one catalog snapshot. Group incident families before splitting. Candidate and NIL policy sets the decision; revision review handles later changes.

Compare and stage

Start with exact aliases under tenant scope, then compare a context ranker on the same audit. Measure candidate recall, correct link, NIL precision and wrong-tenant exposure. If the top two candidates are close, show both to an authorized reviewer without auto-linking. For a catalog merge, stage affected mentions and related edges before moving an index alias. Preserve original decisions for replay.

Operate the release

Record catalog and linker versions with every link. Watch new aliases, missing candidate rate, NIL drift and incorrect cross-service matches. Delete derived links when a source note is removed under retention policy. If a catalog change causes unexpected links, return to the previous snapshot and review the proposed migration rather than mutating historical notes again.

Implementation

def link_record(mention, selected_id, catalog, catalog_revision):
    entry = catalog.get(selected_id)
    if entry is None or entry["tenant_id"] != mention["tenant_id"]:
        return {"state": "unresolved", "reason": "missing-or-inaccessible"}
    return {"state": "proposed", "entity_id": selected_id,
            "catalog_revision": catalog_revision,
            "mention_revision": mention["revision"]}

mention = {"text": "Atlas", "tenant_id": "north", "revision": "note-r47"}
catalog = {"svc-47": {"tenant_id": "north", "name": "Atlas Gateway"}}
assert link_record(mention, "svc-47", catalog, "catalog-r8")["state"] == "proposed"

Performance and operating cost

The access and identity check is O(1) average time per proposed link. Candidate generation, ranking and human ambiguity review dominate cost. Track wrong links per thousand resolved mentions and review minutes per ambiguous case; raw coverage can rise simply by forcing uncertain names into the catalog.

Common Mistakes

Auto-linking every mention to the closest catalog title.
Dropping the catalog revision from a stored decision.
Using a link result to bypass record access controls.
Silently changing old links after a service merge.