Cross-document reference chains: revisions, scope and access

Last updated: 7 Oct 20265 min read

tutorial

The same service can appear in multiple updates, but identical strings alone do not justify merging incidents or exposing restricted evidence.

Define the join scope first

A handoff might combine a status message, deployment note and operator transcript. Link mentions only after verifying incident ID, service registry identity and time context. Two tickets can both say “gateway” while referring to separate environments or regions. Keep document ID, revision and span on every mention, and record why two chains were joined. Entity linking proposes registry identities; coreference still decides whether particular mentions in context denote the same thing.

Treat revisions as new evidence

A corrected update may change “the gateway failed” to “the gateway check failed.” A chain derived from the old sentence cannot remain silently active. Mark its mention and dependent edges stale, then re-evaluate the corrected span under the current document revision. Preserve the old chain for audit. Passage revision tracking helps find derived entries that need a rebuild after source edits.

Keep access on each mention

A public status page and a restricted incident note may refer to the same service. Their mention chains can be connected internally, but a public answer must use only evidence the reader may see. Do not leak a restricted quotation, speaker or document title through a generated explanation. Filter source spans before assembling the visible chain, and distinguish a missing public antecedent from an unresolved private one. The access decision is per evidence item, not a property of the service name.

Audit merges and downstream claims

Review a sample of accepted joins, rejected joins and NIL candidates after every registry or document revision. Measure wrong cross-incident merge rate, stale-edge rate and access violations. Pair metrics alone cannot show whether a summary assigned a rollback to the wrong region. Run a final claim check against visible, active source spans. The applied audit turns these conditions into a release gate.

Implementation

def can_join_mentions(left, right):
    if left["incident_id"] != right["incident_id"]:
        return False
    if left["environment"] != right["environment"]:
        return False
    return (left["registry_id"] is not None and
            left["registry_id"] == right["registry_id"] and
            bool(left["source_revision"]) and bool(right["source_revision"]))

first = {"incident_id": "inc-47", "environment": "staging",
         "registry_id": "gateway-west", "source_revision": "r2"}
second = {"incident_id": "inc-47", "environment": "staging",
          "registry_id": "gateway-west", "source_revision": "r5"}
assert can_join_mentions(first, second)
assert not can_join_mentions(first, {**second, "environment": "production"})

Performance and operating cost

Checking one candidate pair is O(1). Building all cross-document pairs is potentially quadratic in mentions, so partition by incident and environment before matching. A registry ID is useful evidence but not a timeless guarantee: track registry migrations and source revisions, and budget reviewer time for merges that affect incident summaries.

Common Mistakes

Joining two “gateway” mentions across unrelated incidents.
Leaving a chain active after its supporting note is corrected.
Using a restricted antecedent to explain a public mention.
Assuming a shared registry ID means two different environments are the same instance.