Skip to main content
Status: Accepted Date: 2026-02-06 Deciders: Reflections Maintainers

​
Context

Different runtime planes need different DB privileges. Realtime paths must not mutate truth tables, while workers must retain administrative mutation capabilities for ingestion and evaluation workflows.

​
Decision

Expose database behavior through three explicit query entrypoints:
  • @reflection/db/queries/read: read-only retrieval operations.
  • @reflection/db/queries/write: app/API writes for non-truth-table domains (sessions, traces, CRUD).
  • @reflection/db/queries/admin: privileged ingestion/evaluation and truth-table mutation operations.
Enforce the segregation using import contract tests in realtime packages.

​
Alternatives considered

​
Alternative 1: Single DB query barrel export

Pros:
  • Simpler import ergonomics.
Cons:
  • No capability boundary.
  • Easier accidental writes in read-only runtime paths.

​
Alternative 2: Runtime-only guards without import segmentation

Pros:
  • Reduced API surface complexity.
Cons:
  • Fails later (at runtime) instead of early (at import time).
  • Harder static review of privilege boundaries.

​
Alternative 3: Separate physical databases per runtime plane

Pros:
  • Strong isolation guarantees.
Cons:
  • High operational and data synchronization complexity.

​
Consequences

Benefits:
  • Clear privilege model aligned with architecture planes.
  • Faster code review for data safety concerns.
  • Reduced accidental mutation risk in low-latency paths.
Costs:
  • More curated export maintenance.
  • Some developer friction when choosing entrypoints.

​
Implementation notes

  • Keep entrypoint exports minimal and explicit in the query modules.
  • Enforce admin-query boundary via three layers:
    • ESLint: no-restricted-imports blocks @reflection/db/queries/admin from packages/brain-core/ and apps/api/.
    • Architecture guard: simplicity-guard.mjs validates cross-plane import constraints in CI.
    • File-scan tests: dedicated tests in packages/brain-core and apps/api verify no admin imports are present.