Define canonical Cyd Bluesky archive v2 contract and fixtures

CONTEXT.md

@@ -9,62 +9,66 @@ Mobile and desktop Cyd offer the same Bluesky account-management capabilities an
 _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. Version 2 is the first supported Cyd archive format; the earlier unversioned mobile prototype is not a Cyd archive compatibility surface.
-_Avoid_: HTML export, database backup
+An export of one social-platform account's saved data. Each platform defines its own archive contents, behavior, compatibility guarantees, and version history, so references to a particular archive must name the platform.
+_Avoid_: archive, platform-neutral archive
 
-**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
+**Cyd Bluesky archive**:
+A Cyd archive governed by the Bluesky archive contract. Version 2 is the first supported Bluesky archive format; the earlier unversioned mobile prototype is not a compatibility surface.
+_Avoid_: Cyd archive v2, platform-neutral v2 archive
+
+**Bluesky interchange database**:
+The canonical representation of structured Bluesky account data inside a Cyd Bluesky archive. It is independent of each client's private runtime storage.
+_Avoid_: interchange database, 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
+**Bluesky local account**:
+A client's local representation of a Bluesky identity, identified within Cyd by a UUID and containing that client's Bluesky account settings and Bluesky saved data.
+_Avoid_: local account, 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
+**Bluesky archive import**:
+An idempotent recovery merge of a Cyd Bluesky archive into a matching Bluesky local account, preserving the union of Bluesky saved data while collapsing records that share stable Bluesky identifiers. It may restore data previously removed through Bluesky local deletion.
+_Avoid_: archive import, 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
+**Bluesky account settings**:
+Local preferences governing how Cyd saves and manages a Bluesky identity. A Cyd Bluesky archive can supply defaults for a new Bluesky local account, but does not silently override an existing Bluesky local account's preferences or schedules.
+_Avoid_: account settings, 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
+**Bluesky scheduled reminder**:
+A prompt to review and start due Bluesky 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 reminder, 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
+**Bluesky connection**:
+A local installation's authorization to act on a Bluesky identity. Bluesky connections are established separately on each client and are never part of a Cyd Bluesky archive.
+Disconnecting removes authorization without removing the Bluesky local account or its Bluesky saved data.
+_Avoid_: connection, account data, imported session, Bluesky 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
+**Bluesky saved data**:
+The Bluesky 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 Bluesky saved data regardless of the record category.
+_Avoid_: saved data, live feed, HTML export
 
-**Saved record**:
+**Bluesky 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
+_Avoid_: saved record, record revision, live record
 
-**Browse**:
-Inspect saved data inside Cyd without requiring a Bluesky connection or network access.
-_Avoid_: view on Bluesky, live feed
+**Bluesky browse**:
+Inspection of Bluesky saved data inside Cyd without requiring a Bluesky connection or network access.
+_Avoid_: browse, 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
+**Bluesky context snapshot**:
+The directly referenced author, reply parent, quoted record, external embed, and other captured information required to render a Bluesky saved record faithfully without recursively preserving the surrounding social graph.
+_Avoid_: context snapshot, 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
+**Complete Bluesky backup**:
+Bluesky saved data or a Cyd Bluesky 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_: complete backup, 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
+**Bluesky source deletion**:
+Removal of a record or relationship from Bluesky while retaining its Bluesky saved record and deletion state in Cyd.
+_Avoid_: source deletion, Bluesky 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
+**Bluesky local deletion**:
+An explicit removal of Bluesky saved data from Cyd, independent of whether the source still exists on Bluesky.
+_Avoid_: local deletion, Bluesky source deletion, stop saving

docs/adr/0001-bidirectional-cyd-archive-compatibility.md

@@ -1,3 +1,3 @@
-# Bidirectional Cyd archive compatibility begins with version 2
+# Bidirectional Cyd Bluesky archive compatibility begins with version 2
 
-Cyd mobile and desktop exchange Cyd archives beginning with the canonical version 2 format. The unversioned mobile prototype has no users and is unsupported by both clients; abandoning it avoids coupling the shared contract to Mobile's historical runtime schema. Each client clearly rejects archive versions it does not support so evolving one application does not silently break portability with the other.
+Cyd mobile and desktop exchange Cyd Bluesky archives beginning with the canonical Bluesky version 2 format. Bluesky archive versions are independent of the archive contracts and version histories for Cyd's other social platforms. The unversioned mobile prototype has no users and is unsupported by both clients; abandoning it avoids coupling the shared contract to Mobile's historical runtime schema. Each client clearly rejects Bluesky archive versions it does not support so evolving one application does not silently break portability with the other.

