> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reflections.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR-0006: DB query surface segregation

> Constrain data mutation capabilities by design-time import boundaries.

<Info>**Status:** Accepted **Date:** 2026-02-06 **Deciders:** Reflections Maintainers</Info>

## 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.

## Related ADRs

* [ADR-0001: Monorepo and package boundaries](/decisions/adr-0001)
* [ADR-0003: Two-plane system architecture](/decisions/adr-0003)
* [ADR-0009: API architecture and authorization enforcement](/decisions/adr-0009)