docs: Postgres data model reference + stale schema doc cleanup (#2127)

* docs: Add Postgres data model reference and tidy stale schema docs

Consolidates the database-per-service plus schema-per-tenant topology into
a single reference covering service ownership, tenant isolation mechanism,
reference data replication, and the one cross-tenant access pattern.
Reflects PR #2125 (public removed from search_path) and PR #2126
(self-service signup). Updates ADR-0003 with a pointer to the new doc and
marks the CockroachDB compatibility section as historical. Archives the
completed database-per-service migration runbook.

* docs: Update links after archiving database-per-service migration runbook

* docs: Fix relative links in archived database-per-service runbook

---------

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

docs/adr/0002-microservices-per-bian-domain.md

@@ -667,12 +667,7 @@ GRANT ALL ON DATABASE meridian_current_account TO current_account_svc;
 
 ### Migration Strategy
 
-See [Database-Per-Service Migration Runbook](../runbooks/database-per-service-migration.md) for:
-
-- Step-by-step migration guide
-- Rollback procedures
-- Verification checklists
-- Lessons learned
+The initial database-per-service migration is complete. See the [archived migration runbook](../archive/database-per-service-migration.md) for historical context, or the [Data Model Reference](../architecture/data-model.md) for the current topology.
 
 ### Consequences
 
@@ -693,4 +688,5 @@ See [Database-Per-Service Migration Runbook](../runbooks/database-per-service-mi
 ### References
 
 * [ADR-003: Database Schema Migrations](./0003-database-schema-migrations.md)
-* [Migration Runbook](../runbooks/database-per-service-migration.md)
+* [Data Model Reference](../architecture/data-model.md)
+* [Migration Runbook (archived)](../archive/database-per-service-migration.md)

docs/adr/0003-database-schema-migrations.md

@@ -155,8 +155,9 @@ Database: meridian_current_account
 
 - Each service has its own PostgreSQL database
 - Each organization gets its own schema within each service database
-- Connection URL includes `search_path` for org routing: `postgres://...?search_path=org_acme_bank`
+- The search_path is set transactionally via `SET LOCAL search_path TO org_<id>` by `shared/platform/db/gorm_tenant_scope.go`
 - Queries use unqualified table names; PostgreSQL resolves via `search_path`
+- As of PR #2125, `public` is **not** in the search_path — reference data is replicated into each tenant schema on provisioning rather than shared via public. See [data-model.md](../architecture/data-model.md#tenant-isolation-mechanism) for the current mechanism.
 
 ### Naming Conventions
 
@@ -484,7 +485,9 @@ If migrating from golang-migrate:
 * Maintain migration history (no need to replay all migrations)
 * Continue using immutability principles
 
-### CockroachDB Compatibility Considerations
+### CockroachDB Compatibility Considerations (Historical)
+
+> **Note:** Meridian now targets PostgreSQL 16 exclusively. The constraints below are retained because existing migrations were authored under CockroachDB compatibility rules and continue to follow them (no PL/pgSQL, split column-add from partial-index-add, explicit timestamp columns instead of range types). New migrations should follow the same conventions for consistency, but the underlying runtime is Postgres. See [data-model.md](../architecture/data-model.md) for the current topology and [docs/reports/cockroachdb-migration-audit.md](../reports/cockroachdb-migration-audit.md) for historical context.
 
 While CockroachDB is PostgreSQL-compatible, some PostgreSQL features are **not supported**:
 

docs/architecture/data-model.md

@@ -1,18 +1,14 @@
 ---
 name: database-per-service-migration
-description: Step-by-step guide for migrating from single shared database to database-per-service architecture
-triggers:
-
-  - Migrating to database-per-service architecture
-  - Setting up new service databases
-  - Database isolation for microservices
-  - Multi-tenant database setup
+description: "[ARCHIVED] Historical runbook. The database-per-service migration is complete. See docs/architecture/data-model.md for the current topology."
+status: archived
+triggers: []
 
 instructions: |
-  Create separate database per service following naming convention meridian_<service>.
-  Set up schema-per-tenant within each database. Configure dedicated database users
-  with restricted grants. Update Atlas configuration per service. Use gRPC for
-  cross-service data access instead of SQL joins.
+  ARCHIVED. This runbook documented the one-time migration from a shared database
+  to database-per-service. That work is complete - every service already owns its
+  own Postgres database with schema-per-tenant isolation. For the current topology,
+  see docs/architecture/data-model.md.
 ---
 
 # Database-Per-Service Migration Runbook
@@ -394,5 +390,5 @@ kubectl scale deployment current-account --replicas=3 -n production
 
 - [ADR-002: Microservices Per BIAN Domain](../adr/0002-microservices-per-bian-domain.md)
 - [ADR-003: Database Schema Migrations](../adr/0003-database-schema-migrations.md)
-- [Incident Response Runbook](./incident-response.md)
-- [Disaster Recovery Runbook](./disaster-recovery.md)
+- [Incident Response Runbook](../runbooks/incident-response.md)
+- [Disaster Recovery Runbook](../runbooks/disaster-recovery.md)

…nbooks/database-per-service-migration.md …rchive/database-per-service-migration.mddocs/runbooks/database-per-service-migration.md renamed to docs/archive/database-per-service-migration.md docs/runbooks/database-per-service-migration.md renamed to docs/archive/database-per-service-migration.md

@@ -117,6 +117,7 @@ go build ./...                # Verify generated code compiles
 Create the domain model with business rules and validation.
 
 **Convention references**:
+
 - [Error Conventions](error-conventions.md) — sentinel error naming and where to define them
 - [Repository Conventions](repository-conventions.md) — interface location, method naming, error documentation
 - [Value Types](value-types.md) — choosing between Money, Asset, and Amount for domain fields
@@ -186,6 +187,7 @@ go test ./services/{service}/domain/... -v
 Implement the repository using GORM.
 
 **Convention references**:
+
 - [Repository Conventions](repository-conventions.md) — entity-prefixed errors, TableName, optimistic locking, tenant scoping
 - [Value Types](value-types.md) — mapping Qty/Money/Amount to/from persistence columns
 
@@ -357,7 +359,7 @@ func (EntityName) TableName() string {
 **Why singular**: Natural SQL syntax (`FROM account` not `FROM accounts`)
 **Why unqualified**: Allows `search_path` to route queries to tenant schemas
 
-**Reference**: [Database-Per-Service Migration Runbook](../runbooks/database-per-service-migration.md)
+**Reference**: [Data Model Reference](../architecture/data-model.md)
 
 **Verification:**
 
@@ -1784,4 +1786,4 @@ task-master parse-prd docs/guides/new-{service}-service-checklist.md
 - [Adding Starlark Service Bindings](adding-starlark-service-bindings.md)
 - [Circuit Breaker Usage Guide](circuit-breaker-usage.md)
 - [Testcontainers Usage Guide](testcontainers-usage.md)
-- [Database-Per-Service Migration Runbook](../runbooks/database-per-service-migration.md)
+- [Data Model Reference](../architecture/data-model.md)

docs/guides/new-bian-service-checklist.md

@@ -293,6 +293,7 @@ func EncodePartyCursor(c PartyCursor) string {
 ```
 
 Use cursor pagination when:
+
 - The dataset is large (thousands of rows)
 - Stable ordering is required under concurrent inserts
 - The caller needs to resume from a previous position

docs/guides/repository-conventions.md

@@ -101,6 +101,7 @@ both need updating:
    from the manifest. Currently shows 4 types in Resources tab.
 
 These serve complementary roles:
+
 - **Overview** = visual map + high-level summary (graph-first)
 - **Explorer** = detailed browse by resource type (list-first)
 
@@ -225,6 +226,7 @@ extraction paths:
 - `party_type` — from `manifest.partyTypes[]`
 
 Edge types:
+
 - `sourced_by` — market_data_set → market_data_source
 - `typed_as` — internal_account → account_type
 - `denominated_in` — internal_account → instrument
@@ -247,6 +249,7 @@ Add node components following the existing `memo()` pattern
 (`InstrumentNode`, `AccountTypeNode`, etc.).
 
 **ELK layer priorities** (lower = higher in graph):
+
 - Instruments: 50
 - Market Data Sources: 45
 - Market Data Sets: 40
@@ -268,6 +271,7 @@ types, market data) hidden by default — toggled on via filter.
 
 **Grouped filter panel**: Group toggles into 6 categories
 instead of 13 individual checkboxes:
+
 - Financial Core (instruments, account types, valuation rules)
 - Workflows (sagas)
 - Market Data (sources, sets)
@@ -295,6 +299,7 @@ to the Explorer page for the full breakdown.
 #### 2f. Double-click navigation
 
 Add navigation targets for all new types:
+
 - market_data_source/set → `/market-data`
 - organization → `/parties`
 - internal_account → `/internal-accounts`
@@ -370,6 +375,7 @@ type can follow in later PRDs.
 `ReconcileManifest` output. Drift items as a DataTable:
 resource_type, code, drift_type (MISSING, MODIFIED, EXTRA),
 description. "Run Reconciliation" button with:
+
 - Loading state during RPC (can take 5-30 seconds)
 - Warning display when services are unreachable
 - "No manifest applied" message for pre-045 tenants

docs/prd/046-economy-visualization-completeness.md

@@ -50,6 +50,7 @@ limits, allowing any single container to exhaust host resources.
 ### PR #1712 — Enforce Saga Step Limit + Remove Dead MemoryWarningThreshold
 
 **Findings**:
+
 - HIGH-1 — `MaxStepsPerExecution = 1_000_000` was defined but `SetMaxExecutionSteps()`
   was never called on the saga runtime thread, allowing CPU exhaustion via tenant scripts.
 - HIGH-4 (partial) — `MemoryWarningThreshold` constant was defined but never referenced
@@ -157,6 +158,7 @@ are Wave 2 work (approximately 1 week)
 ### PR #1736 — Add OPA Gatekeeper Constraint + Security Defaults CI Gate
 
 **Findings**:
+
 - HIGH-3 (regression prevention) — OPA Gatekeeper had no policy blocking
   `AUTH_ENABLED: "false"` in ConfigMaps.
 - HIGH-3 (CI gate) — No CI job verified security defaults after PRs.

docs/prd/047-security-audit-status.md

@@ -174,6 +174,7 @@ type TemplateRenderer interface {
 ```
 
 **Three Sender implementations**:
+
 - `resend.Sender` - production, wraps Resend Go SDK with circuit breaker
 - `log.Sender` - writes to application log, no API call (for `EMAIL_MODE=log`)
 - `noop.Sender` - discards silently (for `EMAIL_MODE=disabled` and tests)
@@ -235,6 +236,7 @@ Four templates using Go `html/template` with `embed.FS`, stored in
 | `account-frozen.html` | Account frozen (dunning level 3) | account ID, frozen reason, support contact |
 
 **Design principles**:
+
 - Single dunning template with severity parameter (reduces duplication,
   ensures brand consistency across escalation levels)
 - Responsive HTML (single-column, mobile-first)
@@ -361,6 +363,7 @@ Adapted from `shared/platform/events/metrics.go` (rename subsystem):
 | `email_circuit_breaker_state` | Gauge | 0=closed, 1=half-open, 2=open |
 
 **Alerting rules** (Prometheus/Alertmanager):
+
 - `email_outbox_pending_total > 100` for 5 minutes -> warn (backlog)
 - `email_outbox_dead_letter_total` increase > 0 -> alert (permanent failure)
 - `email_circuit_breaker_state == 2` for 5 minutes -> alert (Resend down)
@@ -437,6 +440,7 @@ payment-order service.
 ### Task 2: Email service package (3 points)
 
 `shared/pkg/email/`:
+
 - `sender.go` - `Sender` interface, `Message` type
 - `template.go` - `TemplateRenderer` using `html/template` + `embed.FS`
 - `outbox.go` - Outbox repository (write, read pending, update status,
@@ -449,6 +453,7 @@ payment-order service.
 - `noop/provider.go` - No-op sender for tests
 
 **Reuse explicitly**:
+
 - `circuitbreaker.go` wrapping Resend client
 - `shared/pkg/tokens/` for any future token operations
 - Go `html/template` only (lint rule: no `text/template` in email package)
@@ -457,6 +462,7 @@ payment-order service.
 
 Implement `dispatch.DispatchableInstruction` for `EmailOutboxRow`. Write a
 `BatchProcessor` callback that:
+
 1. Renders template via `TemplateRenderer`
 2. For dunning emails: checks invoice status, cancels if PAID
 3. Calls `Sender.Send()` with idempotency key as Resend header
@@ -481,6 +487,7 @@ as the event worker. Add circuit breaker state gauge. Mechanical adaptation.
 ### Task 5: Resend webhook endpoint (2 points)
 
 `POST /api/v1/webhooks/resend`:
+
 - Verify `Svix-Signature` header (Resend webhook signing)
 - Parse event type: `email.delivered`, `email.bounced`, `email.complained`
 - Look up audit log entry by `provider_id`
@@ -493,6 +500,7 @@ is the auth mechanism).
 ### Task 6: Templates (3 points)
 
 Four templates in `shared/pkg/email/templates/`:
+
 - `invoice.html` + `invoice.txt`
 - `dunning-notice.html` + `dunning-notice.txt` (parameterized: severity
   1/2/3 with `{{if eq .Severity 1}}` blocks)
@@ -566,6 +574,7 @@ EMAIL_BASE_URL=https://meridianhub.cloud
 ```
 
 **EMAIL_MODE**:
+
 - `disabled` - No outbox writes, no sending. For unit tests.
 - `log` - Writes outbox + audit log, renders templates, but does not call
   Resend API. For integration tests and CI.

docs/prd/052-email-platform.md

@@ -108,6 +108,7 @@ concern bridging the party service to authentication (see PRD 031).
 ### Task 2: Email verification flow (3 points)
 
 **Backend**:
+
 - Migration: `email_verification_tokens` table (token_hash, identity_id,
   expires_at, consumed_at)
 - On registration (when verification required): generate token via
@@ -119,6 +120,7 @@ concern bridging the party service to authentication (see PRD 031).
   (3/hour per identity via DB count query on outbox)
 
 **Frontend**:
+
 - Post-registration "check your email" page with resend button
 - Verification landing page (success, expired, already-verified, invalid
   states)
@@ -127,6 +129,7 @@ concern bridging the party service to authentication (see PRD 031).
 ### Task 3: Password reset flow (3 points)
 
 **Backend**:
+
 - Migration: `password_reset_tokens` table (token_hash, identity_id,
   expires_at, consumed_at)
 - `POST /api/v1/forgot-password` - always returns 200 (timing-safe:
@@ -142,6 +145,7 @@ concern bridging the party service to authentication (see PRD 031).
   INTERVAL '1 hour'`
 
 **Frontend**:
+
 - "Forgot password?" link on login page
 - Email input form -> "check your email" confirmation
 - Reset form (new password + confirm) -> success -> redirect to login