fix(docs): make bridge schemas discoverable (REQ-328, #895)

[avrabe]

Closes #895.

rivet coverage reports traceability rules that come from the embedded bridge
schemas. You saw three at 0.0% — constraint-has-requirement,
controller-constraint-has-requirement, stpa-constraints-provide-evidence —
while rivet docs schema/<bridge> answered Unknown topic for every spelling.

Reproduced on current main with your own command:

schema/stpa-dev.bridge          0 hits
schema/safety-case-stpa.bridge  0 hits
schema/dev                      serves the schema normally   ← the contrast

A rule you can watch fail and cannot look up is a rule you cannot act on —
nothing tells you which link type or target types would satisfy it.

The bridges were embedded all along

BRIDGE_SCHEMAS carries filename, extends and content for all seven. They
were simply never registered as documentation topics.

So the fix derives the topics from that registry rather than listing them by
hand — a bridge added later cannot ship undocumented. Lookup, docs --list (text
and JSON) and docs <slug> all consult it.

Deliberately not folded into topic_bodies, which feeds the embedded-doc
invariants in rivet docs check: those scan markdown prose, and bridge content
is schema YAML that would be judged against rules written for something else.

The oracle asserts over the registry, not a list

Every entry must be both servable and present in the listing — a topic nobody
can find is only half fixed.

negative control (fallback disabled):
  these bridge schemas are reported by coverage but cannot be looked up:
  [eu-ai-act-aspice, eu-ai-act-stpa, iso-8800-stpa, safety-case-eu-ai-act,
   safety-case-stpa, sotif-stpa, stpa-dev]

After the fix

schema/stpa-dev.bridge returns 2 hits for constraint-has-requirement.
safety-case-stpa.bridge still returns 0 for that rule — correctly, it's defined
in stpa-dev.bridge. Being able to discover which bridge owns a rule is the
point.

Gates

cargo fmt --check · clippy --all-targets -D warnings on 1.97.0 ·
cargo test --workspace (exit 0, 66 ok) · full cli_commands (194 passed) ·
rivet validate · rivet docs check · yamllint — all exit 0.

[github-actions]

📐 Rivet artifact delta

Change	Count
Added	1
Removed	0
Modified	0
Downstream impacted (depth ≤ 5)	0

Graph

graph LR
  REQ_328["REQ-328"]:::added
  classDef added fill:#d4edda,stroke:#28a745,color:#155724
  classDef removed fill:#f8d7da,stroke:#dc3545,color:#721c24
  classDef modified fill:#fff3cd,stroke:#ffc107,color:#856404
  classDef overflow fill:#e2e3e5,stroke:#6c757d,color:#495057,stroke-dasharray: 3 3

Loading

Added

• REQ-328

📎 Full HTML dashboard attached as workflow artifact rivet-delta-pr-905 — download from the workflow run.

_{Posted by rivet-delta workflow. The graph shows only changed artifacts; open the HTML dashboard (above) for full context.}

[avrabe]

Closing as duplicate of #903, which came first (2026-09-07) and is the better
patch.

I picked up #895 without checking the open PR list, which is on me — second time
this week after #880/#899. The rule I should have been following: check
gh pr list for the issue before starting, not just the issue's own comments.

For the record on why yours wins rather than mine: #903 registers the seven
bridges as DocTopic entries in the same shape every other schema topic already
uses, adds a Bridges category and an overview doc, and carries
every_embedded_bridge_has_a_docs_topic asserting over BRIDGE_SCHEMAS — the
same completeness guard I wrote, so a new bridge still cannot ship undocumented.
Mine derived the topics from the registry at lookup time instead, which is one
fewer place to forget but diverges from the established topic shape for no gain
now that the guard exists either way.

Nothing here is worth salvaging on top of #903. The one line I'd offer as a
follow-up if it isn't already covered: assert the bridge appears in
docs --list output specifically, not only in topic_slugs() — "it works if
you already know the exact slug" isn't discoverability, and the listing is how a
reader finds it. If --list iterates the same TOPICS array then that's already
implied and there is nothing to add.

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'Rivet Criterion Benchmarks'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.20.

Benchmark suite	Current: db8c58f	Previous: a80ca3a	Ratio
store_insert/10000	16838855 ns/iter (± 1775541)	12739051 ns/iter (± 575699)	1.32

This comment was automatically generated by workflow using github-action-benchmark.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!