From d3a1caa01bb676be4a19bf26f17e9f025dcba3ce Mon Sep 17 00:00:00 2001 From: soul Date: Fri, 20 Nov 2026 02:40:09 +0100 Subject: [PATCH] aetherlight: golden session digests, clockwork commit-cost harness, provenance fixtures/golden.digests pins every committed revision's state and commit digest and the export digest for one scripted session: speech (Told), a display, a routine placed and rolled by a thirty-minute tick, and a refused convene. The round-trip test reopens the export and checks the next command gives equal receipts on both worlds. clockwork_commit_cost is an ignored harness that prints mean tick and speech submit times at 100, 400 and 1600 persons. PROVENANCE.md records the id, journal and dependency changes. Co-Authored-By: Claude Sonnet 5.5 --- native/aetherlight/PROVENANCE.md | 61 +++-- native/aetherlight/fixtures/golden.digests | 6 + native/aetherlight/src/golden_tests.rs | 274 +++++++++++++++++++++ native/aetherlight/src/lib.rs | 2 + 4 files changed, 327 insertions(+), 16 deletions(-) create mode 100644 native/aetherlight/fixtures/golden.digests create mode 100644 native/aetherlight/src/golden_tests.rs diff --git a/native/aetherlight/PROVENANCE.md b/native/aetherlight/PROVENANCE.md index 447f1ad70..2f0b14bda 100644 --- a/native/aetherlight/PROVENANCE.md +++ b/native/aetherlight/PROVENANCE.md @@ -30,8 +30,8 @@ fixture (removed in AL2a) was binary and no newline rule touched it. Line ranges | `Cargo.lock` | `Cargo.lock` | all | pruned by cargo to the dependencies below | `Cargo.toml` is new: package `aetherlight`, its own `[workspace]`, no features, -dependencies chrono, cultcache-rs, rmp-serde, serde, serde_json, sha2, thiserror, -unicode-normalization, unicode-properties, uuid; dev tempfile. +dependencies rmp-serde, serde, serde_json, sha2, thiserror, unicode-normalization, +unicode-properties, uuid (serde only); dev uuid with v4 (AL3a). ## Edits @@ -76,14 +76,8 @@ unicode-normalization, unicode-properties, uuid; dev tempfile. `patch.rs`, `journal.rs`, `action.rs`, `grammar/tests.rs` and `import_key_tests.rs` lose the symbols and tests listed there. -Not renamed: the `ghostlight.*` schema ids and namespaces in the code -(`STATE_SCHEMA`, `COMMIT_SCHEMA`, journal schema rows, `ghostlight.speech`). They -enter derived ids and digests. No test pins their digests since AL2a removed the -golden replay (see below); AL3/AL5 add Aetherlight's own once ids are derived -(follow-up `aetherlight-golden-replay-dialogue`). AL2a bumped `STATE_SCHEMA` and -`COMMIT_SCHEMA` from `consumer.v6` to `consumer.v7` because the state shape lost -fields, so a pre-cut store is refused at the schema gate (tested with v6 rows). -AL3 owns the format rename. +The `ghostlight.*` schema ids were renamed in AL3a (see the last section). The +golden replay AL2a removed is back as `fixtures/golden.digests` (AL3a). ## Left behind @@ -111,10 +105,9 @@ binding, preconditions, audience, band selection and lowering (`action.rs`); ## Dependency pin -`cultcache-rs` is pinned at Ghostlight's rev -`85f7024a35ea42cf9f0a0199a064526427150191`, the rev that wrote -Ghostlight's recorded-world fixture (removed in AL2a), not Aetheria's C# CultLib pin. The fork -reproduces Ghostlight first; AL3 removes cultcache-rs. +The crate no longer pins CultLib: `cultcache-rs` (Ghostlight's rev +`85f7024a35ea42cf9f0a0199a064526427150191`) left the manifest in AL3a with the +redb store it served. ## Pulling a later Ghostlight fix @@ -182,8 +175,7 @@ Kept untouched for AL2b: controllers and `ControllerMode`, consumers What the cut deletes is gone; what remains is part B's: - Authenticated-caller vocabulary: `AuthenticatedCaller::fixture`, - `verified_principal`, `verified_play`, and - `requires_owner_restart`; id helpers `text` and `nil_for_test`; + `verified_principal` and `verified_play`; id helpers `text` and `nil_for_test`; `commits_for_test`; grammar `verbs`. AL4's ABI decides which of these it needs. - Patch ingress: `decode_patch`, `check_patch_caps`, `PatchDecodeError` and @@ -322,3 +314,40 @@ Not this cut's, and kept: the channel controller (`ChannelRecord.controller`, `SetController`, `resolve_controller`), which is dialogue (`dialogue-is-world-action`). An earlier version of this file listed `resolve_controller` and `controller_key` as AL2b-2b's; that was wrong. + +## Cut AL3a: the journal is in memory; ids are derived + +Authority: cut `aetherlight-journal-a` r1 of campaign `aetheria-release`; rulings +`aetherlight-narrative-state-owner`, `cultnet-scale-is-not-negotiable`, +`dialogue-is-world-action`. Base `09a1c3256` (spec base `39c50acfc`; no `native/` +change between them). + +Ids. `CommandEnvelope::id()` is the first 16 bytes of sha256 over +`aetherlight.command.v1`, the world id, the big-endian expected revision and the +named messagepack of caller and body. `CreateWorld::id()` is the same over +`aetherlight.create.v1` and the whole creation. `WorldId::of(creation id)` is the +same over `aetherlight.world.v1`; a genesis commit whose world id is not that is +refused at open. The `id` fields on `CreateWorld` and `CommandEnvelope`, +`CommandId::new`/`parse_uuid` and `WorldId::issue` are gone; `CommandId::issue` +is a test fixture. Retry identity went with them: `SubmitReceipt` collapsed into +`CommitReceipt`, and a resubmitted applied command is a `RevisionMismatch`. +`WorldCommit.committed_at` is gone: wall time is the C# store's `stored_at`. + +Journal. `WorldJournal { commits }` is the only record of a world. `export()` is +canonical named messagepack of `{ schema: aetherlight.journal.v1, commits }`; +`open(bytes)` decodes canonically and replays through `verify_history`, which +reads the revision-ordered slice and returns the head state it derives. There is +no state row, no expected world id, no health or ownership check and no +`verify_append`. `STATE_SCHEMA` and `COMMIT_SCHEMA` are +`aetherlight.world_state.v1` and `aetherlight.world_commit.v1`; any `ghostlight.*` +schema is refused at the schema gate and at the commit chain. + +Dependencies. chrono, cultcache-rs (and with it redb) and tempfile left the +manifest; uuid keeps `serde` in `[dependencies]` and `v4` only in +`[dev-dependencies]`, so no shipped path draws a random id (`cargo build --lib` +compiles without it). + +Not taken from the spec's text: the spec's negative pattern `id: CommandId` +matches the `command_id: CommandId` parameters of the band draw and derivation +(the per-command term the spec keeps); the doc comment said `synchronous`, which +`chrono` matches, and now says `single-threaded`. diff --git a/native/aetherlight/fixtures/golden.digests b/native/aetherlight/fixtures/golden.digests new file mode 100644 index 000000000..610f26d9f --- /dev/null +++ b/native/aetherlight/fixtures/golden.digests @@ -0,0 +1,6 @@ +0 sha256:b3a1da45714cfed622b118ac441f562dcf2c1f45637baff335f08a3efa562e55 sha256:e0e30c081917a00f88268916784d55e0e3ee187b8733a6da5953f9864dbc41cd +1 sha256:6315946e2cac6d49e24aae623bb92cdf9c68ac50382c1d27ffec34f78e2ebbb5 sha256:14fa8cbdee9f94944dbc91c9158fb6009c5310e11f57d682a3c17ae3ba4a476e +2 sha256:3bc0ba23bdb8afe6782b08f3223e9a501e17a8cfbbfed3b8c0a94cab20d2de64 sha256:e962a73db29fb48e0b303ac2746f85c88e9eca43e70cb3b5efb5527a885516a7 +3 sha256:cd5930ff97930832f59fb4ad954b0fd9ca94167767a15033011de8ca2b51581d sha256:3c6277ff11415a18376e8c86f1aa742ed8529b216a13492b66e0843dffffdcb4 +4 sha256:735182443e82f4b21d7b88c82aaca27987266653e6d839ab16556ac10b27d7e4 sha256:b138a16729c1f232c11f0b1a2bc692025856d2803820b05084cefd581af1b001 +export sha256:bc412d52ed96520d74bc06faead7c7b735573d268a51e2b4ea7d3f31ff4e8ac4 diff --git a/native/aetherlight/src/golden_tests.rs b/native/aetherlight/src/golden_tests.rs new file mode 100644 index 000000000..84ef74555 --- /dev/null +++ b/native/aetherlight/src/golden_tests.rs @@ -0,0 +1,274 @@ +//! The pinned replay of one scripted session, and the commit-cost harness. +//! +//! The golden file is the determinism contract in its smallest form: every +//! committed revision's state digest and commit digest, and the digest of the +//! export, for a session that touches speech, display, a routine and a refusal. +//! A change to any id derivation, schema, encoding or reducer arm moves a line. + +use crate::tests::{ + affordance_named, auth_principal, command, creation, first_grant, operations, owner, + play_caller, play_command, speak, subject_by_label, submit_play, tick_body, +}; +use crate::{ + AuthenticatedCaller, CommandBody, CommitmentKind, ComponentOp, DecisionInvocation, + FictionalMinutes, KernelError, KnowledgeSource, Ref, Statement, TickMinutes, WorldEffect, + WorldKernel, +}; +use sha2::{Digest, Sha256}; +use std::time::Instant; + +/// The script: The Human speaks to The Witness, The Human shows a gesture, a +/// Routine is placed on The Witness, thirty minutes roll it, and The Human +/// invokes `convene`, which it does not hold. +fn golden_session() -> (WorldKernel, String) { + let (mut kernel, _) = WorldKernel::create(creation("Golden"), &auth_principal(owner())) + .expect("the fixture world is created"); + let human = subject_by_label(&kernel.state, "The Human"); + let witness = subject_by_label(&kernel.state, "The Witness"); + + let snapshot = kernel.snapshot().unwrap(); + let speak_entry = first_grant(&snapshot, human); + submit_play( + &mut kernel, + &snapshot, + CommandBody::Act { + actor: human, + invocation: speak(speak_entry, "The vote carries."), + }, + ); + let heard = kernel.snapshot().unwrap(); + let witness_knowledge = &heard + .subjects + .iter() + .find(|subject| subject.id == witness) + .expect("the witness is a subject") + .knowledge; + assert!( + witness_knowledge.iter().any(|held| matches!( + held.source, + KnowledgeSource::Told { by, .. } if by == human + )), + "the witness holds what the human said as Told" + ); + + submit_play( + &mut kernel, + &heard, + CommandBody::Act { + actor: human, + invocation: DecisionInvocation { + affordance: speak_entry, + bindings: Vec::new(), + proposed: Vec::new(), + speech: None, + display: Some(Statement::new("The Human raises one finger.").unwrap()), + }, + }, + ); + + let snapshot = kernel.snapshot().unwrap(); + submit_play( + &mut kernel, + &snapshot, + operations(vec![ComponentOp::CreateCommitment { + subject: Ref::Existing(witness), + counterparty: None, + kind: CommitmentKind::Routine, + due: FictionalMinutes(10), + period: Some(TickMinutes::new(10).unwrap()), + checks: Vec::new(), + statement: Statement::new("The Witness keeps the lamp.").unwrap(), + }]), + ); + + let snapshot = kernel.snapshot().unwrap(); + submit_play(&mut kernel, &snapshot, tick_body(30)); + let ticked = kernel.journal.commits_for_test(); + let WorldEffect::TimeAdvanced { motion, .. } = + &ticked.last().expect("the tick committed").effect + else { + panic!("the last commit is the tick"); + }; + assert!(!motion.fulfilled.is_empty(), "the routine rolled"); + + // The refusal changes nothing: not the revision, not either digest. + let before = kernel.snapshot().unwrap(); + let convene = affordance_named(&before, "convene"); + let refused = kernel.submit( + command( + &before, + play_caller(), + CommandBody::Act { + actor: human, + invocation: speak(convene, "A meeting is called."), + }, + ), + &AuthenticatedCaller::verified_play(), + ); + assert!(matches!(refused, Err(KernelError::AffordanceDenied)), "{refused:?}"); + assert_eq!(kernel.snapshot().unwrap(), before); + assert_eq!(kernel.journal.commit_count(), 5); + + let mut file = String::new(); + for commit in kernel.journal.commits_for_test() { + file.push_str(&format!( + "{} {} {}\n", + commit.resulting_revision, commit.resulting_state_digest, commit.digest + )); + } + let export = kernel.export().unwrap(); + file.push_str(&format!("export sha256:{:x}\n", Sha256::digest(&export))); + (kernel, file) +} + +#[test] +fn golden_session_digests_are_fixed() { + let (_, computed) = golden_session(); + let (_, again) = golden_session(); + assert_eq!(computed, again, "one session, two runs, one file"); + let fixture: Vec<&str> = include_str!("../fixtures/golden.digests").lines().collect(); + let computed_lines: Vec<&str> = computed.lines().collect(); + assert!( + fixture == computed_lines, + "the golden digests moved; the computed file is:\n{computed}" + ); +} + +#[test] +fn export_open_round_trip_is_exact() { + let (mut original, _) = golden_session(); + let exported = original.export().unwrap(); + let mut reopened = WorldKernel::open(&exported).expect("the golden export opens"); + assert_eq!(reopened.state, original.state); + assert_eq!(reopened.snapshot().unwrap(), original.snapshot().unwrap()); + assert_eq!(reopened.export().unwrap(), exported); + + let human = subject_by_label(&original.state, "The Human"); + let snapshot = original.snapshot().unwrap(); + let next = play_command( + &snapshot, + CommandBody::Act { + actor: human, + invocation: speak(first_grant(&snapshot, human), "Order, please."), + }, + ); + let play = AuthenticatedCaller::verified_play(); + let original_receipt = original.submit(next.clone(), &play).unwrap(); + let reopened_receipt = reopened.submit(next, &play).unwrap(); + assert_eq!(original_receipt, reopened_receipt); + assert_eq!(original.export().unwrap(), reopened.export().unwrap()); +} + +/// What one tick and one speech cost to commit as the world grows: ten persons +/// to a place, one Routine each with period 60, due staggered over the hour. +/// Run on its own, in release, to read the numbers; no threshold is asserted. +/// +/// `cargo test --release --lib clockwork_commit_cost -- --ignored --nocapture` +#[test] +#[ignore] +fn clockwork_commit_cost() { + use crate::patch::kernel_speak_grant; + use crate::patch::{Declaration, DraftHandle, EntityDeclaration, SubjectDeclaration}; + use crate::{CallerId, CommandEnvelope, CreateWorld, EntityKind, SubjectKind, WorldPatch}; + + println!("persons places create_ms tick_mean_ms speech_mean_ms revision_after"); + for persons in [100usize, 400, 1600] { + let places = persons / 10; + let mut declarations = Vec::new(); + for place in 0..places { + declarations.push(Declaration::Entity(EntityDeclaration { + handle: DraftHandle::new(format!("place-{place}")), + label: format!("Place {place}"), + kind: EntityKind::Place, + container: None, + })); + } + for person in 0..persons { + declarations.push(Declaration::Subject(SubjectDeclaration { + handle: DraftHandle::new(format!("person-{person}")), + label: format!("Person {person}"), + kind: SubjectKind::Person, + affordances: kernel_speak_grant(), + position: Some(Ref::Draft(DraftHandle::new(format!("place-{}", person / 10)))), + import_key: None, + })); + } + let started = Instant::now(); + let (mut kernel, _) = WorldKernel::create( + CreateWorld { + owner: owner(), + title: "Clockwork".into(), + patch: WorldPatch { + declarations, + operations: Vec::new(), + evidence: Vec::new(), + }, + grammar: None, + }, + &auth_principal(owner()), + ) + .expect("the clockwork world is created"); + let create_ms = started.elapsed().as_secs_f64() * 1e3; + + let people: Vec<_> = (0..persons) + .map(|person| subject_by_label(&kernel.state, &format!("Person {person}"))) + .collect(); + let routines = people + .iter() + .enumerate() + .map(|(index, subject)| ComponentOp::CreateCommitment { + subject: Ref::Existing(*subject), + counterparty: None, + kind: CommitmentKind::Routine, + due: FictionalMinutes(1 + (index % 60) as u64), + period: Some(TickMinutes::new(60).unwrap()), + checks: Vec::new(), + statement: Statement::new("Keeps the hour.").unwrap(), + }) + .collect(); + let play = AuthenticatedCaller::verified_play(); + let envelope = |kernel: &WorldKernel, body: CommandBody| CommandEnvelope { + world_id: kernel.state.world_id, + expected_revision: kernel.state.revision, + caller: CallerId::Play, + body, + }; + let placing = envelope(&kernel, operations(routines)); + kernel.submit(placing, &play).expect("the routines are placed"); + + let speak_entry = *kernel + .state + .affordance_catalog + .iter() + .find(|(_, entry)| entry.kind.0 == "speak") + .map(|(id, _)| id) + .expect("genesis admits Speak"); + + let mut ticks = 0.0; + for _ in 0..30 { + let tick = envelope(&kernel, tick_body(1)); + let started = Instant::now(); + kernel.submit(tick, &play).expect("the tick commits"); + ticks += started.elapsed().as_secs_f64() * 1e3; + } + let mut speeches = 0.0; + for index in 0..30 { + let act = envelope( + &kernel, + CommandBody::Act { + actor: people[index], + invocation: speak(speak_entry, &format!("Speech {index}.")), + }, + ); + let started = Instant::now(); + kernel.submit(act, &play).expect("the speech commits"); + speeches += started.elapsed().as_secs_f64() * 1e3; + } + println!( + "{persons:>7} {places:>6} {create_ms:>9.1} {:>12.2} {:>14.2} {:>14}", + ticks / 30.0, + speeches / 30.0, + kernel.state.revision + ); + } +} diff --git a/native/aetherlight/src/lib.rs b/native/aetherlight/src/lib.rs index 0647e8db3..ee80dc982 100644 --- a/native/aetherlight/src/lib.rs +++ b/native/aetherlight/src/lib.rs @@ -58,6 +58,8 @@ mod action; mod clock; +#[cfg(test)] +mod golden_tests; mod grammar; #[cfg(test)] mod import_key_tests;