30 lines
1.2 KiB
Markdown
30 lines
1.2 KiB
Markdown
# 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.
|