feat(repository): refactor query/mutation ports with capability-safe

interfaces

- refactor: split UserRepository into AuthUserRepository and
  AdminUserRepository capabilities
- refactor: split SessionRepository into AuthSessionRepository and
  repository-owned CLI/admin methods
- refactor: replace generic Repository Update/Delete with
  operation-specific params and ownership predicates
- refactor: replace CredentialRepository generic CRUD with
  passkey-specific methods
- refactor: replace FileRepository generic Create/Update/Delete with
  UploadedFileParams, DirectoryParams, and owned soft-delete
- refactor: remove repository fields from WebApp struct; repositories
  are now composition-time wiring only
- feat: add domain error kinds ErrParentNotFound, ErrParentNotDir,
  ErrDirectoryNotEmpty, ErrInvalidMove
- feat: add CredentialTypeAppPasskey constant
- feat: add testutil.SetUserAdmin for test fixture setup that bypasses
  production service ports
- test: add architecture test banning GORM Save in repository package
- test: add capability interface contract tests ensuring each service
  receives the minimal interface
- test: add blockingStorage helper for concurrent promotion tests
- test: add preserved DSN parameter test for sqliteImmediateDSN
- docs: update architecture decisions with repository write rules and
  capability separation
- docs: update roadmap to clarify atomic single-use refresh sessions
- docs: add -race test target to development docs

docs/server/architecture.md

@@ -20,6 +20,9 @@ Rules:
 - JSON response DTOs live in HTTP packages. Domain and service result structs are not the public REST schema.
 - Domain models may use `json:"-"` for defensive redaction of sensitive fields; this is not a REST response contract.
 - Domain errors carry a protocol-neutral kind, a safe message, and an optional cause. HTTP status mapping happens only at the API boundary.
+- Repository query ports remain entity-oriented, while mutation ports expose business commands with operation-specific parameter types. Services never pass a mutable domain entity to a generic update or delete method.
+- Service constructors using split repository capabilities accept the smallest capability needed by that service. Their composition-time unions do not cross into business services.
+- Repository mutations use explicit columns and lifecycle/ownership predicates. Full-entity `Save` is prohibited so a write cannot accidentally change protected fields or revive a soft-deleted record.
 - Repository abstracts the database; Storage abstracts where bytes live, including staged upload promotion.
 - `internal/server` is the composition root — wires all dependencies together.
 
@@ -42,6 +45,19 @@ Rules:
 | | `internal/storage` | Storage backend interface + local disk impl, with staging and promotion | 🛠 WIP |
 | **Util** | `internal/auth` | JWT sign/verify (HS256), token type discrimination (access/refresh), password hashing (bcrypt), app passkey tokens | ✅ |
 | | `internal/api` | Unified JSON error response helpers and REST error-kind mapping | ✅ |
+| | `internal/testutil` | Test-only fixture helpers for privileged setup that production service ports intentionally do not expose | ✅ |
+
+## Persistence Write Boundaries
+
+- User registration accepts `RegisteredUserParams`; the repository fixes new users to non-admin, active state. Administrative deletion is a separate capability.
+- File creation, directory creation, metadata changes, and soft deletion use distinct commands. Metadata updates can only write `name`, `parent_id`, and GORM-maintained `updated_at`.
+- Refresh sessions are created, atomically consumed, idempotently revoked, or removed by explicit maintenance operations. Refresh token rotation consumes a session at most once.
+- Passkey creation fixes the credential type to the app-passkey type. Usage recording and revocation include credential-type and ownership conditions where applicable.
+- `app.WebApp` contains runtime services, storage, database lifecycle, configuration, and metadata. Repository implementations remain local to bootstrap and are injected directly into the services that require them.
+
+## File Hierarchy Transactions
+
+File child creation, movement, and directory deletion share one parent-locking protocol. PostgreSQL locks active owned source and parent rows in sorted ID order with `SELECT ... FOR UPDATE`; directory deletion checks active children while holding the directory lock. SQLite connections add `_txlock=immediate` to the configured DSN so the transaction acquires its write reservation before reading hierarchy state. These rules prevent a concurrent mutation from creating an active child below a deleted directory.
 
 ## API Routes (v0)
 

docs/server/decisions.md

@@ -46,7 +46,7 @@
 
 **Consequences**:
 - Version is build metadata from `internal/app/version.go`, not a config-file field.
-- `app.WebApp` is the place to add future services, repositories, storage, and app metadata incrementally.
+- `app.WebApp` is the place to add future runtime services, storage, and app metadata incrementally; repository implementations stay inside composition setup.
 - Request ID middleware is not part of the current foundation; add it only with a logging/tracing/error-correlation design.
 
 ## 2026-04-29: Auth Refinements
@@ -123,3 +123,26 @@
 - Authenticated file operations cannot use status codes or messages to determine whether another user's resource exists.
 - A successful first delete returns `204 No Content`; repeated deletes return `404 Not Found` while remaining idempotent in effect.
 - Unauthenticated requests remain `401 Unauthorized`, non-empty directory deletion remains `409 Conflict`, and permission-denied behavior outside the file boundary remains unchanged.
