design: decide long-term OpenCode data isolation #384

New issue

Open

opened 2026-07-18 00:18:00 +02:00 by dries · 0 comments

dries commented

2026-07-18 00:18:00 +02:00

Owner

Parent

#375

What to build

Decide and document the durable data architecture for managed project containers. The selected direction is isolated per-project OpenCode databases plus an ocman-owned, API-fed host-local read model; shared or bind-mounted OpenCode SQLite is out of scope, especially on Docker Desktop for macOS.

This ticket produces a decision and executable follow-up plan, not a speculative rewrite. The choice must preserve historical dashboard data, session ownership, statistics, parent/child relationships, multi-remote routing, and safe upgrades.

Acceptance criteria

Current dependencies on OpenCode SQLite are inventoried by user-visible behavior rather than only by package or query.
The decision explains why shared/bind-mounted OpenCode SQLite is rejected without requiring #382 qualification.
The options compare isolation, historical availability, schema/version coupling, routing, migration cost, performance, backup/recovery, and remote-host behavior.
Per-instance database analysis defines instance/session identity, state-key implications, aggregation, stopped-container history, and collision handling.
API/event-backed analysis defines ingestion, replay/gap recovery, ordering, retention, initial backfill, statistics, and behavior when an instance is offline.
The selected direction has a recorded architecture decision with explicit rejected alternatives and a migration/rollback strategy.
OpenCode 1.17.15 API assumptions are version-pinned and assigned contract tests before runtime rollout.
Follow-up implementation tickets are created only for the selected direction and are sized as independently verifiable slices.
Documentation states that container mode must not ship by sharing or bind-mounting the host OpenCode database.

Dependency order

Blocks #378.
#382 is superseded by this decision.

## Parent #375 ## What to build Decide and document the durable data architecture for managed project containers. The selected direction is isolated per-project OpenCode databases plus an ocman-owned, API-fed host-local read model; shared or bind-mounted OpenCode SQLite is out of scope, especially on Docker Desktop for macOS. This ticket produces a decision and executable follow-up plan, not a speculative rewrite. The choice must preserve historical dashboard data, session ownership, statistics, parent/child relationships, multi-remote routing, and safe upgrades. ## Acceptance criteria - [ ] Current dependencies on OpenCode SQLite are inventoried by user-visible behavior rather than only by package or query. - [ ] The decision explains why shared/bind-mounted OpenCode SQLite is rejected without requiring #382 qualification. - [ ] The options compare isolation, historical availability, schema/version coupling, routing, migration cost, performance, backup/recovery, and remote-host behavior. - [ ] Per-instance database analysis defines instance/session identity, state-key implications, aggregation, stopped-container history, and collision handling. - [ ] API/event-backed analysis defines ingestion, replay/gap recovery, ordering, retention, initial backfill, statistics, and behavior when an instance is offline. - [ ] The selected direction has a recorded architecture decision with explicit rejected alternatives and a migration/rollback strategy. - [ ] OpenCode 1.17.15 API assumptions are version-pinned and assigned contract tests before runtime rollout. - [ ] Follow-up implementation tickets are created only for the selected direction and are sized as independently verifiable slices. - [ ] Documentation states that container mode must not ship by sharing or bind-mounting the host OpenCode database. ## Dependency order - Blocks #378. - #382 is superseded by this decision.