From 993b7a2948c1d6e1ba2db01cef1ebe844125de1b Mon Sep 17 00:00:00 2001 From: soul Date: Fri, 20 Nov 2026 03:28:03 +0100 Subject: [PATCH] aetherlight: partitions become tracked documents, submit applies in place under an undo log Docs and Tracked record the first-touch value of every written key. submit applies to the live state between begin and finish and rolls back on any error, so the world is no longer cloned per commit; replay reads the commitments subjects finish() reports instead of cloning the partition. The encoding is unchanged: golden.digests is byte-identical. Co-Authored-By: Claude Sonnet 5.5 --- native/aetherlight/src/action.rs | 23 +- native/aetherlight/src/docs.rs | 185 ++++++++++ native/aetherlight/src/golden_tests.rs | 2 +- native/aetherlight/src/grammar/tests.rs | 6 +- native/aetherlight/src/import_key_tests.rs | 17 +- native/aetherlight/src/journal.rs | 48 +-- native/aetherlight/src/lib.rs | 382 +++++++++++++++------ native/aetherlight/src/patch.rs | 8 +- 8 files changed, 507 insertions(+), 164 deletions(-) create mode 100644 native/aetherlight/src/docs.rs diff --git a/native/aetherlight/src/action.rs b/native/aetherlight/src/action.rs index 0c9ac33a2..93758bac8 100644 --- a/native/aetherlight/src/action.rs +++ b/native/aetherlight/src/action.rs @@ -160,7 +160,7 @@ pub(super) fn exercise( } let band = select_band(state, command_id, granted.id, entry)?; - let operations = lower(entry, band, actor, state.now, invocation, &bindings)?; + let operations = lower(entry, band, actor, state.header.now, invocation, &bindings)?; let mut effects = if operations.is_empty() { Vec::new() } else { @@ -188,7 +188,7 @@ pub(super) fn exercise( (Some(statement), true) => { let fact = EntityId(patch::derive_id( patch::ENTITY_NAMESPACE, - state.world_id, + state.header.world_id, command_id, &patch::DraftHandle::new(SPEECH_HANDLE), Some(SPEECH_INDEX), @@ -221,7 +221,7 @@ pub(super) fn exercise( let display = invocation.display.as_ref().map(|statement| { let fact = EntityId(patch::derive_id( patch::ENTITY_NAMESPACE, - state.world_id, + state.header.world_id, command_id, &patch::DraftHandle::new(SPEECH_HANDLE), Some(DISPLAY_INDEX), @@ -780,7 +780,7 @@ fn select_band( entry: &Affordance, ) -> Result { let draw = digest(&BandPreimage { - world_id: state.world_id, + world_id: state.header.world_id, revision: state.revision, command_id, affordance, @@ -1637,14 +1637,13 @@ mod tests { .any(|spec| spec.kind == RefKind::Subject(None)) ); - // The state row encoder and the digest owner are the same `to_vec_named` - // path the store writes through. - let encoded = rmp_serde::to_vec_named(&bench.kernel.state).expect("the state encodes"); - let decoded: WorldState = rmp_serde::from_slice(&encoded).expect("the state decodes"); - assert_eq!( - decoded.affordance_catalog, - bench.kernel.state.affordance_catalog - ); + // The affordance document round-trips through the `to_vec_named` path the + // state digest hashes. + let catalog = rmp_serde::to_vec_named(&bench.kernel.state.affordance_catalog) + .expect("the affordance document encodes"); + let decoded: std::collections::BTreeMap<_, crate::Affordance> = + rmp_serde::from_slice(&catalog).expect("the affordance document decodes"); + assert_eq!(decoded, *bench.kernel.state.affordance_catalog); assert!(digest(&bench.kernel.state).is_ok()); } diff --git a/native/aetherlight/src/docs.rs b/native/aetherlight/src/docs.rs new file mode 100644 index 000000000..ef873c47d --- /dev/null +++ b/native/aetherlight/src/docs.rs @@ -0,0 +1,185 @@ +//! Tracked documents: the one writer of a partition and the one recorder of +//! what a transaction changed. +//! +//! A `Docs` is a map whose every write goes through a method that remembers the +//! key's value as it stood before the transaction (first touch wins). `finish` +//! turns that record into the keys whose value really changed, with their old +//! values; `rollback` puts every touched key back. Reads see the plain map +//! through `Deref`, and there is no `DerefMut`, so a write cannot skip the log. +//! The fields are private to this module for the same reason. + +use serde::{Serialize, Serializer}; +use std::collections::BTreeMap; +use std::collections::btree_map::Entry; +use std::ops::Deref; + +/// A key whose value changed in a transaction, with the value it had before +/// (`None` when the key was absent). The new value is whatever the map holds. +pub(crate) type Changed = (K, Option); + +#[derive(Clone, Debug)] +pub(crate) struct Docs { + map: BTreeMap, + touched: BTreeMap>, +} + +impl Default for Docs { + fn default() -> Self { + Self { + map: BTreeMap::new(), + touched: BTreeMap::new(), + } + } +} + +/// Equality is the documents, never the log: two worlds with the same content +/// are equal whatever transaction state they are in. +impl PartialEq for Docs { + fn eq(&self, other: &Self) -> bool { + self.map == other.map + } +} + +impl Eq for Docs {} + +impl Deref for Docs { + type Target = BTreeMap; + fn deref(&self) -> &BTreeMap { + &self.map + } +} + +impl<'a, K: Ord + Clone, V: Clone + PartialEq> IntoIterator for &'a Docs { + type Item = (&'a K, &'a V); + type IntoIter = std::collections::btree_map::Iter<'a, K, V>; + fn into_iter(self) -> Self::IntoIter { + self.map.iter() + } +} + +/// A partition encodes as its map, so the encoded world is what it was before +/// the partitions were tracked. +impl Serialize for Docs { + fn serialize(&self, serializer: S) -> Result { + self.map.serialize(serializer) + } +} + +impl Docs { + fn touch(&mut self, key: &K) { + if !self.touched.contains_key(key) { + self.touched.insert(key.clone(), self.map.get(key).cloned()); + } + } + + pub(crate) fn insert(&mut self, key: K, value: V) -> Option { + self.touch(&key); + self.map.insert(key, value) + } + + pub(crate) fn remove(&mut self, key: &K) -> Option { + self.touch(key); + self.map.remove(key) + } + + /// Touches only a key that is present: a miss writes nothing. + pub(crate) fn get_mut(&mut self, key: &K) -> Option<&mut V> { + if self.map.contains_key(key) { + self.touch(key); + } + self.map.get_mut(key) + } + + pub(crate) fn entry(&mut self, key: K) -> Entry<'_, K, V> { + self.touch(&key); + self.map.entry(key) + } + + /// The keys whose value differs from the start of the transaction, with the + /// value they had then. A key written back to what it was is not reported. + /// The log is empty afterwards. + pub(crate) fn finish(&mut self) -> Vec> { + std::mem::take(&mut self.touched) + .into_iter() + .filter(|(key, old)| self.map.get(key) != old.as_ref()) + .collect() + } + + /// Puts every touched key back as it was and empties the log. + pub(crate) fn rollback(&mut self) { + for (key, old) in std::mem::take(&mut self.touched) { + match old { + Some(value) => { + self.map.insert(key, value); + } + None => { + self.map.remove(&key); + } + } + } + } + + pub(crate) fn is_clean(&self) -> bool { + self.touched.is_empty() + } +} + +/// One tracked value: the same first-touch rule as a `Docs` key, for the +/// world's own fields. +#[derive(Clone, Debug)] +pub(crate) struct Tracked { + value: T, + /// `None` untouched; `Some(None)` logged as absent (genesis), so `finish` + /// reports it as added. + old: Option>, +} + +impl PartialEq for Tracked { + fn eq(&self, other: &Self) -> bool { + self.value == other.value + } +} + +impl Eq for Tracked {} + +impl Deref for Tracked { + type Target = T; + fn deref(&self) -> &T { + &self.value + } +} + +impl Tracked { + /// A value that did not exist before this transaction. + pub(crate) fn absent(value: T) -> Self { + Self { + value, + old: Some(None), + } + } + + pub(crate) fn get_mut(&mut self) -> &mut T { + if self.old.is_none() { + self.old = Some(Some(self.value.clone())); + } + &mut self.value + } + + /// The old value when the value changed (`Some(None)`: it was absent). + pub(crate) fn finish(&mut self) -> Option> { + match self.old.take() { + Some(old) if old.as_ref() != Some(&self.value) => Some(old), + _ => None, + } + } + + pub(crate) fn rollback(&mut self) { + if let Some(Some(old)) = self.old.take() { + self.value = old; + } + } + + pub(crate) fn is_clean(&self) -> bool { + self.old.is_none() + } +} diff --git a/native/aetherlight/src/golden_tests.rs b/native/aetherlight/src/golden_tests.rs index fef93ba24..e1138bd39 100644 --- a/native/aetherlight/src/golden_tests.rs +++ b/native/aetherlight/src/golden_tests.rs @@ -281,7 +281,7 @@ fn clockwork_commit_cost() { .collect(); let play = AuthenticatedCaller::verified_play(); let envelope = |kernel: &WorldKernel, body: CommandBody| CommandEnvelope { - world_id: kernel.state.world_id, + world_id: kernel.state.header.world_id, expected_revision: kernel.state.revision, caller: CallerId::Play, body, diff --git a/native/aetherlight/src/grammar/tests.rs b/native/aetherlight/src/grammar/tests.rs index c7486841e..e59df991c 100644 --- a/native/aetherlight/src/grammar/tests.rs +++ b/native/aetherlight/src/grammar/tests.rs @@ -352,9 +352,9 @@ fn the_bound_grammar_is_part_of_the_world_state_digest() { let kernel = kernel.unwrap(); let bound_digest = crate::state_digest(&kernel.state).unwrap(); let mut state = kernel.state.clone(); - state.grammar = None; + state.header.get_mut().grammar = None; let open_digest = crate::state_digest(&state).unwrap(); - state.grammar = Some(grammar_with(&[("dock", verb(RenderPath::ShipAction, &[]))])); + state.header.get_mut().grammar = Some(grammar_with(&[("dock", verb(RenderPath::ShipAction, &[]))])); let other_digest = crate::state_digest(&state).unwrap(); assert_ne!(bound_digest, open_digest); assert_ne!(bound_digest, other_digest); @@ -621,7 +621,7 @@ fn an_effect_resolved_elsewhere_cannot_install_an_entry_outside_the_grammar() { let kernel = create(bound(Some(grammar_with(&extra)), "Forged")); let kernel = kernel.unwrap(); let mut twin = kernel.state.clone(); - twin.grammar = None; + twin.header.get_mut().grammar = None; let resolve = |kind: &str, roles: &[(&str, RefKind)]| { crate::patch::resolve_patch( &twin, diff --git a/native/aetherlight/src/import_key_tests.rs b/native/aetherlight/src/import_key_tests.rs index 4d217c586..40914edc3 100644 --- a/native/aetherlight/src/import_key_tests.rs +++ b/native/aetherlight/src/import_key_tests.rs @@ -450,22 +450,16 @@ fn keyless_world_digests_unchanged() { !contains(&state, b"import_key"), "a keyless world grew a field" ); - // A keyed world carries it, round-trips, and digests differently. + // A keyed world carries it and digests differently. let keyed = keyed_world(); let keyed_state = rmp_serde::to_vec_named(&keyed.state).unwrap(); assert!(contains(&keyed_state, b"import_key")); - let back: crate::WorldState = rmp_serde::from_slice(&keyed_state).unwrap(); - assert_eq!( - crate::state_digest(&back).unwrap(), - crate::state_digest(&keyed.state).unwrap() - ); assert_ne!( crate::state_digest(&keyed.state).unwrap(), crate::state_digest(&kernel.state).unwrap() ); - // And a pre-key state deserialises with every key absent. - let stripped: crate::WorldState = rmp_serde::from_slice(&state).unwrap(); - assert!(stripped.subjects.values().all(|s| s.import_key.is_none())); + // And a world nobody imported into holds every key absent. + assert!(kernel.state.subjects.values().all(|s| s.import_key.is_none())); } #[test] @@ -571,8 +565,9 @@ fn a_loaded_state_with_a_bad_import_key_is_refused() { assert!(crate::journal::verify_state_shape(&kernel.state).is_ok()); let corrupt = |edit: &dyn Fn(&mut ImportKey)| { let mut state = kernel.state.clone(); - for subject in state.subjects.values_mut() { - if let Some(held) = subject.import_key.as_mut() { + let ids: Vec<_> = state.subjects.keys().copied().collect(); + for id in ids { + if let Some(held) = state.subjects.get_mut(&id).and_then(|s| s.import_key.as_mut()) { edit(held); } } diff --git a/native/aetherlight/src/journal.rs b/native/aetherlight/src/journal.rs index f3414e4fe..aea378de6 100644 --- a/native/aetherlight/src/journal.rs +++ b/native/aetherlight/src/journal.rs @@ -1,7 +1,8 @@ use super::{ - COMMIT_SCHEMA, CommittedCommand, KernelError, STATE_SCHEMA, WorldCommit, WorldEffect, + COMMIT_SCHEMA, CommittedCommand, KernelError, WorldCommit, WorldEffect, WorldId, WorldState, apply_effect, commit_digest, reduce, state_digest, }; +use crate::docs::Changed; use serde::{Deserialize, Serialize, de::DeserializeOwned}; use std::collections::{BTreeMap, BTreeSet}; use thiserror::Error; @@ -121,7 +122,8 @@ pub(super) fn verify_history(commits: &[WorldCommit]) -> Result = replay.commitments.keys().map(|subject| (*subject, None)).collect(); + verify_commitments_are_future(&replay, &born)?; if replay.state_digest != genesis.resulting_state_digest { return Err(JournalError::Corrupt( "genesis resulting state digest is invalid".into(), @@ -131,7 +133,7 @@ pub(super) fn verify_history(commits: &[WorldCommit]) -> Result Result Result previous_now) != advanced { + if replay.header.now < previous_now || (replay.header.now > previous_now) != advanced { return Err(JournalError::Corrupt( "the world clock moved without a time-advanced commit, or ran backwards".into(), )); } - verify_commitments_are_future(&replay, &previous_commitments)?; + let touched = replay.finish(); + verify_commitments_are_future(&replay, &touched)?; replay.revision = commit.resulting_revision; replay.state_digest = state_digest(&replay).map_err(kernel_error)?; if replay.state_digest != commit.resulting_state_digest { @@ -176,17 +179,21 @@ pub(super) fn verify_history(commits: &[WorldCommit]) -> Result>, + touched: &[Changed>], ) -> Result<(), JournalError> { - for (subject_id, held) in &state.commitments { + for (subject_id, before) in touched { + let Some(held) = state.commitments.get(subject_id) else { + continue; + }; for (key, commitment) in held { let existed = before - .get(subject_id) + .as_ref() .is_some_and(|previous| previous.contains_key(key)); - if !existed && commitment.due <= state.now { + if !existed && commitment.due <= state.header.now { return Err(JournalError::Corrupt( "a commitment was born at or after its own due date".into(), )); @@ -197,15 +204,12 @@ fn verify_commitments_are_future( } pub(super) fn verify_state_shape(state: &WorldState) -> Result<(), JournalError> { - if state.schema != STATE_SCHEMA { - return Err(JournalError::Corrupt("invalid state schema".into())); - } - if state.title.trim().is_empty() || state.title.trim() != state.title { + if state.header.title.trim().is_empty() || state.header.title.trim() != state.header.title { return Err(JournalError::Corrupt( "world title is empty or noncanonical".into(), )); } - super::validate_principal(&state.owner).map_err(kernel_error)?; + super::validate_principal(&state.header.owner).map_err(kernel_error)?; if state.subjects.is_empty() { return Err(JournalError::Corrupt("world ontology is empty".into())); } @@ -613,7 +617,7 @@ fn apply_committed_command( "creation command appears after world genesis".into(), )); }; - if command.world_id != state.world_id || command.expected_revision != state.revision { + if command.world_id != state.header.world_id || command.expected_revision != state.revision { return Err(JournalError::Corrupt( "committed command does not target the exact replay state".into(), )); @@ -894,14 +898,14 @@ mod tests { let kernel = clock_history(); let replayed = reopen(&kernel.journal.commits).expect("the honest history replays"); assert_eq!(replayed.state_digest, kernel.state.state_digest); - assert_eq!(replayed.now, kernel.state.now); + assert_eq!(replayed.header.now, kernel.state.header.now); - let (digest, now) = (kernel.state.state_digest.clone(), kernel.state.now); + let (digest, now) = (kernel.state.state_digest.clone(), kernel.state.header.now); let exported = kernel.export().unwrap(); drop(kernel); let reopened = WorldKernel::open(&exported).unwrap(); assert_eq!(reopened.state.state_digest, digest); - assert_eq!(reopened.state.now, now); + assert_eq!(reopened.state.header.now, now); } /// An export is a claim about a chain, and `open` believes none of it that @@ -1806,7 +1810,7 @@ mod custody_tests { verify_state_shape(&kernel.state).expect("a canonical title passes"); for title in ["", " ", " Titled", "Titled "] { let mut forged = kernel.state.clone(); - forged.title = title.into(); + forged.header.get_mut().title = title.into(); assert!( matches!(verify_state_shape(&forged), Err(JournalError::Corrupt(_))), "title {title:?} passed the shape check" diff --git a/native/aetherlight/src/lib.rs b/native/aetherlight/src/lib.rs index b173dc6a6..f6bc8b3ea 100644 --- a/native/aetherlight/src/lib.rs +++ b/native/aetherlight/src/lib.rs @@ -58,6 +58,7 @@ mod action; mod clock; +mod docs; #[cfg(test)] mod golden_tests; mod grammar; @@ -98,6 +99,7 @@ pub(crate) use patch::{ }; use patch::{EdgeRecord, EntityRecord, LedgerDelta, ResolvedOp, ResolvedPatch}; +use docs::{Changed, Docs, Tracked}; use serde::{Deserialize, Serialize}; use sha2::{Digest, Sha256}; use std::collections::{BTreeMap, BTreeSet}; @@ -426,70 +428,76 @@ pub(crate) struct DecisionEvent { pub(crate) effects: Vec, } -#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)] -struct WorldState { - schema: String, +/// The world's own fields: the one document that is not a map row. Tracked like +/// a partition key, so a tick that advances the clock is one changed document. +#[derive(Clone, Debug, PartialEq, Eq)] +struct WorldHeader { world_id: WorldId, - revision: u64, owner: PrincipalId, title: String, /// Bound by genesis and never written again; absent from a world with no /// grammar, so such a world's state and digests are what they were before /// grammars existed. - #[serde(default, skip_serializing_if = "Option::is_none")] grammar: Option, - subjects: BTreeMap, - entities: BTreeMap, - edges: BTreeMap, - positions: BTreeMap, + /// Minutes since genesis. The world's only clock, advanced by exactly one + /// command body and read by no wall clock. It is world truth, and it is + /// read by no precondition. + now: FictionalMinutes, +} + +/// Every partition is a `Docs`: reads see the map, every write is logged, and +/// `submit` applies in place and either finishes or rolls the log back. +#[derive(Clone, Debug, PartialEq, Eq)] +struct WorldState { + header: Tracked, + revision: u64, + subjects: Docs, + entities: Docs, + edges: Docs, + positions: Docs, /// What each subject holds. Absence is zero at both levels: no stored /// `Quantity(0)` and no empty inner map, so a duplicate holding is /// unrepresentable and "nothing" has one shape. - holdings: BTreeMap>, + holdings: Docs>, /// What each subject depends on. Never empty for a present key. - dependencies: BTreeMap>, + dependencies: Docs>, /// One row per `EntityKind::Fact` entity, and no orphan either way. Facts /// are write-once: declaration and `AssertClaim` are the only writers, and /// standing never changes after admission. - facts: BTreeMap, + facts: Docs, /// One row per `EntityKind::Channel` entity, and no orphan either way. - channels: BTreeMap, + channels: Docs, /// What each subject knows. The sole owner of who-heard-what: `events` /// records what was done, and this decides what a subject may act on and /// what its projection may contain. Never empty for a present key, and /// absence is "knows nothing of it" — forgetting removes the key. - knowledge: BTreeMap>, + knowledge: Docs>, /// What ground each subject has jurisdiction over, and under which /// world-declared kind. Never empty for a present key. No subject holds two /// grants of one kind over overlapping ground, so nothing ever arbitrates /// between two sources of one permission. - authority: BTreeMap>, + authority: Docs>, /// The offices each institution constitutes, and who sits in them. An /// incumbent never acts as its institution: an office answers what its /// incumbent has jurisdiction over, not who the actor is. - selection: BTreeMap>, + selection: Docs>, /// Where each kind of grievance goes, and who may bring it. Keyed by /// neither a subject nor a referent, so it enters no scope components and /// is admission-only state. - redress: BTreeMap, + redress: Docs, /// What each subject has promised. Never empty for a present key. - commitments: BTreeMap>, - /// Lived meaning per subject. Read by projection and by nothing that - /// decides, so it enters `state_digest` and no scope. + commitments: Docs>, /// Pressure *on* each subject, keyed target-major then source. Never empty - /// for a present key; no stored zero magnitude. - pressures: BTreeMap>, - /// Minutes since genesis. The world's only clock, advanced by exactly one - /// command body and read by no wall clock. It enters `state_digest` and no - /// scope: it is world truth, and it is read by no precondition. - now: FictionalMinutes, + /// for a present key; no stored zero magnitude. Lived meaning: read by + /// projection and by nothing that decides. + pressures: Docs>, /// What an affordance *is*. World-authored and written by `admit_resolved` /// alone. - affordance_catalog: BTreeMap, + affordance_catalog: Docs, /// Who may exercise which entry: a row exists if and only if the subject /// holds at least one verb. A grant carries no payload, so a duplicate /// grant is unrepresentable rather than checked. - affordance_grants: BTreeMap>, + affordance_grants: Docs>, events: Vec, state_digest: String, last_commit_digest: Option, @@ -972,7 +980,7 @@ impl WorldKernel { authenticated: &AuthenticatedCaller, ) -> Result { let command_id = command.id(); - if command.world_id != self.state.world_id { + if command.world_id != self.state.header.world_id { return Err(KernelError::WorldMismatch); } if command.caller != authenticated.caller { @@ -986,32 +994,47 @@ impl WorldKernel { } let effect = reduce(&self.state, &command)?; - let mut candidate = self.state.clone(); - apply_effect(&mut candidate, command_id, &command.caller, &effect)?; - candidate.revision = candidate - .revision - .checked_add(1) - .ok_or_else(|| KernelError::Serialization("world revision overflow".into()))?; - candidate.state_digest = state_digest(&candidate)?; - - let mut commit = WorldCommit { - schema: COMMIT_SCHEMA.into(), - world_id: self.state.world_id, - command: CommittedCommand::WorldCommand(command), - previous_revision: Some(self.state.revision), - resulting_revision: candidate.revision, - previous_state_digest: Some(self.state.state_digest.clone()), - resulting_state_digest: candidate.state_digest.clone(), - previous_commit_digest: self.state.last_commit_digest.clone(), - effect, - digest: String::new(), + let previous_revision = self.state.revision; + let previous_state_digest = self.state.state_digest.clone(); + let previous_commit_digest = self.state.last_commit_digest.clone(); + // Applied in place under the partitions' undo logs: the world is never + // cloned, and any failure up to the sealed commit puts it back. + self.state.begin(); + let sealed = (|| -> Result { + apply_effect(&mut self.state, command_id, &command.caller, &effect)?; + self.state.revision = previous_revision + .checked_add(1) + .ok_or_else(|| KernelError::Serialization("world revision overflow".into()))?; + self.state.state_digest = state_digest(&self.state)?; + let mut commit = WorldCommit { + schema: COMMIT_SCHEMA.into(), + world_id: self.state.header.world_id, + command: CommittedCommand::WorldCommand(command), + previous_revision: Some(previous_revision), + resulting_revision: self.state.revision, + previous_state_digest: Some(previous_state_digest.clone()), + resulting_state_digest: self.state.state_digest.clone(), + previous_commit_digest, + effect, + digest: String::new(), + }; + commit.digest = commit_digest(&commit)?; + Ok(commit) + })(); + let commit = match sealed { + Ok(commit) => commit, + Err(error) => { + self.state.rollback(); + self.state.revision = previous_revision; + self.state.state_digest = previous_state_digest; + return Err(error); + } }; - commit.digest = commit_digest(&commit)?; - candidate.last_commit_digest = Some(commit.digest.clone()); + self.state.finish(); + self.state.last_commit_digest = Some(commit.digest.clone()); let receipt = CommitReceipt::from(&commit); self.journal.append(commit); - self.state = candidate; Ok(receipt) } @@ -1034,7 +1057,7 @@ fn reduce(state: &WorldState, command: &CommandEnvelope) -> Result { let to = state - .now + .header.now .checked_add(*minutes) .ok_or_else(|| KernelError::Serialization("world clock overflow".into()))?; // A tick with an empty motion is still a commit: the clock moved, @@ -1073,6 +1096,129 @@ fn is_genesis(revision: u64, subjects: &BTreeMap) -> bo revision == 0 && subjects.is_empty() } +impl WorldState { + /// The encoding the state digest has always hashed: every partition as its + /// map, in this order. `sealed` false writes the chain head (the two digest + /// fields) as blank, the form the state digest is taken over. + fn write_encoded( + &self, + serializer: S, + sealed: bool, + ) -> Result { + use serde::ser::SerializeStruct; + let header = &*self.header; + let fields = if header.grammar.is_some() { 26 } else { 25 }; + let mut out = serializer.serialize_struct("WorldState", fields)?; + out.serialize_field("schema", STATE_SCHEMA)?; + out.serialize_field("world_id", &header.world_id)?; + out.serialize_field("revision", &self.revision)?; + out.serialize_field("owner", &header.owner)?; + out.serialize_field("title", &header.title)?; + if header.grammar.is_some() { + out.serialize_field("grammar", &header.grammar)?; + } + out.serialize_field("subjects", &self.subjects)?; + out.serialize_field("entities", &self.entities)?; + out.serialize_field("edges", &self.edges)?; + out.serialize_field("positions", &self.positions)?; + out.serialize_field("holdings", &self.holdings)?; + out.serialize_field("dependencies", &self.dependencies)?; + out.serialize_field("facts", &self.facts)?; + out.serialize_field("channels", &self.channels)?; + out.serialize_field("knowledge", &self.knowledge)?; + out.serialize_field("authority", &self.authority)?; + out.serialize_field("selection", &self.selection)?; + out.serialize_field("redress", &self.redress)?; + out.serialize_field("commitments", &self.commitments)?; + out.serialize_field("pressures", &self.pressures)?; + out.serialize_field("now", &header.now)?; + out.serialize_field("affordance_catalog", &self.affordance_catalog)?; + out.serialize_field("affordance_grants", &self.affordance_grants)?; + out.serialize_field("events", &self.events)?; + if sealed { + out.serialize_field("state_digest", &self.state_digest)?; + out.serialize_field("last_commit_digest", &self.last_commit_digest)?; + } else { + out.serialize_field("state_digest", "")?; + out.serialize_field("last_commit_digest", &None::)?; + } + out.end() + } + + /// Opens a transaction. Every log must be empty: a write outside a + /// transaction, or a transaction left open, is a bug here and not state. + fn begin(&self) { + debug_assert!(self.header.is_clean(), "a transaction is open"); + debug_assert!(self.subjects.is_clean() && self.entities.is_clean()); + debug_assert!(self.edges.is_clean() && self.positions.is_clean()); + debug_assert!(self.holdings.is_clean() && self.dependencies.is_clean()); + debug_assert!(self.facts.is_clean() && self.channels.is_clean()); + debug_assert!(self.knowledge.is_clean() && self.authority.is_clean()); + debug_assert!(self.selection.is_clean() && self.redress.is_clean()); + debug_assert!(self.commitments.is_clean() && self.pressures.is_clean()); + debug_assert!(self.affordance_catalog.is_clean() && self.affordance_grants.is_clean()); + } + + /// Closes the transaction, keeping its writes. Returns the commitments + /// subjects that changed, with their old promises, for replay's check that + /// every commitment stays in the future. + fn finish(&mut self) -> Vec>> { + self.header.finish(); + self.subjects.finish(); + self.entities.finish(); + self.edges.finish(); + self.positions.finish(); + self.holdings.finish(); + self.dependencies.finish(); + self.facts.finish(); + self.channels.finish(); + self.knowledge.finish(); + self.authority.finish(); + self.selection.finish(); + self.redress.finish(); + self.pressures.finish(); + self.affordance_catalog.finish(); + self.affordance_grants.finish(); + self.commitments.finish() + } + + /// Closes the transaction, undoing every write in it. + fn rollback(&mut self) { + self.header.rollback(); + self.subjects.rollback(); + self.entities.rollback(); + self.edges.rollback(); + self.positions.rollback(); + self.holdings.rollback(); + self.dependencies.rollback(); + self.facts.rollback(); + self.channels.rollback(); + self.knowledge.rollback(); + self.authority.rollback(); + self.selection.rollback(); + self.redress.rollback(); + self.commitments.rollback(); + self.pressures.rollback(); + self.affordance_catalog.rollback(); + self.affordance_grants.rollback(); + } +} + +impl Serialize for WorldState { + fn serialize(&self, serializer: S) -> Result { + self.write_encoded(serializer, true) + } +} + +/// The state with its chain head blanked: what `state_digest` hashes. +struct Unsealed<'a>(&'a WorldState); + +impl Serialize for Unsealed<'_> { + fn serialize(&self, serializer: S) -> Result { + self.0.write_encoded(serializer, false) + } +} + impl WorldState { /// The world before any structure. Genesis resolves its own patch against /// this value, so the genesis lane and `AdmitPatch` share one resolver @@ -1084,29 +1230,30 @@ impl WorldState { grammar: Option, ) -> Self { Self { - schema: STATE_SCHEMA.into(), - world_id, + header: Tracked::absent(WorldHeader { + world_id, + owner, + title, + grammar, + now: FictionalMinutes::default(), + }), revision: 0, - owner, - title, - grammar, - subjects: BTreeMap::new(), - entities: BTreeMap::new(), - edges: BTreeMap::new(), - positions: BTreeMap::new(), - holdings: BTreeMap::new(), - dependencies: BTreeMap::new(), - facts: BTreeMap::new(), - channels: BTreeMap::new(), - knowledge: BTreeMap::new(), - authority: BTreeMap::new(), - selection: BTreeMap::new(), - redress: BTreeMap::new(), - commitments: BTreeMap::new(), - pressures: BTreeMap::new(), - now: FictionalMinutes::default(), - affordance_catalog: BTreeMap::new(), - affordance_grants: BTreeMap::new(), + subjects: Docs::default(), + entities: Docs::default(), + edges: Docs::default(), + positions: Docs::default(), + holdings: Docs::default(), + dependencies: Docs::default(), + facts: Docs::default(), + channels: Docs::default(), + knowledge: Docs::default(), + authority: Docs::default(), + selection: Docs::default(), + redress: Docs::default(), + commitments: Docs::default(), + pressures: Docs::default(), + affordance_catalog: Docs::default(), + affordance_grants: Docs::default(), events: Vec::new(), state_digest: String::new(), last_commit_digest: None, @@ -1158,6 +1305,7 @@ impl WorldState { // unlike every later commit, which resolves to `state.revision + 1`. let genesis_revision = state.revision; admit_resolved(&mut state, resolved, genesis_revision)?; + state.finish(); state.state_digest = state_digest(&state)?; Ok(state) } @@ -1239,7 +1387,7 @@ fn admit_resolved( // The catalog's only writer holds the same grammar check the resolver // runs, so an effect resolved elsewhere cannot install an entry the // bound grammar refuses. - if state.grammar.as_ref().is_some_and(|grammar| { + if state.header.grammar.as_ref().is_some_and(|grammar| { grammar .refusal(&entry.affordance.kind, &entry.affordance.roles) .is_some() @@ -2188,10 +2336,21 @@ fn apply_operation( subject: *subject, key: *key, }; - state.pressures.retain(|_, held| { - held.remove(&sourced); - !held.is_empty() - }); + let holding: Vec = state + .pressures + .iter() + .filter(|(_, held)| held.contains_key(&sourced)) + .map(|(target, _)| *target) + .collect(); + for target in holding { + let emptied = state.pressures.get_mut(&target).is_some_and(|held| { + held.remove(&sourced); + held.is_empty() + }); + if emptied { + state.pressures.remove(&target); + } + } } ResolvedOp::AdvancePressure { source, target, by } | ResolvedOp::ReducePressure { source, target, by } => { @@ -2315,7 +2474,7 @@ fn commitment_is_live(state: &WorldState, subject: SubjectId, commitment: &Commi counterparty_is_live && (commitment.kind == CommitmentKind::Routine) == commitment.period.is_some() && (commitment.kind == CommitmentKind::Routine || commitment.checks.is_empty()) - && commitment.due > state.now + && commitment.due > state.header.now && commitment .checks .iter() @@ -2900,7 +3059,7 @@ fn snapshot(state: &WorldState) -> Result { due: commitment.due, period: commitment.period, statement: commitment.statement.clone(), - past_due: commitment.due <= state.now, + past_due: commitment.due <= state.header.now, }) .collect(), dependencies: components.dependencies.iter().copied().collect(), @@ -2987,11 +3146,11 @@ fn snapshot(state: &WorldState) -> Result { }) .collect(); Ok(WorldSnapshot { - world_id: state.world_id, + world_id: state.header.world_id, revision: state.revision, - owner: state.owner.clone(), - title: state.title.clone(), - grammar: state.grammar.as_ref().map(GrammarBinding::identity), + owner: state.header.owner.clone(), + title: state.header.title.clone(), + grammar: state.header.grammar.as_ref().map(GrammarBinding::identity), subjects, affordances: state .affordance_catalog @@ -3000,7 +3159,7 @@ fn snapshot(state: &WorldState) -> Result { id: *affordance_id, entry: entry.clone(), render_path: state - .grammar + .header.grammar .as_ref() .and_then(|grammar| grammar.verb(&entry.kind.0)) .map(|verb| verb.render_path), @@ -3011,7 +3170,7 @@ fn snapshot(state: &WorldState) -> Result { routes, channels, facts, - now: state.now, + now: state.header.now, state_digest: state.state_digest.clone(), last_commit_digest: state.last_commit_digest.clone(), }) @@ -3140,13 +3299,14 @@ fn apply_effect( "acted effect does not derive from the actor's grants".into(), )); } - state.events.push(event.clone()); if !event.effects.is_empty() { // `derived != *event` above already proved `event.revision` is // exactly what `resolution_revision(state)` would compute right // now; read it back rather than computing it a second time. apply_operations(state, &event.effects, &[], event.revision)?; } + // After the writes, so a failed apply leaves nothing to undo here. + state.events.push(event.clone()); } WorldEffect::TimeAdvanced { minutes, @@ -3154,7 +3314,7 @@ fn apply_effect( motion, } => { let derived_to = state - .now + .header.now .checked_add(*minutes) .ok_or_else(|| KernelError::Serialization("world clock overflow".into()))?; // The whole motion is re-derived rather than trusted field by @@ -3165,7 +3325,7 @@ fn apply_effect( "time effect does not derive from the world clock".into(), )); } - state.now = *to; + state.header.get_mut().now = *to; for rolled in &motion.fulfilled { let commitment = state .commitments @@ -3197,10 +3357,7 @@ fn digest(value: &T) -> Result { } fn state_digest(state: &WorldState) -> Result { - let mut value = state.clone(); - value.state_digest.clear(); - value.last_commit_digest = None; - digest(&value) + digest(&Unsealed(state)) } fn commit_digest(commit: &WorldCommit) -> Result { @@ -4691,10 +4848,10 @@ mod tests { let (mut kernel, receipt) = create("Same"); let (twin, twin_receipt) = create("Same"); assert_eq!(receipt, twin_receipt); - assert_eq!(kernel.state.world_id, twin.state.world_id); + assert_eq!(kernel.state.header.world_id, twin.state.header.world_id); assert_eq!(receipt.world_id, WorldId::of(receipt.command_id)); let (other, _) = create("Other"); - assert_ne!(kernel.state.world_id, other.state.world_id); + assert_ne!(kernel.state.header.world_id, other.state.header.world_id); // The same patch at two revisions is two commands, so the entity it // declares is minted twice under two ids. @@ -7108,7 +7265,7 @@ mod knowledge_tests { #[test] fn every_canonical_id_comes_from_one_of_two_sites() { let (mut kernel, speech, active) = speech_kernel("Allocation"); - let world_id = kernel.state.world_id; + let world_id = kernel.state.header.world_id; let caller = play_caller(); let entities_before = kernel.state.entities.len(); let whisper = command( @@ -7986,7 +8143,10 @@ mod soul_knowledge_tests { // Those two are the whole of it: strip `facts` and `events` and the // rest of the state is silent. let mut stripped = kernel.state.clone(); - stripped.facts.clear(); + let facts: Vec<_> = stripped.facts.keys().copied().collect(); + for fact in facts { + stripped.facts.remove(&fact); + } stripped.events.clear(); let encoded = rmp_serde::to_vec_named(&stripped).unwrap(); assert!( @@ -9527,7 +9687,7 @@ mod clock_tests { let before = kernel.state.clone(); tick(&mut kernel, 1).expect("the tick commits"); - assert_eq!(kernel.state.now, FictionalMinutes(1)); + assert_eq!(kernel.state.header.now, FictionalMinutes(1)); assert_eq!(kernel.state.revision, before.revision + 1); assert!(kernel.state.pressures.is_empty()); assert_eq!(kernel.state.commitments, before.commitments); @@ -9536,7 +9696,7 @@ mod clock_tests { assert_eq!(kernel.state.events, before.events); tick(&mut kernel, 2).expect("the tick commits"); - assert_eq!(kernel.state.now, FictionalMinutes(3)); + assert_eq!(kernel.state.header.now, FictionalMinutes(3)); } /// A closed route in one place becomes political pressure in another without @@ -9595,7 +9755,7 @@ mod clock_tests { fn time_advances_only_through_advance_time() { let (mut kernel, clockwork, _) = clock_kernel("OnlyTick"); tick(&mut kernel, 5).expect("the tick commits"); - let now = kernel.state.now; + let now = kernel.state.header.now; exercise( &mut kernel, @@ -9604,7 +9764,7 @@ mod clock_tests { vec![binding("target", Target::Subject(clockwork.farmer))], ) .expect("the threat commits"); - assert_eq!(kernel.state.now, now); + assert_eq!(kernel.state.header.now, now); let snapshot = kernel.snapshot().unwrap(); submit_play( @@ -9614,7 +9774,7 @@ mod clock_tests { route: Ref::Existing(clockwork.gate), }]), ); - assert_eq!(kernel.state.now, now); + assert_eq!(kernel.state.header.now, now); } /// Who may tick, when, and how far. @@ -9659,11 +9819,11 @@ mod clock_tests { minutes: minutes(7), }, ); - assert_eq!(kernel.state.now, FictionalMinutes(7)); + assert_eq!(kernel.state.header.now, FictionalMinutes(7)); // And a span that would overflow the clock is refused rather than // wrapping. - kernel.state.now = FictionalMinutes(u64::MAX); + kernel.state.header.get_mut().now = FictionalMinutes(u64::MAX); let snapshot = kernel.snapshot().unwrap(); let error = kernel .submit( @@ -9765,7 +9925,7 @@ mod clock_tests { }, ) .expect("the honest motion applies"); - assert_eq!(candidate.now, to); + assert_eq!(candidate.header.now, to); } /// Replay across a tick is exact, and every envelope is idempotent. @@ -10226,11 +10386,11 @@ mod clock_tests { .collect() }; let before = digests(&kernel); - let before_now = kernel.state.now; + let before_now = kernel.state.header.now; // Short of every due date in the fixture. tick(&mut kernel, 10).expect("the tick commits"); - assert_eq!(kernel.state.now, FictionalMinutes(before_now.0 + 10)); + assert_eq!(kernel.state.header.now, FictionalMinutes(before_now.0 + 10)); assert!(kernel.state.pressures.is_empty()); assert_eq!(digests(&kernel), before, "the clock entered a scope"); } @@ -10541,7 +10701,7 @@ mod clock_tests { kernel .submit(ticking, &AuthenticatedCaller::fixture(CallerId::Play)) .expect("the tick commits"); - assert_eq!(replayed.now, kernel.state.now); + assert_eq!(replayed.header.now, kernel.state.header.now); assert_eq!(replayed.commitments, kernel.state.commitments); assert_eq!(replayed.pressures, kernel.state.pressures); } @@ -10672,7 +10832,7 @@ mod clock_tests { ) .expect("the play authority advances time"); assert!(receipt.resulting_revision > 0); - assert!(kernel.state.now > active.now); + assert!(kernel.state.header.now > active.now); } /// P3.4: a ruled fact is world truth to every subject that knows it. @@ -11953,7 +12113,7 @@ mod agency_tests { let granted = require_granted(state, human, affordance).unwrap(); let event = action::exercise(state, command_id, human, &granted, &invocation).unwrap(); let minutes = TickMinutes::new(9).unwrap(); - let to = state.now.checked_add(minutes).unwrap(); + let to = state.header.now.checked_add(minutes).unwrap(); let effects = [ ( "patch", diff --git a/native/aetherlight/src/patch.rs b/native/aetherlight/src/patch.rs index 7e585682e..a8e19aa23 100644 --- a/native/aetherlight/src/patch.rs +++ b/native/aetherlight/src/patch.rs @@ -3035,7 +3035,7 @@ fn check_against_grammar( roles: &[RoleSpec], mismatches: &mut Vec, ) { - let Some(grammar) = &state.grammar else { + let Some(grammar) = &state.header.grammar else { return; }; let handle = handle.clone(); @@ -3057,7 +3057,7 @@ pub(super) fn resolve_patch( command_id: CommandId, patch: &WorldPatch, ) -> Result> { - let world_id = state.world_id; + let world_id = state.header.world_id; let genesis = super::is_genesis(state.revision, &state.subjects); let mut mismatches = Vec::new(); let mut index: BTreeMap = BTreeMap::new(); @@ -3651,7 +3651,7 @@ pub(super) fn resolve_patch( } // A promise cannot be born past due: it would press on its // subject on the very next tick with no chance to act. - if *due <= state.now { + if *due <= state.header.now { mismatches.push(Mismatch::CommitmentDueInThePast { operation: position, }); @@ -6878,7 +6878,7 @@ mod tests { &auth_principal(owner()), ) .unwrap(); - let world_id = kernel.state.world_id; + let world_id = kernel.state.header.world_id; let command_id = CommandId::issue(); let handle = DraftHandle::new("a-handle"); assert_ne!(