ADR 001: persistence authority

Status: accepted

Decision

Octonode has one durable authority per deployment mode:

The event log is not an authority in v1. Run records are history, not a replay source.

Alternatives considered

• File-canonical Server/Studio would make Git integration simple, but cannot represent workspace-only records or provide atomic multi-record writes without turning the file into a database.
• Store-canonical Server/Studio matches the existing visibility and workspace model and keeps every server mutation behind one storage boundary. This is the selected model.
• Event-log canonical storage would provide replay and audit history, but adds migrations, compaction, and projections before v1 needs them.

Revisions and reconciliation

Exact file bytes own file revisions. Workflow graph revisions hash the canonical workflow record and its layout. Mutable API writes require the revision returned by the corresponding read; a mismatch returns 409 without changing live state.

On Server/Studio startup, the semantic revision of the selected config file is compared with the last imported revision. An unchanged file does nothing. A changed file replaces records owned by the previous import, preserves store-only records, and records the new imported revision. An unreadable or invalid file is reported and never replaces the store. External edits therefore become visible at the next reconciliation; they do not race an active commit.

Exports are point-in-time, versioned snapshots of the store. Restore validates the archive version and checksums before replacing live state. Secrets are excluded unless a deployment provides an encrypted secret backend.

Design review authority

Repository/project files remain authoritative for site content. A design artifact stores only review identity, an immutable full-project revision hash, and a bounded preview descriptor in the workspace social Durable Object. Each design thread stores its original artifact revision and viewport/source anchor once. Projection to another revision is append-only: a confident projection records new normalized coordinates, while uncertainty records detached; neither case rewrites the historical target.

Project removal stops new revisions and previews but does not silently retarget or erase historical review anchors. They follow workspace collaboration retention and are removed by the existing workspace deletion flow. Moderation changes comment content/status through the shared review-comment tables, never the immutable target.

Failure recovery

Multi-artifact mutations stage and validate their complete candidate state before commit. Filesystem commits use unique transaction directories and atomic rename. Startup either finishes a transaction whose commit marker exists or removes an uncommitted transaction, so a restart exposes the old complete state or the new complete state, never a mixture.

Deterministic examples

• Restart without an external edit: the stored records and revisions are unchanged.
• External file edit followed by restart/reconciliation: imported records take the edited values; unrelated Studio-only records remain.
• External edit concurrent with a stale Studio save: the first committed revision wins and the stale writer receives 409 with the current revision.
• Invalid external file or corrupt backup: live store remains unchanged and startup/restore reports the error.