Offline

Status: ✅ Decided — grounded in ADR-0013

Offline-first means the kernel is designed so that a field worker who loses connectivity can queue Actions and sync when reconnected — without data loss or silent duplication. The offline client stack (local action queue, local evidence vault, offline maps, conflict inbox) is deferred post-proof. The kernel invariants that make it possible are non-negotiable from day one.

The four non-negotiable kernel invariants (ADR-0013):

1. Actions are coarse semantic intents (SubmitSurvey{…}, ApproveAsBuilt{…}), never field-level column patches. A queued offline Action must replay meaningfully after a long gap; semantic intent makes this possible; a column delta does not.
2. Client-minted IDs and idempotency keys. Entities get client-generated UUIDs minted on-device before sync. Actions carry client idempotency keys. Reconnect deduplications are exact; nothing is duplicated.
3. Expected-version optimistic concurrency + conflict-as-first-class-outcome. A stale edit surfaces as a modeled reconciliation result fed to a conflict inbox — never a raw error. This is the same machinery as the GIS-vs-survey Statement conflict in ADR-0004.
4. Working Set as the sync/cache boundary. The offline package is a bounded, materializable working-set snapshot (a crew’s assigned work plus neighbors). Working Sets must be definable and size-bounded by design.

Bitemporal time — validTime (when it happened in the field) vs. transactionTime (when it synced) — rides along for free in the Statement model.

See also

• Concepts — Offline-first
• Data Model — Statement model carries bitemporal time; opt-in conflict resolution
• Consistency — expected-version against current state depends on the consistency model
• ADR-0013 — offline decision
• ADR-0004 — conflict-as-first-class-outcome

Open questions

• The offline client stack design (action queue, local vault, conflict inbox UI, offline map package) is deferred. ADR-0013 deliberately leaves it for post-proof field hardening.

← Architecture