A canonical_id is a 26-character ULID. It is assigned when the page is first saved (the structural-spine save filter auto-injects it) and stays with the page across every rename. Slugs are routes; canonical_ids are identity.
Whenever you write a wiki citation that another process or another session might read.
The structural index maintains a page_canonical_ids table that maps
canonical_id → current_slug, plus a page_slug_history audit trail of
every previous slug. This is why /api/pages/by-id/{canonical_id}
always works even after a rename — the index resolves through the
mapping table.
For human-facing links in prose, slugs are fine — the SPA redirects.
For machine-readable identity, only canonical_ids will do. The
frontmatter steps are the lookup procedure.
The frontmatter pitfalls are the recurring failure modes. The most
expensive is caching slug→canonical_id mappings in long-lived agent
memory: when a page renames, the cached slug is wrong forever.