11. Domain Model and State Ownership

The canonical data contract is specified in specs/002-v000-technical-specification/data-model.md. The core entities are DocumentSource, DocumentIdentity, SourceCapabilities, ExternalRevision, FormatDescriptor, DocumentSession, RendererDescriptor, RendererCapabilities, TextRoundTripProfile, MetadataFact, and RecoveryRecord.

Native source handles are opaque UUID-keyed tokens scoped to one process and session. Desktop identity uses platform file identity with normalized path fallback. Android identity uses provider authority, document ID when available, and canonical URI. A path or URI string alone is never assumed to be stable identity.

Rust owns source handles, external revisions, format evidence, text profiles, normalized metadata, save preconditions, and persisted recovery. TypeScript owns the active editor state, tab order, selections, navigation, visible warnings, and renderer lifecycle. Every editable change increments a session revision. Every save includes the expected session and external revisions.

stateDiagram-v2
  direction TB
  [*] --> Acquiring
  Acquiring --> Detecting
  Detecting --> Loading
  Detecting --> Unsupported
  Loading --> Clean
  Loading --> Failed
  Clean --> Dirty: edit
  Clean --> Reloading: external change
  Dirty --> Saving: save
  Dirty --> Conflicted: external change
  Saving --> Clean: durable receipt
  Saving --> Dirty: write failure
  Saving --> Conflicted: stale revision
  Conflicted --> Dirty: keep local
  Conflicted --> Reloading: use external
  Reloading --> Clean
  Dirty --> RecoveryAvailable: abnormal termination
  RecoveryAvailable --> Dirty: restore
  Clean --> Closed
  Dirty --> Closed: explicit discard
  Unsupported --> Closed
  Failed --> Closed
  Closed --> [*]