feat(db): stable external read model — versioned read-only SQL views + read-only role

[thewrz]

Why

SpecR's REST/MCP surface is the contract for interactive clients, but a class of consumers
integrates at the database layer instead: BI dashboards, warehouse ETL, and data platforms that
sync tables over standard JDBC/ODBC connectors. Internal tables are not a contract — they evolve
with migrations, and pointing an external sync at them couples every schema change to someone
else's pipeline. The house rule already says direct DB reads are fine for discovery; this issue
makes that officially safe by giving external readers a stable, versioned surface, so the
canonical AST in PostgreSQL is consumable by any downstream data tooling without freezing
internal schema evolution.

What

• Migration (reversible): schema export_v1 containing read-only views:
  • export_specs — id, section, title, library/project scope, revision/lineage basics, timestamps
  • export_paragraphs — id, spec id, position, hierarchy path, node type, text, confidence,
    editability, vanish
  • export_refs — section refs and standards refs with source paragraph anchors
  • export_findings — coordination/report findings (flattened), if cheap; else defer to v2
• A documented read-only role pattern (GRANT USAGE/SELECT on export_v1 only) — documented,
  not auto-created, since role management is deployment-specific.
• Versioning policy (in the ADR + docs/architecture/): views within export_v1 are additive-only;
  breaking changes mint export_v2 alongside; deprecation is announced, never silent.
• Contract test: an integration test pinning each view's column set, so an accidental
  internal-migration break turns CI red.

Tasks

• ADR-NNN: external data contract, versioning + deprecation policy
• Migration: export_v1 views (paired down)
• docs/architecture/: external read-model page (consumers, role setup, guarantees)
• Integration test: view column-set pinning + a smoke row-shape check
• README/deployment note pointing DB-level consumers at export_v1, never internal tables

Acceptance criteria

• A read-only DB user granted only export_v1 can serve the documented views and nothing else.
• An internal schema migration that would break a view fails CI via the contract test.
• The versioning policy is written down and referenced from the architecture docs.