refactor(api): enforce protocol-neutral service boundaries

- refactor: move HTTP status and DTO concerns out of model and service
  layers into API and handler code.
- feat: add admin service boundary and route auth through services
  instead of direct repository access.
- test: add architecture and error tests covering package boundaries,
  redaction, and service behavior.
- docs: record the protocol-neutral boundary decision and update
  architecture and roadmap notes.

docs/decisions.md

@@ -87,3 +87,22 @@
 - Interrupted, malformed, and oversized uploads leave only staging objects, which are safe to clean by path prefix and age.
 - Local storage promotes with `os.Rename` and falls back to copy/delete on cross-device `EXDEV`; future S3 storage can implement promotion with copy/delete while keeping business visibility controlled by the DB row.
 - A DB failure after promotion can still leave a long-term orphan object, but it is not visible through the file API and can be cleaned independently.
+
+## 2026-07-05: Protocol-Neutral Service Boundary
+
+**Context**: The service and model layers carried HTTP status codes and JSON response tags, and some middleware and handlers accessed repositories directly. That made the business layer harder to reuse for future WebDAV and Nextcloud-compatible APIs.
+
+**Decisions**:
+
+| Decision | Guidance |
+|----------|----------|
+| Protocol-neutral errors | `model.AppError` uses an error `Kind`, safe message, and optional cause. REST status codes are mapped in `internal/api` only. |
+| API log references | REST error responses may include `error.log_id` for server-recorded errors: all 5xx responses and 4xx responses with internal causes. |
+| Service boundaries | Handlers and middleware depend on services, not repositories. `AuthService` authenticates access tokens into a principal; `AdminService` owns admin user operations. |
+| DTO ownership | Service and model structs are internal/domain data. HTTP handlers assemble response DTOs with JSON tags. |
+| Architecture enforcement | Package-level tests reject HTTP imports in model/service and repository imports in handlers/middleware. Targeted model tests verify defensive JSON redaction for sensitive fields. |
+
+**Consequences**:
+- REST remains a handler/API concern, and future protocols can reuse services without HTTP leakage.
+- Error responses keep the same top-level shape, with optional `log_id` instead of embedding log references in the message.
+- Admin and auth middleware behavior is testable through service contracts rather than database access.