# ADR-0007: Use Command-Scoped Persistence Mutations

Status: Accepted  
Date: 2026-07-16

## Context

Each business operation needs a persistence contract that exposes its writable fields, authorization predicates, and transaction boundary.

## Decision

- Give each mutation a use-case-specific method and parameter type.
- Inject the query and mutation capabilities required by each service.
- Select mutation columns explicitly.
- Include ownership, credential type, and active-state predicates where the operation requires them.
- Revalidate file hierarchy state inside the mutation transaction.
- Lock PostgreSQL hierarchy rows in sorted order.
- Start SQLite write transactions with `_txlock=immediate`.
- Consume a refresh session in one lock, read, and delete transaction.
- Use `internal/testutil` for privileged fixture setup.

## Consequences

- Mutation inputs expose the fields writable by the use case.
- Guarded zero-row updates map to domain not-found results.
- File hierarchy mutations preserve active parent-child relationships under concurrency.
- One refresh session issues one replacement token pair.
- SQLite serializes these write transactions from their first database operation.
- Future mutations require a named command and an explicit capability.