Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,11 @@

- **The plugin moves to the checkpointed-local-log 0.6 stack (#300).** It now builds on agent-action-capsule 0.11.0, evidence-request 0.6.0, evidencebook 0.0.19, capsule-emit 0.0.13 and capsule-emit-artifact 0.0.4. A checkpoint this node signs carries the bare log id as the CWT `sub` (CLL -02), so every checkpoint, its anchor digest and the signatures over it differ from before; the golden answer fixtures and `vectors/no-complete-answer` are regenerated and nothing else in them changes. A witness must accept both `sub` forms before this node is deployed.

**There is no downgrade from this build.** A node that has run it cannot go back to 0.1.19 or earlier: the older plugin reads the new checkpoint `sub` as a failed COSE check (`failed to load checkpoint state ... the checkpoint's COSE does not verify: CWT subject ...`), and because `capsules` is a required plugin the whole node stops. Before upgrading, stop the node and copy the whole data directory (by default `~/.local/share/capsules`); that copy is the only way back. `keys/` holds the node's private keys: keep that copy as private as the keys themselves, and never attach it to an issue or share it. `capsules export-flat` does not change this: it copies the checkpoints as they are, and an earlier plugin refuses the new ones (#308).

### Added

- **The ledger carries a format marker, and a build refuses a ledger written in a newer format (#308).** The plugin writes `ledger/format` (this release writes `1`, the checkpointed-local-log 0.6 stack) when it opens the ledger. A build that meets a higher number stops at start (the node does not start, since `capsules` is a required plugin) with `this ledger was written by a newer plugin (ledger format N, this build reads up to M); downgrade is not supported`, and leaves the ledger as it was, instead of failing in the checkpoint check. Builds before this one do not read the marker, so it does not make a rollback to them safe: back the data directory up before upgrading (the checkpointed-local-log 0.6 entry under Changed says how). Nothing a peer reads changes.
- **`history_card/2` and a range of checkpoints are answered, and this node's commitment staples the `/2` card, so a long-running node serves its card and commitment again (Mesh-LLM/capsules-plugin#76, #70; Evidence Request -03 §8.1.2, §8.1.3).** A `/2` card lists the first checkpoint, the checkpoints 1, 2, 4, 8 and so on positions back from the anchor, and the latest 16, each with its consistency proof from the entry before, so its size grows with the log of the checkpoint count, and is not refused for the count of checkpoints (past 1024 for `/1`); the 1 MiB cap on an answer still applies, which a `/2` card of a long log stays far under (lab-3's `/1` card was 715,749 bytes at 318 checkpoints). `{"checkpoints": [a, b]}` answers the entries at positions a through b, with the proof to the anchor, so a requester can fetch the checkpoints between two listed entries. Both go to any requester, like `checkpoints` and `/1`, which is unchanged and still answered within its caps. The commitment's staple, its `answers.derivations` and the policy's `stranger_safe` list now name `history_card/2` (the default policy digest changes with the list); a reader of a commitment accepts either card. `doctor --probe` and the history page now ask the stranger's card as `history_card/2`, as loop's daily reporter will (loop#459 accepts a `/2` staple). Needs evidence-request 0.7.0, evidencebook 0.0.21 and agent-action-capsule 0.12.0. A reader that accepts only a `/1` staple, such as loop's `check_commitment.py`, refuses this commitment until it accepts `/2`.

- **`service_history/2` counts the referee verdicts this node holds about itself (Mesh-LLM/capsules-plugin#289; action-state-group/agent-action-capsule#614, #615, #617).** A new definition document and digest (`derivations/service-history-2.json`); `service_history/1` is unchanged and still answered. The new `verdict_counts` member counts, per closed week and model hash, the four results the spec keeps apart (`corroborated`, `contradicted`, `inconclusive`, `not_comparable`) from the verdicts delivered to this node and sealed on its own chain, with the same floor of 5 and complementary suppression as the served counts. Whoever asked the referee, the node counts the verdicts its own log holds (ISH §5.3); this plugin counts a verdict once per referee and pair of halves. Shared under `share_standard_history`, like `/1`. See `docs/SERVICE-HISTORY.md`.
Expand Down
25 changes: 25 additions & 0 deletions crates/evidence-plugin/src/capsule_emit.rs
Original file line number Diff line number Diff line change
Expand Up @@ -589,6 +589,7 @@ impl CapsuleState {
std::time::Duration::from_secs(2),
)?)
};
crate::ledger_format::check_and_stamp(&ledger_dir)?;
let keys = keys::load_or_create(&data_dir.join("keys"))?;
let node_keys = crate::chain_store::node_signing_keys(&data_dir.join("keys"));
let (stores, (ledger, report)) = match crate::chain_store::stays_flat(&ledger_dir)? {
Expand Down Expand Up @@ -2436,6 +2437,30 @@ pub(crate) mod tests {
);
}

/// A node that meets a ledger marked with a newer format stops at a start
/// error naming the cause and leaves the ledger as it was (#308), and a
/// fresh start marks its ledger.
#[test]
fn open_refuses_a_ledger_written_in_a_newer_format() {
let dir = tempfile::tempdir().expect("tempdir");
let marker = dir.path().join("ledger").join(crate::ledger_format::FILE);
drop(CapsuleState::open(dir.path(), "node-under-test").expect("first open"));
assert_eq!(
std::fs::read_to_string(&marker).expect("marker").trim(),
crate::ledger_format::CURRENT.to_string()
);
std::fs::write(&marker, "999\n").expect("mark newer");
let err = CapsuleState::open(dir.path(), "node-under-test")
.err()
.expect("a newer ledger is refused")
.to_string();
assert!(err.contains("written by a newer plugin"), "{err}");
assert_eq!(
std::fs::read_to_string(&marker).expect("marker").trim(),
"999"
);
}

/// A block then an unblock both land on the chain, in order (the unblock
/// chains onto the block), each carrying the commitment the caller's salt
/// gives.
Expand Down
2 changes: 1 addition & 1 deletion crates/evidence-plugin/src/chain_store/tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ fn tree(dir: &Path) -> BTreeMap<PathBuf, Vec<u8>> {
let path = entry.path();
if matches!(
entry.file_name().to_str(),
Some(".capsules-writer.lock" | "capsules.lock")
Some(".capsules-writer.lock" | "capsules.lock" | crate::ledger_format::FILE)
) {
continue;
}
Expand Down
6 changes: 6 additions & 0 deletions crates/evidence-plugin/src/flat_export.rs
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,12 @@
//! deleted. `capsules.jsonl` moves in last and the shelf is set aside after
//! it, so an earlier release reads the flat files at every point; a run cut
//! short finishes at the next run.
//!
//! The flat files are readable by an earlier release only up to the checkpoints
//! it can read: a checkpoint signed by a build on the checkpointed-local-log
//! 0.6 stack (#300, after 0.1.19) carries the bare log id as its CWT `sub`,
//! which 0.1.19 and earlier refuse, so this export does not make a rollback
//! past that stack possible (#308).

use std::fs;
use std::io::{self, Write};
Expand Down
105 changes: 105 additions & 0 deletions crates/evidence-plugin/src/ledger_format.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
//! The ledger's format marker: `ledger/format`, one integer.
//!
//! A build that opens the ledger writes the number it writes ledgers in
//! ([`CURRENT`]) and refuses a ledger marked with a higher one, so a rollback
//! to a build that cannot read the ledger stops at a clear start error naming
//! the cause, not deep in the checkpoint check (#308: the build before the
//! checkpointed-local-log 0.6 stack reads the bare-id checkpoint `sub` as a
//! failed COSE check and takes a node with a required `capsules` down).
//!
//! Format 1 is the checkpointed-local-log 0.6 stack (#300): a checkpoint's CWT
//! `sub` is the bare log id. A ledger with no marker was written by a build
//! that predates this check; it is stamped on first open. Builds before this
//! one do not read the marker, so it cannot protect a rollback to them; the
//! changelog says to back the data directory up before upgrading.
//!
//! It is checked first, before a pending new history moves the ledger
//! (`owner_maintenance::resolve_log_id`), and again when the ledger opens.
//!
//! Raise [`CURRENT`] only for a change an older build cannot read.

use std::path::Path;

/// The marker's file name, in the ledger directory.
pub const FILE: &str = "format";
/// The format this build writes and the highest it reads.
pub const CURRENT: u32 = 1;

/// Refuse a ledger written in a newer format; otherwise stamp [`CURRENT`].
pub fn check_and_stamp(ledger_dir: &Path) -> anyhow::Result<()> {
let path = ledger_dir.join(FILE);
match std::fs::read_to_string(&path) {
Ok(text) => {
let found: u32 = text.trim().parse().map_err(|_| {
anyhow::anyhow!(
"the ledger's format marker {} is not a number; this ledger was written by a newer or foreign plugin",
path.display()
)
})?;
if found > CURRENT {
anyhow::bail!(
"this ledger was written by a newer plugin (ledger format {found}, this build reads up to {CURRENT}); downgrade is not supported: run the newer plugin again, or restore a backup of the data directory taken before the upgrade ({})",
ledger_dir.display()
);
}
if found == CURRENT {
return Ok(());
}
}
Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
Err(e) => return Err(anyhow::anyhow!("reading {}: {e}", path.display())),
}
std::fs::create_dir_all(ledger_dir)?;
// Replaced whole (written, synced, renamed): a write cut short must not
// leave an empty marker that refuses a sound ledger on every start.
crate::owner_maintenance::write_atomically(&path, format!("{CURRENT}\n").as_bytes())
.map_err(|e| anyhow::anyhow!("writing {}: {e}", path.display()))
}

#[cfg(test)]
mod tests {
use super::*;

#[test]
fn stamps_a_ledger_with_no_marker() {
let dir = tempfile::tempdir().unwrap();
let ledger = dir.path().join("ledger");
check_and_stamp(&ledger).unwrap();
assert_eq!(
std::fs::read_to_string(ledger.join(FILE)).unwrap().trim(),
CURRENT.to_string()
);
check_and_stamp(&ledger).unwrap();
}

#[test]
fn refuses_a_newer_format_and_names_the_cause() {
let dir = tempfile::tempdir().unwrap();
std::fs::write(dir.path().join(FILE), format!("{}\n", CURRENT + 1)).unwrap();
let err = check_and_stamp(dir.path()).unwrap_err().to_string();
assert!(err.contains("written by a newer plugin"), "{err}");
assert!(err.contains("downgrade is not supported"), "{err}");
// The marker is left as it was.
assert_eq!(
std::fs::read_to_string(dir.path().join(FILE))
.unwrap()
.trim(),
(CURRENT + 1).to_string()
);
}

#[test]
fn refuses_an_unreadable_marker_and_keeps_an_older_one_updated() {
let dir = tempfile::tempdir().unwrap();
std::fs::write(dir.path().join(FILE), "x").unwrap();
assert!(check_and_stamp(dir.path()).is_err());
std::fs::write(dir.path().join(FILE), "0\n").unwrap();
check_and_stamp(dir.path()).unwrap();
assert_eq!(
std::fs::read_to_string(dir.path().join(FILE))
.unwrap()
.trim(),
CURRENT.to_string()
);
}
}
1 change: 1 addition & 0 deletions crates/evidence-plugin/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ mod history_page;
mod host_status;
mod ledger_checkpoints;
mod ledger_fetch_bridge;
mod ledger_format;
mod leg_catch_up;
mod lifecycle_channel;
mod mesh_evidence_bridge;
Expand Down
24 changes: 24 additions & 0 deletions crates/evidence-plugin/src/owner_maintenance.rs
Original file line number Diff line number Diff line change
Expand Up @@ -157,6 +157,9 @@ pub fn resolve_log_id(
node_key_id: &str,
log_id_setting: Option<&str>,
) -> anyhow::Result<String> {
// First, before a pending new history moves the ledger aside: a ledger
// written in a newer format is refused where it is (#308).
crate::ledger_format::check_and_stamp(&data_dir.join("ledger"))?;
let setting = log_id_setting.map(str::trim).filter(|s| !s.is_empty());
let base = setting
.map(str::to_string)
Expand Down Expand Up @@ -1286,6 +1289,27 @@ mod tests {
let _ = fs::remove_dir_all(&dir);
}

/// A ledger marked with a newer format is refused before a pending new
/// history moves it into the archive (#308).
#[test]
fn a_newer_format_ledger_is_refused_before_a_pending_new_history_moves_it() {
let dir = temp_dir("new-history-newer-format");
let (m, _ids) = maintenance(&dir, 2);
m.start_new_history(StartNewHistoryArgs { confirm: true })
.unwrap();
drop(m);
let marker = dir.join("ledger").join(crate::ledger_format::FILE);
fs::write(&marker, "999\n").unwrap();
let err = resolve_log_id(&dir, "capsules", "old-shared", "node-key", None)
.unwrap_err()
.to_string();
assert!(err.contains("written by a newer plugin"), "{err}");
assert!(read_pending(&dir).is_some(), "the request is still pending");
assert!(!dir.join("archive/1").exists(), "nothing was archived");
assert!(marker.exists(), "the ledger stayed where it was");
let _ = fs::remove_dir_all(&dir);
}

/// End to end across a restart: the old history is kept whole and still
/// opens clean under `archive/1`, the new history opens clean, and its
/// first record cites the old one's closing record.
Expand Down
Loading