Record the lens and its text on the session; adopt rows by answer (L1 Cut 3)

A new elaborator session draws its lens and authors its instruction text
once, and the checkpoint row carries both from then on. A resume reads the
row's session instead of demanding the fresh derivation equal it.

Session:
- `ElaboratorSession` gains `lens: Lens` and `instructions: String`
  (`deny_unknown_fields` kept).
- `select_answer` derives the command id from world, jurisdiction and
  answer digest, draws `lens::draw(snapshot.lens_weights, world, id)`, and
  authors `lens.instructions()`. It returns the id with the session, and
  `step` uses that id instead of deriving it a second time.
- `session_command_id` takes the three identity fields instead of a session,
  because the lens is drawn from the id and so the id exists before the
  session does. The derivation bytes are unchanged: the Cut 0 id
  `56dbcdb2-9337-ac07-f322-37376b58cbcb` is pinned in
  `a_session_identity_is_derived_from_its_answer`.
- `ELABORATION_INSTRUCTIONS` moves into `lens.rs` as a private constant.
  `elaboration_request` takes the text, and `step`, `persist_repair` and
  `integrity_is_valid` pass `session.instructions`. Integrity binds the
  stored invocation to the stored text, not to code (L1-Q7 (a)).

Adoption rule (L1-Q9, boundary half): the whole-session supersession
equality in `step` is deleted. A found row is this answer's row when world,
jurisdiction, answer and answer digest match (`same_answer`). Its session,
including ancestry, lens and text, replaces the fresh one. A boundary session
is no longer `Superseded` forever after an unrelated commit.
`valid_elaboration_progression` is unchanged and still compares whole
sessions row to row; the doc comments on both rules say why they differ.

Store: `controller_work.v15` -> `v16`; v15 rows are refused at open, not
migrated. The world ontology doc names v16.

Tests (controllers): `a_boundary_session_resumes_after_an_unrelated_commit`
(at 1a402e1 it reported Superseded),
`a_resumed_session_keeps_its_recorded_lens_when_the_weights_change`,
`a_checkpoint_that_changes_the_lens_or_its_text_is_an_illegal_transition`,
`a_row_whose_text_and_invocation_disagree_is_refused_at_open`,
`a_controller_work_row_from_v15_is_refused_at_open`,
`soul_the_same_patch_admits_the_same_under_every_lens` (pinned to the
Cut 0 mismatch JSON), and `the_catalog_takes_no_lens`. The single-dead-end
fixture now delegates to `dead_end_mailbox(weights, dead_ends)`, which builds
the first dead end with the same handles and labels as before.

Builds, but with two "this lint expectation is unfulfilled" warnings from
the `expect(dead_code)` markers on `Lens::instructions` and `lens::draw`. The
next commit removes those markers (c1.s1.f3).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-09-16 16:07:25 +02:00
commit 18b1098c3f
4 changed files with 886 additions and 95 deletions

View file

