Document mobile v2 archive decisions

CONTEXT.md

@@ -0,0 +1,70 @@
+# Cyd
+
+Cyd helps people preserve, inspect, and manage the data associated with their social-media accounts.
+
+## Language
+
+**Bluesky workflow parity**:
+Mobile and desktop Cyd offer the same Bluesky account-management capabilities and preserve the same data semantics, while each may use platform-appropriate interfaces and operating-system integrations.
+_Avoid_: UI parity, identical clients
+
+**Cyd archive**:
+A complete, self-contained, versioned snapshot of an account's saved data and media that supported Cyd clients can exchange without losing its meaning.
+_Avoid_: HTML export, database backup
+
+**Interchange database**:
+The canonical representation of structured account data inside a Cyd archive. It is independent of each client's private runtime storage.
+_Avoid_: runtime database, mobile database
+
+**Bluesky identity**:
+A Bluesky account identified durably by its DID, even when its handle changes or separate Cyd installations know it by different local identifiers.
+_Avoid_: handle, Cyd UUID
+
+**Local account**:
+A client's local representation of a Bluesky identity, identified within Cyd by a UUID and containing that client's settings and saved data.
+_Avoid_: Bluesky identity
+
+**Archive import**:
+An idempotent recovery merge of a Cyd archive into a matching local account, preserving the union of saved data while collapsing records that share stable Bluesky identifiers. It may restore data previously removed through local deletion.
+_Avoid_: replace, synchronize
+
+**Account settings**:
+Local preferences governing how Cyd saves and manages a Bluesky identity. An archive can supply defaults for a new local account, but does not silently override an existing local account's preferences or schedules.
+_Avoid_: account data, archive state
+
+**Scheduled reminder**:
+A prompt to review and start due account-management work. It does not authorize Cyd to perform deletion unattended; clients may use platform-appropriate delivery such as local notifications or server-scheduled push.
+_Avoid_: scheduled job, automatic deletion
+
+**Connection**:
+A local installation's authorization to act on a Bluesky identity. Connections are established separately on each client and are never part of a Cyd archive.
+Disconnecting removes authorization without removing the local account or its saved data.
+_Avoid_: account data, imported session, local account
+
+**Saved data**:
+The account records and complete media Cyd has preserved locally, including material that may later disappear from Bluesky. When a record is selected for saving, its full media is part of the saved data regardless of the record category.
+_Avoid_: live feed, HTML export
+
+**Saved record**:
+The latest representation of a Bluesky record observed by Cyd at a stable AT URI, together with its observation timestamps and deletion state. It is not a history of every CID revision.
+_Avoid_: record revision, live record
+
+**Browse**:
+Inspect saved data inside Cyd without requiring a Bluesky connection or network access.
+_Avoid_: view on Bluesky, live feed
+
+**Context snapshot**:
+The directly referenced author, reply parent, quoted record, external embed, and other captured information required to render a saved record faithfully without recursively preserving the surrounding social graph.
+_Avoid_: full thread, live lookup
+
+**Complete backup**:
+A saved dataset or Cyd archive containing every expected asset for its selected records. Missing assets are explicit and make the backup incomplete without invalidating the data that was successfully preserved.
+_Avoid_: valid archive, successful export
+
+**Source deletion**:
+Removal of a record or relationship from Bluesky while retaining Cyd's saved copy and deletion state.
+_Avoid_: local deletion
+
+**Local deletion**:
+An explicit removal of saved data from Cyd, independent of whether the source still exists on Bluesky.
+_Avoid_: source deletion, stop saving

docs/adr/0001-adopt-the-shared-cyd-contract.md

@@ -0,0 +1,3 @@
+# Adopt the shared Cyd contract
+
+Cyd Mobile adopts the cross-client Bluesky semantics, archive specification, version history, canonical fixtures, and compatibility expectations owned by the `cyd` repository rather than maintaining a duplicate normative contract. Mobile records only its implementation-specific decisions locally, so shared behavior has one source of truth while mobile constraints remain discoverable in this repository.

docs/adr/0002-translate-archives-through-private-runtime-storage.md

@@ -0,0 +1,3 @@
+# Translate archives through private runtime storage
+
+Cyd Mobile retains and migrates its existing private per-account runtime database rather than replacing it with the version 2 interchange schema. Dedicated version 2 adapters translate archive data at the boundary, allowing installed mobile data and mobile-specific persistence to evolve without coupling runtime migrations to the shared archive contract.

docs/adr/0003-store-connections-in-os-protected-storage.md

@@ -0,0 +1,3 @@
+# Store connections in OS-protected storage
+
+Cyd Mobile stores Bluesky OAuth session material outside account databases and archives in iOS Keychain or Android Keystore-backed secure storage, keyed by local-account UUID. Existing session material in `AsyncStorage` is moved and its old copy removed only after the protected write succeeds; disconnecting removes the protected connection while retaining the local account and its saved data.

docs/adr/0004-gate-v2-writing-on-complete-local-media.md

@@ -0,0 +1,3 @@
+# Gate version 2 writing on complete local media
+
+Cyd Mobile may implement and release a version 2 archive reader before it can preserve all selected media locally, but it does not enable its version 2 writer or claim complete version 2 conformance until issue #90 covers full-size images and full video. Specification work and reader rollout remain unblocked; the gate prevents mobile from producing nominally portable backups that still depend on live Bluesky media.

