feat: establish versioned repository format
This commit is contained in:
parent
d4548ff479
commit
b87dd9eda8
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
||||
|
|
|
|||
|
|
@ -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 }));
|
||||
}
|
||||
}
|
||||
|
|
@ -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"
|
||||
}
|
||||
]
|
||||
|
|
@ -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);
|
||||
}
|
||||
Loading…
Reference in New Issue