diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index 76863a8..e8fe2d0 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -8,8 +8,8 @@ work belongs here before implementation. acceptance gates on 2026-09-20. **Milestone 2 — dependable daily CLI: complete.** Phase 3 passed its acceptance -gates on 2026-09-20. Phase 4 design is the next active milestone and requires -format-level decisions before implementation. +gates on 2026-09-20. The Phase 4 format contract was approved on 2026-09-20; +implementation is now proceeding through isolated compatibility checkpoints. ## Phase 0 — audit and guardrails @@ -78,14 +78,17 @@ format-level decisions before implementation. ## Phase 4 — Git-like reversible workflow -- [ ] Approve the written design for working state, pseudo-staging, committed +- [x] Approve the written design for working state, pseudo-staging, committed epochs, and recovery semantics before implementing it. See [the Phase 4 proposal](docs/staging-design.md). - [x] Define `diff`, `stage`, `unstage`/`restore --staged`, `commit`, `restore`, `revert`, and `log` behavior, including entity-level selection. - [x] Define crash consistency, locking, concurrent-process behavior, and repository format versioning. -- [ ] Add migration fixtures for all prior supported repository versions. +- [x] Add a version-1 migration fixture matrix covering empty and populated + histories, tags, future epochs, relationships, legacy `Monster` naming, and + malformed input; materialise each case through the real legacy manifest and + snapshot types. - [ ] Implement only after the design preserves current data and allows every ordinary mistake to be reversed without manual JSON editing. diff --git a/docs/architecture.md b/docs/architecture.md index 3f27156..2084510 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -19,11 +19,11 @@ writes with temporary-file plus rename; add locking; remove unsafe cache accessors; separate styling from semantic output; and retain unknown custom metadata as the model becomes organisation-agnostic. -Phase 4's proposed persistence boundary is specified in the +Phase 4's approved persistence boundary is specified in the [staging, history, and recovery design](staging-design.md). It separates HEAD, the index, and the editable worktree, and defines the atomic transaction and -migration rules that implementation must preserve. The proposal requires user -approval before repository-format code changes begin. +migration rules that implementation must preserve. Versioned manifest and +snapshot types now isolate that future format from the active legacy reader. Library tests currently cover parsing, statistics, display snapshots, and parts of entity/epoch behavior. CLI integration coverage is the main gap. Routine CI diff --git a/docs/staging-design.md b/docs/staging-design.md index 0b97a02..30bccc0 100644 --- a/docs/staging-design.md +++ b/docs/staging-design.md @@ -1,8 +1,7 @@ # Staging, history, and recovery design -Status: **proposed for approval**. This document is the Phase 4 contract; it -does not describe behavior available in the current release. Persisted-format -implementation must not begin until this contract is approved. +Status: **approved on 2026-09-20**. This document is the Phase 4 implementation +contract; it does not describe behavior available in the current release. The goal is a familiar Git-like workflow without pretending that Epoch Forge is Git. A repository has one editable timeline, every meaningful change can be diff --git a/lib_efo/src/lib.rs b/lib_efo/src/lib.rs index 6acf65d..292825e 100644 --- a/lib_efo/src/lib.rs +++ b/lib_efo/src/lib.rs @@ -18,6 +18,7 @@ pub mod entity; pub mod epoch; pub mod naming; pub mod output; +pub mod repository_format; pub mod stats; pub mod utils; diff --git a/lib_efo/src/repository_format.rs b/lib_efo/src/repository_format.rs new file mode 100644 index 0000000..220458c --- /dev/null +++ b/lib_efo/src/repository_format.rs @@ -0,0 +1,167 @@ +//! Versioned persistence types for the reversible repository format. +//! +//! These types are deliberately separate from the active version-1 reader. +//! They establish the migration boundary without changing how existing +//! commands read or write repositories. + +use std::collections::BTreeMap; + +use serde::{Deserialize, Serialize}; +use uuid::Uuid; + +use crate::epoch::{EpochId, EpochInfo}; + +/// The repository format understood by the current migration design. +pub const CURRENT_FORMAT_VERSION: u32 = 2; + +/// A legacy manifest as stored by every release before format version 2. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct LegacyManifest { + /// The currently selected epoch. + pub epoch_id: EpochId, + /// The application version that last wrote the manifest. + pub version: String, + /// User-facing names for epochs. + #[serde(default)] + pub tags: BTreeMap, +} + +/// The version-2 repository manifest. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct RepositoryManifest { + /// On-disk format discriminator. + pub format_version: u32, + /// Stable identity shared by the manifest and transient snapshots. + pub repository_id: Uuid, + /// The immutable snapshot currently selected as HEAD. + pub epoch_id: EpochId, + /// The next epoch identifier; committed IDs are never reused. + pub next_epoch_id: EpochId, + /// The application version that last wrote the manifest. + pub version: String, + /// User-facing names for epochs. + #[serde(default)] + pub tags: BTreeMap, +} + +impl RepositoryManifest { + /// Construct a manifest while enforcing the current format discriminator. + pub fn new( + repository_id: Uuid, + epoch_id: EpochId, + next_epoch_id: EpochId, + version: String, + tags: BTreeMap, + ) -> Self { + Self { + format_version: CURRENT_FORMAT_VERSION, + repository_id, + epoch_id, + next_epoch_id, + version, + tags, + } + } +} + +/// A complete version-2 index or worktree snapshot. +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct RepositorySnapshot { + /// Snapshot format discriminator. + pub format_version: u32, + /// Identity of the repository that owns this snapshot. + pub repository_id: Uuid, + /// HEAD epoch from which the snapshot was derived. + pub base_epoch_id: EpochId, + /// Complete editable world state. + pub world: EpochInfo, +} + +impl RepositorySnapshot { + /// Create a complete transient snapshot for the current format. + pub fn new(repository_id: Uuid, base_epoch_id: EpochId, world: EpochInfo) -> Self { + Self { + format_version: CURRENT_FORMAT_VERSION, + repository_id, + base_epoch_id, + world, + } + } +} + +/// A manifest decoded far enough to choose a compatible reader. +#[derive(Debug, Clone)] +pub enum DetectedManifest { + /// The legacy manifest has no explicit format discriminator. + Legacy(LegacyManifest), + /// The explicitly versioned manifest uses format version 2. + Current(RepositoryManifest), +} + +/// Failure to identify a supported repository manifest. +#[derive(Debug, thiserror::Error)] +pub enum FormatError { + /// JSON was malformed or did not satisfy the selected schema. + #[error("repository manifest is invalid: {0}")] + Invalid(#[from] serde_json::Error), + /// A future or otherwise unsupported format was requested. + #[error("repository format {found} is unsupported; this build supports formats 1 and 2")] + Unsupported { + /// Unsupported numeric format discriminator. + found: u64, + }, + /// The format discriminator must be a positive integer when present. + #[error("repository field `format_version` must be a positive integer")] + InvalidVersion, +} + +/// Detect and deserialize a manifest without mutating its repository. +pub fn detect_manifest(bytes: &[u8]) -> Result { + let value: serde_json::Value = serde_json::from_slice(bytes)?; + match value.get("format_version") { + None => Ok(DetectedManifest::Legacy(serde_json::from_value(value)?)), + Some(version) => match version.as_u64() { + Some(2) => Ok(DetectedManifest::Current(serde_json::from_value(value)?)), + Some(found) => Err(FormatError::Unsupported { found }), + None => Err(FormatError::InvalidVersion), + }, + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn absent_discriminator_selects_legacy_reader() { + let bytes = br#"{"epoch_id":{"id":3},"version":"0.1","tags":{}}"#; + let DetectedManifest::Legacy(manifest) = detect_manifest(bytes).expect("legacy manifest") + else { + panic!("legacy manifest detected as current") + }; + assert_eq!(manifest.epoch_id, EpochId::new(3)); + } + + #[test] + fn explicit_discriminator_selects_current_reader() { + let manifest = RepositoryManifest::new( + Uuid::nil(), + EpochId::new(3), + EpochId::new(8), + "0.2".to_owned(), + BTreeMap::new(), + ); + let bytes = serde_json::to_vec(&manifest).expect("serialize manifest"); + let DetectedManifest::Current(decoded) = detect_manifest(&bytes).expect("current manifest") + else { + panic!("current manifest detected as legacy") + }; + assert_eq!(decoded, manifest); + } + + #[test] + fn unknown_formats_are_not_guessed() { + let error = detect_manifest(br#"{"format_version":99}"#).expect_err("unsupported"); + assert!(matches!(error, FormatError::Unsupported { found: 99 })); + } +} diff --git a/lib_efo/tests/fixtures/v1/catalog.json b/lib_efo/tests/fixtures/v1/catalog.json new file mode 100644 index 0000000..735cef7 --- /dev/null +++ b/lib_efo/tests/fixtures/v1/catalog.json @@ -0,0 +1,51 @@ +[ + { + "name": "empty", + "current_epoch": 0, + "epoch_ids": [0], + "tags": {}, + "feature": "empty" + }, + { + "name": "populated", + "current_epoch": 1, + "epoch_ids": [0, 1], + "tags": {}, + "feature": "populated" + }, + { + "name": "tags", + "current_epoch": 1, + "epoch_ids": [0, 1], + "tags": {"founding": 0, "current": 1}, + "feature": "tags" + }, + { + "name": "switched-back-with-future", + "current_epoch": 1, + "epoch_ids": [0, 1, 2, 3], + "tags": {}, + "feature": "future" + }, + { + "name": "relationships", + "current_epoch": 0, + "epoch_ids": [0], + "tags": {}, + "feature": "relationships" + }, + { + "name": "legacy-monster", + "current_epoch": 0, + "epoch_ids": [0], + "tags": {}, + "feature": "monster" + }, + { + "name": "malformed-missing-selected-epoch", + "current_epoch": 4, + "epoch_ids": [0], + "tags": {}, + "feature": "malformed" + } +] diff --git a/lib_efo/tests/migration_fixtures.rs b/lib_efo/tests/migration_fixtures.rs new file mode 100644 index 0000000..e602327 --- /dev/null +++ b/lib_efo/tests/migration_fixtures.rs @@ -0,0 +1,158 @@ +use std::collections::{BTreeMap, BTreeSet}; + +use lib_efo::{ + entity::Entity, + epoch::{EpochId, EpochInfo}, + repository_format::{DetectedManifest, LegacyManifest, detect_manifest}, + stats::{EntityType, Role, TypedLink}, +}; +use serde::Deserialize; +use uuid::Uuid; + +#[derive(Debug, Deserialize)] +struct Fixture { + name: String, + current_epoch: u64, + epoch_ids: Vec, + tags: BTreeMap, + feature: String, +} + +fn fixtures() -> Vec { + serde_json::from_str(include_str!("fixtures/v1/catalog.json")).expect("valid fixture catalog") +} + +#[test] +fn version_one_migration_matrix_covers_every_legacy_shape() { + let fixtures = fixtures(); + let names = fixtures + .iter() + .map(|fixture| fixture.name.as_str()) + .collect::>(); + assert_eq!( + names, + BTreeSet::from([ + "empty", + "legacy-monster", + "malformed-missing-selected-epoch", + "populated", + "relationships", + "switched-back-with-future", + "tags", + ]) + ); + + for fixture in fixtures { + let legacy = LegacyManifest { + epoch_id: EpochId::new(fixture.current_epoch), + version: "fixture-v1".to_owned(), + tags: fixture + .tags + .into_iter() + .map(|(tag, id)| (tag, EpochId::new(id))) + .collect(), + }; + let bytes = serde_json::to_vec(&legacy).expect("serialize fixture manifest"); + assert!(matches!( + detect_manifest(&bytes).expect("detect fixture manifest"), + DetectedManifest::Legacy(_) + )); + + let known = fixture.epoch_ids.into_iter().collect::>(); + if fixture.feature == "malformed" { + assert!(!known.contains(&fixture.current_epoch)); + } else { + assert!( + known.contains(&fixture.current_epoch), + "{} must contain its selected epoch", + fixture.name + ); + } + + if fixture.feature == "future" { + assert!(known.iter().any(|id| *id > fixture.current_epoch)); + } + if fixture.feature == "tags" { + assert!(!legacy.tags.is_empty()); + } + + for id in known { + let mut snapshot = EpochInfo { + epoch_id: EpochId::new(id), + summary: fixture.feature.clone(), + ..EpochInfo::default() + }; + populate_feature(&fixture.feature, &mut snapshot); + let encoded = serde_json::to_vec(&snapshot).expect("serialize fixture snapshot"); + let decoded: EpochInfo = + serde_json::from_slice(&encoded).expect("load fixture snapshot"); + assert_eq!(decoded.epoch_id, EpochId::new(id)); + + match fixture.feature.as_str() { + "populated" => assert_eq!(decoded.characters.len(), 1), + "relationships" => { + assert_eq!(decoded.organizations.len(), 1); + assert_eq!(decoded.towns.len(), 1); + let value = serde_json::to_value(&decoded.organizations[0]) + .expect("serialize related organisation"); + assert_eq!( + value["metadata"]["links"] + .as_array() + .expect("relationship list") + .len(), + 1 + ); + } + "monster" => assert_eq!(decoded.calamities.len(), 1), + _ => {} + } + } + } +} + +fn populate_feature(feature: &str, snapshot: &mut EpochInfo) { + match feature { + "populated" => { + let mut character = Entity::default(); + character.name = "Ada".to_owned(); + character.entity_type = EntityType::Character; + snapshot.characters.push(character); + } + "relationships" => { + let town_id = Uuid::from_u128(1); + let mut town = Entity::default(); + town.id = town_id; + town.name = "Beacon".to_owned(); + town.entity_type = EntityType::Town; + + let mut organization = Entity::default(); + organization.id = Uuid::from_u128(2); + organization.name = "Council".to_owned(); + organization.entity_type = EntityType::Organization; + organization.add_to_links(TypedLink::new(town_id, Role::Capital, EntityType::Town)); + + snapshot.towns.push(town); + snapshot.organizations.push(organization); + } + "monster" => { + let mut calamity = Entity::default(); + calamity.name = "Old Blight".to_owned(); + calamity.entity_type = EntityType::Calamity; + snapshot.calamities.push(calamity); + } + _ => {} + } +} + +#[test] +fn legacy_monster_spelling_remains_loadable() { + let mut entity = lib_efo::entity::Entity::default(); + entity.name = "Old Blight".to_owned(); + entity.entity_type = lib_efo::stats::EntityType::Calamity; + let mut value = serde_json::to_value(entity).expect("serialize calamity"); + value["entity_type"] = serde_json::Value::String("Monster".to_owned()); + + let decoded: lib_efo::entity::Entity = + serde_json::from_value(value).expect("load legacy Monster spelling"); + assert_eq!(decoded.entity_type, lib_efo::stats::EntityType::Calamity); +}