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 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-10-11 08:58:20 +02:00
commit 2daa80e159
12 changed files with 2371 additions and 9 deletions

12
Cargo.lock generated
View file

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

View file

@ -3,6 +3,7 @@ members = [
"crates/ghostlight",
"crates/ghostlight-dungeon",
"crates/ghostlight-persona-projection",
"crates/ghostlight-verse",
]
resolver = "2"

View file

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

View file

@ -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<String> = 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<String>) -> Result<ExitCode> {
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<Self> {
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<T: std::str::FromStr + PartialOrd + Default>(&self, name: &str) -> Result<T> {
match self.text(name).parse::<T>() {
Ok(value) if value > T::default() => Ok(value),
_ => bail!("--{name} is not a positive integer"),
}
}
}
async fn genesis(flags: Flags) -> Result<ExitCode> {
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<ExitCode> {
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<Arc<dyn ghostlight::InferencePort>> {
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://<address>:<port>")?;
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")
}

View file

@ -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<AtomicUsize>,
}
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::<usize>().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}");
}
}

View file

@ -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<Item = &WorldCommit> {
self.commits.values()
}
#[cfg(test)]
pub(super) fn commit_count(&self) -> usize {
self.commits.len()

View file

@ -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<Statement>,
pub display: Option<Statement>,
/// 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<RenderPath>,
/// What the act bound each of the verb's roles to, in the invocation's
/// order.
pub roles: Vec<BoundRole>,
}
/// 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<Vec<OperatorEvent>, 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<EventId, &DecisionInvocation> = 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<Vec<DecisionOpportunity>, 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<Vec<OperatorEvent>, KernelError> {
fn operator_log(
state: &WorldState,
invocations: &BTreeMap<EventId, &DecisionInvocation>,
) -> Result<Vec<OperatorEvent>, KernelError> {
state
.events
.iter()
@ -3749,6 +3793,30 @@ fn operator_log(state: &WorldState) -> Result<Vec<OperatorEvent>, 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::<Result<Vec<_>, _>>()?;
Ok(OperatorEvent {
revision: event.revision,
speaker: event.scope.subject_id,
@ -3761,6 +3829,13 @@ fn operator_log(state: &WorldState) -> Result<Vec<OperatorEvent>, 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.

View file

@ -82,6 +82,11 @@ enum Request {
AgencyGraph {
reply: oneshot::Sender<Result<AgencyGraph, KernelError>>,
},
/// 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<Result<Vec<DecisionOpportunity>, 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<Vec<DecisionOpportunity>, 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<Vec<OperatorEvent>, MailboxError> {
let (reply, response) = oneshot::channel();
self.sender
@ -955,6 +975,19 @@ async fn run_owner(mut owned: OwnedWorld, mut receiver: mpsc::Receiver<Request>)
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,

View file

@ -256,7 +256,7 @@ enum DecodedRow {
Ledger(RunLedger),
}
fn canonical<T: Serialize + for<'de> Deserialize<'de>>(
pub(super) fn canonical<T: Serialize + for<'de> Deserialize<'de>>(
row: &CultCacheEnvelope,
) -> Result<T, CallRecordError> {
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)

View file

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

View file

@ -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<CommandId>,
pub refusals: Vec<Refusal>,
/// 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<TickCheckpoint>,
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<OperatorEvent>,
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<OwnedRedbMessagePackBackingStore>,
}
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<Path>) -> Result<Self, VerseRunError> {
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<Vec<VerseRunRecord>, 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<u64, VerseRunError> {
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<Vec<VerseRunRecord>, 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<CommandId>,
refusals: &mut Vec<Refusal>,
) -> 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<Cell> {
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<Constituent> = 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<RunOutcome, VerseRunError> {
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<TickReport>) {
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<RunStatus> = 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;

View file

@ -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<dyn Fn(&str) -> Vec<InferenceEvent> + Send + Sync>,
faults: std::sync::Mutex<VecDeque<InferenceFault>>,
bounds: std::sync::Mutex<Vec<u64>>,
calls: AtomicUsize,
}
impl ScriptedPort {
fn new(reply: impl Fn(&str) -> Vec<InferenceEvent> + Send + Sync + 'static) -> Arc<Self> {
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> {
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<u64> {
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, InferenceFault> {
PreparedInference::prepare("verse-run-test", 4_102_444_800_000, request)
}
async fn infer(&self, request: PreparedInference) -> Result<InferenceOutput, InferenceFault> {
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<CallRecordStore>,
runs: VerseRunStore,
work: Arc<dyn ControllerWorkStore>,
}
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<dyn InferencePort>,
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<dyn InferencePort>, 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<u64> = 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<CommandId> = 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<u64> = 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<u64> = 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<String> = [
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<u8>| 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"
);
}
}