docs/adr/0005-use-server-push-for-mobile-reminders.md

@@ -0,0 +1,3 @@
+# Use server-scheduled push for mobile reminders
+
+Cyd Mobile sends schedule registration to Cyd’s service and uses server-scheduled push notifications rather than relying only on local notification scheduling, because delivery must remain stable when the app is closed. A push is only a scheduled reminder: opening it leads to review and requires the user to start the work, and the server is never authorized to run Bluesky deletion or hold Bluesky credentials.

docs/adr/0006-resume-archive-jobs-in-the-foreground.md

@@ -0,0 +1,3 @@
+# Resume archive jobs in the foreground
+
+Cyd Mobile persists import and export checkpoints plus isolated staging artifacts in durable app-managed storage so operating-system termination does not force a restart or partially mutate a local account. Jobs resume when Cyd next runs rather than promising background execution; import validates and prepares outside the live account and performs only its final merge transactionally.

docs/adr/0007-deduplicate-media-within-each-account.md

@@ -0,0 +1,3 @@
+# Deduplicate media within each local account
+
+Cyd Mobile stores full-size images and video content-addressably within each UUID-keyed local account, and saved records reference those assets rather than owning duplicate files. It does not deduplicate across accounts, so deleting, importing, or exporting one account never depends on another account’s storage while version 2 archives can package each unique asset once.

docs/adr/0008-pin-versioned-archive-contract-bundles.md

@@ -0,0 +1,3 @@
+# Pin versioned archive contract bundles
+
+Cyd Mobile validates archive behavior against immutable, versioned contract-test bundles published from the `cyd` repository, containing the normative specification, canonical fixtures, and expected normalized results. CI pins an explicit bundle for reproducibility and reports newer available bundles; mobile does not depend on a sibling checkout, a moving branch, or shared production runtime code.

docs/adr/0009-stream-and-defensively-validate-archive-imports.md

@@ -0,0 +1,3 @@
+# Stream and defensively validate archive imports
+
+Cyd Mobile’s version 2 importer reads ZIP entries incrementally into an isolated staging root and validates normalized paths, entry types, counts, declared sizes, digests, expansion, and available storage before commit. An extract-all API is insufficient; mobile may keep its ZIP library only if it exposes these controls, otherwise it uses a narrow replacement or native adapter so traversal, symlinks, forged manifests, and resource-exhaustion archives are rejected safely.

docs/adr/0010-export-a-point-in-time-account-snapshot.md

@@ -0,0 +1,3 @@
+# Export a point-in-time account snapshot
+
+Cyd Mobile briefly pauses account-mutating jobs to create a SQLite backup and transactional inventory of referenced media, then resumes normal work while hashing and packaging that staged point-in-time snapshot. Assets missing or changed before staging completes are represented and reported as unavailable rather than silently omitted, so the resulting archive is internally consistent and its completeness claim is honest.

docs/adr/0011-reconcile-duplicate-dids-before-enforcing-uniqueness.md

@@ -0,0 +1,3 @@
+# Reconcile duplicate DIDs before enforcing uniqueness
+
+Cyd Mobile migration detects existing local accounts that share a Bluesky DID and flags them for explicit reconciliation rather than selecting one silently. The user previews an idempotent union of saved data and chooses the surviving local-account UUID and settings; after duplicates are resolved, mobile enforces one local account per DID so archive imports have an unambiguous destination.

docs/adr/0012-abandon-the-unreleased-v1-archive.md

@@ -0,0 +1,3 @@
+# Abandon the unreleased version 1 archive
+
+Cyd Mobile neither imports nor exports its unversioned prototype archive, retrospectively called version 1, because it has no users and exposes mobile’s private runtime schema rather than the canonical interchange contract. Version 2 is the first supported Cyd archive; removing v1 compatibility avoids maintaining an unsafe filename-dependent extract-and-copy path or constraining the cross-client design around unused data.

docs/adr/0013-encrypt-connections-not-saved-content.md

@@ -0,0 +1,3 @@
+# Encrypt connections, not saved content
+
+Cyd Mobile does not add application-level encryption for runtime databases, chats, or media in the initial version 2 work; saved content relies on the mobile operating system’s app sandbox, access controls, and device encryption. OAuth connection material remains the protected-storage exception, while plaintext version 2 export explicitly warns that an archive may contain sensitive saved content; archive encryption requires a future format and recovery design.

docs/adr/0014-allow-os-backup-of-committed-account-data.md

@@ -0,0 +1,3 @@
+# Allow OS backup of committed account data
+
+Cyd Mobile leaves committed per-account databases and media eligible for normal iOS and Android device backup because users expect Cyd data to restore with their device. Temporary import/export staging and reproducible caches are excluded to avoid backing up partial or inflated working state, while OAuth connection material follows the separate Keychain or Keystore backup policy.

docs/adr/0015-keep-archive-portability-free.md

@@ -0,0 +1,3 @@
+# Keep archive portability free
+
+Cyd Mobile does not require a premium subscription to export locally saved data, import a supported Cyd archive, or browse restored data offline. Premium policy may govern collection and automation features, but it does not restrict recovery or portability of data the user already holds.