@ -74,8 +74,8 @@ pub(super) const CELL_TOOL_STEP_BUDGET: usize = 2;
/// carried by tool identity, never by a model-written argument.
const HANDLE_SEPARATOR: &str = "__";
const PERSONA_WORD_BUDGET: usize = 180;
const CONTROLLER_WORK_ROW: &str = "controller_work.v15";
const CONTROLLER_WORK_SCHEMA: &str = "ghostlight.controller_work.v15";
const CONTROLLER_WORK_ROW: &str = "controller_work.v16";
const CONTROLLER_WORK_SCHEMA: &str = "ghostlight.controller_work.v16";
/// The Interpreter's byte-span capture tool. It is not the generated `speak`
/// affordance tool: one captures an utterance out of preserved prose, the other
@ -6376,7 +6376,8 @@ mod tests {
}
}
use super::*;
use crate::elaboration::{EvidenceError, EvidenceQuery, EvidenceReceipt};
use crate::elaboration::{ElaboratorSession, EvidenceError, EvidenceQuery, EvidenceReceipt};
use crate::{CausalBoundary, Lens, LensWeights};
use crate::patch::{RECORD_GAP_PATCH_TOOL, kernel_speak_entry, kernel_speak_grant};
use crate::{
CommitmentKind, CoverBudget, CreateJurisdictionIntent, CreateWorldIntent,
@ -9410,50 +9411,73 @@ mod tests {
tokio::task::JoinHandle<()>,
EntityId,
EntityId,
) {
let (directory, mailbox, task, commons, roads) =
dead_end_mailbox(crate::tests::stock_weights(), &["The Unwalked Road"]).await;
(directory, mailbox, task, commons, roads[0])
}
/// An Active world under the given lens weights, with one dead end per
/// label: each a place inside an inhabited commons, reached by its own
/// route and holding nothing. The roads come back in label order.
async fn dead_end_mailbox(
lens_weights: LensWeights,
dead_ends: &[&str],
) -> (
tempfile::TempDir,
WorldMailbox,
tokio::task::JoinHandle<()>,
EntityId,
Vec<EntityId>,
) {
let directory = tempfile::tempdir().unwrap();
let (mailbox, task) = WorldMailbox::open(directory.path().join("world.cc")).unwrap();
let owner = PrincipalId::new("owner");
let authenticated = AuthenticatedCaller::fixture(CallerId::Principal(owner.clone()));
let mut declarations = vec![Declaration::Entity(EntityDeclaration {
handle: DraftHandle::new("commons"),
label: "The Commons".into(),
kind: EntityKind::Place,
container: None,
})];
for (index, label) in dead_ends.iter().enumerate() {
// The first dead end keeps the single-road fixture's own handles
// and route label.
let suffix = if index == 0 { String::new() } else { format!("_{index}") };
let road = DraftHandle::new(&format!("road{suffix}"));
declarations.push(Declaration::Entity(EntityDeclaration {
handle: road.clone(),
label: (*label).into(),
kind: EntityKind::Place,
container: Some(Ref::Draft(DraftHandle::new("commons"))),
}));
declarations.push(Declaration::Route(crate::RouteDeclaration {
handle: DraftHandle::new(&format!("lane{suffix}")),
label: format!("The Long Lane{suffix}"),
from: Ref::Draft(DraftHandle::new("commons")),
to: Ref::Draft(road),
access: crate::AccessKind::Public,
cost: Cost(1),
}));
}
declarations.push(Declaration::Subject(SubjectDeclaration {
handle: DraftHandle::new("subject"),
label: "Subject".into(),
kind: SubjectKind::Person,
controller: NewController::NarrativePersona,
affordances: kernel_speak_grant(),
position: Some(Ref::Draft(DraftHandle::new("commons"))),
}));
let creation = mailbox
.create_fixture(
CreateWorld {
lens_weights: crate::tests::stock_weights(),
lens_weights,
id: CommandId::new(),
owner: owner.clone(),
title: "Elaboration Fixture".into(),
brief: String::new(),
patch: WorldPatch {
declarations: vec![
Declaration::Entity(EntityDeclaration {
handle: DraftHandle::new("commons"),
label: "The Commons".into(),
kind: EntityKind::Place,
container: None,
}),
Declaration::Entity(EntityDeclaration {
handle: DraftHandle::new("road"),
label: "The Unwalked Road".into(),
kind: EntityKind::Place,
container: Some(Ref::Draft(DraftHandle::new("commons"))),
}),
Declaration::Route(crate::RouteDeclaration {
handle: DraftHandle::new("lane"),
label: "The Long Lane".into(),
from: Ref::Draft(DraftHandle::new("commons")),
to: Ref::Draft(DraftHandle::new("road")),
access: crate::AccessKind::Public,
cost: Cost(1),
}),
Declaration::Subject(SubjectDeclaration {
handle: DraftHandle::new("subject"),
label: "Subject".into(),
kind: SubjectKind::Person,
controller: NewController::NarrativePersona,
affordances: kernel_speak_grant(),
position: Some(Ref::Draft(DraftHandle::new("commons"))),
}),
],
declarations,
operations: Vec::new(),
evidence: Vec::new(),
},
@ -9489,9 +9513,14 @@ mod tests {
.expect("the declared place")
.id
};
let (commons, road) = (place("The Commons"), place("The Unwalked Road"));
assert_eq!(snapshot.boundaries.len(), 1, "one dead end, and only one");
(directory, mailbox, task, commons, road)
let commons = place("The Commons");
let roads = dead_ends.iter().map(|label| place(label)).collect();
assert_eq!(
snapshot.boundaries.len(),
dead_ends.len(),
"one boundary per dead end, and no other"
);
(directory, mailbox, task, commons, roads)
}
/// Spec test 20, which the pass wired and did not write. Round one submits a
@ -9642,6 +9671,668 @@ mod tests {
task.await.unwrap();
}
/// Round one declares a shed inside a handle nothing declares and submits,
/// which the kernel refuses; round two declares the same shed on the road
/// and submits, which commits.
fn shed_script(road: EntityId) -> Arc<ElaborationScript> {
let road_id = serde_json::to_value(road).unwrap();
let shed = |container: Value| {
vec![
(
"declare_place",
json!({
"handle": "shed",
"label": "The Roadside Shed",
"container": container,
}),
),
("submit", json!({})),
]
};
Arc::new(ElaborationScript {
outputs: Mutex::new(vec![
tool_round(
shed(json!({"ref": "draft", "value": "nowhere"})),
"elaboration-round-zero",
),
tool_round(
shed(json!({"ref": "existing", "value": road_id})),
"elaboration-round-one",
),
]),
seen: Mutex::new(Vec::new()),
})
}
/// A model that has nothing to add, for as many rounds as a session has.
fn idle_script() -> Arc<ElaborationScript> {
Arc::new(ElaborationScript {
outputs: Mutex::new(
(0..crate::elaboration::ELABORATION_ROUND_BUDGET)
.map(|round| {
output(
vec![InferenceEvent::Text("nothing to add".into())],
&format!("idle-{round}"),
)
})
.collect(),
),
seen: Mutex::new(Vec::new()),
})
}
fn elaboration_runner(
mailbox: &WorldMailbox,
script: Arc<ElaborationScript>,
store: Arc<dyn ControllerWorkStore>,
) -> ElaborationRunner {
ElaborationRunner::new(
ElaborationPort::new(mailbox.clone()),
script,
Arc::new(NullEvidenceSource),
store,
models().elaborator,
)
}
/// The session a checkpoint carries, whatever its stage.
fn recorded_session(work: &ControllerWork) -> ElaboratorSession {
let ControllerWork::Elaboration(
ElaborationCheckpoint::ElaboratorInFlight { session, .. }
| ElaborationCheckpoint::ReadyToSubmit { session, .. }
| ElaborationCheckpoint::NoPatch { session, .. },
) = work
else {
panic!("not an elaboration checkpoint: {work:?}");
};
session.clone()
}
/// Every stock lens named, the given one at one and the rest at zero.
fn only(lens: Lens) -> LensWeights {
LensWeights::new(
Lens::ALL
.into_iter()
.map(|each| (each, u32::from(each == lens)))
.collect(),
)
}
fn owner_command(snapshot: &WorldSnapshot, body: CommandBody) -> CommandEnvelope {
CommandEnvelope {
id: CommandId::new(),
world_id: snapshot.world_id,
expected_revision: snapshot.revision,
caller: CallerId::Principal(PrincipalId::new("owner")),
body,
}
}
fn owner_caller() -> AuthenticatedCaller {
AuthenticatedCaller::fixture(CallerId::Principal(PrincipalId::new("owner")))
}
/// A real refused-and-reopened elaboration checkpoint: round one refused,
/// its refusal recorded, the repair invocation prepared. Taken from a run,
/// not assembled by hand.
async fn refused_checkpoint() -> ElaborationCheckpoint {
let (_directory, mailbox, task, commons, road) = elaboration_mailbox().await;
let store = fresh_store();
let runner = elaboration_runner(&mailbox, shed_script(road), store.clone());
assert_eq!(
runner
.step(JurisdictionKey::PlaceSubtree(commons))
.await
.unwrap(),
crate::elaboration::ElaborationOutcome::Rejected
);
drop(runner);
drop(mailbox);
task.await.unwrap();
let stored = store.work.lock().unwrap();
let ControllerWork::Elaboration(
checkpoint @ ElaborationCheckpoint::ElaboratorInFlight { .. },
) = stored.values().next().unwrap().clone()
else {
panic!("the refusal did not reopen the session");
};
checkpoint
}
/// Pushes one raw row into a fresh store file under the given row type and
/// schema, then opens it.
fn open_with_raw_row(
directory: &tempfile::TempDir,
name: &str,
checkpoint: &ElaborationCheckpoint,
row_type: &str,
schema: &str,
) -> Result<CultCacheControllerWorkStore, ControllerWorkStoreError> {
let path = directory.path().join(name);
{
let mut store = OwnedRedbMessagePackBackingStore::new(&path).unwrap();
store
.push(&CultCacheEnvelope {
key: store_key(checkpoint.command_id()).unwrap(),
r#type: row_type.into(),
payload: rmp_serde::to_vec_named(&ControllerWork::Elaboration(
checkpoint.clone(),
))
.unwrap(),
stored_at: Utc::now().to_rfc3339(),
schema_id: Some(schema.into()),
})
.unwrap();
}
CultCacheControllerWorkStore::open(&path)
}
/// The same in-flight checkpoint with its session's text replaced and its
/// invocation prepared under `request_text`.
fn with_texts(
checkpoint: &ElaborationCheckpoint,
stored_text: &str,
request_text: &str,
) -> ElaborationCheckpoint {
let ElaborationCheckpoint::ElaboratorInFlight {
command_id,
session,
agent_prompt,
refusals,
completed,
invocation,
} = checkpoint.clone()
else {
panic!("not in flight");
};
let request = crate::elaboration::elaboration_request(
command_id,
completed.len(),
&invocation.invocation.request.model,
request_text,
invocation.invocation.request.input.clone(),
)
.unwrap();
ElaborationCheckpoint::ElaboratorInFlight {
command_id,
session: ElaboratorSession {
instructions: stored_text.into(),
..session
},
agent_prompt,
refusals,
completed,
invocation: PreparedInference::prepare(
"ghostlight-controller-test",
4_102_444_800_000,
request,
)
.unwrap(),
}
}
/// Probe 3's boundary half, kept. A refused boundary session is persisted;
/// an unrelated commit moves the world's last commit digest; a fresh runner
/// over the reopened store resumes the same row, repairs from the refusal it
/// earned, and commits under the same command id. The world moving is not
/// the answer moving, so the row is adopted rather than reported
/// `Superseded`.
#[tokio::test]
async fn a_boundary_session_resumes_after_an_unrelated_commit() {
let (directory, mailbox, task, commons, road) = elaboration_mailbox().await;
let jurisdiction = JurisdictionKey::PlaceSubtree(commons);
let path = directory.path().join("controller-work.cc");
let script = shed_script(road);
let store = Arc::new(CultCacheControllerWorkStore::open(&path).unwrap());
let first = elaboration_runner(&mailbox, script.clone(), store.clone());
assert_eq!(
first.step(jurisdiction).await.unwrap(),
crate::elaboration::ElaborationOutcome::Rejected
);
drop(first);
drop(store);
let before = mailbox.snapshot().await.unwrap().last_commit_digest;
mailbox
.submit_clock(CommandId::new(), TickMinutes::new(60).unwrap())
.await
.unwrap();
assert_ne!(
mailbox.snapshot().await.unwrap().last_commit_digest,
before,
"the unrelated commit did not move the ancestry"
);
let store = Arc::new(CultCacheControllerWorkStore::open(&path).unwrap());
let (command_id, recorded) = {
let journal = store.journal.lock().unwrap();
assert_eq!(journal.work.len(), 1);
let (id, work) = journal.work.iter().next().unwrap();
(*id, recorded_session(work))
};
assert_eq!(Some(recorded.ancestry.clone()), before);
let second = elaboration_runner(&mailbox, script.clone(), store.clone());
assert_eq!(
second.step(jurisdiction).await.unwrap(),
crate::elaboration::ElaborationOutcome::Committed,
"the world moving superseded the boundary's session"
);
{
let journal = store.journal.lock().unwrap();
assert_eq!(journal.work.len(), 1, "the resume opened a second row");
let work = journal.work.get(&command_id).expect("the same command id");
assert_eq!(recorded_session(work), recorded, "the resume rewrote the session");
}
let seen = script.seen.lock().unwrap();
assert_eq!(seen.len(), 2, "the resume repeated or skipped an inference");
let second_wire = serde_json::to_string(&seen[1].invocation.request.input).unwrap();
assert!(
second_wire.contains("The world refused the patch you submitted"),
"the resumed round lost the refusal it earned"
);
assert!(mailbox.snapshot().await.unwrap().boundaries.is_empty());
drop(seen);
drop(second);
drop(mailbox);
task.await.unwrap();
}
/// A session records the lens it drew and keeps it. The world draws only
/// Patina; round one is refused and persisted; the owner then moves every
/// weight to Numen, which is also a commit, so the ancestry moves too; the
/// store is reopened and a fresh runner resumes the same row and commits
/// under the same command id, with the lens, text and ancestry the row
/// recorded, and the repair invocation still carries Patina's text and the
/// refusal. The world's second dead end then starts a new session, which
/// draws from the weights as they now are.
#[tokio::test]
async fn a_resumed_session_keeps_its_recorded_lens_when_the_weights_change() {
let (directory, mailbox, task, commons, roads) = dead_end_mailbox(
only(Lens::Patina),
&["The Unwalked Road", "The Far Road"],
)
.await;
let jurisdiction = JurisdictionKey::PlaceSubtree(commons);
let path = directory.path().join("controller-work.cc");
let snapshot = mailbox.snapshot().await.unwrap();
let answered = match snapshot.boundaries.first() {
Some(CausalBoundary::UnelaboratedDestination { place, .. }) => *place,
other => panic!("the first boundary is not a dead end: {other:?}"),
};
assert!(roads.contains(&answered));
let script = shed_script(answered);
let store = Arc::new(CultCacheControllerWorkStore::open(&path).unwrap());
let first = elaboration_runner(&mailbox, script.clone(), store.clone());
assert_eq!(
first.step(jurisdiction).await.unwrap(),
crate::elaboration::ElaborationOutcome::Rejected
);
drop(first);
let (command_id, recorded) = {
let journal = store.journal.lock().unwrap();
let (id, work) = journal.work.iter().next().unwrap();
(*id, recorded_session(work))
};
assert_eq!(recorded.lens, Lens::Patina);
assert_eq!(recorded.instructions, Lens::Patina.instructions());
drop(store);
let before = mailbox.snapshot().await.unwrap();
mailbox
.submit_fixture(
owner_command(
&before,
CommandBody::SetLensWeights {
weights: only(Lens::Numen),
},
),
&owner_caller(),
)
.await
.unwrap();
let after = mailbox.snapshot().await.unwrap();
assert_eq!(after.lens_weights, only(Lens::Numen));
assert_ne!(after.last_commit_digest, before.last_commit_digest);
let store = Arc::new(CultCacheControllerWorkStore::open(&path).unwrap());
let second = elaboration_runner(&mailbox, script.clone(), store.clone());
assert_eq!(
second.step(jurisdiction).await.unwrap(),
crate::elaboration::ElaborationOutcome::Committed
);
drop(second);
{
let journal = store.journal.lock().unwrap();
assert_eq!(journal.work.len(), 1, "the resume opened a second row");
let work = journal.work.get(&command_id).expect("the same command id");
let resumed = recorded_session(work);
assert_eq!(resumed.lens, Lens::Patina, "the resume redrew the lens");
assert_eq!(resumed.instructions, Lens::Patina.instructions());
assert_eq!(resumed, recorded);
}
{
let seen = script.seen.lock().unwrap();
assert_eq!(seen.len(), 2);
for invocation in seen.iter() {
assert_eq!(
invocation.invocation.request.instructions,
Lens::Patina.instructions()
);
}
let repair = serde_json::to_string(&seen[1].invocation.request.input).unwrap();
assert!(repair.contains("The world refused the patch you submitted"));
}
// The remaining dead end is a different answer and a new session.
let remaining = mailbox.snapshot().await.unwrap();
assert_eq!(remaining.boundaries.len(), 1, "the answered dead end survived");
let idle = idle_script();
let third = elaboration_runner(&mailbox, idle.clone(), store.clone());
third.step(jurisdiction).await.unwrap();
drop(third);
{
let journal = store.journal.lock().unwrap();
assert_eq!(journal.work.len(), 2);
let (_, work) = journal
.work
.iter()
.find(|(id, _)| **id != command_id)
.unwrap();
let fresh = recorded_session(work);
assert_eq!(fresh.lens, Lens::Numen);
assert_eq!(fresh.instructions, Lens::Numen.instructions());
}
assert_eq!(
idle.seen.lock().unwrap()[0].invocation.request.instructions,
Lens::Numen.instructions()
);
drop(store);
drop(mailbox);
task.await.unwrap();
}
/// Row to row, a session is whole: from a persisted in-flight checkpoint,
/// a next checkpoint that differs only in the lens, only in the text (with
/// its invocation prepared under that text, so integrity passes and the
/// refusal is progression's), or only in the ancestry is refused by the
/// real store as an illegal transition. The unchanged checkpoint is
/// accepted as already present, so the refusals are not an inert harness.
#[tokio::test]
async fn a_checkpoint_that_changes_the_lens_or_its_text_is_an_illegal_transition() {
let checkpoint = refused_checkpoint().await;
let directory = tempfile::tempdir().unwrap();
let store = CultCacheControllerWorkStore::open(directory.path().join("work.cc")).unwrap();
let ElaborationCheckpoint::ElaboratorInFlight {
command_id,
session,
agent_prompt,
invocation,
..
} = checkpoint.clone()
else {
unreachable!();
};
// The row enters the store through its initial stage, as a session's
// does: no rounds, and the round-zero invocation over the prompt alone.
let request = crate::elaboration::elaboration_request(
command_id,
0,
&invocation.invocation.request.model,
&session.instructions,
vec![CodexInputItem::UserText {
text: agent_prompt.clone(),
}],
)
.unwrap();
let initial = ElaborationCheckpoint::ElaboratorInFlight {
command_id,
session,
agent_prompt,
refusals: Vec::new(),
completed: Vec::new(),
invocation: PreparedInference::prepare(
"ghostlight-controller-test",
4_102_444_800_000,
request,
)
.unwrap(),
};
assert!(initial.integrity_is_valid());
for work in [&initial, &checkpoint] {
store
.persist(&ControllerWork::Elaboration(work.clone()))
.await
.expect("the session's own rows progress");
}
assert_eq!(
store
.persist(&ControllerWork::Elaboration(checkpoint.clone()))
.await
.unwrap(),
ControllerWorkWrite::AlreadyPresent
);
let rewrite = |change: &dyn Fn(&mut ElaboratorSession)| {
let ElaborationCheckpoint::ElaboratorInFlight {
command_id,
mut session,
agent_prompt,
refusals,
completed,
invocation,
} = checkpoint.clone()
else {
unreachable!();
};
change(&mut session);
ElaborationCheckpoint::ElaboratorInFlight {
command_id,
session,
agent_prompt,
refusals,
completed,
invocation,
}
};
let lens = rewrite(&|session| session.lens = Lens::Numen);
let text = with_texts(
&checkpoint,
"text a later build wrote",
"text a later build wrote",
);
let ancestry = rewrite(&|session| session.ancestry = "sha256:a later commit".into());
for (what, next) in [("lens", lens), ("text", text), ("ancestry", ancestry)] {
assert!(next.integrity_is_valid(), "the {what} rewrite fails integrity");
assert_ne!(next, checkpoint);
let result = store.persist(&ControllerWork::Elaboration(next)).await;
let Err(ControllerWorkStoreError::Fault { detail }) = &result else {
panic!("a checkpoint that changed the {what} was accepted: {result:?}");
};
assert!(
detail.contains("attempted an illegal checkpoint transition"),
"{what}: {detail}"
);
}
let journal = store.journal.lock().unwrap();
assert_eq!(
journal.work.get(&command_id),
Some(&ControllerWork::Elaboration(checkpoint))
);
}
/// Integrity binds the stored invocation to the stored text. A row whose
/// session says one text and whose invocation was prepared under another
/// fails its checkpoint binding at open. A row whose two texts agree on a
/// string no current lens authors opens: that is the trade ruling L1-Q7 (a)
/// makes, stated as a test, so a lens-text edit strands no store.
#[tokio::test]
async fn a_row_whose_text_and_invocation_disagree_is_refused_at_open() {
let checkpoint = refused_checkpoint().await;
let directory = tempfile::tempdir().unwrap();
let disagree = with_texts(&checkpoint, "STORED TEXT A", "REQUEST TEXT B");
let Err(ControllerWorkStoreError::Fault { detail }) = open_with_raw_row(
&directory,
"disagree.cc",
&disagree,
CONTROLLER_WORK_ROW,
CONTROLLER_WORK_SCHEMA,
) else {
panic!("a row whose text and invocation disagree opened");
};
assert!(detail.contains("failed its checkpoint binding"), "{detail}");
let agree = with_texts(&checkpoint, "STORED TEXT A", "STORED TEXT A");
assert!(
Lens::ALL
.into_iter()
.all(|lens| lens.instructions() != "STORED TEXT A")
);
let store = open_with_raw_row(
&directory,
"agree.cc",
&agree,
CONTROLLER_WORK_ROW,
CONTROLLER_WORK_SCHEMA,
)
.expect("a row whose texts agree opens whatever the code now authors");
assert_eq!(
store.lookup(agree.command_id()).await.unwrap(),
ControllerWorkLookup::Confirmed(ControllerWork::Elaboration(agree))
);
}
/// A real lensed in-flight payload under the previous row version is
/// refused at open and not migrated; the same payload under the current
/// version opens, so the refusal is the version's.
#[tokio::test]
async fn a_controller_work_row_from_v15_is_refused_at_open() {
let checkpoint = refused_checkpoint().await;
let directory = tempfile::tempdir().unwrap();
let Err(error) = open_with_raw_row(
&directory,
"v15.cc",
&checkpoint,
"controller_work.v15",
"ghostlight.controller_work.v15",
) else {
panic!("a v15 row was accepted by the {CONTROLLER_WORK_ROW} store");
};
assert!(matches!(error, ControllerWorkStoreError::Fault { .. }));
open_with_raw_row(
&directory,
"current.cc",
&checkpoint,
CONTROLLER_WORK_ROW,
CONTROLLER_WORK_SCHEMA,
)
.expect("the same payload under the current version opens");
}
/// The kernel's refusal of round one's patch, captured before L1 (Cut 0,
/// `base-mismatches.json`).
const BASE_MISMATCHES: &str = r#"[{"mismatch":"unresolved_draft","site":{"site":"declaration","at":"shed"},"referent":"nowhere","expected":{"namespace":"entity","kind":"place"}}]"#;
/// A lens never gates admission. For each stock lens, a world that draws
/// only that lens runs the same two rounds: round one is refused with the
/// mismatch set captured before lenses existed, and round two commits. The
/// eight prompts are byte-equal, because the prompt carries no lens text;
/// the eight instructions are each lens's own and share the one sentence
/// before the lens clause.
#[tokio::test]
async fn soul_the_same_patch_admits_the_same_under_every_lens() {
let mut prompts = BTreeSet::new();
let mut texts = BTreeSet::new();
for lens in Lens::ALL {
let (_directory, mailbox, task, commons, roads) =
dead_end_mailbox(only(lens), &["The Unwalked Road"]).await;
let jurisdiction = JurisdictionKey::PlaceSubtree(commons);
let store = fresh_store();
let script = shed_script(roads[0]);
let first = elaboration_runner(&mailbox, script.clone(), store.clone());
assert_eq!(
first.step(jurisdiction).await.unwrap(),
crate::elaboration::ElaborationOutcome::Rejected,
"{lens:?}"
);
drop(first);
{
let stored = store.work.lock().unwrap();
let ControllerWork::Elaboration(ElaborationCheckpoint::ElaboratorInFlight {
session,
agent_prompt,
refusals,
..
}) = stored.values().next().unwrap()
else {
panic!("{lens:?}: the refusal did not reopen the session");
};
assert_eq!(
serde_json::to_string(&refusals[0].mismatches).unwrap(),
BASE_MISMATCHES,
"{lens:?} changed what the kernel refused"
);
assert_eq!(session.lens, lens);
assert_eq!(session.instructions, lens.instructions());
prompts.insert(agent_prompt.clone());
texts.insert(session.instructions.clone());
}
let second = elaboration_runner(&mailbox, script.clone(), store.clone());
assert_eq!(
second.step(jurisdiction).await.unwrap(),
crate::elaboration::ElaborationOutcome::Committed,
"{lens:?} changed what the kernel admits"
);
drop(second);
assert!(mailbox.snapshot().await.unwrap().boundaries.is_empty());
drop(mailbox);
task.await.unwrap();
}
assert_eq!(prompts.len(), 1, "a lens reached the prompt");
assert_eq!(texts.len(), 8, "two lenses share a text");
let shared = |text: &str| text.split(" Lens: ").next().unwrap().to_owned();
let sentences: BTreeSet<String> = texts.iter().map(|text| shared(text)).collect();
assert_eq!(sentences.len(), 1, "the lenses differ outside their clause");
}
/// The catalog takes no lens, by signature: both renderings are
/// zero-argument functions. The `Tools:` line of a lensed session's prompt
/// is `patch_tool_signatures()` byte for byte, and the tools on its wire
/// are `patch_tools()`.
#[tokio::test]
async fn the_catalog_takes_no_lens() {
let _: fn() -> String = crate::patch::patch_tool_signatures;
let _: fn() -> Vec<CodexToolDefinition> = crate::patch::patch_tools;
let (_directory, mailbox, task, commons, _roads) =
dead_end_mailbox(only(Lens::Numen), &["The Unwalked Road"]).await;
let store = fresh_store();
let idle = idle_script();
let runner = elaboration_runner(&mailbox, idle.clone(), store.clone());
runner
.step(JurisdictionKey::PlaceSubtree(commons))
.await
.unwrap();
drop(runner);
let seen = idle.seen.lock().unwrap();
let first = &seen[0].invocation.request;
assert_eq!(first.instructions, Lens::Numen.instructions());
assert_eq!(first.tools, crate::patch::patch_tools());
let Some(CodexInputItem::UserText { text }) = first.input.first() else {
panic!("the first turn is not the prompt");
};
let tools = text
.lines()
.find_map(|line| line.strip_prefix("Tools: "))
.expect("the prompt names its tools");
assert_eq!(tools, crate::patch::patch_tool_signatures());
drop(seen);
drop(mailbox);
task.await.unwrap();
}
/// A jurisdiction with no boundary and no deficit is the terminating
/// condition, and it spends no inference.
#[tokio::test]

View file

@ -18,6 +18,7 @@ use super::controllers::{
};
#[cfg(test)]
use super::patch::RECORD_GAP_PATCH_TOOL;
use super::lens::{self, Lens};
use super::patch::{self, ComponentOp, FactStandingRef};
use super::patch::{
PATCH_TOOLS, PatchToolShape, SUBMIT_PATCH_TOOL, patch_tool_signatures, patch_tools,
@ -49,9 +50,8 @@ pub(super) const SEED_ROUND_BUDGET: usize = 24;
const ELABORATION_NAMESPACE: &str = "ghostlight.command.elaboration.v1";
pub(super) const ELABORATION_INSTRUCTIONS: &str = "Use only the supplied tools to author structure inside your jurisdiction. Answer the boundary or deficit you were given, then submit. Recording a gap changes nothing.";
/// The answer a session is bound to, plus the ancestry it was built against.
/// The answer a session is bound to, plus the ancestry it was built against,
/// the lens it drew, and the instruction text it was built with.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ElaboratorSession {
@ -63,6 +63,25 @@ pub struct ElaboratorSession {
pub(super) answer_digest: BoundaryDigest,
/// The commit digest the draft is built against.
pub(super) ancestry: String,
/// Drawn once when the session is first built from its command id, recorded
/// here, and never redrawn; a resumed session reads it back.
pub(super) lens: Lens,
/// The instruction text this session was built with, persisted as
/// `agent_prompt` is; integrity binds the stored invocation to this text,
/// not to the code constant.
pub(super) instructions: String,
}
impl ElaboratorSession {
/// Whether two sessions answer the same thing: the fields the command id
/// is derived from, plus the answer they digest. Ancestry, lens and
/// instructions are not identity; they are what a recorded session carries.
fn same_answer(&self, other: &ElaboratorSession) -> bool {
self.world_id == other.world_id
&& self.jurisdiction == other.jurisdiction
&& self.answer == other.answer
&& self.answer_digest == other.answer_digest
}
}
/// The stages one authoring session moves through. The draft is **not** a
@ -135,11 +154,11 @@ impl ElaborationCheckpoint {
match self {
Self::ElaboratorInFlight {
command_id,
session,
agent_prompt,
refusals,
completed,
invocation,
..
} => {
!agent_prompt.is_empty()
&& canonical_model(&invocation.invocation.request.model)
@ -154,6 +173,7 @@ impl ElaborationCheckpoint {
*command_id,
completed.len(),
&invocation.invocation.request.model,
&session.instructions,
conversation,
)
.is_ok_and(|expected| {
@ -197,7 +217,10 @@ impl ElaborationCheckpoint {
}
/// A session may gather more evidence and may end, but it may never rewrite the
/// answer it bound to.
/// answer it bound to, the ancestry it was built against, the lens it drew, or
/// the text it was built with. This compares a row to the row that follows it,
/// so the whole session must be equal; the adoption rule in `step` compares a
/// fresh derivation to a row, and there only the answer's identity must be.
pub(super) fn valid_elaboration_progression(
existing: &ElaborationCheckpoint,
next: &ElaborationCheckpoint,
@ -368,10 +391,10 @@ impl ElaborationRunner {
}
}
/// One answer, start to finish. Session identity is derived, so resumption
/// needs no registry: a boundary that survives a repair keeps its digest and
/// therefore its command id, and a boundary whose digest moved is a
/// different answer with a different id.
/// One answer, start to finish. Session identity is derived, so a crashed
/// loop finds its row again: a boundary that survives a repair keeps its
/// digest and therefore its command id, and a boundary whose digest moved
/// is a different answer with a different id.
pub(super) async fn step(
&self,
jurisdiction: JurisdictionKey,
@ -380,15 +403,14 @@ impl ElaborationRunner {
if snapshot.phase != WorldPhase::Active {
return Ok(ElaborationOutcome::Inactive);
}
let Some(session) = select_answer(&snapshot, jurisdiction)? else {
let Some((command_id, fresh)) = select_answer(&snapshot, jurisdiction)? else {
return Ok(ElaborationOutcome::Clean);
};
let command_id = session_command_id(&session)?;
let receipts = self
.evidence
.retrieve(&EvidenceQuery {
referents: answer_referents(&snapshot, &session.answer),
referents: answer_referents(&snapshot, &fresh.answer),
})
.await
.map_err(|error| ControllerError::WorkPersistence(error.to_string()))?;
@ -397,14 +419,19 @@ impl ElaborationRunner {
.map(|receipt| receipt.reference.clone())
.collect();
let existing = match self.work.lookup(command_id).await? {
ControllerWorkLookup::Missing => None,
// The row is the recorded session. Identity decides whether it is this
// answer's row; everything else about the session is read from it: the
// ancestry, because the world moving is not the answer moving, and the
// lens and its text, because a resume never redraws. The fresh session
// is used only when no row exists.
let (session, existing) = match self.work.lookup(command_id).await? {
ControllerWorkLookup::Missing => (fresh, None),
ControllerWorkLookup::Confirmed(ControllerWork::Elaboration(checkpoint))
| ControllerWorkLookup::CustodyUncertain(ControllerWork::Elaboration(checkpoint)) => {
if checkpoint.session() != &session {
if !checkpoint.session().same_answer(&fresh) {
return Ok(ElaborationOutcome::Superseded);
}
Some(checkpoint)
(checkpoint.session().clone(), Some(checkpoint))
}
ControllerWorkLookup::Confirmed(_) | ControllerWorkLookup::CustodyUncertain(_) => {
return Err(ControllerError::CommandMismatch);
@ -446,6 +473,7 @@ impl ElaborationRunner {
command_id,
completed.len(),
&self.model,
&session.instructions,
conversation,
)?;
let invocation = self.inference.prepare(request).map_err(|source| {
@ -581,7 +609,13 @@ impl ElaborationRunner {
));
}
};
let request = elaboration_request(command_id, completed.len(), &self.model, conversation)?;
let request = elaboration_request(
command_id,
completed.len(),
&self.model,
&session.instructions,
conversation,
)?;
let invocation =
self.inference
.prepare(request)
@ -639,41 +673,57 @@ fn snapshot_error(error: MailboxError) -> ControllerError {
/// The oldest derived boundary in this jurisdiction, else its first nonzero
/// deficit row, else nothing. `snapshot.boundaries` is already ordered by the
/// kernel's derivation, so "oldest" is "first in that order".
///
/// Returns the session a new run would start, with its command id. The id is
/// derived from the answer alone; the lens is drawn from that id and the
/// world's current weights, and the lens's text is authored here. When the
/// store already holds this answer's row, `step` discards this session and
/// reads the recorded one.
fn select_answer(
snapshot: &WorldSnapshot,
jurisdiction: JurisdictionKey,
) -> Result<Option<ElaboratorSession>, ControllerError> {
) -> Result<Option<(CommandId, ElaboratorSession)>, ControllerError> {
let ancestry = snapshot.last_commit_digest.clone().unwrap_or_default();
if let Some(boundary) = snapshot
let (answer, answer_digest) = if let Some(boundary) = snapshot
.boundaries
.iter()
.find(|boundary| boundary_in(snapshot, jurisdiction, boundary))
{
return Ok(Some(ElaboratorSession {
(
PatchAnswer::Boundary(boundary.clone()),
boundary_digest(boundary),
)
} else {
let deficit = snapshot
.scale_deficit
.iter()
.any(|row| row.jurisdiction == jurisdiction && row.deficit > 0);
if !deficit {
return Ok(None);
}
// A deficit mixes the ancestry, so each admitted commit opens a fresh
// session and the loop advances instead of resubmitting one id forever.
let digest = digest_of(&(snapshot.world_id, jurisdiction, "deficit", &ancestry))?;
(
PatchAnswer::Deficit(jurisdiction),
BoundaryDigest::from_digest(digest),
)
};
let command_id = session_command_id(snapshot.world_id, jurisdiction, &answer_digest)?;
let lens = lens::draw(&snapshot.lens_weights, snapshot.world_id, command_id)
.map_err(|error| ControllerError::Serialization(error.to_string()))?;
Ok(Some((
command_id,
ElaboratorSession {
world_id: snapshot.world_id,
jurisdiction,
answer: PatchAnswer::Boundary(boundary.clone()),
answer_digest: boundary_digest(boundary),
answer,
answer_digest,
ancestry,
}));
}
let deficit = snapshot
.scale_deficit
.iter()
.any(|row| row.jurisdiction == jurisdiction && row.deficit > 0);
if !deficit {
return Ok(None);
}
// A deficit mixes the ancestry, so each admitted commit opens a fresh
// session and the loop advances instead of resubmitting one id forever.
let digest = digest_of(&(snapshot.world_id, jurisdiction, "deficit", &ancestry))?;
Ok(Some(ElaboratorSession {
world_id: snapshot.world_id,
jurisdiction,
answer: PatchAnswer::Deficit(jurisdiction),
answer_digest: BoundaryDigest::from_digest(digest),
ancestry,
}))
lens,
instructions: lens.instructions(),
},
)))
}
/// Selection reads the same covering the kernel's authority check does: a
@ -1230,10 +1280,14 @@ pub(super) fn derive_elaboration_capture(
}
}
/// `instructions` is the session's recorded text, never a code constant: the
/// first round, every later round, a repair, and the integrity check all build
/// the request from what the session carries.
pub(super) fn elaboration_request(
command_id: CommandId,
round: usize,
model: &str,
instructions: &str,
input: Vec<CodexInputItem>,
) -> Result<InferenceRequest, ControllerError> {
tool_request(
@ -1241,7 +1295,7 @@ pub(super) fn elaboration_request(
round,
InferencePurpose::Elaboration,
model,
ELABORATION_INSTRUCTIONS,
instructions,
input,
patch_tools(),
RequestShape {
@ -1254,7 +1308,10 @@ pub(super) fn elaboration_request(
}
/// A session's identity is derived from the world, the jurisdiction, and the
/// answer's digest, so a crashed loop resumes the same store row and the
/// answer's digest, and from nothing else a session carries: not its ancestry,
/// not its lens, not its text. It takes those three fields rather than a
/// session because the lens is drawn from this id, so the id exists before the
/// session does. A crashed loop resumes the same store row and the
/// mailbox's idempotency probe sees the same command. The derivation itself is
/// `CommandId::derived`, which is the one recipe every derived command key
/// uses.
@ -1268,11 +1325,15 @@ pub(super) fn elaboration_request(
/// for. The `controller_work` row and schema constants carry v9 for the same
/// reason the `consumer.v1` bump exists — a pre-refactor checkpoint refuses to
/// open rather than resuming under a mismatched id.
fn session_command_id(session: &ElaboratorSession) -> Result<CommandId, ControllerError> {
let scope = digest_of(&(session.world_id, session.jurisdiction))?;
fn session_command_id(
world_id: WorldId,
jurisdiction: JurisdictionKey,
answer_digest: &BoundaryDigest,
) -> Result<CommandId, ControllerError> {
let scope = digest_of(&(world_id, jurisdiction))?;
Ok(CommandId::derived(
ELABORATION_NAMESPACE,
&[&scope, session.answer_digest.text()],
&[&scope, answer_digest.text()],
))
}
@ -2394,6 +2455,17 @@ mod tests {
/// this pass resumes under a different command id. That is a silent id
/// migration for in-flight elaboration rows, and this test pins the fact so
/// it cannot move again unnoticed.
/// The command id of a session's identity fields, for tests that hold a
/// whole session.
fn id_of(session: &ElaboratorSession) -> CommandId {
session_command_id(
session.world_id,
session.jurisdiction,
&session.answer_digest,
)
.unwrap()
}
#[test]
fn soul_the_session_command_id_derivation_moved_under_the_refactor() {
let session = ElaboratorSession {
@ -2402,9 +2474,11 @@ mod tests {
answer: PatchAnswer::Deficit(JurisdictionKey::Uncovered),
answer_digest: BoundaryDigest::from_digest("sha256:deadbeef".into()),
ancestry: "sha256:ancestry".into(),
lens: Lens::Patina,
instructions: Lens::Patina.instructions(),
};
let live = session_command_id(&session).unwrap();
assert_eq!(live, session_command_id(&session).unwrap());
let live = id_of(&session);
assert_eq!(live, id_of(&session));
// The pass-9 spelling, reproduced exactly.
let mut hasher = Sha256::new();
@ -2429,7 +2503,7 @@ mod tests {
answer_digest: BoundaryDigest::from_digest("sha256:cafe".into()),
..session.clone()
};
assert_ne!(live, session_command_id(&moved).unwrap());
assert_ne!(live, id_of(&moved));
}
/// The author owns the size of what it authors. The kernel gets no cap.
@ -2545,6 +2619,13 @@ mod tests {
/// A boundary that survives a repair keeps its digest and therefore its
/// command id, so a crashed loop resumes the same store row. A different
/// answer is a different id.
///
/// L1 recorded a lens and its text on the session and left the identity
/// alone: the id is byte-equal to the one captured before L1 (Cut 0,
/// `base-session-id.txt`), and a session that differs only in lens, text
/// or ancestry has the same id. The derivation takes no session, so those
/// fields cannot reach it; the pinned text is what catches a changed
/// recipe.
#[test]
fn a_session_identity_is_derived_from_its_answer() {
let session = |digest: &str| ElaboratorSession {
@ -2553,18 +2634,32 @@ mod tests {
answer: PatchAnswer::Deficit(JurisdictionKey::Uncovered),
answer_digest: BoundaryDigest::from_digest(digest.to_owned()),
ancestry: "sha256:ancestry".into(),
lens: Lens::Patina,
instructions: Lens::Patina.instructions(),
};
let first = session_command_id(&session("sha256:one")).unwrap();
assert_eq!(first, session_command_id(&session("sha256:one")).unwrap());
assert_ne!(first, session_command_id(&session("sha256:two")).unwrap());
let first = id_of(&session("sha256:one"));
assert_eq!(
first,
CommandId::parse_uuid("56dbcdb2-9337-ac07-f322-37376b58cbcb").unwrap()
);
assert_eq!(first, id_of(&session("sha256:one")));
assert_ne!(first, id_of(&session("sha256:two")));
let recorded = ElaboratorSession {
lens: Lens::Numen,
instructions: "text a later build wrote".into(),
ancestry: "sha256:later".into(),
..session("sha256:one")
};
assert_eq!(first, id_of(&recorded));
}
// ---- Soul --------------------------------------------------------
/// The identity's preimage is (world, jurisdiction, answer digest) and all
/// three separate. The ancestry is deliberately not in it for the boundary
/// lane: a boundary that survives a repair keeps its id, which is what
/// makes the resume idempotent rather than orphaning a store row.
/// lane: a boundary that survives a repair keeps its id, so the resume
/// finds its store row; `step`'s adoption rule then reads the row's session
/// rather than demanding the fresh one equal it.
#[test]
fn soul_a_session_identity_separates_world_jurisdiction_and_answer() {
let root = EntityId(Uuid::from_u128(1));
@ -2577,6 +2672,8 @@ mod tests {
answer: PatchAnswer::Deficit(jurisdiction),
answer_digest: BoundaryDigest::from_digest(digest.to_owned()),
ancestry: ancestry.to_owned(),
lens: Lens::Patina,
instructions: Lens::Patina.instructions(),
}
};
let base = session(
@ -2585,7 +2682,7 @@ mod tests {
"sha256:one",
"sha256:ancestry",
);
let id = |value: &ElaboratorSession| session_command_id(value).unwrap();
let id = id_of;
assert_ne!(
id(&base),

View file

@ -3,11 +3,13 @@
//! or quota. This module owns the stock table, each lens's instruction text,
//! and the draw recipe; it reads no world state and writes nothing.
use super::elaboration::ELABORATION_INSTRUCTIONS;
use super::{CommandId, KernelError, WorldId, digest};
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;
/// The sentence every lens's instructions begin with.
const ELABORATION_INSTRUCTIONS: &str = "Use only the supplied tools to author structure inside your jurisdiction. Answer the boundary or deficit you were given, then submit. Recording a gap changes nothing.";
/// The library's stock lens set. Serialized by snake_case name, so a name the
/// library does not know cannot be represented at any deserialization boundary.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
@ -123,7 +125,8 @@ impl Lens {
}
/// The elaborator's instructions under this lens: the shared sentence, then
/// the lens clause.
/// the lens clause. Read once, when a session is first built; the session
/// then carries the text, and nothing rebuilds it from here.
#[cfg_attr(
not(test),
expect(dead_code, reason = "read by its tests until a session carries a lens")

View file

@ -306,7 +306,7 @@ knowledge row, and never another subject's snapshot. The re-lowering's
provider request is a distinct round (`interpreter_round`) with its own
content-addressed request id, so it cannot collide with the first lowering's
request. State schema is `ghostlight.world_state.consumer.v5`, commit schema
`ghostlight.world_commit.consumer.v5`, controller work `controller_work.v15`,
`ghostlight.world_commit.consumer.v5`, controller work `controller_work.v16`,
Persona turn receipt `ghostlight.persona_turn_receipt.v3`; earlier stores and
earlier rows are refused. Ghostlight owns a conserved narrative ledger;
Delvehold owns the economy (`delvehold-forced-ontology-integration.md`).