+
+## 2026-07-16: Command-Scoped Persistence Mutations
+
+**Context**: Generic `Repository.Update(*Entity)`, full-entity GORM `Save`, and broad delete methods exposed fields and lifecycle transitions that individual services were not authorized to perform. They also allowed a stale file entity to revive a soft-deleted row, left file parent checks vulnerable to concurrent deletion, and allowed two refresh requests to consume the same session.
+
+**Decisions**:
+
+| Decision | Guidance |
+|----------|----------|
+| Command-scoped writes | Every mutation has a use-case-specific method and parameter type. Mutable domain entities do not cross a service-to-repository write boundary. |
+| Capability interfaces | Auth and admin services accept only the query and command capabilities they require. Wider user and session interfaces exist only for construction and repository-focused consumers. |
+| Explicit mutation predicates | Updates name concrete columns and include ownership, credential type, and/or active-state predicates appropriate to the command. A zero-row guarded mutation maps to a domain not-found result. |
+| Transactional file hierarchy | Child creation, movement, and directory deletion revalidate hierarchy state in the same transaction. PostgreSQL locks relevant rows in sorted ID order; SQLite DSNs force `_txlock=immediate`. |
+| Atomic refresh consumption | Refresh rotates through one transaction that locks, returns, and deletes the session. A concurrent replay cannot issue a second token pair. Logout remains an idempotent revoke-by-hash command. |
+| Test-only privilege setup | Tests elevate users through `internal/testutil`; no production role mutation is added merely to prepare fixtures. |
+
+**Consequences**:
+
+- Protected user, file, session, and credential fields are absent from ordinary mutation inputs, reducing illegal write paths at compile time.
+- Deleted file rows cannot be revived by stale metadata updates, and successful hierarchy races cannot leave active orphan children.
+- PostgreSQL relies on row-level locking while SQLite serializes these hierarchy and session write transactions from their first database operation. This favors correctness over concurrent SQLite writers.
+- Adding a future profile, password, role, restore, or other mutation requires a named command and an explicit capability rather than extending a universal update method.
+- REST routes, payloads, status codes, database schema, and dependency set remain unchanged.

docs/server/development.md

@@ -17,6 +17,7 @@ go build -o mygo .
 ```bash
 go test ./...
 go test -v -run TestName ./internal/...
+go test -race ./internal/repository ./internal/service ./internal/server
 ```
 
 ## Lint & Format
@@ -52,6 +53,12 @@ go mod tidy     # after adding/removing imports
 
 Server config is loaded via viper from `config.yaml` (defaults in `internal/config/load.go`).
 
+For SQLite, the repository preserves configured DSN parameters and adds
+`_txlock=immediate`. Write transactions therefore reserve the database before
+performing hierarchy or refresh-session reads, matching the locking assumptions
+used by the repository commands. Keep this behavior when supplying a SQLite URI
+such as `file:mygo.db?cache=shared`.
+
 ```yaml
 server:
     host: 0.0.0.0

docs/server/roadmap.md

@@ -5,7 +5,7 @@
 | Feature | Status | Notes |
 |---------|--------|-------|
 | CLI config management | ✅ | Viper YAML + env + flags, typed Duration config |
-| JWT authentication | ✅ | access + refresh tokens, refresh token in DB, app passkey support |
+| JWT authentication | ✅ | access + refresh tokens, atomic single-use refresh sessions, app passkey support |
 | Web API foundation | ✅ | WebApp composition, Gin router, graceful shutdown, `GET /api/v1/version` |
 | File upload/download/manage APIs | 🛠 WIP | REST API via Gin |
 | Admin endpoints | 🛠 WIP | user service boundary in place for superusers |
@@ -21,13 +21,13 @@ Package-level implementation order (each task includes unit tests):
 4. `internal/api` — protocol-neutral error kind to REST response mapping ✅
 5. `internal/auth` — JWT utils ✅
 6. `internal/storage` — backend interface + local fs with staged upload promotion
-7. `internal/repository` — interfaces + GORM/SQLite impl ✅
+7. `internal/repository` — command-scoped mutation capabilities + GORM/SQLite transaction protocol ✅
 8. `internal/service` — auth, file, admin services ✅
 9. `internal/middleware` — logger, cors, auth ✅ (auth done; principal boundary enforced)
 10. `internal/handler` — auth, account, file, admin handlers 🛠 (HTTP DTO mapping in place)
 11. `internal/server` — Gin router, route registration, graceful shutdown ✅
 12. `cmd/serve.go`, `cmd/config.go`, `cmd/status.go` ✅ (serve done)
-13. Integration tests 🛠 (authenticated register → login → upload → list → download route flow covered with a small file; authentication bypass, invalid token, concealed cross-user resources, and strict delete boundaries covered)
+13. Integration tests 🛠 (authenticated register → login → upload → list → download route flow covered with a small file; authentication bypass, invalid token, concealed cross-user resources, strict delete, atomic refresh consumption, and file hierarchy race boundaries covered)
 14. Architecture boundary tests ✅
 
 ## Future