mygo/docs/server/decisions/0007-command-scoped-persistence.md

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.