From 9efb4cd7abbe71aa2f5b3e38521e9f0b39333141 Mon Sep 17 00:00:00 2001 From: Ethan Zhang Date: Wed, 18 Nov 2026 14:31:58 -0600 Subject: [PATCH 1/5] feat(evidence-plugin): mark the ledger's format and refuse a newer one; say there is no downgrade (#308) The build before the checkpointed-local-log 0.6 stack cannot read a ledger the 0.6 build wrote and takes a node with a required capsules plugin down. A ledger/format marker now makes a build that meets a newer format stop with a message naming the cause, and the changelog says to back the data directory up before upgrading. Signed-off-by: Ethan Zhang --- CHANGELOG.md | 2 + crates/evidence-plugin/src/capsule_emit.rs | 25 +++++ .../evidence-plugin/src/chain_store/tests.rs | 2 +- crates/evidence-plugin/src/ledger_format.rs | 100 ++++++++++++++++++ crates/evidence-plugin/src/main.rs | 1 + 5 files changed, 129 insertions(+), 1 deletion(-) create mode 100644 crates/evidence-plugin/src/ledger_format.rs diff --git a/CHANGELOG.md b/CHANGELOG.md index ff78e2d5..dfdfb42e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,9 +9,11 @@ ### Changed - **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 data directory (`ledger/` and `keys/`, by default `~/.local/share/capsules`); that copy is the only way back (#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 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`. diff --git a/crates/evidence-plugin/src/capsule_emit.rs b/crates/evidence-plugin/src/capsule_emit.rs index cd7056f4..af2b1cff 100644 --- a/crates/evidence-plugin/src/capsule_emit.rs +++ b/crates/evidence-plugin/src/capsule_emit.rs @@ -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)? { @@ -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. diff --git a/crates/evidence-plugin/src/chain_store/tests.rs b/crates/evidence-plugin/src/chain_store/tests.rs index 77324c9c..9c246b6d 100644 --- a/crates/evidence-plugin/src/chain_store/tests.rs +++ b/crates/evidence-plugin/src/chain_store/tests.rs @@ -174,7 +174,7 @@ fn tree(dir: &Path) -> BTreeMap> { 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; } diff --git a/crates/evidence-plugin/src/ledger_format.rs b/crates/evidence-plugin/src/ledger_format.rs new file mode 100644 index 00000000..9460be9a --- /dev/null +++ b/crates/evidence-plugin/src/ledger_format.rs @@ -0,0 +1,100 @@ +//! 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. +//! +//! 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)?; + std::fs::write(&path, format!("{CURRENT}\n")) + .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() + ); + } +} diff --git a/crates/evidence-plugin/src/main.rs b/crates/evidence-plugin/src/main.rs index 456459ae..311b0b42 100644 --- a/crates/evidence-plugin/src/main.rs +++ b/crates/evidence-plugin/src/main.rs @@ -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; From bf984deab3c21059c7fddd1bac2b1f16db527a8a Mon Sep 17 00:00:00 2001 From: Ethan Zhang Date: Wed, 18 Nov 2026 14:35:21 -0600 Subject: [PATCH 2/5] fix(evidence-plugin): check the ledger format before a pending new history moves it, write the marker atomically, say export-flat is no way back (#308) Signed-off-by: Ethan Zhang --- CHANGELOG.md | 2 +- crates/evidence-plugin/src/flat_export.rs | 6 +++++ crates/evidence-plugin/src/ledger_format.rs | 7 +++++- .../evidence-plugin/src/owner_maintenance.rs | 24 +++++++++++++++++++ 4 files changed, 37 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dfdfb42e..7f39171e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ ### Changed - **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 data directory (`ledger/` and `keys/`, by default `~/.local/share/capsules`); that copy is the only way back (#308). + **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 data directory (`ledger/` and `keys/`, by default `~/.local/share/capsules`); that copy is the only way back. `capsules export-flat` does not change this: it copies the checkpoints as they are, and an earlier plugin refuses the new ones (#308). ### Added diff --git a/crates/evidence-plugin/src/flat_export.rs b/crates/evidence-plugin/src/flat_export.rs index 41887820..dfbfced2 100644 --- a/crates/evidence-plugin/src/flat_export.rs +++ b/crates/evidence-plugin/src/flat_export.rs @@ -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}; diff --git a/crates/evidence-plugin/src/ledger_format.rs b/crates/evidence-plugin/src/ledger_format.rs index 9460be9a..bd99d27a 100644 --- a/crates/evidence-plugin/src/ledger_format.rs +++ b/crates/evidence-plugin/src/ledger_format.rs @@ -13,6 +13,9 @@ //! 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; @@ -47,7 +50,9 @@ pub fn check_and_stamp(ledger_dir: &Path) -> anyhow::Result<()> { Err(e) => return Err(anyhow::anyhow!("reading {}: {e}", path.display())), } std::fs::create_dir_all(ledger_dir)?; - std::fs::write(&path, format!("{CURRENT}\n")) + // 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())) } diff --git a/crates/evidence-plugin/src/owner_maintenance.rs b/crates/evidence-plugin/src/owner_maintenance.rs index 53247f04..a001a097 100644 --- a/crates/evidence-plugin/src/owner_maintenance.rs +++ b/crates/evidence-plugin/src/owner_maintenance.rs @@ -157,6 +157,9 @@ pub fn resolve_log_id( node_key_id: &str, log_id_setting: Option<&str>, ) -> anyhow::Result { + // 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) @@ -1289,6 +1292,27 @@ mod tests { /// 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. + /// 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); + } + #[test] fn start_new_history_archives_the_old_log_and_starts_a_cited_new_one_at_next_start() { let dir = temp_dir("new-history"); From 0b704609dfaea3f96f5fb76d1a36f0a3d495d054 Mon Sep 17 00:00:00 2001 From: Ethan Zhang Date: Wed, 18 Nov 2026 14:36:26 -0600 Subject: [PATCH 3/5] docs(evidence-plugin): put the end-to-end restart test's doc back on its test (#308) Signed-off-by: Ethan Zhang --- crates/evidence-plugin/src/owner_maintenance.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/crates/evidence-plugin/src/owner_maintenance.rs b/crates/evidence-plugin/src/owner_maintenance.rs index a001a097..66ab26f0 100644 --- a/crates/evidence-plugin/src/owner_maintenance.rs +++ b/crates/evidence-plugin/src/owner_maintenance.rs @@ -1289,9 +1289,6 @@ mod tests { 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. /// A ledger marked with a newer format is refused before a pending new /// history moves it into the archive (#308). #[test] @@ -1313,6 +1310,9 @@ mod tests { 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. #[test] fn start_new_history_archives_the_old_log_and_starts_a_cited_new_one_at_next_start() { let dir = temp_dir("new-history"); From 2f38ab6020d4996b6ce4b6a87f5241cb2661d010 Mon Sep 17 00:00:00 2001 From: Ethan Zhang Date: Wed, 18 Nov 2026 14:37:28 -0600 Subject: [PATCH 4/5] docs: say the keys backup is private and that a rollback or a refusal stops the node (#308) Signed-off-by: Ethan Zhang --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7f39171e..b4e5e968 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,11 +9,11 @@ ### Changed - **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 data directory (`ledger/` and `keys/`, by default `~/.local/share/capsules`); that copy is the only way back. `capsules export-flat` does not change this: it copies the checkpoints as they are, and an earlier plugin refuses the new ones (#308). + **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 data directory (`ledger/` and `keys/`, 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. Rolling back to 0.1.19 or earlier after running this build stops the node, not just the plugin. `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 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. +- **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`. From 39544b2ea9a0a07c188e39171d8b5c66c22b3b42 Mon Sep 17 00:00:00 2001 From: Ethan Zhang Date: Wed, 18 Nov 2026 14:38:26 -0600 Subject: [PATCH 5/5] docs: back up the whole data directory; drop a repeated sentence; set the no-downgrade paragraph apart (#308) Signed-off-by: Ethan Zhang --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b4e5e968..194b195e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,8 @@ ### Changed - **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 data directory (`ledger/` and `keys/`, 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. Rolling back to 0.1.19 or earlier after running this build stops the node, not just the plugin. `capsules export-flat` does not change this: it copies the checkpoints as they are, and an earlier plugin refuses the new ones (#308). + + **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