feat: establish versioned repository format

This commit is contained in:
Dandaedre 2026-09-20 22:16:37 +02:00
parent d4548ff479
commit b87dd9eda8
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
7 changed files with 389 additions and 10 deletions

View File

@ -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.

View File

@ -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

View File

@ -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

View File

@ -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;

View File

@ -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<String, EpochId>,
}
/// 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<String, EpochId>,
}
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<String, EpochId>,
) -> 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<DetectedManifest, FormatError> {
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 }));
}
}

51
lib_efo/tests/fixtures/v1/catalog.json vendored Normal file
View File

@ -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"
}
]

View File

@ -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<u64>,
tags: BTreeMap<String, u64>,
feature: String,
}
fn fixtures() -> Vec<Fixture> {
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::<BTreeSet<_>>();
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::<BTreeSet<_>>();
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);
}