FIN Central

ADR-005: Doc-CQRS migrations renumbered 045/046 → 049/050

3 min read

ADR-005: Doc-CQRS migrations renumbered 045/046 → 049/050

Status: accepted (2026-05-15) Date decided: 2026-05-15

Context

Engineering Spec §11.5.1 and §11.5.2 reference the doc-CQRS projection migrations by specific numbers:

11.5.2 entity_doc_projection (migration 046)

These were referenced as 045 and 046 when the Engineering Spec was authored (2026-05-13). However, by the time Phase 1 §1 schema apply ran (2026-05-15), the actual migration files at those slot numbers were unrelated:

  • db/migrations/045_events_causation_index.sql
  • db/migrations/046_events_tenant_actor_timestamp_index.sql
  • db/migrations/047_fts_hybrid_search.sql
  • db/migrations/048_veteran_panelist_role.sql

The spec-described migrations (doc_backlink_projection + entity_doc_projection) had not yet been authored in code. The numbering in the spec was speculative, claimed before the slots were filled.

Decision

Author the doc-CQRS migrations at the next available unused slots:

  • db/migrations/049_doc_backlink_projection.sql — implements §11.5.1
  • db/migrations/050_entity_doc_projection.sql — implements §11.5.2

Both files include a leading comment that explicitly notes:

Note: Engineering Spec §11.5.1 numbered this as migration 045 but the actual 045 slot was taken by events_causation_index. Renumbered to 049.

The schema shape, RLS rules, and transactional-write contract (§11.5.3) are implemented per spec — only the file number changed.

The Engineering Spec source doc remains unedited in this session; a follow-up spec amendment will update §11.5.1 and §11.5.2 to read “(migration 049)” and “(migration 050)” respectively.

Consequences

Positive

  • No collision with existing migration files
  • Schema apply works cleanly — dbmate sees 049/050 as new, applies them in order with no manual schema_migrations patching
  • Code intent preserved — both files implement exactly the §11.5.1 and §11.5.2 contracts; consumers don’t need to care about the number
  • Sequential and contiguous — 049/050 are the next-available slots, preserving the “migrations apply in numbered order” simplicity

Negative

  • Spec doc drift — FIN_INTRANET_HUMAN_AGENT_PROJECTION_ENGINEERING_SPEC_2026-05-13.md §11.5.1 + §11.5.2 still say “(migration 045)” and “(migration 046)“. Anyone reading the spec sees a different number than the actual code. Mitigation: spec amendment landed in a follow-up session
  • Anyone debugging via migration number sees 049/050 in the DB but might search the spec for “045” and not find a match. Mitigation: the migration file headers themselves explain the renumbering

Neutral

  • The doc-CQRS migrations were NOT YET APPLIED to fin-central-prod as of 2026-05-15 — they exist in source files only. Application happens when T7 wires the consumer code (vault webhook, doc.indexed/archived consumers, the renderer worker that uses these projections)

Implementation

Done 2026-05-15:

  • db/migrations/049_doc_backlink_projection.sql written
  • db/migrations/050_entity_doc_projection.sql written
  • Both registered at audit/card-window-system/approved-projection-tables.json with transactional_write_required: true (per §11.5.3 stricter discipline than the existing 041-044 fire-and-forget CQRS pattern)
  • Both pending application — applies when T7 consumer code lands

Pending:

  • Engineering Spec §11.5.1 + §11.5.2 amendment to reflect actual numbers (defer to a focused doc-cleanup session)
  • Schema apply on fin-central-prod (waits on T7)
  • Engineering spec being amended: Intranet Projection Engineering Spec v0.2 §11.5.1, §11.5.2
  • Migration files: fin-agentic/db/migrations/049_doc_backlink_projection.sql, fin-agentic/db/migrations/050_entity_doc_projection.sql
  • Approved-projection registry: fin-agentic/audit/card-window-system/approved-projection-tables.json
  • Phase 1 verification (notes pending application): Phase 1 Verification Record §2.2

Graph View