docs/adr/0002-canonical-archive-interchange-database.md

@@ -1,3 +1,3 @@
-# Canonical archive interchange database
+# Canonical Bluesky interchange database
 
-The `data.db` inside version 2 and later Cyd archives is a canonical interchange database rather than a copy of either client's runtime database. Mobile and desktop translate between private storage and this versioned schema, allowing their implementations and migrations to evolve independently; neither client maintains an adapter for the unused unversioned mobile prototype.
+The `data.db` inside Bluesky version 2 and later Cyd Bluesky archives is a canonical Bluesky interchange database rather than a copy of either client's runtime database. Mobile and desktop translate between private storage and this versioned schema, allowing their implementations and migrations to evolve independently; neither client maintains an adapter for the unused unversioned mobile prototype.

docs/adr/0004-merge-archive-imports-idempotently.md

@@ -1,3 +1,3 @@
 # Merge archive imports idempotently
 
-Importing a Cyd archive merges it with the matching local account rather than replacing local data. Records match on stable Bluesky identifiers such as AT URIs, richer or newer representations can update older ones, data absent from the archive is retained, and importing the same archive repeatedly has no further effect; this supports safe cross-device transfer without sacrificing data collected independently on either device. Because import is an explicit recovery action, it may restore locally deleted records, and its preview reports that restoration rather than relying on permanent deletion tombstones that would suppress older backups.
+A Bluesky archive import merges a Cyd Bluesky archive with the matching Bluesky local account rather than replacing Bluesky saved data. Bluesky saved records match on stable identifiers such as AT URIs, richer or newer representations can update older ones, Bluesky saved data absent from the Cyd Bluesky archive is retained, and importing the same archive repeatedly has no further effect; this supports safe cross-device transfer without sacrificing data collected independently on either device. Because Bluesky archive import is an explicit recovery action, it may restore records removed through Bluesky local deletion, and its preview reports that restoration rather than relying on permanent deletion tombstones that would suppress older backups.

docs/adr/0005-exclude-credentials-from-archives.md

@@ -1,3 +1,3 @@
 # Exclude credentials from Cyd archives
 
-Cyd archives never contain OAuth tokens, private keys, session state, or other reusable credentials. Imported accounts are immediately available for offline browsing, but each installation must establish its own Bluesky connection before it can refresh data or perform account actions, preventing a portable archive from becoming an account-control credential.
+Cyd Bluesky archives never contain OAuth tokens, private keys, session state, or other reusable credentials. Imported accounts are immediately available for offline browsing, but each installation must establish its own Bluesky connection before it can refresh data or perform account actions, preventing a portable archive from becoming an account-control credential.

docs/adr/0008-own-the-archive-contract-in-cyd.md

@@ -1,3 +1,3 @@
 # Own the shared archive contract in cyd
 
-The normative Cyd archive specification, format-version history, and canonical compatibility fixtures live in the `cyd` repository. Mobile and desktop may maintain implementation-specific types, but both must validate against this shared contract so compatibility is not inferred from either application's current runtime schema.
+The normative Cyd Bluesky archive specification, Bluesky format-version history, and canonical compatibility fixtures live in the `cyd` repository. Other social platforms have independent archive contracts and version histories. Mobile and desktop may maintain implementation-specific types, but both must validate against this shared Bluesky contract so compatibility is not inferred from either application's current runtime schema.

docs/adr/0010-make-each-archive-self-contained.md

@@ -1,3 +1,3 @@
-# Make each Cyd archive self-contained
+# Make each Cyd Bluesky archive self-contained
 
-Every Cyd archive is a complete snapshot of the local account's saved data and media at export time rather than an incremental delta that depends on earlier archives. Individual archives may be larger, but any one of them remains sufficient for recovery or cross-device transfer and can be merged idempotently on import.
+Every Cyd Bluesky archive is a complete snapshot of a Bluesky local account's Bluesky saved data at export time rather than an incremental delta that depends on earlier Cyd Bluesky archives. Individual archives may be larger, but any one of them remains sufficient for recovery or cross-device transfer through Bluesky archive import.

docs/adr/0011-ship-v2-archives-without-encryption.md

@@ -1,3 +1,3 @@
-# Ship version 2 archives without encryption
+# Ship Bluesky version 2 archives without encryption
 
-Version 2 Cyd archives are plaintext ZIP packages while the initial cross-platform contract is established. Passphrase encryption is deferred to a later format version; clients must not imply that version 2 archives protect sensitive saved data such as chats, and exports should communicate that limitation clearly.
+Cyd Bluesky archives at version 2 are plaintext ZIP packages while the initial cross-client Bluesky contract is established. Passphrase encryption is deferred to a later Bluesky format version; clients must not imply that Bluesky version 2 archives protect sensitive Bluesky saved data such as chats, and exports should communicate that limitation clearly.

