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 <noreply@anthropic.com>
This commit is contained in:
soul 2026-11-20 02:40:09 +01:00
commit d3a1caa01b
4 changed files with 327 additions and 16 deletions

View file

@ -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`.

View file

@ -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

View file

@ -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
);
}
}

View file

@ -58,6 +58,8 @@
mod action;
mod clock;
#[cfg(test)]
mod golden_tests;
mod grammar;
#[cfg(test)]
mod import_key_tests;