documentation-docusaurus/references/cross-linking-source-and-derived-dossiers.md

Cross-linking source dossiers to generated derived dossiers

Use this pattern when canonical entity pages contain observations that are consolidated into generated records such as systems, suppliers, or projects.

Objective

Add a generated column to each source observation table that displays the derived record's internal ID and links to its documentation route, without editing the canonical source corpus or duplicating identity logic.

Example:

| Service or system | System dossier | Relationship | Evidence | Confidence |
|---|---|---|---|---|
| PPVIS | [`SYS-2D859CB9C5`](/org/repo/systems/ppvis-2d859cb9c5/) | operates | … | high |

Generation pattern

1. Parse canonical source tables and retain a stable observation locator, normally (source_file, source_line).
2. Run the canonical identity/consolidation algorithm once.
3. When assigning each derived record its ID and slug, annotate every contributing observation with both values.
4. Return an observation-link map from the derived-registry generator:

{
    (observation["source_file"], observation["source_line"]): {
        "id": observation["derived_id"],
        "slug": observation["derived_slug"],
    }
}

5. Generate MDX-safe source dossier copies. Add the new table header and inject one link into each data row using that map.
6. Leave canonical source Markdown unchanged; generated display enrichment belongs in the publishing layer.

Coverage invariant

Generation must fail when any parsed observation is not linked:

expected = sum(1 for source, _line in observation_links if source == source_file)
if linked != expected:
    raise SystemExit(
        f"derived-link coverage mismatch in {source_file}: "
        f"linked={linked} expected={expected}"
    )

After generation, independently verify:

• displayed link count equals the registry observation count;
• every (ID, slug) target exists in the generated registry;
• the number of unique targets equals the expected derived-record count;
• representative legacy and structured table formats render correctly;
• the full Docusaurus production build and route validator pass.

Important pitfalls

• Do not recompute identity independently in the source-page generator. Reuse the canonical registry result or links will drift when aliases change.
• Do not match only by displayed label; duplicate labels and client-scoped generic resources make that unsafe.
• Do not use the internal ID as a guessed route. Display the ID, but link with the generated canonical slug.
• Preserve numeric source line locators until enrichment is complete. Transformations such as frontmatter injection or <br> normalization can otherwise shift line numbers.
• Ensure generated internal links are not collected into public-source References indexes; references should remain provenance links, not site-navigation links.