docs/adr/0012-validate-v2-archive-integrity-before-import.md

@@ -1,3 +1,3 @@
-# Validate version 2 archive integrity before import
+# Validate Bluesky version 2 archive integrity before import
 
-Version 2 archives include a manifest listing every payload file's path, byte size, and SHA-256 digest, and export captures a point-in-time-consistent database and media snapshot. Import validates the complete manifest before mutating local data and applies the merge transactionally, preventing corrupt or partial packages from producing partially imported accounts.
+Bluesky version 2 archives include a manifest listing every payload file's path, byte size, and SHA-256 digest, and export captures a point-in-time-consistent database and media snapshot. Bluesky archive import validates the complete manifest before mutating Bluesky saved data and applies the merge transactionally, preventing corrupt or partial packages from producing partially imported Bluesky local accounts.

docs/adr/0019-store-the-latest-observed-record.md

@@ -1,3 +1,3 @@
 # Store the latest observed record
 
-Version 2 represents the latest observation of each Bluesky record at its stable AT URI, including observation timestamps and deletion state, rather than retaining every historical CID revision. Import selects the newer observation and does not replace populated fields with absent data; complete revision history is outside the initial parity scope.
+Bluesky version 2 represents the latest observation of each Bluesky record at its stable AT URI, including observation timestamps and deletion state, rather than retaining every historical CID revision. Import selects the newer observation and does not replace populated fields with absent data; complete revision history is outside the initial parity scope.

docs/adr/0020-do-not-use-the-archive-filename-for-validation.md

@@ -1,3 +1,3 @@
 # Do not use the archive filename for validation
 
-Version 2 archive filenames are friendly suggestions and may be changed by users without affecting import. Clients determine identity, format support, and integrity from validated internal metadata, schema, and manifest content rather than a handle-bearing filename; the unused unversioned mobile prototype receives no filename-based compatibility exception.
+Bluesky version 2 archive filenames are friendly suggestions and may be changed by users without affecting import. Clients determine platform, identity, format support, and integrity from validated internal metadata, schema, and manifest content rather than a handle-bearing filename; the unused unversioned mobile prototype receives no filename-based compatibility exception.

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

@@ -1,3 +1,3 @@
-# Deduplicate media within each local account
+# Deduplicate media within each Bluesky local account
 
-Desktop stores media content-addressably within each UUID-keyed local account, and saved records reference those assets rather than owning duplicate files. Version 2 archives likewise package each unique asset once and map record references through the interchange database; cross-account deduplication is deferred so deleting or exporting one account does not depend on another account's storage.
+Desktop stores media content-addressably within each UUID-keyed Bluesky local account, and Bluesky saved records reference those assets rather than owning duplicate files. Bluesky version 2 archives likewise package each unique asset once and map record references through the Bluesky interchange database; cross-account deduplication is deferred so deleting or exporting one Bluesky local account does not depend on another Bluesky local account's storage.

docs/adr/0026-export-portable-account-data-not-operational-state.md

@@ -1,3 +1,3 @@
-# Export portable account data, not operational state
+# Export portable Bluesky saved data, not operational state
 
-Version 2 archives include account identity and captured profile, saved records and media, source-deletion state, asset-completeness state, and portable save/delete rule defaults. They exclude credentials, schedules, pending or historical jobs, logs, analytics, error reports, temporary files, caches, and UI state because those are client-local operations whose transfer could duplicate work or trigger unintended behavior.
+Bluesky version 2 archives include the Bluesky identity and captured profile, Bluesky saved records and media, Bluesky source-deletion state, asset-completeness state, and portable Bluesky account settings. They exclude credentials, schedules, pending or historical jobs, logs, analytics, error reports, temporary files, caches, and UI state because those are client-local operations whose transfer could duplicate work or trigger unintended behavior.

docs/adr/0028-roll-out-archive-readers-before-writers.md

@@ -1,3 +1,3 @@
 # Roll out archive readers before writers
 
-Archive format changes ship readers before writers: Mobile and Desktop first gain and verify version 2 import, and version 2 export is enabled only after compatible readers are released. Version 2 is the first supported archive format; neither client imports or exports the unused unversioned mobile prototype.
+Bluesky archive format changes ship readers before writers: Mobile and Desktop first gain and verify Bluesky version 2 import, and Bluesky version 2 export is enabled only after compatible readers are released. Version 2 is the first supported Bluesky archive format; neither client imports or exports the unused unversioned mobile prototype.