From 2daa80e159ea19874918e4826fce1d9311131a0a Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sun, 11 Oct 2026 08:58:20 +0200 Subject: [PATCH] Verse run: the manual tick driver, its run record and the ghostlight-verse command run_manual advances the verse world tick by tick under the recording port's token cap: snapshot, opportunities and agency graph from the mailbox, derive_cover, each cell on its members' current opportunities, one clock advance, a checkpoint in ghostlight.verse_run.v1. A tick that cannot finish leaves the clock where it was, so a later run re-derives the same cells and command ids and the kernel answers from its ledger. WorldMailbox::opportunities is the tick driver's own door beside agency_graph. OperatorEvent now names the verb, its render path and the bound roles. Not yet built or tested: this commit is the first write of the pass. Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 12 + Cargo.toml | 1 + crates/ghostlight-verse/Cargo.toml | 15 + crates/ghostlight-verse/src/main.rs | 294 ++++++ crates/ghostlight-verse/tests/verse_binary.rs | 283 +++++ crates/ghostlight/src/journal.rs | 5 + crates/ghostlight/src/lib.rs | 86 +- crates/ghostlight/src/mailbox.rs | 33 + crates/ghostlight/src/verse/calls.rs | 12 +- crates/ghostlight/src/verse/mod.rs | 14 +- crates/ghostlight/src/verse/run.rs | 627 +++++++++++ crates/ghostlight/src/verse/run/tests.rs | 998 ++++++++++++++++++ 12 files changed, 2371 insertions(+), 9 deletions(-) create mode 100644 crates/ghostlight-verse/Cargo.toml create mode 100644 crates/ghostlight-verse/src/main.rs create mode 100644 crates/ghostlight-verse/tests/verse_binary.rs create mode 100644 crates/ghostlight/src/verse/run.rs create mode 100644 crates/ghostlight/src/verse/run/tests.rs diff --git a/Cargo.lock b/Cargo.lock index dfffd46..251c9fe 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -730,6 +730,18 @@ dependencies = [ "unicode-segmentation", ] +[[package]] +name = "ghostlight-verse" +version = "0.1.0" +dependencies = [ + "anyhow", + "chrono", + "ghostlight", + "serde_json", + "tempfile", + "tokio", +] + [[package]] name = "hmac" version = "0.12.1" diff --git a/Cargo.toml b/Cargo.toml index 7bfeb7e..681ebc9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,6 +3,7 @@ members = [ "crates/ghostlight", "crates/ghostlight-dungeon", "crates/ghostlight-persona-projection", + "crates/ghostlight-verse", ] resolver = "2" diff --git a/crates/ghostlight-verse/Cargo.toml b/crates/ghostlight-verse/Cargo.toml new file mode 100644 index 0000000..89dd37f --- /dev/null +++ b/crates/ghostlight-verse/Cargo.toml @@ -0,0 +1,15 @@ +[package] +name = "ghostlight-verse" +version.workspace = true +edition.workspace = true +license.workspace = true + +[dependencies] +anyhow.workspace = true +chrono.workspace = true +ghostlight = { path = "../ghostlight" } +tokio.workspace = true + +[dev-dependencies] +serde_json.workspace = true +tempfile = "3" diff --git a/crates/ghostlight-verse/src/main.rs b/crates/ghostlight-verse/src/main.rs new file mode 100644 index 0000000..3bc026e --- /dev/null +++ b/crates/ghostlight-verse/src/main.rs @@ -0,0 +1,294 @@ +//! The verse runner's operator command line. +//! +//! `genesis` creates the canonical Aetheria verse world in a state root, and +//! `run` advances it a given number of ticks under a token cap, printing per +//! tick what each faction did and what it cost. A run starts only when this +//! command is invoked, and ends when it has done what it was asked. +//! +//! The state root holds `world.cc`, `controller-work.cc`, `runs.cc` and +//! `calls.cc`. The provider key is read from a file at run time and appears +//! nowhere else. + +use anyhow::{Context, Result, bail}; +use chrono::{Duration, Utc}; +use ghostlight::{ + CommandBody, CommandId, ControllerModels, ControllerRunner, DEFAULT_HOSTED_MODEL_PREFIX, + DEFAULT_LOCAL_MODEL_PREFIX, CallRecordStore, CoverBudget, CreateVerseWorldIntent, + HostedBinding, Lens, LensWeights, LocalBinding, PrincipalCommandIntent, RecordingInferencePort, + RunStart, RunStatus, TickMinutes, VerifiedPrincipalEvidence, VerseRunConfig, VerseRunStore, + WorldMailbox, call_run_id, id_text, open_controller_work, open_inference, + read_aetheria_catalog, run_manual, +}; +use std::collections::BTreeMap; +use std::net::SocketAddr; +use std::ops::ControlFlow; +use std::path::{Path, PathBuf}; +use std::process::ExitCode; +use std::sync::Arc; +use std::sync::atomic::{AtomicBool, Ordering}; + +/// What a manual run spends per tick on cognition cells. The operator's lever +/// on cost is the token cap; the partition always covers every faction. +const COVER: CoverBudget = CoverBudget { + cells: 8, + constituent_cap: 8, + urgency_slots: 2, +}; + +const RUNTIME_ID: &str = "ghostlight-verse"; + +#[tokio::main] +async fn main() -> ExitCode { + let arguments: Vec = std::env::args().skip(1).collect(); + match command(arguments).await { + Ok(code) => code, + Err(error) => { + eprintln!("ghostlight-verse: {error:#}"); + ExitCode::FAILURE + } + } +} + +async fn command(arguments: Vec) -> Result { + let Some((name, rest)) = arguments.split_first() else { + bail!("usage: ghostlight-verse genesis|run [flags]"); + }; + match name.as_str() { + "genesis" => genesis(Flags::parse(rest, &GENESIS_FLAGS)?).await, + "run" => run(Flags::parse(rest, &RUN_FLAGS)?).await, + _ => bail!("unknown command, expected genesis or run"), + } +} + +const GENESIS_FLAGS: [&str; 4] = ["catalog", "aetheria-commit", "state", "owner-hash"]; +const RUN_FLAGS: [&str; 7] = [ + "state", + "ticks", + "token-cap", + "tick-span-minutes", + "model", + "base-url", + "key-file", +]; +/// Flags a command may omit. +const OPTIONAL: [&str; 1] = ["key-file"]; + +/// `--name value` pairs, each named once and from the command's own list. +struct Flags(BTreeMap<&'static str, String>); + +impl Flags { + fn parse(arguments: &[String], allowed: &[&'static str]) -> Result { + let mut seen = BTreeMap::new(); + let mut rest = arguments.iter(); + while let Some(flag) = rest.next() { + let Some(name) = flag.strip_prefix("--") else { + bail!("expected a --flag, found a bare argument"); + }; + let Some(&known) = allowed.iter().find(|candidate| **candidate == name) else { + bail!("a flag this command does not take was given"); + }; + let Some(value) = rest.next() else { + bail!("--{known} needs a value"); + }; + if seen.insert(known, value.clone()).is_some() { + bail!("--{known} was given twice"); + } + } + for &required in allowed { + if !OPTIONAL.contains(&required) && !seen.contains_key(required) { + bail!("--{required} is required"); + } + } + Ok(Self(seen)) + } + + fn text(&self, name: &str) -> &str { + self.0.get(name).map_or("", String::as_str) + } + + fn path(&self, name: &str) -> PathBuf { + PathBuf::from(self.text(name)) + } + + fn number(&self, name: &str) -> Result { + match self.text(name).parse::() { + Ok(value) if value > T::default() => Ok(value), + _ => bail!("--{name} is not a positive integer"), + } + } +} + +async fn genesis(flags: Flags) -> Result { + let state = flags.path("state"); + std::fs::create_dir_all(&state).context("the state directory cannot be created")?; + let catalog = read_aetheria_catalog(flags.path("catalog")) + .context("the Aetheria catalog cannot be read")?; + let factions = catalog.factions.len(); + let principal = VerifiedPrincipalEvidence::new(flags.text("owner-hash"), Utc::now() + Duration::hours(1)); + + let (mailbox, task) = WorldMailbox::open(state.join("world.cc")) + .context("the world file cannot be opened")?; + let receipt = mailbox + .create_verse( + CreateVerseWorldIntent { + id: CommandId::new(), + title: "The Aetheria Verse".into(), + brief: "The Aetheria verse, simulated from its catalog.".into(), + catalog, + aetheria_commit: flags.text("aetheria-commit").into(), + lens_weights: LensWeights::new(Lens::ALL.into_iter().map(|lens| (lens, 1)).collect()), + targets: BTreeMap::new(), + }, + &principal, + ) + .await + .context("the verse world cannot be created")?; + // A created world is a draft: the owner approves and activates it, so the + // factions hold opportunities. + for body in [CommandBody::ApproveDraft, CommandBody::ActivateWorld] { + let revision = mailbox.snapshot().await.context("the world cannot be read")?.revision; + mailbox + .submit_principal( + PrincipalCommandIntent { + id: CommandId::new(), + world_id: receipt.world_id, + expected_revision: revision, + body, + }, + &principal, + ) + .await + .context("the world cannot be activated")?; + } + drop(mailbox); + task.await.context("the world file did not close cleanly")?; + println!("world {}", id_text(receipt.world_id)); + println!("factions {factions}"); + println!("phase Active"); + Ok(ExitCode::SUCCESS) +} + +async fn run(flags: Flags) -> Result { + let state = flags.path("state"); + let ticks: u32 = flags.number("ticks")?; + let cap: u64 = flags.number("token-cap")?; + let span: u32 = flags.number("tick-span-minutes")?; + let tick_span = TickMinutes::new(span).context("--tick-span-minutes is outside the clock's span")?; + if !state.join("world.cc").is_file() { + bail!("the state directory holds no world; run genesis first"); + } + + let model = flags.text("model").to_owned(); + let models = ControllerModels { + projector: model.clone(), + persona: model.clone(), + interpreter: model.clone(), + operational_agent: model.clone(), + elaborator: model.clone(), + }; + let inner = open_lane(&flags, &model, &models)?; + + let (mailbox, task) = WorldMailbox::open(state.join("world.cc")) + .context("the world file cannot be opened")?; + let world = mailbox.snapshot().await.context("the world cannot be read")?; + let calls = Arc::new(CallRecordStore::open(state.join("calls.cc")).context("the call records cannot be opened")?); + let runs = VerseRunStore::open(state.join("runs.cc")).context("the run records cannot be opened")?; + let work = open_controller_work(state.join("controller-work.cc")) + .context("the controller work store cannot be opened")?; + let sequence = runs.next_sequence(world.world_id).context("the run records cannot be read")?; + let port = Arc::new( + RecordingInferencePort::open(inner, calls, call_run_id(sequence), cap, &RunStart::of(&world)) + .context("the run's call records cannot be opened")?, + ); + let runner = ControllerRunner::open(mailbox.clone(), port.clone(), work, models) + .context("the controller organ cannot open")?; + + println!( + "run {sequence}: {ticks} ticks of {span} minutes, cap {cap} tokens, model {model}" + ); + let interrupted = Arc::new(AtomicBool::new(false)); + { + let interrupted = interrupted.clone(); + tokio::spawn(async move { + if tokio::signal::ctrl_c().await.is_ok() { + interrupted.store(true, Ordering::SeqCst); + } + }); + } + let outcome = run_manual( + &mailbox, + &runner, + &port, + &runs, + &VerseRunConfig { + ticks, + tick_span, + cover: COVER, + }, + sequence, + |report| { + print!("{report}"); + if interrupted.load(Ordering::SeqCst) { + ControlFlow::Break(()) + } else { + ControlFlow::Continue(()) + } + }, + ) + .await + .context("the run could not be recorded")?; + println!( + "status: {}; {} of {} ticks closed", + outcome.record.status, + outcome.record.checkpoints.len(), + outcome.record.ticks_requested + ); + drop(runner); + drop(port); + drop(mailbox); + task.await.context("the world file did not close cleanly")?; + Ok(match outcome.record.status { + RunStatus::Failed { .. } => ExitCode::FAILURE, + _ => ExitCode::SUCCESS, + }) +} + +/// The inference lane the model's prefix names. A hosted model needs an https +/// origin and a key file; a local one reaches a loopback server and needs +/// neither, so a key file beside it is refused. +fn open_lane( + flags: &Flags, + model: &str, + models: &ControllerModels, +) -> Result> { + let (mut hosted, mut local) = (None, None); + if model.starts_with(DEFAULT_HOSTED_MODEL_PREFIX) { + let Some(key) = flags.0.get("key-file") else { + bail!("a hosted model needs --key-file"); + }; + hosted = Some(HostedBinding { + base_url: flags.text("base-url").to_owned(), + key_path: Path::new(key).to_owned(), + model_prefix: DEFAULT_HOSTED_MODEL_PREFIX.into(), + caller_runtime_id: RUNTIME_ID.into(), + }); + } else if model.starts_with(DEFAULT_LOCAL_MODEL_PREFIX) { + if flags.0.contains_key("key-file") { + bail!("a local model takes no --key-file"); + } + let endpoint: SocketAddr = flags + .text("base-url") + .strip_prefix("http://") + .and_then(|address| address.trim_end_matches('/').parse().ok()) + .context("--base-url for a local model is not http://
:")?; + local = Some(LocalBinding { + endpoint, + model_prefix: DEFAULT_LOCAL_MODEL_PREFIX.into(), + caller_runtime_id: RUNTIME_ID.into(), + }); + } else { + bail!("--model names no inference lane (expected a hosted/ or local/ prefix)"); + } + open_inference(None, None, local, hosted, &models.each()) + .context("the inference lane cannot open") +} diff --git a/crates/ghostlight-verse/tests/verse_binary.rs b/crates/ghostlight-verse/tests/verse_binary.rs new file mode 100644 index 0000000..269d145 --- /dev/null +++ b/crates/ghostlight-verse/tests/verse_binary.rs @@ -0,0 +1,283 @@ +//! The `ghostlight-verse` command against a loopback scripted responder. No +//! real model is called and no key file is read: the responder answers the +//! OpenAI-compatible chat-completions request the local lane sends. + +use serde_json::{Value, json}; +use std::io::{Read, Write}; +use std::net::{SocketAddr, TcpListener, TcpStream}; +use std::path::Path; +use std::process::{Command, Output}; +use std::sync::Arc; +use std::sync::atomic::{AtomicUsize, Ordering}; + +const BINARY: &str = env!("CARGO_BIN_EXE_ghostlight-verse"); +const CATALOG: &str = concat!( + env!("CARGO_MANIFEST_DIR"), + "/../ghostlight/tests/fixtures/aetheria-verse-catalog.cc" +); +const COMMIT: &str = "92b82e9aa5bb422c568c4bfc85a8f641426a41fc"; +/// What the responder reports each call cost: 120 prompt and 30 completion. +const PER_CALL: u64 = 150; + +fn verse(arguments: &[&str]) -> Output { + Command::new(BINARY).args(arguments).output().unwrap() +} + +fn stdout(output: &Output) -> String { + String::from_utf8_lossy(&output.stdout).into_owned() +} + +fn stderr(output: &Output) -> String { + String::from_utf8_lossy(&output.stderr).into_owned() +} + +fn genesis(state: &Path) -> Output { + verse(&[ + "genesis", + "--catalog", + CATALOG, + "--aetheria-commit", + COMMIT, + "--state", + state.to_str().unwrap(), + "--owner-hash", + "verse-owner", + ]) +} + +/// Answers every chat-completions request with one tool call: the faction the +/// prompt names speaks its own line. Counts the requests it served. +struct Responder { + address: SocketAddr, + served: Arc, +} + +impl Responder { + fn start() -> Self { + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + let address = listener.local_addr().unwrap(); + let served = Arc::new(AtomicUsize::new(0)); + let counter = served.clone(); + std::thread::spawn(move || { + for stream in listener.incoming() { + let Ok(stream) = stream else { return }; + let counter = counter.clone(); + std::thread::spawn(move || serve(stream, &counter)); + } + }); + Self { address, served } + } + + fn url(&self) -> String { + format!("http://{}", self.address) + } +} + +fn serve(mut stream: TcpStream, served: &AtomicUsize) { + let mut raw = Vec::new(); + let mut chunk = [0u8; 4096]; + let (head_end, length) = loop { + let read = stream.read(&mut chunk).unwrap_or(0); + if read == 0 { + return; + } + raw.extend_from_slice(&chunk[..read]); + if let Some(end) = raw.windows(4).position(|window| window == b"\r\n\r\n") { + let head = String::from_utf8_lossy(&raw[..end]).to_ascii_lowercase(); + let length = head + .lines() + .find_map(|line| line.strip_prefix("content-length:")) + .and_then(|value| value.trim().parse::().ok()) + .unwrap_or(0); + break (end + 4, length); + } + }; + while raw.len() < head_end + length { + let read = stream.read(&mut chunk).unwrap_or(0); + if read == 0 { + return; + } + raw.extend_from_slice(&chunk[..read]); + } + let request: Value = serde_json::from_slice(&raw[head_end..head_end + length]).unwrap(); + let text = request.to_string(); + let faction = ["Adrasteia", "Brannoch"] + .into_iter() + .find(|name| text.contains(&format!("Decision owner:\\n{name}\\n"))) + .expect("a request names its faction"); + let sequence = served.fetch_add(1, Ordering::SeqCst); + let reply = json!({ + "id": format!("reply-{sequence}"), + "choices": [{ + "message": { + "role": "assistant", + "content": null, + "tool_calls": [{ + "id": format!("call-{sequence}"), + "type": "function", + "function": { + "name": "speak", + "arguments": json!({ "text": format!("{faction} holds the line.") }).to_string(), + }, + }], + }, + "finish_reason": "tool_calls", + }], + "usage": { "prompt_tokens": 120, "completion_tokens": 30 }, + }) + .to_string(); + let response = format!( + "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{reply}", + reply.len() + ); + let _ = stream.write_all(response.as_bytes()); +} + +fn run(state: &Path, responder: &Responder, ticks: &str, cap: &str) -> Output { + verse(&[ + "run", + "--state", + state.to_str().unwrap(), + "--ticks", + ticks, + "--token-cap", + cap, + "--tick-span-minutes", + "60", + "--model", + "local/scripted", + "--base-url", + &responder.url(), + ]) +} + +#[test] +fn binary_run_prints_acts_and_spend() { + let state = tempfile::tempdir().unwrap(); + let made = genesis(state.path()); + assert!(made.status.success(), "{}", stderr(&made)); + let made = stdout(&made); + assert!(made.contains("factions 2\n") && made.contains("phase Active\n"), "{made}"); + for file in ["world.cc"] { + assert!(state.path().join(file).is_file()); + } + + let responder = Responder::start(); + let output = run(state.path(), &responder, "2", "1000000"); + assert!(output.status.success(), "{}", stderr(&output)); + let text = stdout(&output); + + // Two ticks, each with both factions named by verb, and the spend as it + // accrues against the cap. + assert!(text.starts_with("run 1: 2 ticks of 60 minutes, cap 1000000 tokens"), "{text}"); + for tick in 0..2u64 { + let spent = PER_CALL * 2 * (tick + 1); + assert!( + text.contains(&format!("tick {tick} closed: 2 cells, 2 acts, 0 refused\n")), + "{text}" + ); + assert!( + text.contains(&format!( + " tokens: {} this tick, {spent} spent, {} remaining\n", + PER_CALL * 2, + 1_000_000 - spent + )), + "{text}" + ); + } + for faction in ["Adrasteia", "Brannoch"] { + assert_eq!( + text.matches(&format!(" {faction} speak [")).count(), + 2, + "{text}" + ); + assert!(text.contains(&format!("says \"{faction} holds the line.\"")), "{text}"); + } + assert!(text.ends_with("status: Completed; 2 of 2 ticks closed\n"), "{text}"); + assert_eq!(responder.served.load(Ordering::SeqCst), 4); + + // The state root holds each store the run wrote. + for file in ["world.cc", "controller-work.cc", "runs.cc", "calls.cc"] { + assert!(state.path().join(file).is_file(), "{file} was not written"); + } + + // A second run is the next in the world and carries on from its clock. + let again = run(state.path(), &responder, "1", "1000000"); + assert!(again.status.success(), "{}", stderr(&again)); + let text = stdout(&again); + assert!(text.starts_with("run 2: 1 ticks of 60 minutes"), "{text}"); + assert!(text.contains("tick 2 closed: 2 cells, 2 acts, 0 refused\n"), "{text}"); +} + +#[test] +fn a_cap_the_first_call_could_pass_ends_the_run_with_nothing_spent() { + let state = tempfile::tempdir().unwrap(); + assert!(genesis(state.path()).status.success()); + let responder = Responder::start(); + let output = run(state.path(), &responder, "3", "1000"); + assert!(output.status.success(), "{}", stderr(&output)); + let text = stdout(&output); + assert!(text.contains("tick 0 open: "), "{text}"); + assert!(text.contains("tokens: 0 this tick, 0 spent, 1000 remaining"), "{text}"); + assert!(text.ends_with("status: BudgetExhausted; 0 of 3 ticks closed\n"), "{text}"); + assert_eq!(responder.served.load(Ordering::SeqCst), 0, "no call was made"); +} + +#[test] +fn the_command_refuses_what_it_cannot_run_and_never_echoes_a_value() { + let state = tempfile::tempdir().unwrap(); + let responder = Responder::start(); + + // No world yet. + let output = run(state.path(), &responder, "1", "1000"); + assert!(!output.status.success()); + assert!(stderr(&output).contains("run genesis first"), "{}", stderr(&output)); + + assert!(genesis(state.path()).status.success()); + // A second genesis does not overwrite the first. + assert!(!genesis(state.path()).status.success()); + + let secret = "sk-not-a-real-key-0000"; + let key = state.path().join(secret); + let cases: [(Vec<&str>, &str); 6] = [ + (vec![], "usage"), + (vec!["fly"], "unknown command"), + ( + vec!["run", "--state", state.path().to_str().unwrap(), "--ticks", "0"], + "--token-cap is required", + ), + ( + vec![ + "run", "--state", state.path().to_str().unwrap(), "--ticks", "many", + "--token-cap", "1", "--tick-span-minutes", "60", "--model", "local/x", + "--base-url", "http://127.0.0.1:1", + ], + "--ticks is not a positive integer", + ), + ( + // A hosted model needs its key file; a missing one is named by flag. + vec![ + "run", "--state", state.path().to_str().unwrap(), "--ticks", "1", + "--token-cap", "1", "--tick-span-minutes", "60", "--model", "hosted/x", + "--base-url", "https://api.example.test", "--key-file", key.to_str().unwrap(), + ], + "the inference lane cannot open", + ), + ( + vec![ + "run", "--state", state.path().to_str().unwrap(), "--ticks", "1", + "--token-cap", "1", "--tick-span-minutes", "60", "--model", "local/x", + "--base-url", "http://127.0.0.1:1", "--key-file", key.to_str().unwrap(), + ], + "a local model takes no --key-file", + ), + ]; + for (arguments, expected) in cases { + let output = verse(&arguments); + assert!(!output.status.success(), "{arguments:?} succeeded"); + let error = stderr(&output); + assert!(error.contains(expected), "{arguments:?}: {error}"); + assert!(!error.contains(secret), "{arguments:?} echoed a path: {error}"); + assert!(!error.contains("many"), "{arguments:?} echoed a value: {error}"); + } +} diff --git a/crates/ghostlight/src/journal.rs b/crates/ghostlight/src/journal.rs index 8163d3a..a2d36fb 100644 --- a/crates/ghostlight/src/journal.rs +++ b/crates/ghostlight/src/journal.rs @@ -181,6 +181,11 @@ impl WorldJournal { self.commits.get(&command_id) } + /// Every commit the journal holds, in no particular order. + pub(super) fn commits(&self) -> impl Iterator { + self.commits.values() + } + #[cfg(test)] pub(super) fn commit_count(&self) -> usize { self.commits.len() diff --git a/crates/ghostlight/src/lib.rs b/crates/ghostlight/src/lib.rs index f373b42..ada2c6d 100644 --- a/crates/ghostlight/src/lib.rs +++ b/crates/ghostlight/src/lib.rs @@ -145,7 +145,10 @@ pub use table::{ pub use vault::{VaultError, VaultEvidenceSource}; pub use verse::{ CALL_RECORD_SCHEMA, CallRecordError, CallRecordStore, CreateVerseWorldIntent, ProviderCallRecord, - RecordingInferencePort, ReplayInferencePort, RunField, RunId, RunStart, VerseGenesisError, + RUN_RECORD_SCHEMA, RecordedCoverBudget, RecordingInferencePort, Refusal, RefusalReason, + ReplayInferencePort, RunField, RunId, RunOutcome, RunStart, RunStatus, TickCheckpoint, + TickReport, VerseGenesisError, VerseRunConfig, VerseRunError, VerseRunRecord, VerseRunStore, + call_run_id, run_manual, }; use patch::{EdgeRecord, EntityRecord, LedgerDelta, ResolvedOp, ResolvedPatch}; @@ -1275,6 +1278,21 @@ pub struct OperatorEvent { pub speaker_label: String, pub speech: Option, pub display: Option, + /// The affordance kind the act exercised. + pub verb: String, + /// How the world's grammar renders that verb; none in a world with no + /// grammar. + pub render_path: Option, + /// What the act bound each of the verb's roles to, in the invocation's + /// order. + pub roles: Vec, +} + +/// One role an act bound, with the label of what it was bound to. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct BoundRole { + pub role: String, + pub target: String, } #[derive(Clone, Debug, PartialEq, Eq)] @@ -1565,7 +1583,30 @@ impl WorldKernel { /// no consumer may read in full would be a loaded gun with a comment on it. fn operator_log(&self) -> Result, KernelError> { self.journal.ensure_healthy()?; - operator_log(&self.state) + // An event records what the world did; the invocation, which names the + // bound roles, lives on the commit that produced it. + let invocations: BTreeMap = self + .journal + .commits() + .filter_map(|commit| match &commit.effect { + WorldEffect::DecisionExercised { + invocation, event, .. + } => Some((event.id, invocation)), + _ => None, + }) + .collect(); + operator_log(&self.state, &invocations) + } + + /// The tick driver's opportunity list, in the same order a snapshot + /// carries it. Separate from `snapshot` for the reason `agency_graph` is: + /// only the tick driver reads it. + fn opportunities(&self) -> Result, KernelError> { + self.journal.ensure_healthy()?; + Ok(order_opportunities( + &self.state, + derive_opportunities(&self.state)?, + )) } /// The scheduler's adjacency projection. Separate from `snapshot` for the @@ -3740,7 +3781,10 @@ fn scope_components(state: &WorldState, subject_id: SubjectId) -> ScopeComponent /// The human operator's story feed, derived from the causal record. The events /// log is not a perception surface: `knowledge` is the sole answer to what a /// subject may act on and what its projection may contain. -fn operator_log(state: &WorldState) -> Result, KernelError> { +fn operator_log( + state: &WorldState, + invocations: &BTreeMap, +) -> Result, KernelError> { state .events .iter() @@ -3749,6 +3793,30 @@ fn operator_log(state: &WorldState) -> Result, KernelError> { .subjects .get(&event.scope.subject_id) .ok_or_else(|| KernelError::Invariant("event names no live subject".into()))?; + let invocation = invocations.get(&event.id).ok_or_else(|| { + KernelError::Invariant("event has no committed invocation".into()) + })?; + let entry = state + .affordance_catalog + .get(&event.affordance) + .ok_or_else(|| KernelError::Invariant("event names no catalog entry".into()))?; + let roles = invocation + .bindings + .iter() + .map(|binding| { + let label = match binding.target { + Target::Subject(id) => state.subjects.get(&id).map(|s| s.label.clone()), + Target::Entity(id) => state.entities.get(&id).map(|e| e.label.clone()), + Target::Edge(id) => state.edges.contains_key(&id).then(|| "edge".to_owned()), + }; + label + .map(|target| BoundRole { + role: binding.role.0.clone(), + target, + }) + .ok_or_else(|| KernelError::Invariant("event binds no live referent".into())) + }) + .collect::, _>>()?; Ok(OperatorEvent { revision: event.revision, speaker: event.scope.subject_id, @@ -3761,6 +3829,13 @@ fn operator_log(state: &WorldState) -> Result, KernelError> { .display .and_then(|fact| state.facts.get(&fact)) .map(|record| record.statement.clone()), + verb: entry.kind.0.clone(), + render_path: state + .grammar + .as_ref() + .and_then(|grammar| grammar.verb(&entry.kind.0)) + .map(|verb| verb.render_path), + roles, }) }) .collect() @@ -11533,7 +11608,7 @@ mod soul_knowledge_tests { // Nobody holds it. assert!(kernel.state.knowledge.is_empty()); // The operator reads it anyway, with the speaker resolved by label. - let log = operator_log(&kernel.state).unwrap(); + let log = kernel.operator_log().unwrap(); assert_eq!( log, vec![OperatorEvent { @@ -11542,6 +11617,9 @@ mod soul_knowledge_tests { speaker_label: "The Yard Bystander".into(), speech: Some(Statement::new(text).unwrap()), display: None, + verb: "speak".into(), + render_path: None, + roles: Vec::new(), }] ); // And no subject snapshot carries it. diff --git a/crates/ghostlight/src/mailbox.rs b/crates/ghostlight/src/mailbox.rs index 76f76da..4c162ce 100644 --- a/crates/ghostlight/src/mailbox.rs +++ b/crates/ghostlight/src/mailbox.rs @@ -82,6 +82,11 @@ enum Request { AgencyGraph { reply: oneshot::Sender>, }, + /// The tick driver's opportunity list. Separate from `Snapshot` so the + /// list a cover is derived from has one door, held by the driver. + Opportunities { + reply: oneshot::Sender, KernelError>>, + }, ControllerReceipt { command_id: CommandId, opportunity: super::DecisionOpportunity, @@ -486,6 +491,21 @@ impl WorldMailbox { .map_err(MailboxError::Kernel) } + /// The tick driver's opportunity list, in snapshot order. It is on + /// `WorldMailbox` and on no controller port, as `agency_graph` is. + pub async fn opportunities(&self) -> Result, MailboxError> { + let (reply, response) = oneshot::channel(); + self.sender + .send(Request::Opportunities { reply }) + .await + .map_err(|_| MailboxError::Unavailable)?; + + response + .await + .map_err(|_| MailboxError::Unavailable)? + .map_err(MailboxError::Kernel) + } + pub async fn operator_log(&self) -> Result, MailboxError> { let (reply, response) = oneshot::channel(); self.sender @@ -955,6 +975,19 @@ async fn run_owner(mut owned: OwnedWorld, mut receiver: mpsc::Receiver) return; } } + Request::Opportunities { reply } => { + let result = match &owned { + OwnedWorld::Empty(_) => Err(KernelError::WorldNotCreated), + OwnedWorld::Live(kernel) => kernel.opportunities(), + }; + let owner_must_stop = result + .as_ref() + .is_err_and(KernelError::requires_owner_restart); + let _ = reply.send(result); + if owner_must_stop { + return; + } + } Request::ControllerReceipt { command_id, opportunity, diff --git a/crates/ghostlight/src/verse/calls.rs b/crates/ghostlight/src/verse/calls.rs index d86a92d..079fa44 100644 --- a/crates/ghostlight/src/verse/calls.rs +++ b/crates/ghostlight/src/verse/calls.rs @@ -256,7 +256,7 @@ enum DecodedRow { Ledger(RunLedger), } -fn canonical Deserialize<'de>>( +pub(super) fn canonical Deserialize<'de>>( row: &CultCacheEnvelope, ) -> Result { let value: T = rmp_serde::from_slice(&row.payload).map_err(|_| CallRecordError::Corrupt)?; @@ -585,6 +585,16 @@ impl RecordingInferencePort { }) } + /// The run this port records. + pub fn run_id(&self) -> &RunId { + &self.run + } + + /// The token cap the run was opened under. + pub fn cap(&self) -> u64 { + self.cap + } + /// Tokens reserved or charged to the run so far. pub fn spent(&self) -> u64 { self.store.spent(&self.run).unwrap_or(u64::MAX) diff --git a/crates/ghostlight/src/verse/mod.rs b/crates/ghostlight/src/verse/mod.rs index 2600127..443b999 100644 --- a/crates/ghostlight/src/verse/mod.rs +++ b/crates/ghostlight/src/verse/mod.rs @@ -1,13 +1,19 @@ -//! The Aetheria verse run's own organs. The verse binary and its run record -//! live above this module; here sit the parts of a run that belong to the -//! library: the record of every provider call and the spend it implies, and the -//! genesis of the canonical verse world. +//! The Aetheria verse run's own organs. The verse binary sits above this +//! module; here sit the parts of a run that belong to the library: the record +//! of every provider call and the spend it implies, the genesis of the +//! canonical verse world, and the manual run that advances it with its record. mod calls; mod genesis; +mod run; pub use genesis::{CreateVerseWorldIntent, VerseGenesisError}; pub use calls::{ CALL_RECORD_SCHEMA, CallRecordError, CallRecordStore, ProviderCallRecord, RecordingInferencePort, ReplayInferencePort, RunField, RunId, RunStart, }; +pub use run::{ + RUN_RECORD_SCHEMA, RecordedCoverBudget, Refusal, RefusalReason, RunOutcome, RunStatus, + TickCheckpoint, TickReport, VerseRunConfig, VerseRunError, VerseRunRecord, VerseRunStore, + call_run_id, run_manual, +}; diff --git a/crates/ghostlight/src/verse/run.rs b/crates/ghostlight/src/verse/run.rs new file mode 100644 index 0000000..47c6dec --- /dev/null +++ b/crates/ghostlight/src/verse/run.rs @@ -0,0 +1,627 @@ +//! The manual verse run: the tick driver and its record. +//! +//! One invocation advances the world tick by tick. A tick reads the world, +//! derives the budgeted cover, runs each cell through the controller organ, +//! advances the clock once by the tick span, and checkpoints. The driver owns +//! the order of those steps and nothing else: cells decide what factions do, +//! the recording port owns spend, the kernel owns the world. +//! +//! The world's own clock is the resume point. A tick whose cells did not all +//! finish never advances the clock, so a later run derives the same tick index, +//! the same cells and the same command ids, the controller-work rows pick up +//! where they stopped, and the kernel answers every re-submission with the +//! original receipt. A run record therefore reports a run and is never read to +//! resume one. +//! +//! A run starts only when it is invoked: nothing here waits, schedules or +//! repeats. + +use super::calls::{RecordingInferencePort, canonical}; +use crate::controllers::{ + CellRun, ControllerError, ControllerPendingReason, ControllerRunner, InferenceFaultClass, + NarrativeRun, OperationalRun, SubmissionDisposition, +}; +use crate::cover::{Cell, Constituent, CoverBudget, CoverBudgetError, derive_cover}; +use crate::{ + CommandId, DecisionOpportunity, MailboxError, OperatorEvent, RenderPath, SubmitReceipt, + TickMinutes, WorldId, WorldMailbox, +}; +use chrono::Utc; +use cultcache_rs::{CacheBackingStore, CultCacheEnvelope, OwnedRedbMessagePackBackingStore}; +use serde::{Deserialize, Serialize}; +use std::{ops::ControlFlow, path::Path, sync::Mutex}; +use thiserror::Error; + +/// The run record document's schema. +pub const RUN_RECORD_SCHEMA: &str = "ghostlight.verse_run.v1"; +const RUN_ROW: &str = "verse_run.v1"; +const CLOCK_NAMESPACE: &str = "ghostlight.verse.clock"; + +/// Why a run could not be recorded or started. Every variant names a kind of +/// fault; none carries a value the run held. +#[derive(Debug, Error)] +pub enum VerseRunError { + #[error("the run record store could not be read or written")] + Store, + #[error("the run record store holds a row that is not a canonical run record")] + Corrupt, + #[error("a run record's sequence is not an existing run or the next in its world")] + OutOfSequence, + #[error("the recording port belongs to another run")] + PortNotThisRun, + #[error("the cover budget is not valid: {0}")] + Budget(#[from] CoverBudgetError), + #[error(transparent)] + Mailbox(#[from] MailboxError), +} + +/// Where a run stands. `Running` is only ever the record of a run in flight, +/// or of one whose process died before it could say how it ended. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub enum RunStatus { + Running, + Completed, + /// A provider call could pass the token cap, so the run ended before the + /// open tick's clock advance. + BudgetExhausted, + /// The run ended without finishing its open tick. `reason` is a fixed code + /// naming the kind of fault, never a value. + Failed { + reason: String, + }, + /// The caller asked the run to end after a finished tick. + Stopped, +} + +/// Why a cell committed nothing and the run went on. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub enum RefusalReason { + /// A narrative turn the world moved under and could not lower again. + Interrupted, + /// The world refused the cell's submission. + WorldRejected, + /// The cell's subject no longer holds the opportunity it was derived for. + OpportunityGone, +} + +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Refusal { + /// The cell's position in the tick's cover. + pub cell: u32, + pub reason: RefusalReason, +} + +/// One finished tick. The clock has advanced by the run's span. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct TickCheckpoint { + pub tick: u64, + pub cells: u32, + /// Every command the tick's cells hold a receipt for, in cell order. A + /// decline is a commit, so it is listed. + pub committed: Vec, + pub refusals: Vec, + /// Tokens the recording port charged during the tick. + pub tokens: u64, +} + +/// The cover budget as the record carries it. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct RecordedCoverBudget { + pub cells: u16, + pub constituent_cap: u16, + pub urgency_slots: u16, +} + +/// One invocation of the verse runner: what it was asked, what it did. +/// Document `ghostlight.verse_run.v1`, keyed (world, run sequence). +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct VerseRunRecord { + pub world_id: WorldId, + pub sequence: u64, + pub token_cap: u64, + pub ticks_requested: u32, + pub tick_span_minutes: u32, + pub cover_budget: RecordedCoverBudget, + /// The world's revision when the run began. + pub start_revision: u64, + pub checkpoints: Vec, + pub status: RunStatus, +} + +/// What a caller asks of one run. The token cap is not here: the recording +/// port owns it. +#[derive(Clone, Copy, Debug)] +pub struct VerseRunConfig { + pub ticks: u32, + pub tick_span: TickMinutes, + pub cover: CoverBudget, +} + +/// A tick as the operator reads it. `closed` is false for the tick a run ended +/// inside, whose cells may have committed before the run stopped. +#[derive(Clone, Debug)] +pub struct TickReport { + pub checkpoint: TickCheckpoint, + /// Every act the tick committed, from the operator log. + pub acts: Vec, + pub spent: u64, + pub remaining: u64, + pub closed: bool, +} + +impl std::fmt::Display for RunStatus { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + Self::Running => f.write_str("Running"), + Self::Completed => f.write_str("Completed"), + Self::BudgetExhausted => f.write_str("BudgetExhausted"), + Self::Failed { reason } => write!(f, "Failed ({reason})"), + Self::Stopped => f.write_str("Stopped"), + } + } +} + +/// The tick as the operator reads it: a header, one line per committed act +/// (who, which verb, how it renders, what its roles are bound to, what was +/// said or shown), one per refusal, and the spend. +impl std::fmt::Display for TickReport { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + let checkpoint = &self.checkpoint; + writeln!( + f, + "tick {} {}: {} cells, {} acts, {} refused", + checkpoint.tick, + if self.closed { "closed" } else { "open" }, + checkpoint.cells, + self.acts.len(), + checkpoint.refusals.len() + )?; + for act in &self.acts { + let path = match act.render_path { + Some(RenderPath::ShipAction) => "ship_action", + Some(RenderPath::Conversation) => "conversation", + None => "-", + }; + write!(f, " {} {} [{path}]", act.speaker_label, act.verb)?; + for role in &act.roles { + write!(f, " {}={}", role.role, role.target)?; + } + if let Some(speech) = &act.speech { + write!(f, " says {:?}", speech.as_str())?; + } + if let Some(display) = &act.display { + write!(f, " shows {:?}", display.as_str())?; + } + writeln!(f)?; + } + for refusal in &checkpoint.refusals { + let reason = match refusal.reason { + RefusalReason::Interrupted => "interrupted", + RefusalReason::WorldRejected => "world_rejected", + RefusalReason::OpportunityGone => "opportunity_gone", + }; + writeln!(f, " refused: cell {} {reason}", refusal.cell)?; + } + writeln!( + f, + " tokens: {} this tick, {} spent, {} remaining", + checkpoint.tokens, self.spent, self.remaining + ) + } +} + +#[derive(Clone, Debug)] +pub struct RunOutcome { + pub record: VerseRunRecord, +} + +fn row_key(world: WorldId, sequence: u64) -> String { + format!("{}/{sequence:020}", world.key()) +} + +/// Run records in one CultCache file. A run is saved when it begins and again +/// each time it moves, so a row is replaced by its own later state. +pub struct VerseRunStore { + store: Mutex, +} + +impl VerseRunStore { + /// Opens the file, creating it empty when absent. Every row must be a + /// canonical run record of this schema under its own key. + pub fn open(path: impl AsRef) -> Result { + let store = OwnedRedbMessagePackBackingStore::new(path.as_ref()) + .map_err(|_| VerseRunError::Store)?; + store + .validate_path_identity() + .map_err(|_| VerseRunError::Store)?; + let opened = Self { + store: Mutex::new(store), + }; + opened.records()?; + Ok(opened) + } + + fn records(&self) -> Result, VerseRunError> { + let rows = self + .store + .lock() + .map_err(|_| VerseRunError::Store)? + .pull_all() + .map_err(|_| VerseRunError::Store)?; + let mut records = Vec::new(); + for row in &rows { + if row.r#type != RUN_ROW || row.schema_id.as_deref() != Some(RUN_RECORD_SCHEMA) { + return Err(VerseRunError::Corrupt); + } + let record: VerseRunRecord = + canonical(row).map_err(|_| VerseRunError::Corrupt)?; + if row.key != row_key(record.world_id, record.sequence) || record.sequence == 0 { + return Err(VerseRunError::Corrupt); + } + records.push(record); + } + records.sort_by_key(|record| (record.world_id.key(), record.sequence)); + Ok(records) + } + + /// The sequence the next run of this world must carry. Sequences count from + /// one. + pub fn next_sequence(&self, world: WorldId) -> Result { + Ok(self + .records()? + .iter() + .filter(|record| record.world_id == world) + .map(|record| record.sequence) + .max() + .unwrap_or(0) + + 1) + } + + /// Every run of the world, in sequence. + pub fn runs(&self, world: WorldId) -> Result, VerseRunError> { + Ok(self + .records()? + .into_iter() + .filter(|record| record.world_id == world) + .collect()) + } + + /// Writes the record: the next run of its world, or a run already saved. + pub fn save(&self, record: &VerseRunRecord) -> Result<(), VerseRunError> { + if record.sequence == 0 || record.sequence > self.next_sequence(record.world_id)? { + return Err(VerseRunError::OutOfSequence); + } + let row = CultCacheEnvelope { + key: row_key(record.world_id, record.sequence), + r#type: RUN_ROW.into(), + payload: rmp_serde::to_vec_named(record).map_err(|_| VerseRunError::Store)?, + stored_at: Utc::now().to_rfc3339(), + schema_id: Some(RUN_RECORD_SCHEMA.into()), + }; + self.store + .lock() + .map_err(|_| VerseRunError::Store)? + .push(&row) + .map_err(|_| VerseRunError::Store) + } +} + +/// How an error ends a cell. +enum CellEnd { + Budget, + Fatal(&'static str), + Refused(RefusalReason), +} + +fn classify(error: &ControllerError) -> CellEnd { + match error { + ControllerError::Inference { source, .. } + if source.class() == InferenceFaultClass::BudgetExhausted => + { + CellEnd::Budget + } + _ if error.requires_quarantine() => CellEnd::Fatal("controller_quarantined"), + ControllerError::World(_) => CellEnd::Refused(RefusalReason::WorldRejected), + ControllerError::NoOpportunity { .. } + | ControllerError::AmbiguousOpportunity + | ControllerError::OpportunityMismatch => CellEnd::Refused(RefusalReason::OpportunityGone), + _ => CellEnd::Fatal("controller_error"), + } +} + +fn pending_code(reason: ControllerPendingReason) -> &'static str { + match reason { + ControllerPendingReason::InferenceRetryable => "inference_retryable", + ControllerPendingReason::InferenceRecoveryRequired => "inference_recovery_required", + ControllerPendingReason::WorldUnavailable => "world_unavailable", + ControllerPendingReason::WorldOutcomeUnknown => "world_outcome_unknown", + ControllerPendingReason::StoreReopenRequired => "store_reopen_required", + } +} + +fn command_of(submission: &SubmissionDisposition) -> CommandId { + match submission { + SubmissionDisposition::NoProposal(receipt) | SubmissionDisposition::Completed(receipt) => { + match receipt { + SubmitReceipt::Applied(commit) | SubmitReceipt::AlreadyApplied(commit) => { + commit.command_id + } + } + } + SubmissionDisposition::PreviouslyConfirmed(commit) => commit.command_id, + } +} + +/// Folds one finished cell into the tick. Returns the code of the pending state +/// that ends the run, when the cell did not finish. +fn absorb( + run: CellRun, + cell: u32, + committed: &mut Vec, + refusals: &mut Vec, +) -> Option<&'static str> { + match run { + CellRun::Narrative(NarrativeRun::Completed(decision)) => { + committed.push(command_of(decision.submission())); + None + } + CellRun::Narrative(NarrativeRun::Pending(pending)) => Some(pending_code(pending.reason())), + CellRun::Narrative(NarrativeRun::Interrupted(_)) => { + refusals.push(Refusal { + cell, + reason: RefusalReason::Interrupted, + }); + None + } + CellRun::Operational(OperationalRun::Completed(decision)) => { + committed.push(command_of(decision.submission())); + None + } + CellRun::Operational(OperationalRun::Pending(pending)) => { + Some(pending_code(pending.reason())) + } + CellRun::Grouped(run) => { + committed.extend(run.submissions.iter().map(|entry| command_of(&entry.submission))); + run.pending.map(pending_code) + } + } +} + +/// The cell with each member's opportunity read fresh. The cover is a +/// partition of subjects, fixed for the tick; an opportunity is the world's +/// current binding for a subject, and an earlier cell's act can move it (a +/// word spoken in a shared room changes what its listeners know). A subject +/// that no longer holds an opportunity leaves the cell, and an empty cell is +/// gone. +fn refreshed(cell: &Cell, fresh: &[DecisionOpportunity]) -> Option { + let current = |member: &Constituent| { + fresh + .iter() + .find(|opportunity| opportunity.scope == member.opportunity.scope) + .map(|opportunity| Constituent { + subject: member.subject, + opportunity: opportunity.clone(), + }) + }; + match cell { + Cell::Singleton { id, tick, member } => current(member).map(|member| Cell::Singleton { + id: *id, + tick: *tick, + member, + }), + Cell::Group { id, tick, members } => { + let members: Vec = members.iter().filter_map(current).collect(); + (!members.is_empty()).then(|| Cell::Group { + id: *id, + tick: *tick, + members, + }) + } + } +} + +enum TickEnd { + /// Every cell finished and the clock advanced. + Closed, + /// The run ends inside this tick with this status. + Open(RunStatus), +} + +fn failed(reason: &str) -> RunStatus { + RunStatus::Failed { + reason: reason.to_owned(), + } +} + +/// Runs `config.ticks` ticks from the world's present clock under the cap the +/// recording port was opened with. `observe` sees each tick as it ends, +/// including the one a run ends inside, and may stop the run after a finished +/// tick by breaking. `sequence` is the run's number from +/// [`VerseRunStore::next_sequence`]; the port must have been opened for it +/// ([`call_run_id`]). +pub async fn run_manual( + mailbox: &WorldMailbox, + runner: &ControllerRunner, + port: &RecordingInferencePort, + store: &VerseRunStore, + config: &VerseRunConfig, + sequence: u64, + mut observe: impl FnMut(&TickReport) -> ControlFlow<()>, +) -> Result { + if port.run_id() != &call_run_id(sequence) { + return Err(VerseRunError::PortNotThisRun); + } + let cover_budget = config.cover.validated()?; + let begun = mailbox.snapshot().await?; + let mut record = VerseRunRecord { + world_id: begun.world_id, + sequence, + token_cap: port.cap(), + ticks_requested: config.ticks, + tick_span_minutes: config.tick_span.minutes(), + cover_budget: RecordedCoverBudget { + cells: cover_budget.cells, + constituent_cap: cover_budget.constituent_cap, + urgency_slots: cover_budget.urgency_slots, + }, + start_revision: begun.revision, + checkpoints: Vec::new(), + status: RunStatus::Running, + }; + store.save(&record)?; + + let mut spent_before = port.spent(); + for completed in 0..config.ticks { + let (end, report) = run_tick( + mailbox, + runner, + port, + config, + cover_budget, + spent_before, + ) + .await; + spent_before = port.spent(); + match end { + TickEnd::Open(status) => { + record.status = status; + store.save(&record)?; + if let Some(report) = report { + let _ = observe(&report); + } + return Ok(RunOutcome { record }); + } + TickEnd::Closed => { + let report = report.expect("a closed tick has its report"); + record.checkpoints.push(report.checkpoint.clone()); + store.save(&record)?; + if observe(&report).is_break() && completed + 1 < config.ticks { + record.status = RunStatus::Stopped; + store.save(&record)?; + return Ok(RunOutcome { record }); + } + } + } + } + record.status = RunStatus::Completed; + store.save(&record)?; + Ok(RunOutcome { record }) +} + +/// The key a run's provider calls are recorded under: the run's sequence, so a +/// run record and its call records name each other. +pub fn call_run_id(sequence: u64) -> super::RunId { + super::RunId::new(&format!("run-{sequence}")) + .expect("a decimal sequence is a canonical run id") +} + +/// One tick. The report is absent only when the world could not be read at all. +async fn run_tick( + mailbox: &WorldMailbox, + runner: &ControllerRunner, + port: &RecordingInferencePort, + config: &VerseRunConfig, + cover_budget: CoverBudget, + spent_before: u64, +) -> (TickEnd, Option) { + let read = async { + let snapshot = mailbox.snapshot().await?; + let opportunities = mailbox.opportunities().await?; + let graph = mailbox.agency_graph().await?; + Ok::<_, MailboxError>((snapshot, opportunities, graph)) + } + .await; + let Ok((snapshot, opportunities, graph)) = read else { + return (TickEnd::Open(failed("world_unavailable")), None); + }; + let span = config.tick_span; + let cover = derive_cover( + snapshot.world_id, + snapshot.now, + span.minutes(), + &opportunities, + &graph, + cover_budget, + ); + + let mut committed = Vec::new(); + let mut refusals = Vec::new(); + let mut open: Option = None; + for (index, cell) in cover.cells.iter().enumerate() { + let index = index as u32; + let fresh = match mailbox.opportunities().await { + Ok(fresh) => fresh, + Err(_) => { + open = Some(failed("world_unavailable")); + break; + } + }; + let Some(cell) = refreshed(cell, &fresh) else { + refusals.push(Refusal { + cell: index, + reason: RefusalReason::OpportunityGone, + }); + continue; + }; + match runner.run_cell(&cell).await { + Ok(run) => { + if let Some(code) = absorb(run, index, &mut committed, &mut refusals) { + open = Some(failed(code)); + break; + } + } + Err(error) => match classify(&error) { + CellEnd::Budget => { + open = Some(RunStatus::BudgetExhausted); + break; + } + CellEnd::Fatal(code) => { + open = Some(failed(code)); + break; + } + CellEnd::Refused(reason) => refusals.push(Refusal { + cell: index, + reason, + }), + }, + } + } + + let closed = open.is_none(); + if closed { + let clock = CommandId::derived( + CLOCK_NAMESPACE, + &[&snapshot.world_id.text(), &cover.tick.0.to_string()], + ); + if mailbox.submit_clock(clock, span).await.is_err() { + open = Some(failed("clock_refused")); + } + } + + let spent = port.spent(); + let report = TickReport { + checkpoint: TickCheckpoint { + tick: cover.tick.0, + cells: cover.cells.len() as u32, + committed, + refusals, + tokens: spent.saturating_sub(spent_before), + }, + acts: mailbox + .operator_log() + .await + .map(|log| { + log.into_iter() + .filter(|event| event.revision > snapshot.revision) + .collect() + }) + .unwrap_or_default(), + spent, + remaining: port.cap().saturating_sub(spent), + closed: open.is_none(), + }; + (open.map_or(TickEnd::Closed, TickEnd::Open), Some(report)) +} + +#[cfg(test)] +mod tests; diff --git a/crates/ghostlight/src/verse/run/tests.rs b/crates/ghostlight/src/verse/run/tests.rs new file mode 100644 index 0000000..1ee04d4 --- /dev/null +++ b/crates/ghostlight/src/verse/run/tests.rs @@ -0,0 +1,998 @@ +use super::*; +use crate::aetheria::read_aetheria_catalog; +use crate::controllers::{ + ControllerModels, ControllerWorkStore, InferenceEvent, InferenceFault, InferenceOutput, + InferencePort, InferencePurpose, InferenceRequest, PreparedInference, TokenUsage, + open_controller_work, +}; +use crate::cover::derive_cover; +use crate::tests::stock_weights; +use crate::verse::{ + CallRecordStore, CreateVerseWorldIntent, RecordingInferencePort, ReplayInferencePort, + RunStart, +}; +use crate::{ + BoundRole, CommandBody, ControllerMode, FictionalMinutes, KernelError, + PrincipalCommandIntent, RenderPath, VerifiedPrincipalEvidence, id_text, +}; +use async_trait::async_trait; +use chrono::Duration; +use serde_json::json; +use std::collections::{BTreeMap, VecDeque}; +use std::path::Path; +use std::sync::Arc; +use std::sync::atomic::{AtomicUsize, Ordering}; +use tokio::task::JoinHandle; + +const COMMIT: &str = "92b82e9aa5bb422c568c4bfc85a8f641426a41fc"; +const FIXTURE: &str = concat!( + env!("CARGO_MANIFEST_DIR"), + "/tests/fixtures/aetheria-verse-catalog.cc" +); +const SPAN: u32 = 60; + +/// Creates the verse world at `dir/world.cc` from the fixture catalog and +/// activates it, then lets go of the file so a copy of it is a restored world. +async fn create_world(dir: &Path) { + let (mailbox, task) = WorldMailbox::open(dir.join("world.cc")).unwrap(); + let principal = + VerifiedPrincipalEvidence::fixture("verse-owner", Utc::now() + Duration::hours(1)); + let receipt = mailbox + .create_verse( + CreateVerseWorldIntent { + id: CommandId::new(), + title: "The Verse".into(), + brief: "Aetheria.".into(), + catalog: read_aetheria_catalog(FIXTURE).unwrap(), + aetheria_commit: COMMIT.into(), + lens_weights: stock_weights(), + targets: BTreeMap::new(), + }, + &principal, + ) + .await + .unwrap(); + for body in [CommandBody::ApproveDraft, CommandBody::ActivateWorld] { + let revision = mailbox.snapshot().await.unwrap().revision; + mailbox + .submit_principal( + PrincipalCommandIntent { + id: CommandId::new(), + world_id: receipt.world_id, + expected_revision: revision, + body, + }, + &principal, + ) + .await + .unwrap(); + } + drop(mailbox); + task.await.unwrap(); +} + +/// A scripted provider. `reply` sees the serialized request and answers with +/// the events a model would. It reports usage as a fixed share of the bound the +/// recording port holds the call to, so the charge is a function of the +/// request. +struct ScriptedPort { + reply: Box Vec + Send + Sync>, + faults: std::sync::Mutex>, + bounds: std::sync::Mutex>, + calls: AtomicUsize, +} + +impl ScriptedPort { + fn new(reply: impl Fn(&str) -> Vec + Send + Sync + 'static) -> Arc { + Arc::new(Self { + reply: Box::new(reply), + faults: std::sync::Mutex::new(VecDeque::new()), + bounds: std::sync::Mutex::new(Vec::new()), + calls: AtomicUsize::new(0), + }) + } + + /// Every faction speaks its own line. + fn speaking() -> Arc { + Self::new(|request| { + let name = who(request); + vec![speak_call(&format!("{name} holds the line."))] + }) + } + + fn fail_next(&self, fault: InferenceFault) { + self.faults.lock().unwrap().push_back(fault); + } + + fn calls(&self) -> usize { + self.calls.load(Ordering::SeqCst) + } + + fn bounds(&self) -> Vec { + self.bounds.lock().unwrap().clone() + } +} + +/// Which faction a request is for: the prompt names its decision owner. +fn who(request: &str) -> String { + for name in ["Adrasteia", "Brannoch"] { + if request.contains(&format!("Decision owner:\\n{name}\\n")) { + return name.to_owned(); + } + } + panic!("a request names no faction"); +} + +fn speak_call(text: &str) -> InferenceEvent { + InferenceEvent::ToolCall { + call_id: "act".into(), + name: "speak".into(), + arguments: json!({ "text": text }).to_string(), + } +} + +#[async_trait] +impl InferencePort for ScriptedPort { + fn prepare(&self, request: InferenceRequest) -> Result { + PreparedInference::prepare("verse-run-test", 4_102_444_800_000, request) + } + + async fn infer(&self, request: PreparedInference) -> Result { + let sequence = self.calls.fetch_add(1, Ordering::SeqCst); + let wire = &request.invocation.request; + let bound = serde_json::to_vec(wire).unwrap().len() as u64 + + u64::from(wire.max_output_tokens.unwrap()); + self.bounds.lock().unwrap().push(bound); + if let Some(fault) = self.faults.lock().unwrap().pop_front() { + return Err(fault); + } + let text = serde_json::to_string(wire).unwrap(); + Ok( + InferenceOutput::new((self.reply)(&text), format!("sha256:scripted-{sequence}")) + .with_usage(TokenUsage { + prompt: bound / 2, + completion: bound / 4, + cached_prompt: None, + }), + ) + } +} + +fn models() -> ControllerModels { + ControllerModels { + projector: "scripted".into(), + persona: "scripted".into(), + interpreter: "scripted".into(), + operational_agent: "scripted".into(), + elaborator: "scripted".into(), + } +} + +fn two_cells() -> CoverBudget { + CoverBudget { + cells: 2, + constituent_cap: 8, + urgency_slots: 0, + } +} + +fn config(ticks: u32) -> VerseRunConfig { + VerseRunConfig { + ticks, + tick_span: TickMinutes::new(SPAN).unwrap(), + cover: two_cells(), + } +} + +/// An opened verse state root: the world, its call records, its run records +/// and its controller work, as the binary holds them. +struct Harness { + mailbox: WorldMailbox, + _task: JoinHandle<()>, + calls: Arc, + runs: VerseRunStore, + work: Arc, +} + +impl Harness { + async fn open(dir: &Path) -> Self { + let (mailbox, task) = WorldMailbox::open(dir.join("world.cc")).unwrap(); + Self { + mailbox, + _task: task, + calls: Arc::new(CallRecordStore::open(dir.join("calls.cc")).unwrap()), + runs: VerseRunStore::open(dir.join("runs.cc")).unwrap(), + work: open_controller_work(dir.join("controller-work.cc")).unwrap(), + } + } + + async fn fresh() -> (tempfile::TempDir, Self) { + let dir = tempfile::tempdir().unwrap(); + create_world(dir.path()).await; + let harness = Self::open(dir.path()).await; + (dir, harness) + } + + /// One run over `inner`, recorded under the next sequence. + async fn run( + &self, + inner: Arc, + cap: u64, + ticks: u32, + observe: impl FnMut(&TickReport) -> ControlFlow<()>, + ) -> RunOutcome { + let world = self.mailbox.snapshot().await.unwrap(); + let sequence = self.runs.next_sequence(world.world_id).unwrap(); + let port = Arc::new( + RecordingInferencePort::open( + inner, + self.calls.clone(), + call_run_id(sequence), + cap, + &RunStart::of(&world), + ) + .unwrap(), + ); + let runner = + ControllerRunner::open(self.mailbox.clone(), port.clone(), self.work.clone(), models()) + .unwrap(); + run_manual( + &self.mailbox, + &runner, + &port, + &self.runs, + &config(ticks), + sequence, + observe, + ) + .await + .unwrap() + } + + async fn run_quietly(&self, inner: Arc, cap: u64, ticks: u32) -> RunOutcome { + self.run(inner, cap, ticks, |_| ControlFlow::Continue(())) + .await + } + + async fn now(&self) -> u64 { + self.mailbox.snapshot().await.unwrap().now.0 + } + + async fn acts(&self) -> usize { + self.mailbox.operator_log().await.unwrap().len() + } + + async fn subject(&self, label: &str) -> crate::SubjectId { + self.mailbox + .snapshot() + .await + .unwrap() + .subjects + .iter() + .find(|subject| subject.label == label) + .unwrap() + .id + } +} + +#[tokio::test] +async fn scripted_run_commits_and_checkpoints_every_tick() { + let (_dir, verse) = Harness::fresh().await; + let world = verse.mailbox.snapshot().await.unwrap(); + let opportunities = verse.mailbox.opportunities().await.unwrap(); + let graph = verse.mailbox.agency_graph().await.unwrap(); + let port = ScriptedPort::speaking(); + let mut reports = Vec::new(); + let outcome = verse + .run(port.clone(), 10_000_000, 3, |report| { + reports.push(report.clone()); + ControlFlow::Continue(()) + }) + .await; + + // One checkpoint per tick, tick indexes 0 to 2, the clock moved three spans. + assert_eq!(outcome.record.status, RunStatus::Completed); + let ticks: Vec = outcome.record.checkpoints.iter().map(|c| c.tick).collect(); + assert_eq!(ticks, vec![0, 1, 2]); + assert_eq!(verse.now().await, 3 * u64::from(SPAN)); + // Both factions acted every tick, the second on a scope the first moved. + assert_eq!(verse.acts().await, 6); + assert_eq!(port.calls(), 6); + + // Every committed command id is the one the cover derives for that cell, + // in cell order. + for checkpoint in &outcome.record.checkpoints { + let cover = derive_cover( + world.world_id, + FictionalMinutes(checkpoint.tick * u64::from(SPAN)), + SPAN, + &opportunities, + &graph, + two_cells(), + ); + let expected: Vec = cover + .cells + .iter() + .map(|cell| match cell { + Cell::Singleton { id, tick, member } => { + CommandId::for_cell_constituent(world.world_id, *id, member.subject, *tick) + } + Cell::Group { .. } => panic!("two factions under two cells are singletons"), + }) + .collect(); + assert_eq!(expected.len(), 2); + assert_eq!(checkpoint.committed, expected); + assert_eq!(checkpoint.cells, 2); + assert!(checkpoint.refusals.is_empty()); + } + + // The record in the store is the record the run returned, and it says what + // the run was asked. + assert_eq!( + verse.runs.runs(world.world_id).unwrap(), + vec![outcome.record.clone()] + ); + assert_eq!(outcome.record.world_id, world.world_id); + assert_eq!(outcome.record.sequence, 1); + assert_eq!(outcome.record.token_cap, 10_000_000); + assert_eq!(outcome.record.ticks_requested, 3); + assert_eq!(outcome.record.tick_span_minutes, SPAN); + assert_eq!(outcome.record.start_revision, world.revision); + assert_eq!( + outcome.record.cover_budget, + RecordedCoverBudget { + cells: 2, + constituent_cap: 8, + urgency_slots: 0 + } + ); + + // A tick's tokens are what the call store charged for its two calls. + let records = verse.calls.records(&call_run_id(1)).unwrap(); + assert_eq!(records.len(), 6); + for (tick, checkpoint) in outcome.record.checkpoints.iter().enumerate() { + let charged = records[2 * tick].charged() + records[2 * tick + 1].charged(); + assert!(charged > 0); + assert_eq!(checkpoint.tokens, charged); + } + let total: u64 = outcome.record.checkpoints.iter().map(|c| c.tokens).sum(); + assert_eq!(total, verse.calls.spent(&call_run_id(1)).unwrap()); + + // The operator sees each tick as it ends: its acts, and the spend so far. + assert_eq!(reports.len(), 3); + let mut spent = 0; + for (tick, report) in reports.iter().enumerate() { + spent += report.checkpoint.tokens; + assert!(report.closed); + assert_eq!(report.acts.len(), 2); + assert_eq!(report.spent, spent); + assert_eq!(report.remaining, 10_000_000 - spent); + assert_eq!(report.checkpoint, outcome.record.checkpoints[tick]); + for act in &report.acts { + assert_eq!(act.verb, "speak"); + assert_eq!( + act.speech.as_ref().unwrap().as_str(), + format!("{} holds the line.", act.speaker_label) + ); + } + } + // A tick reports only its own acts. + let revisions: Vec = reports + .iter() + .flat_map(|report| report.acts.iter().map(|act| act.revision)) + .collect(); + assert_eq!(revisions.len(), 6); + assert!(revisions.windows(2).all(|pair| pair[0] < pair[1])); +} + +#[tokio::test] +async fn budget_exhausted_stops_before_the_clock_and_resumes() { + // What the first call is held to, measured on a world of its own. + let (_probe_dir, probe) = Harness::fresh().await; + let measuring = ScriptedPort::speaking(); + probe.run_quietly(measuring.clone(), u64::MAX, 1).await; + let first_bound = measuring.bounds()[0]; + + let (_dir, verse) = Harness::fresh().await; + let world = verse.mailbox.snapshot().await.unwrap(); + // Room for the first call, and not for a second after the first's charge. + let first = ScriptedPort::speaking(); + let mut reports = Vec::new(); + let ended = verse + .run(first.clone(), first_bound + 64, 2, |report| { + reports.push(report.clone()); + ControlFlow::Continue(()) + }) + .await; + assert_eq!(ended.record.status, RunStatus::BudgetExhausted); + assert!(ended.record.checkpoints.is_empty()); + assert_eq!(verse.now().await, 0, "the open tick's clock did not advance"); + assert_eq!(first.calls(), 1, "the second call never reached the provider"); + assert_eq!(verse.acts().await, 1); + // The open tick is reported, unclosed, with what it committed. + assert_eq!(reports.len(), 1); + assert!(!reports[0].closed); + assert_eq!(reports[0].acts.len(), 1); + assert_eq!(reports[0].checkpoint.committed.len(), 1); + assert!(reports[0].remaining < first_bound); + assert_eq!( + verse.runs.runs(world.world_id).unwrap(), + vec![ended.record.clone()] + ); + + // A later run, under its own cap, finishes the tick: the first faction's + // act is answered from the kernel's ledger and costs no call. + let second = ScriptedPort::speaking(); + let resumed = verse.run_quietly(second.clone(), u64::MAX, 2).await; + assert_eq!(resumed.record.status, RunStatus::Completed); + assert_eq!(resumed.record.sequence, 2); + let ticks: Vec = resumed.record.checkpoints.iter().map(|c| c.tick).collect(); + assert_eq!(ticks, vec![0, 1], "the open tick is the first this run closes"); + assert_eq!(verse.now().await, 2 * u64::from(SPAN)); + assert_eq!(second.calls(), 3, "one call finished tick 0, two ran tick 1"); + assert_eq!(verse.acts().await, 4, "no act was committed twice"); + // The tick that was open committed both of its cells' commands. + assert_eq!(resumed.record.checkpoints[0].committed.len(), 2); + assert_eq!( + resumed.record.checkpoints[0].committed[0], + reports[0].checkpoint.committed[0] + ); +} + +#[tokio::test] +async fn recorded_run_replays_to_the_same_journal() { + let live_dir = tempfile::tempdir().unwrap(); + create_world(live_dir.path()).await; + let replay_dir = tempfile::tempdir().unwrap(); + std::fs::copy( + live_dir.path().join("world.cc"), + replay_dir.path().join("world.cc"), + ) + .unwrap(); + let live = Harness::open(live_dir.path()).await; + let replayed = Harness::open(replay_dir.path()).await; + + let provider = ScriptedPort::speaking(); + let recorded = live.run_quietly(provider.clone(), u64::MAX, 3).await; + assert_eq!(recorded.record.status, RunStatus::Completed); + + // The same run again, from the recorded replies and no provider. + let start = RunStart::of(&replayed.mailbox.snapshot().await.unwrap()); + let replay = Arc::new( + ReplayInferencePort::new("verse-replay", &live.calls, &call_run_id(1), &start).unwrap(), + ); + let again = replayed.run_quietly(replay, u64::MAX, 3).await; + assert_eq!(again.record.status, RunStatus::Completed); + assert_eq!(provider.calls(), 6, "replay made no provider call"); + + assert_eq!(again.record.checkpoints, recorded.record.checkpoints); + let live_world = live.mailbox.snapshot().await.unwrap(); + let replayed_world = replayed.mailbox.snapshot().await.unwrap(); + assert_eq!(replayed_world.revision, live_world.revision); + assert_eq!(replayed_world.state_digest, live_world.state_digest); + assert_eq!( + replayed.mailbox.operator_log().await.unwrap(), + live.mailbox.operator_log().await.unwrap() + ); + // Both stores hold the same calls, charged the same. + assert_eq!( + replayed.calls.records(&call_run_id(1)).unwrap(), + live.calls.records(&call_run_id(1)).unwrap() + ); +} + +#[tokio::test] +async fn a_run_the_caller_stops_ends_after_a_finished_tick() { + let (_dir, verse) = Harness::fresh().await; + let stopped = verse + .run(ScriptedPort::speaking(), u64::MAX, 3, |_| { + ControlFlow::Break(()) + }) + .await; + assert_eq!(stopped.record.status, RunStatus::Stopped); + assert_eq!(stopped.record.checkpoints.len(), 1); + assert_eq!(verse.now().await, u64::from(SPAN)); + + // A stop asked on the last tick is not a stop: the run was done. + let done = verse + .run(ScriptedPort::speaking(), u64::MAX, 1, |_| { + ControlFlow::Break(()) + }) + .await; + assert_eq!(done.record.status, RunStatus::Completed); +} + +#[tokio::test] +async fn a_pending_cell_ends_the_run_without_the_clock_and_a_later_run_finishes_it() { + let (_dir, verse) = Harness::fresh().await; + let flaky = ScriptedPort::speaking(); + flaky.fail_next(InferenceFault::retryable("the provider is busy")); + let ended = verse.run_quietly(flaky.clone(), u64::MAX, 2).await; + assert_eq!( + ended.record.status, + RunStatus::Failed { + reason: "inference_retryable".into() + } + ); + assert!(ended.record.checkpoints.is_empty()); + assert_eq!(verse.now().await, 0); + assert_eq!(verse.acts().await, 0); + + let finished = verse + .run_quietly(ScriptedPort::speaking(), u64::MAX, 1) + .await; + assert_eq!(finished.record.status, RunStatus::Completed); + assert_eq!(verse.now().await, u64::from(SPAN)); + assert_eq!(verse.acts().await, 2); +} + +#[tokio::test] +async fn a_provider_answer_against_the_tool_contract_ends_the_run_without_the_clock() { + let (_dir, verse) = Harness::fresh().await; + // The faction acts and then calls finish_without_proposal, which + // contradicts its own choice. + let port = ScriptedPort::new(|request| { + let name = who(request); + vec![ + speak_call(&format!("{name} speaks.")), + InferenceEvent::ToolCall { + call_id: "finish".into(), + name: "finish_without_proposal".into(), + arguments: "{}".into(), + }, + ] + }); + let outcome = verse.run_quietly(port, u64::MAX, 1).await; + assert_eq!( + outcome.record.status, + RunStatus::Failed { + reason: "inference_recovery_required".into() + } + ); + assert!(outcome.record.checkpoints.is_empty()); + assert_eq!(verse.now().await, 0); +} + +#[tokio::test] +async fn a_cell_the_world_refuses_is_a_refusal_and_the_tick_closes() { + let (_dir, verse) = Harness::fresh().await; + // Adrasteia attacks something that is not in the world; Brannoch speaks. + let nothing = id_text(CommandId::new()); + let port = ScriptedPort::new(move |request| { + let name = who(request); + if name == "Adrasteia" { + vec![InferenceEvent::ToolCall { + call_id: "act".into(), + name: "attack".into(), + arguments: json!({ "target": nothing, "text": "Adrasteia strikes." }).to_string(), + }] + } else { + vec![speak_call("Brannoch speaks.")] + } + }); + let outcome = verse.run_quietly(port, u64::MAX, 1).await; + assert_eq!(outcome.record.status, RunStatus::Completed); + let [checkpoint] = outcome.record.checkpoints.as_slice() else { + panic!("one tick, one checkpoint") + }; + assert_eq!(checkpoint.cells, 2); + assert_eq!(checkpoint.committed.len(), 1); + assert_eq!(checkpoint.refusals.len(), 1); + assert_eq!(checkpoint.refusals[0].reason, RefusalReason::WorldRejected); + assert!(checkpoint.refusals[0].cell < 2); + assert_eq!(verse.now().await, u64::from(SPAN)); + assert_eq!(verse.acts().await, 1); +} + +#[test] +fn the_operator_reads_refusals_and_how_a_run_ended() { + let report = TickReport { + checkpoint: TickCheckpoint { + tick: 4, + cells: 3, + committed: Vec::new(), + refusals: vec![ + Refusal { + cell: 1, + reason: RefusalReason::WorldRejected, + }, + Refusal { + cell: 2, + reason: RefusalReason::OpportunityGone, + }, + Refusal { + cell: 0, + reason: RefusalReason::Interrupted, + }, + ], + tokens: 7, + }, + acts: Vec::new(), + spent: 40, + remaining: 60, + closed: false, + }; + assert_eq!( + report.to_string(), + "tick 4 open: 3 cells, 0 acts, 3 refused + refused: cell 1 world_rejected + refused: cell 2 opportunity_gone + refused: cell 0 interrupted + tokens: 7 this tick, 40 spent, 60 remaining +" + ); + let ended: Vec = [ + RunStatus::Running, + RunStatus::Completed, + RunStatus::BudgetExhausted, + RunStatus::Failed { + reason: "clock_refused".into(), + }, + RunStatus::Stopped, + ] + .iter() + .map(ToString::to_string) + .collect(); + assert_eq!( + ended, + ["Running", "Completed", "BudgetExhausted", "Failed (clock_refused)", "Stopped"] + ); +} + +#[tokio::test] +async fn an_act_names_its_verb_render_path_and_bound_roles() { + let (_dir, verse) = Harness::fresh().await; + let target = id_text(verse.subject("Brannoch").await); + let port = ScriptedPort::new(move |request| { + if who(request) == "Adrasteia" { + vec![InferenceEvent::ToolCall { + call_id: "act".into(), + name: "attack".into(), + arguments: json!({ "target": target, "text": "Adrasteia strikes." }).to_string(), + }] + } else { + vec![speak_call("Brannoch answers.")] + } + }); + let mut reports = Vec::new(); + let outcome = verse + .run(port, u64::MAX, 1, |report| { + reports.push(report.clone()); + ControlFlow::Continue(()) + }) + .await; + assert_eq!(outcome.record.status, RunStatus::Completed); + let catalog = read_aetheria_catalog(FIXTURE).unwrap(); + let acts = &reports[0].acts; + let attack = acts.iter().find(|act| act.verb == "attack").unwrap(); + assert_eq!(attack.speaker_label, "Adrasteia"); + assert_eq!( + attack.render_path, + Some(catalog.grammar.verb("attack").unwrap().render_path) + ); + assert_eq!( + attack.roles, + vec![BoundRole { + role: "target".into(), + target: "Brannoch".into() + }] + ); + + // And the operator reads them so. + let name = |verb: &str| match catalog.grammar.verb(verb).unwrap().render_path { + RenderPath::ShipAction => "ship_action", + RenderPath::Conversation => "conversation", + }; + let text = reports[0].to_string(); + let checkpoint = &reports[0].checkpoint; + assert!(text.starts_with("tick 0 closed: 2 cells, 2 acts, 0 refused +"), "{text}"); + assert!(text.contains(&format!( + " + Adrasteia attack [{}] target=Brannoch says \"Adrasteia strikes.\" +", + name("attack") + )), "{text}"); + assert!(text.contains(&format!( + " + Brannoch speak [{}] says \"Brannoch answers.\" +", + name("speak") + )), "{text}"); + assert!(text.ends_with(&format!( + " tokens: {} this tick, {} spent, {} remaining +", + checkpoint.tokens, reports[0].spent, reports[0].remaining + )), "{text}"); + let speak = acts.iter().find(|act| act.verb == "speak").unwrap(); + assert_eq!(speak.speaker_label, "Brannoch"); + assert_eq!( + speak.render_path, + Some(catalog.grammar.verb("speak").unwrap().render_path) + ); + assert!(speak.roles.is_empty()); +} + +#[tokio::test] +async fn the_opportunity_door_answers_what_a_snapshot_carries() { + let (_dir, verse) = Harness::fresh().await; + let snapshot = verse.mailbox.snapshot().await.unwrap(); + assert_eq!(snapshot.opportunities.len(), 2); + assert_eq!( + verse.mailbox.opportunities().await.unwrap(), + snapshot.opportunities + ); +} + +#[tokio::test] +async fn a_cell_is_run_on_what_the_world_holds_for_its_members_now() { + let (_dir, verse) = Harness::fresh().await; + let opportunities = verse.mailbox.opportunities().await.unwrap(); + let graph = verse.mailbox.agency_graph().await.unwrap(); + let world = verse.mailbox.snapshot().await.unwrap().world_id; + let singles = derive_cover( + world, + FictionalMinutes(0), + SPAN, + &opportunities, + &graph, + two_cells(), + ); + let group = derive_cover( + world, + FictionalMinutes(0), + SPAN, + &opportunities, + &graph, + CoverBudget { + cells: 1, + constituent_cap: 8, + urgency_slots: 0, + }, + ); + let [grouped @ Cell::Group { members, .. }] = group.cells.as_slice() else { + panic!("one cell for two subjects is a group") + }; + assert_eq!(members.len(), 2); + + // Changed opportunities replace the ones the cover held. + let mut moved = opportunities.clone(); + for opportunity in &mut moved { + opportunity.revision += 1; + } + for cell in &singles.cells { + let Cell::Singleton { member: held, .. } = cell else { + panic!("two subjects under two cells are singletons") + }; + let Some(Cell::Singleton { member, .. }) = refreshed(cell, &moved) else { + panic!("a subject that still has an opportunity keeps its cell") + }; + assert_ne!(member.opportunity, held.opportunity); + assert!(moved.contains(&member.opportunity)); + } + let Some(Cell::Group { members: now, .. }) = refreshed(grouped, &moved) else { + panic!("a group keeps its members") + }; + assert_eq!(now.len(), 2); + assert!(now.iter().all(|member| moved.contains(&member.opportunity))); + + // A subject with no opportunity leaves its cell, and an empty cell is gone. + let one = &opportunities[..1]; + let Some(Cell::Group { members: left, .. }) = refreshed(grouped, one) else { + panic!("one member remains") + }; + assert_eq!(left.len(), 1); + assert_eq!(left[0].opportunity.scope, one[0].scope); + let gone = singles + .cells + .iter() + .filter(|cell| refreshed(cell, one).is_none()) + .count(); + assert_eq!(gone, 1); + assert!(refreshed(grouped, &[]).is_none()); +} + +#[test] +fn an_error_ends_a_cell_as_the_run_must_treat_it() { + let budget = ControllerError::Inference { + purpose: InferencePurpose::OperationalAgent, + source: InferenceFault::budget_exhausted(), + }; + assert!(matches!(classify(&budget), CellEnd::Budget)); + // Any other fault that stops the cognition organ stops the run. + let corrupted = ControllerError::Inference { + purpose: InferencePurpose::OperationalAgent, + source: InferenceFault::integrity_violation("the reply cannot be trusted"), + }; + assert!(matches!( + classify(&corrupted), + CellEnd::Fatal("controller_quarantined") + )); + assert!(matches!( + classify(&ControllerError::Serialization("x".into())), + CellEnd::Fatal("controller_quarantined") + )); + // What the world or the subject's standing refused stays with its cell. + assert!(matches!( + classify(&ControllerError::World(KernelError::AffordanceDenied)), + CellEnd::Refused(RefusalReason::WorldRejected) + )); + for gone in [ + ControllerError::NoOpportunity { + expected: ControllerMode::OperationalAgent, + }, + ControllerError::AmbiguousOpportunity, + ControllerError::OpportunityMismatch, + ] { + assert!(matches!( + classify(&gone), + CellEnd::Refused(RefusalReason::OpportunityGone) + )); + } + assert!(matches!( + classify(&ControllerError::CommandMismatch), + CellEnd::Fatal("controller_error") + )); +} + +#[tokio::test] +async fn a_port_opened_for_another_run_is_refused_before_anything_is_written() { + let (_dir, verse) = Harness::fresh().await; + let world = verse.mailbox.snapshot().await.unwrap(); + let port = Arc::new( + RecordingInferencePort::open( + ScriptedPort::speaking(), + verse.calls.clone(), + call_run_id(7), + 1_000, + &RunStart::of(&world), + ) + .unwrap(), + ); + let runner = ControllerRunner::open( + verse.mailbox.clone(), + port.clone(), + verse.work.clone(), + models(), + ) + .unwrap(); + let error = run_manual( + &verse.mailbox, + &runner, + &port, + &verse.runs, + &config(1), + 1, + |_| ControlFlow::Continue(()), + ) + .await + .unwrap_err(); + assert!(matches!(error, VerseRunError::PortNotThisRun)); + assert!(verse.runs.runs(world.world_id).unwrap().is_empty()); + + // A cover budget with no cells is refused before the record exists. + let mut bad = config(1); + bad.cover.cells = 0; + let own = Arc::new( + RecordingInferencePort::open( + ScriptedPort::speaking(), + verse.calls.clone(), + call_run_id(1), + 1_000, + &RunStart::of(&world), + ) + .unwrap(), + ); + let error = run_manual(&verse.mailbox, &runner, &own, &verse.runs, &bad, 1, |_| { + ControlFlow::Continue(()) + }) + .await + .unwrap_err(); + assert!(matches!( + error, + VerseRunError::Budget(CoverBudgetError::NoCells) + )); + assert!(verse.runs.runs(world.world_id).unwrap().is_empty()); +} + +fn record(world: WorldId, sequence: u64) -> VerseRunRecord { + VerseRunRecord { + world_id: world, + sequence, + token_cap: 10, + ticks_requested: 1, + tick_span_minutes: SPAN, + cover_budget: RecordedCoverBudget { + cells: 2, + constituent_cap: 8, + urgency_slots: 0, + }, + start_revision: 0, + checkpoints: Vec::new(), + status: RunStatus::Running, + } +} + +#[test] +fn the_run_store_numbers_runs_per_world_and_replaces_a_run_with_its_later_state() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("runs.cc"); + let store = VerseRunStore::open(&path).unwrap(); + let one = WorldId::nil_for_test(); + let other = WorldId::issue(); + assert_eq!(store.next_sequence(one).unwrap(), 1); + + // A run can only begin as the next in its world. + assert!(matches!( + store.save(&record(one, 2)), + Err(VerseRunError::OutOfSequence) + )); + assert!(matches!( + store.save(&record(one, 0)), + Err(VerseRunError::OutOfSequence) + )); + store.save(&record(one, 1)).unwrap(); + assert_eq!(store.next_sequence(one).unwrap(), 2); + assert_eq!( + store.next_sequence(other).unwrap(), + 1, + "sequences are per world" + ); + + // Saving a run again replaces it, and the file reopens to the same rows. + let mut finished = record(one, 1); + finished.status = RunStatus::Completed; + store.save(&finished).unwrap(); + store.save(&record(one, 2)).unwrap(); + store.save(&record(other, 1)).unwrap(); + drop(store); + let store = VerseRunStore::open(&path).unwrap(); + assert_eq!(store.runs(one).unwrap(), vec![finished, record(one, 2)]); + assert_eq!(store.runs(other).unwrap(), vec![record(other, 1)]); +} + +#[test] +fn the_run_store_refuses_rows_that_are_not_canonical_run_records() { + let dir = tempfile::tempdir().unwrap(); + let world = WorldId::nil_for_test(); + let good = record(world, 1); + let envelope = |key: String, schema: &str, payload: Vec| CultCacheEnvelope { + key, + r#type: RUN_ROW.into(), + payload, + stored_at: Utc::now().to_rfc3339(), + schema_id: Some(schema.into()), + }; + let named = rmp_serde::to_vec_named(&good).unwrap(); + let cases = [ + // Another schema version is not migrated. + envelope(row_key(world, 1), "ghostlight.verse_run.v2", named.clone()), + // A row under a key that is not its own. + envelope(row_key(world, 9), RUN_RECORD_SCHEMA, named.clone()), + // A payload that is not the record. + envelope(row_key(world, 1), RUN_RECORD_SCHEMA, vec![0xc0]), + // The record in a non-canonical encoding. + envelope( + row_key(world, 1), + RUN_RECORD_SCHEMA, + rmp_serde::to_vec(&good).unwrap(), + ), + // A sequence of zero. + envelope( + row_key(world, 0), + RUN_RECORD_SCHEMA, + rmp_serde::to_vec_named(&record(world, 0)).unwrap(), + ), + ]; + for (index, row) in cases.into_iter().enumerate() { + let file = dir.path().join(format!("case-{index}.cc")); + { + let mut raw = OwnedRedbMessagePackBackingStore::new(&file).unwrap(); + raw.push(&row).unwrap(); + } + assert!( + matches!(VerseRunStore::open(&file), Err(VerseRunError::Corrupt)), + "case {index} was accepted" + ); + } +}