docs/PHASE2_ADJACENT_GAP_AUDIT.md

# Phase 2 Adjacent-Gap Audit — Durable Database and Domain State

**Audit date (UTC):** 2026-07-23  
**Scope:** relational backends, migrations, identity/account/analysis entities, financial lifecycle entities, transaction boundaries, restart behavior, idempotency, execution locking, legacy state, browser/process authority, and multi-worker failure behavior.  
**Release posture:** Paper-only; `HERMES_EXECUTION_ENABLED=false` remains the default; Testnet/Live mutation remains disabled.

## Architecture reviewed

- SQLite is restricted to isolated local Paper operation. Production-shaped configuration requires PostgreSQL and rejects dialect mismatches or in-memory SQLite.
- PostgreSQL has explicit ordered DDL, checksums, transactional forward migration, and advisory-lock serialization. The driver is lazy and injectable; DSNs are never emitted in connection failures.
- The lifecycle schema includes users, sessions, roles, exchange accounts, trading-mode policy, analysis requests, market snapshots, plans, approvals, risk decisions, executions/events, orders/events, fills, positions/events, protective orders, audit events, idempotency evidence, and fenced execution locks.
- Financial records are owner/account/mode/environment scoped and versioned where required. Order/fill/protection scope is inherited and query isolation is enforced.
- Position mutations and position-event insertion share one transaction. Fill insertion and order aggregate updates share one transaction. Realized PnL ledger updates occur in the same transaction as close fills.
- Idempotency is persisted before adapter communication, request-content and operation-scope bound, retained after active TTL expiry, and restart safe. Execution locks are database-backed, scoped, leased, and fenced.
- The historical direct Paper API now delegates to the relational execution service. The former module singleton, in-memory duplicate map, and `paper_positions.json` authority were removed.
- The legacy `hermes_durable.sqlite3` facade is not imported by runtime code. A separate one-way operator tool validates legacy records, imports positions as `manual_review`, imports plans as invalidated, and cannot authorize execution.
- Browser `localStorage` is limited to presentation preferences; approval, account, mode, leverage, position, and execution controls are not accepted as authority.

## Failure and concurrency evidence

- Fresh and previous-schema migration paths are tested for SQLite and an injected PostgreSQL driver.
- Invalid/unknown/checksum-tampered migration histories fail startup.
- PostgreSQL migration rollback preserves the previous applied version in the injected-driver contract test.
- Failure injection proves fill/order aggregates and position/event pairs roll back atomically.
- A fresh Python process observes persisted plans, approvals, orders, fills, positions, protection, PnL, position events, and idempotency evidence.
- Concurrent idempotency claims produce one winner. Duplicate client-order creation produces one committed order/event pair. Scoped lock contention and stale fencing-token release fail safely.
- Database startup failure raises a diagnostic server-side error and does not fall back to memory or an alternate database.

## Adjacent findings and dispositions

1. **Position events were missing.** Closed with SQLite migration `012_position_events.sql`, PostgreSQL migration `004_position_events.sql`, transactional repository writes, and lifecycle tests.
2. **Legacy direct Paper execution retained module/JSON authority.** Closed by routing the compatibility API through relational repositories and removing the singleton/JSON book.
3. **Realized PnL was not atomically coupled to close fills.** Closed by updating the daily risk ledger inside the close-fill transaction.
4. **Protective orders remained active after a confirmed full close.** Closed by cancelling matching active/submitted/ambiguous protection after durable close confirmation.
5. **The authority audit only detected obvious container literals and missed class-instance singletons.** Closed with AST-based module-state checks and negative fixtures for a position-book singleton, legacy financial JSON path, runtime legacy-store import, and browser approval storage.

## Remaining external-only verification

A real disposable PostgreSQL instance is not available in this workspace. The backend, migrations, advisory-lock protocol, connector injection, SQL compatibility, failure rollback, and operator commands are implemented and tested locally; an actual `psycopg` migration/backup/restore smoke run remains a Desktop/CI verification item. This does not enable Testnet or Live execution.

## Audit conclusion

No known critical process-local, browser-local, flat-file, transaction-integrity, restart, or multi-worker authority gap remains in the implemented Paper path. Phase 2 file implementation is complete except for the named disposable-PostgreSQL smoke verification.

**Note (2026-07-27):** LLM-facing mutation tools were re-verified under plugin-based registration; the three mutation handlers remain hard-reject stubs and are not registered in the runtime toolset.