Bind world compilation to typed lore Vaults

This commit is contained in:
Meta Vens 2026-08-25 18:26:28 +02:00
commit eb1f119286
4 changed files with 425 additions and 60 deletions

View file

@ -10,7 +10,7 @@ use crate::{
run_validated_stage_with_timeout,
},
session_zero::{ApprovedCampaignBrief, MAX_SESSION_ZERO_MEMBERS, actor_from_character},
vault::{VaultProvider, VaultQuery},
vault::{DEFAULT_VAULT_ID, VaultProvider, VaultQuery, canonical_vault_id},
};
use anyhow::{Result, anyhow};
use chrono::{DateTime, Utc};
@ -569,6 +569,7 @@ pub struct WorldCompiler {
model: Arc<dyn ModelPort>,
retrieval_model: String,
compiler_model: String,
vault_id: String,
}
impl WorldCompiler {
@ -583,9 +584,22 @@ impl WorldCompiler {
model,
retrieval_model: retrieval_model.into(),
compiler_model: compiler_model.into(),
vault_id: DEFAULT_VAULT_ID.into(),
}
}
pub fn for_vault(&self, vault_id: &str) -> Result<Self> {
let vault_id = canonical_vault_id(vault_id)
.ok_or_else(|| anyhow!("unknown or unavailable lore Vault {vault_id:?}"))?;
Ok(Self {
vault: self.vault.clone(),
model: self.model.clone(),
retrieval_model: self.retrieval_model.clone(),
compiler_model: self.compiler_model.clone(),
vault_id: vault_id.into(),
})
}
pub async fn suggest_openings(&self, request: OpeningRequest) -> Result<SuggestedOpenings> {
validate_user_text("setting", &request.setting, 120)?;
if request.constraints.len() > 8 {
@ -595,7 +609,7 @@ impl WorldCompiler {
validate_user_text("opening constraint", constraint, 240)?;
}
let (queries, retrieval_receipt) = self.plan_opening_queries(&request).await?;
let receipts = self.retrieve_all(&queries, "all", 8).await?;
let receipts = self.retrieve_all_player_visible(&queries, "all", 8).await?;
let evidence = opening_evidence_text(&queries, &receipts);
let base_prompt = format!(
"Generate exactly three source-grounded openings, taking one from each labeled historical-frame evidence group when that group contains adequate support. The three literal `era` values must name specific, genuinely different historical periods and be pairwise distinct after trimming and case-folding. An umbrella label such as `Post-Elysium` is insufficient when used twice: qualify each with its distinct source-supported event, phase, or date. The three `place` values and three `pressure` values must independently be pairwise distinct. Do not return aliases for the same period or place merely to satisfy spelling-level diversity. Do not fill material evidence gaps with invention. Before returning, verify the nine axis values yourself. REQUEST:\n{}\nEVIDENCE GROUPS:\n{}",
@ -663,7 +677,9 @@ impl WorldCompiler {
2,
)
.await?;
let receipts = self.retrieve_all(&queries, &opening.era, 8).await?;
let receipts = self
.retrieve_all_player_visible(&queries, &opening.era, 8)
.await?;
let base_prompt = format!(
"Generate exactly three materially distinct player roles grounded in this opening and evidence. Names and premises must each be pairwise distinct after trimming and case-folding. The roles must differ in social position, capabilities, and obligations rather than being cosmetic aliases. OPENING:\n{}\nEVIDENCE:\n{}",
serde_json::to_string(opening)?,
@ -787,7 +803,7 @@ impl WorldCompiler {
.transpose()?
.unwrap_or_default();
let base_prompt = format!(
"{shared_prefix}{player_identity_context}{operational_playability_context}Compile a bounded playable region with stable topology, local actors, populations, clocks, and only those remote institutions that have a direct causal relationship to this requested start. SCOPED EVIDENCE contains direct_seed witnesses only. Setting-background and excluded witnesses remain visible in the approval coverage but are deliberately absent here: they cannot donate cast, incidents, clocks, location state, goals, or institutional posture to this branch. Use evidence as canon constraints, not as an exhaustive game map. When the Vault omits game-scale geometry, routes, local people, procedures, or daily texture, invent the smallest coherent playable elaboration, mark facts branch_local or provisional_local, and disclose consequential choices in branch_assumptions. An unevidenced route needed to connect the bounded region is branch-local geometry, not an evidence gap. Use a material gap only when no compatible elaboration can preserve the requested premise without choosing between contradictory canon baselines or exceeding an approved capability; never borrow a nearby story to fill it. Do not eagerly materialize remote settlements or people outside the bounded playable region. Private character history, secrets, relationships, and relationship subjects are deliberately absent and compile in a separate private stage; do not assume or reconstruct them. Emit only supported canon facts. A canon_baseline fact must cite one or more exact receipt_id values printed in SCOPED EVIDENCE whose witnesses directly support the whole statement. Never label an invented proper noun canon. Facts that an actor can uncover through an admitted local observation must exist before play and list the exact discoverable_at_location_ids where that observation is possible. Seed enough branch_local or provisional_local discoverable facts to make the requested opening pressure and immediate goal actionable; at least one such non-canon fact must be discoverable at the player's exact starting location. The later action assessor can reveal an existing fact but cannot invent one. Facts that are private history or not directly observable have an empty discovery-location set. The player location and every actor location must exist. Containment describes nested geometry; it never creates implicit movement. Every supplied location is a playable occupancy node. When the region contains more than one location, explicit route chains must let the player reach every supplied location from the starting location and return. Model inaccessible scenery as a persistent feature instead of an unreachable location. Every route record needs a stable route_id within its origin, an exact supplied destination_id, a distance, and positive travel_minutes. Every fact discovery location must exist, clocks need positive thresholds, and the player id must be unique. Actor relationship records must use subject_id values copied from exact actor, institution, gestalt, or named-member subject IDs declared in this candidate, never display names, roles, undeclared groups, or location IDs. A relationship to a collective population names its exact gestalt; it does not union that population's knowledge or turn the actor into its authority. Represent populations that can act collectively (villages, crews, crowds, departments, corporations) as gestalt Personas. Seed a small roster of plausible durable member identities for people the player may encounter; member deltas contain only departures from their gestalt baseline and begin dematerialized. Do not duplicate a gestalt member in actors. Keep named plot-critical people as ordinary actors. Every gestalt home location and member gestalt reference must exist. Do not emit agency profiles or relations; those are compiled from the exact validated subject roster in the next stage."
"{shared_prefix}{player_identity_context}{operational_playability_context}Compile a bounded playable region with stable topology, local actors, populations, clocks, and only those remote institutions that have a direct causal relationship to this requested start. SCOPED EVIDENCE contains direct_seed witnesses only. Setting-background and excluded witnesses remain visible in the approval coverage but are deliberately absent here: they cannot donate cast, incidents, clocks, location state, goals, or institutional posture to this branch. Use evidence as canon constraints, not as an exhaustive game map. A source marked with a `.gm_canon` authority lane may constrain hidden canonical state, but it must not be quoted or paraphrased into opening narration or granted as player or NPC knowledge merely because this compiler received it. When the Vault omits game-scale geometry, routes, local people, procedures, or daily texture, invent the smallest coherent playable elaboration, mark facts branch_local or provisional_local, and disclose consequential choices in branch_assumptions. An unevidenced route needed to connect the bounded region is branch-local geometry, not an evidence gap. Use a material gap only when no compatible elaboration can preserve the requested premise without choosing between contradictory canon baselines or exceeding an approved capability; never borrow a nearby story to fill it. Do not eagerly materialize remote settlements or people outside the bounded playable region. Private character history, secrets, relationships, and relationship subjects are deliberately absent and compile in a separate private stage; do not assume or reconstruct them. Emit only supported canon facts. A canon_baseline fact must cite one or more exact receipt_id values printed in SCOPED EVIDENCE whose witnesses directly support the whole statement. Never label an invented proper noun canon. Facts that an actor can uncover through an admitted local observation must exist before play and list the exact discoverable_at_location_ids where that observation is possible. Seed enough branch_local or provisional_local discoverable facts to make the requested opening pressure and immediate goal actionable; at least one such non-canon fact must be discoverable at the player's exact starting location. The later action assessor can reveal an existing fact but cannot invent one. Facts that are private history or not directly observable have an empty discovery-location set. The player location and every actor location must exist. Containment describes nested geometry; it never creates implicit movement. Every supplied location is a playable occupancy node. When the region contains more than one location, explicit route chains must let the player reach every supplied location from the starting location and return. Model inaccessible scenery as a persistent feature instead of an unreachable location. Every route record needs a stable route_id within its origin, an exact supplied destination_id, a distance, and positive travel_minutes. Every fact discovery location must exist, clocks need positive thresholds, and the player id must be unique. Actor relationship records must use subject_id values copied from exact actor, institution, gestalt, or named-member subject IDs declared in this candidate, never display names, roles, undeclared groups, or location IDs. A relationship to a collective population names its exact gestalt; it does not union that population's knowledge or turn the actor into its authority. Represent populations that can act collectively (villages, crews, crowds, departments, corporations) as gestalt Personas. Seed a small roster of plausible durable member identities for people the player may encounter; member deltas contain only departures from their gestalt baseline and begin dematerialized. Do not duplicate a gestalt member in actors. Keep named plot-critical people as ordinary actors. Every gestalt home location and member gestalt reference must exist. Do not emit agency profiles or relations; those are compiled from the exact validated subject roster in the next stage."
);
let schema = serde_json::to_value(schema_for!(CompiledSeed))?;
let sources = receipt_ids_for_coverage(&receipts, &evidence_coverage);
@ -1524,14 +1540,39 @@ impl WorldCompiler {
queries: &[String],
temporal_scope: &str,
limit: u8,
) -> Result<Vec<VaultEvidenceReceipt>> {
self.retrieve_all_with_visibility(queries, temporal_scope, limit, false)
.await
}
async fn retrieve_all_player_visible(
&self,
queries: &[String],
temporal_scope: &str,
limit: u8,
) -> Result<Vec<VaultEvidenceReceipt>> {
self.retrieve_all_with_visibility(queries, temporal_scope, limit, true)
.await
}
async fn retrieve_all_with_visibility(
&self,
queries: &[String],
temporal_scope: &str,
limit: u8,
player_visible_only: bool,
) -> Result<Vec<VaultEvidenceReceipt>> {
let mut receipts = Vec::new();
for query in queries {
let mut authority_lanes = vec![self.vault_id.clone()];
if player_visible_only {
authority_lanes.push("visibility.player".into());
}
receipts.push(
self.vault
.search(&VaultQuery {
query: query.clone(),
authority_lanes: vec!["Aetheria".into(), "AetheriaLore".into()],
authority_lanes,
temporal_scope: temporal_scope.into(),
limit,
})
@ -2316,7 +2357,11 @@ fn global_agency_queries(start: &CustomStart) -> Vec<String> {
fn authority_allows_direct_seed(authority_lane: &str) -> bool {
matches!(
authority_lane,
"aetheria.canon_worldbuilding" | "aetheria.vault_document" | "AetheriaLore"
"aetheria.canon_worldbuilding"
| "aetheria.vault_document"
| "AetheriaLore"
| "kalsa.public"
| "kalsa.gm_canon"
)
}
@ -2330,7 +2375,11 @@ fn canonical_worldbuilding_receipts(
filtered.witnesses.retain(|witness| {
matches!(
witness.authority_lane.as_str(),
"aetheria.canon_worldbuilding" | "aetheria.vault_document" | "AetheriaLore"
"aetheria.canon_worldbuilding"
| "aetheria.vault_document"
| "AetheriaLore"
| "kalsa.public"
| "kalsa.gm_canon"
)
});
(!filtered.witnesses.is_empty()).then_some(filtered)
@ -2977,9 +3026,10 @@ fn evidence_text(receipts: &[VaultEvidenceReceipt]) -> String {
})
.map(|(receipt_id, witness)| {
format!(
"[receipt_id={} | source={} | locator={} | content_hash={}] {}",
"[receipt_id={} | source={} | authority_lane={} | locator={} | content_hash={}] {}",
receipt_id,
witness.source_id,
witness.authority_lane,
witness.exact_locator,
witness.content_hash,
witness.excerpt
@ -3033,10 +3083,11 @@ fn direct_seed_evidence_text(
return None;
}
Some(format!(
"[usage_lane=direct_seed | rationale={} | receipt_id={} | source={} | locator={} | content_hash={}] {}",
"[usage_lane=direct_seed | rationale={} | receipt_id={} | source={} | authority_lane={} | locator={} | content_hash={}] {}",
use_plan.rationale,
receipt_id,
witness.source_id,
witness.authority_lane,
witness.exact_locator,
witness.content_hash,
witness.excerpt

View file

@ -44,7 +44,7 @@ use ghostlight_dungeon::{
campaign_interface_version, player_surface_for_actor, rebase_campaign_surface_revision,
},
turn::{SnapshotPermit, appraise_present, resolve_speech_addresses},
vault::VoidBotMcpVault,
vault::{VoidBotMcpVault, bundled_vault_manifests, canonical_vault_id},
};
use serde::Deserialize;
use serde::Serialize;
@ -89,6 +89,16 @@ struct AppState {
mesh: MeshPublisher,
}
fn compiler_for_vault(
compiler: &Option<Arc<WorldCompiler>>,
vault_id: &str,
) -> anyhow::Result<Arc<WorldCompiler>> {
let compiler = compiler
.as_ref()
.ok_or_else(|| anyhow::anyhow!("world compiler is unavailable"))?;
Ok(Arc::new(compiler.for_vault(vault_id)?))
}
struct LiveTurnGuard {
counter: Arc<AtomicUsize>,
finished: Arc<Notify>,
@ -2165,10 +2175,17 @@ async fn begin_session_zero(
Some(value) => value,
None => return StatusCode::UNAUTHORIZED.into_response(),
};
let Some(vault_id) = canonical_vault_id(&request.vault_provider) else {
return (
StatusCode::UNPROCESSABLE_ENTITY,
"Select one of the advertised lore Vaults.",
)
.into_response();
};
let allowance = state.entitlements.persona_cell_allowance(&account_hash);
match SessionZeroState::new_with_allowance(
request.name,
request.vault_provider,
vault_id.into(),
account_hash.clone(),
request.display_name,
allowance,
@ -2179,7 +2196,10 @@ async fn begin_session_zero(
Ok(runtime) => match state.session_zeros.snapshot(id).await {
Ok(snapshot) => match session_zero_surface(&snapshot, &account_hash) {
Ok(surface) => {
if let Some(compiler) = state.compiler.clone() {
if let Ok(compiler) = compiler_for_vault(
&state.compiler,
&snapshot.contract.vault_provider,
) {
let mesh_state = state.clone();
tokio::spawn(async move {
if let Err(error) = run_live_model_work(
@ -2984,7 +3004,8 @@ async fn resolve_session_zero_decision(
}
if accepted
&& let Some(opening) = accepted_opening_suggestion(&result.state, &decision_id)
&& let Some(compiler) = state.compiler.clone()
&& let Ok(compiler) =
compiler_for_vault(&state.compiler, &result.state.contract.vault_provider)
{
let role_runtime = runtime.clone();
let role_state = state.clone();
@ -3170,12 +3191,11 @@ async fn compile_session_zero(
Err(error) => (StatusCode::CONFLICT, error.to_string()).into_response(),
};
}
let Some(compiler) = state.compiler.clone() else {
return (
StatusCode::SERVICE_UNAVAILABLE,
"world compiler is unavailable",
)
.into_response();
let compiler = match compiler_for_vault(&state.compiler, &brief.contract.vault_provider) {
Ok(compiler) => compiler,
Err(error) => {
return (StatusCode::SERVICE_UNAVAILABLE, error.to_string()).into_response();
}
};
let kernel = runtime.kernel.clone();
let mesh_state = state.clone();
@ -3748,12 +3768,23 @@ async fn session_zero_entry_surface(
invite: Option<&str>,
) -> anyhow::Result<serde_json::Value> {
let campaign_choices = campaign_choice_components_for_account(state, account_hash).await?;
let vault_options = bundled_vault_manifests()
.into_iter()
.map(|manifest| {
serde_json::json!({
"id":format!("entry.vault.option.{}", manifest.id),
"kind":"control.option",
"props":{"value":manifest.id,"label":manifest.title},
"children":[]
})
})
.collect::<Vec<_>>();
let mut children = vec![
serde_json::json!({"id":"entry.intro","kind":"card","props":{"title":"Begin Session Zero"},"children":[
{"id":"entry.intro.text","kind":"text","props":{"value":"Build the campaign with the DM before the world becomes canonical. Tone, boundaries, characters, evidence gaps, and opening pressure remain negotiable until everyone approves."},"children":[]}
]}),
serde_json::json!({"id":"entry.name","kind":"control.input.text","props":{"label":"Draft name","placeholder":"The campaign you are about to regret caring about"},"stateBindings":[eve_local_draft("name","string")],"children":[]}),
serde_json::json!({"id":"entry.vault","kind":"control.input.text","props":{"label":"Lore Vault","value":"Aetheria","placeholder":"Aetheria"},"stateBindings":[eve_local_draft("vault_provider","string")],"children":[]}),
serde_json::json!({"id":"entry.vault","kind":"control.select","props":{"label":"Lore Vault","value":"aetheria"},"stateBindings":[eve_local_draft("vault_provider","choice")],"children":vault_options}),
serde_json::json!({"id":"entry.display-name","kind":"control.input.text","props":{"label":"Your display name"},"stateBindings":[eve_local_draft("display_name","string")],"children":[]}),
eve_button(
"entry.begin",
@ -3978,12 +4009,15 @@ async fn compile_destination(
Ok(value) => value,
Err(error) => return (StatusCode::NOT_FOUND, error.to_string()).into_response(),
};
let Some(compiler) = &state.compiler else {
return (
StatusCode::SERVICE_UNAVAILABLE,
"Model provider credential is unavailable",
)
.into_response();
let vault_id = match campaign_vault_id(&runtime.store, campaign.id) {
Ok(value) => value,
Err(error) => return (StatusCode::CONFLICT, error.to_string()).into_response(),
};
let compiler = match compiler_for_vault(&state.compiler, &vault_id) {
Ok(value) => value,
Err(error) => {
return (StatusCode::SERVICE_UNAVAILABLE, error.to_string()).into_response();
}
};
match compiler
.compile_destination(&campaign, &request.origin_location_id, &request.destination)
@ -4079,12 +4113,15 @@ async fn compile_fission(
Ok(value) => value,
Err(error) => return (StatusCode::NOT_FOUND, error.to_string()).into_response(),
};
let Some(compiler) = &state.compiler else {
return (
StatusCode::SERVICE_UNAVAILABLE,
"Model provider credential is unavailable",
)
.into_response();
let vault_id = match campaign_vault_id(&runtime.store, campaign.id) {
Ok(value) => value,
Err(error) => return (StatusCode::CONFLICT, error.to_string()).into_response(),
};
let compiler = match compiler_for_vault(&state.compiler, &vault_id) {
Ok(value) => value,
Err(error) => {
return (StatusCode::SERVICE_UNAVAILABLE, error.to_string()).into_response();
}
};
match compiler.compile_fission(&campaign, request).await {
Ok((preview, evidence_receipts, model_receipts)) => {
@ -6095,6 +6132,18 @@ fn campaign_model_policy(
(Some(publication.contract), boundaries)
}
fn campaign_vault_id(store: &CampaignStore, campaign_id: uuid::Uuid) -> anyhow::Result<String> {
let (_, contract) = store
.load::<ghostlight_dungeon::session_zero::CampaignContract>(
"campaign_contract.v1",
&campaign_id.to_string(),
)?
.ok_or_else(|| anyhow::anyhow!("campaign contract is missing"))?;
canonical_vault_id(&contract.vault_provider)
.map(str::to_owned)
.ok_or_else(|| anyhow::anyhow!("campaign refers to unavailable lore Vault"))
}
async fn migrate_legacy_campaign_memberships(
registry: &CampaignRegistry,
auth: &LegacyAuthState,

View file

@ -7,6 +7,7 @@ use crate::{
model::{ModelRuntimeStatus, ModelStageReceipt},
session_zero::{CampaignMembership, SessionZeroState},
surface::{operator_surface, player_surface, player_surface_for_actor},
vault::VaultSourceManifest,
};
use anyhow::Result;
use chrono::Utc;
@ -565,7 +566,8 @@ fn remote_options(target: SocketAddr, runtime_id: &str) -> CultMeshRudpDocumentP
fn schema_catalog() -> Value {
json!({
"ghostlight.campaign.v1": schemars::schema_for!(Campaign),
"ghostlight.session_zero.v1": schemars::schema_for!(SessionZeroState)
"ghostlight.session_zero.v1": schemars::schema_for!(SessionZeroState),
"ghostlight.vault_source_manifest.v1": schemars::schema_for!(VaultSourceManifest)
})
}

View file

@ -3,11 +3,65 @@ use anyhow::{Result, anyhow};
use async_trait::async_trait;
use chrono::Utc;
use reqwest::Client;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use std::collections::BTreeMap;
use thiserror::Error;
const VOIDBOT_SEARCH_RESULT_LIMIT: u8 = 12;
pub const DEFAULT_VAULT_ID: &str = "aetheria";
#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
pub struct VaultSourceManifest {
pub schema: String,
pub id: String,
pub title: String,
pub provider_id: String,
pub repository_name: String,
pub source_root: String,
pub git_remote: String,
pub compiler_authority_lanes: Vec<String>,
pub player_authority_lanes: Vec<String>,
}
pub fn bundled_vault_manifests() -> Vec<VaultSourceManifest> {
vec![
VaultSourceManifest {
schema: "ghostlight.vault_source_manifest.v1".into(),
id: "aetheria".into(),
title: "Aetheria".into(),
provider_id: "voidbot.aetheria".into(),
repository_name: "AetheriaLore".into(),
source_root: "Aetheria/Worldbuilding/".into(),
git_remote: "https://github.com/GameCult/AetheriaLore.git".into(),
compiler_authority_lanes: vec!["aetheria.canon_worldbuilding".into()],
player_authority_lanes: vec!["aetheria.canon_worldbuilding".into()],
},
VaultSourceManifest {
schema: "ghostlight.vault_source_manifest.v1".into(),
id: "kalsa".into(),
title: "Kalsa".into(),
provider_id: "voidbot.kalsa".into(),
repository_name: "Kalsa".into(),
source_root: "Kalsa/".into(),
git_remote: "https://github.com/GameCult/Kalsa.git".into(),
compiler_authority_lanes: vec!["kalsa.public".into(), "kalsa.gm_canon".into()],
player_authority_lanes: vec!["kalsa.public".into()],
},
]
}
pub fn canonical_vault_id(value: &str) -> Option<&'static str> {
match value.trim().to_ascii_lowercase().as_str() {
// `fixture` is the persisted legacy migration label used before Vault
// selection became typed. Those campaigns were compiled from the
// bundled Aetheria provider.
"aetheria" | "aetherialore" | "voidbot.aetheria" | "fixture" => Some("aetheria"),
"kalsa" | "voidbot.kalsa" => Some("kalsa"),
_ => None,
}
}
#[derive(Debug, Error)]
#[error("{provider} Vault retrieval is unavailable: {detail}")]
@ -84,12 +138,18 @@ impl VaultProvider for FixtureVault {
pub struct VoidBotMcpVault {
client: Client,
endpoint: String,
manifests: BTreeMap<String, VaultSourceManifest>,
}
impl VoidBotMcpVault {
pub fn new(endpoint: impl Into<String>) -> Self {
let manifests = bundled_vault_manifests()
.into_iter()
.map(|manifest| (manifest.id.clone(), manifest))
.collect();
Self {
client: Client::new(),
endpoint: endpoint.into(),
manifests,
}
}
pub fn starfire_loopback() -> Self {
@ -145,6 +205,28 @@ impl VoidBotMcpVault {
}
Ok(value)
}
fn manifest_for_query(&self, query: &VaultQuery) -> Result<&VaultSourceManifest> {
let selected = query
.authority_lanes
.iter()
.find_map(|value| canonical_vault_id(value))
.ok_or_else(|| anyhow!("Vault query has no configured Vault identity"))?;
self.manifests
.get(selected)
.ok_or_else(|| anyhow!("unknown Vault {selected}"))
}
fn manifest_for_source(&self, source_id: &str) -> Result<&VaultSourceManifest> {
let repository = source_id
.split_once(':')
.map(|(repository, _)| repository)
.ok_or_else(|| anyhow!("Vault source ID has no repository namespace"))?;
self.manifests
.values()
.find(|manifest| manifest.repository_name.eq_ignore_ascii_case(repository))
.ok_or_else(|| anyhow!("Vault source {source_id} is outside every configured Vault"))
}
}
#[cfg(test)]
@ -167,7 +249,7 @@ mod tests {
#[tokio::test]
async fn voidbot_search_results_become_exact_evidence_witnesses() {
let app=Router::new().route("/mcp",post(||async { ([("content-type","text/event-stream")], "event: message\ndata: {\"result\":{\"structuredContent\":{\"results\":[{\"sourceId\":\"AetheriaLore:place.md\",\"path\":\"place.md\",\"lineStart\":7,\"lineEnd\":9,\"text\":\"The route takes six hours.\"}]}}}\n\n").into_response() }));
let app=Router::new().route("/mcp",post(||async { ([("content-type","text/event-stream")], "event: message\ndata: {\"result\":{\"structuredContent\":{\"results\":[{\"sourceId\":\"AetheriaLore:Aetheria/Worldbuilding/place.md\",\"path\":\"Aetheria/Worldbuilding/place.md\",\"lineStart\":7,\"lineEnd\":9,\"text\":\"The route takes six hours.\"}]}}}\n\n").into_response() }));
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
tokio::spawn(async move {
@ -183,11 +265,14 @@ mod tests {
})
.await
.unwrap();
assert_eq!(result.witnesses[0].exact_locator, "place.md:7-9");
assert_eq!(
result.witnesses[0].exact_locator,
"Aetheria/Worldbuilding/place.md:7-9"
);
assert!(result.witnesses[0].content_hash.starts_with("sha256:"));
assert_eq!(
result.witnesses[0].authority_lane,
"aetheria.vault_document"
"aetheria.canon_worldbuilding"
);
}
@ -201,9 +286,14 @@ mod tests {
.and_then(|value| value.as_u64()),
Some(VOIDBOT_SEARCH_RESULT_LIMIT as u64)
);
assert_eq!(
body.pointer("/params/arguments/pathPrefix")
.and_then(|value| value.as_str()),
Some("Aetheria/Worldbuilding/")
);
([
("content-type", "text/event-stream"),
], "event: message\ndata: {\"result\":{\"structuredContent\":{\"results\":[{\"sourceId\":\"AetheriaLore:place.md\",\"path\":\"place.md\",\"lineStart\":7,\"lineEnd\":9,\"text\":\"The route takes six hours.\"}]}}}\n\n").into_response()
], "event: message\ndata: {\"result\":{\"structuredContent\":{\"results\":[{\"sourceId\":\"AetheriaLore:Aetheria/Worldbuilding/place.md\",\"path\":\"Aetheria/Worldbuilding/place.md\",\"lineStart\":7,\"lineEnd\":9,\"text\":\"The route takes six hours.\"}]}}}\n\n").into_response()
}),
);
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
@ -231,22 +321,22 @@ mod tests {
#[tokio::test]
async fn voidbot_exact_document_is_hashed_as_the_complete_archive_witness() {
let app=Router::new().route("/mcp",post(||async { ([ ("content-type","text/event-stream") ], "event: message\ndata: {\"result\":{\"structuredContent\":{\"found\":true,\"sourceId\":\"AetheriaLore:forge.md\",\"repoName\":\"AetheriaLore\",\"path\":\"forge.md\",\"content\":\"John keeps the forge.\\nThe road takes six hours.\",\"lastModifiedAt\":\"2026-01-01T00:00:00Z\"}}}\n\n").into_response() }));
let app=Router::new().route("/mcp",post(||async { ([ ("content-type","text/event-stream") ], "event: message\ndata: {\"result\":{\"structuredContent\":{\"found\":true,\"sourceId\":\"AetheriaLore:Aetheria/Worldbuilding/forge.md\",\"repoName\":\"AetheriaLore\",\"path\":\"Aetheria/Worldbuilding/forge.md\",\"content\":\"John keeps the forge.\\nThe road takes six hours.\",\"lastModifiedAt\":\"2026-01-01T00:00:00Z\"}}}\n\n").into_response() }));
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
tokio::spawn(async move {
axum::serve(listener, app).await.unwrap();
});
let witness = VoidBotMcpVault::new(format!("http://{address}/mcp"))
.exact_document("AetheriaLore:forge.md")
.exact_document("AetheriaLore:Aetheria/Worldbuilding/forge.md")
.await
.unwrap();
assert_eq!(
witness.excerpt,
"John keeps the forge.\nThe road takes six hours."
);
assert_eq!(witness.exact_locator, "forge.md");
assert_eq!(witness.authority_lane, "aetheria.vault_document");
assert_eq!(witness.exact_locator, "Aetheria/Worldbuilding/forge.md");
assert_eq!(witness.authority_lane, "aetheria.canon_worldbuilding");
assert_eq!(
witness.content_hash,
format!("sha256:{:x}", Sha256::digest(witness.excerpt.as_bytes()))
@ -255,18 +345,18 @@ mod tests {
#[tokio::test]
async fn voidbot_context_combines_the_typed_chunk_window() {
let app=Router::new().route("/mcp",post(||async { ([ ("content-type","text/event-stream") ], "event: message\ndata: {\"result\":{\"structuredContent\":{\"found\":true,\"sourceId\":\"AetheriaLore:forge.md\",\"repoName\":\"AetheriaLore\",\"path\":\"forge.md\",\"chunks\":[{\"lineStart\":1,\"lineEnd\":2,\"text\":\"first\"},{\"lineStart\":3,\"lineEnd\":4,\"text\":\"second\"}]}}}\n\n").into_response() }));
let app=Router::new().route("/mcp",post(||async { ([ ("content-type","text/event-stream") ], "event: message\ndata: {\"result\":{\"structuredContent\":{\"found\":true,\"sourceId\":\"AetheriaLore:Aetheria/Worldbuilding/forge.md\",\"repoName\":\"AetheriaLore\",\"path\":\"Aetheria/Worldbuilding/forge.md\",\"chunks\":[{\"lineStart\":1,\"lineEnd\":2,\"text\":\"first\"},{\"lineStart\":3,\"lineEnd\":4,\"text\":\"second\"}]}}}\n\n").into_response() }));
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
tokio::spawn(async move {
axum::serve(listener, app).await.unwrap();
});
let witness = VoidBotMcpVault::new(format!("http://{address}/mcp"))
.surrounding_context("AetheriaLore:forge.md", 0)
.surrounding_context("AetheriaLore:Aetheria/Worldbuilding/forge.md", 0)
.await
.unwrap();
assert_eq!(witness.excerpt, "first\nsecond");
assert_eq!(witness.exact_locator, "forge.md:1-4");
assert_eq!(witness.exact_locator, "Aetheria/Worldbuilding/forge.md:1-4");
}
#[test]
@ -292,23 +382,111 @@ mod tests {
"aetheria.draft_working"
);
}
#[test]
fn kalsa_manifest_keeps_public_and_gm_lanes_distinct() {
let manifest = bundled_vault_manifests()
.into_iter()
.find(|manifest| manifest.id == "kalsa")
.unwrap();
assert_eq!(
authority_lane_for_source(&manifest, "Kalsa/Public/World/Magic and Miracles.md")
.unwrap(),
"kalsa.public"
);
assert_eq!(
authority_lane_for_source(
&manifest,
"Kalsa/Spoilers/Foundations/Divine Interception.md"
)
.unwrap(),
"kalsa.gm_canon"
);
assert!(
authority_lane_for_source(&manifest, "workshop/Direction and Constraints.md").is_err()
);
let public_query = VaultQuery {
query: "starting places".into(),
authority_lanes: vec!["kalsa".into(), "visibility.player".into()],
temporal_scope: "all".into(),
limit: 3,
};
assert_eq!(query_source_root(&manifest, &public_query), "Kalsa/Public/");
}
#[tokio::test]
async fn kalsa_search_is_repository_and_root_scoped() {
let app = Router::new().route(
"/mcp",
post(|axum::Json(body): axum::Json<serde_json::Value>| async move {
assert_eq!(
body.pointer("/params/arguments/repoName")
.and_then(|value| value.as_str()),
Some("Kalsa")
);
assert_eq!(
body.pointer("/params/arguments/pathPrefix")
.and_then(|value| value.as_str()),
Some("Kalsa/")
);
([
("content-type", "text/event-stream"),
], "event: message\ndata: {\"result\":{\"structuredContent\":{\"results\":[{\"sourceId\":\"Kalsa:Kalsa/Spoilers/Places/Low Sere.md\",\"path\":\"Kalsa/Spoilers/Places/Low Sere.md\",\"lineStart\":7,\"lineEnd\":9,\"text\":\"Low Sere keeps three ledgers.\"}]}}}\n\n").into_response()
}),
);
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
tokio::spawn(async move {
axum::serve(listener, app).await.unwrap();
});
let result = VoidBotMcpVault::new(format!("http://{address}/mcp"))
.search(&VaultQuery {
query: "Low Sere".into(),
authority_lanes: vec!["kalsa".into()],
temporal_scope: "campaign start".into(),
limit: 3,
})
.await
.unwrap();
assert_eq!(result.provider, "voidbot.kalsa");
assert_eq!(result.witnesses[0].authority_lane, "kalsa.gm_canon");
}
#[tokio::test]
async fn a_vault_cannot_return_another_repository() {
let app=Router::new().route("/mcp",post(||async { ([("content-type","text/event-stream")], "event: message\ndata: {\"result\":{\"structuredContent\":{\"results\":[{\"sourceId\":\"Kalsa:Kalsa/Public/index.md\",\"path\":\"Kalsa/Public/index.md\",\"lineStart\":1,\"lineEnd\":2,\"text\":\"Wrong world.\"}]}}}\n\n").into_response() }));
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
tokio::spawn(async move {
axum::serve(listener, app).await.unwrap();
});
let error = VoidBotMcpVault::new(format!("http://{address}/mcp"))
.search(&VaultQuery {
query: "route".into(),
authority_lanes: vec!["aetheria".into()],
temporal_scope: "era".into(),
limit: 3,
})
.await
.unwrap_err();
assert!(error.to_string().contains("crossed repository boundary"));
}
}
#[async_trait]
impl VaultProvider for VoidBotMcpVault {
async fn search(&self, query: &VaultQuery) -> Result<VaultEvidenceReceipt> {
let mut effective_query = query.clone();
effective_query.limit = effective_query.limit.min(VOIDBOT_SEARCH_RESULT_LIMIT);
let manifest = self.manifest_for_query(&effective_query)?;
let source_root = query_source_root(manifest, &effective_query);
let response = self
.call_tool(
"search_sources",
serde_json::json!({
"query":effective_query.query,
"limit":effective_query.limit,
"repoName": if effective_query.authority_lanes.iter().any(|lane| lane == "AetheriaLore") {
Some("AetheriaLore")
} else {
None
}
"repoName":manifest.repository_name,
"pathPrefix":source_root,
}),
)
.await?;
@ -318,9 +496,9 @@ impl VaultProvider for VoidBotMcpVault {
.ok_or_else(|| anyhow!("VoidBot MCP returned no typed search results"))?;
let witnesses = results
.iter()
.map(|item| witness_from_result(item, &effective_query))
.map(|item| witness_from_result(item, &effective_query, manifest, source_root))
.collect::<Result<Vec<_>>>()?;
Ok(receipt(self.provider_id(), &effective_query, witnesses))
Ok(receipt(&manifest.provider_id, &effective_query, witnesses))
}
async fn surrounding_context(
&self,
@ -336,6 +514,7 @@ impl VaultProvider for VoidBotMcpVault {
let value = response
.pointer("/result/structuredContent")
.ok_or_else(|| anyhow!("VoidBot MCP returned no source context"))?;
let manifest = self.manifest_for_source(source_id)?;
let chunks = value
.get("chunks")
.and_then(|v| v.as_array())
@ -352,6 +531,7 @@ impl VaultProvider for VoidBotMcpVault {
.get("path")
.and_then(|v| v.as_str())
.unwrap_or(source_id);
validate_manifest_source(manifest, source_id, path)?;
let first_line = chunks
.first()
.and_then(|chunk| chunk.get("lineStart"))
@ -369,7 +549,7 @@ impl VaultProvider for VoidBotMcpVault {
exact_locator,
content_hash: format!("sha256:{:x}", Sha256::digest(excerpt.as_bytes())),
excerpt,
authority_lane: authority_lane_for_path(path).into(),
authority_lane: authority_lane_for_source(manifest, path)?.into(),
temporal_scope: "unspecified".into(),
})
}
@ -383,6 +563,7 @@ impl VaultProvider for VoidBotMcpVault {
let value = response
.pointer("/result/structuredContent")
.ok_or_else(|| anyhow!("VoidBot MCP returned no exact source document"))?;
let manifest = self.manifest_for_source(source_id)?;
if value.get("found").and_then(|v| v.as_bool()) != Some(true) {
return Err(anyhow!("VoidBot exact source document was not found"));
}
@ -394,12 +575,13 @@ impl VaultProvider for VoidBotMcpVault {
.get("path")
.and_then(|v| v.as_str())
.unwrap_or(source_id);
validate_manifest_source(manifest, source_id, path)?;
Ok(SourceWitness {
source_id: source_id.into(),
exact_locator: path.into(),
content_hash: format!("sha256:{:x}", Sha256::digest(content.as_bytes())),
excerpt: content.into(),
authority_lane: authority_lane_for_path(path).into(),
authority_lane: authority_lane_for_source(manifest, path)?.into(),
temporal_scope: value
.get("lastModifiedAt")
.and_then(|v| v.as_str())
@ -412,7 +594,12 @@ impl VaultProvider for VoidBotMcpVault {
}
}
fn witness_from_result(item: &serde_json::Value, query: &VaultQuery) -> Result<SourceWitness> {
fn witness_from_result(
item: &serde_json::Value,
query: &VaultQuery,
manifest: &VaultSourceManifest,
required_root: &str,
) -> Result<SourceWitness> {
let source_id = item
.get("sourceId")
.and_then(|v| v.as_str())
@ -429,21 +616,97 @@ fn witness_from_result(item: &serde_json::Value, query: &VaultQuery) -> Result<S
(Some(path), Some(start), Some(end)) => format!("{path}:{start}-{end}"),
_ => source_id.into(),
};
let path = item
.get("path")
.and_then(|value| value.as_str())
.unwrap_or(source_id);
validate_manifest_source(manifest, source_id, path)?;
validate_source_root(required_root, path)?;
Ok(SourceWitness {
source_id: source_id.into(),
exact_locator: locator,
content_hash: format!("sha256:{:x}", Sha256::digest(excerpt.as_bytes())),
excerpt: excerpt.into(),
authority_lane: authority_lane_for_path(
item.get("path")
.and_then(|value| value.as_str())
.unwrap_or(source_id),
)
.into(),
authority_lane: authority_lane_for_source(manifest, path)?.into(),
temporal_scope: query.temporal_scope.clone(),
})
}
fn query_source_root<'a>(manifest: &'a VaultSourceManifest, query: &VaultQuery) -> &'a str {
if manifest.id == "kalsa"
&& query
.authority_lanes
.iter()
.any(|lane| lane == "visibility.player")
{
"Kalsa/Public/"
} else {
&manifest.source_root
}
}
fn validate_source_root(required_root: &str, path: &str) -> Result<()> {
if !path
.replace('\\', "/")
.to_ascii_lowercase()
.starts_with(&required_root.to_ascii_lowercase())
{
return Err(anyhow!(
"Vault provider crossed requested visibility boundary: expected {required_root}, received {path}"
));
}
Ok(())
}
fn validate_manifest_source(
manifest: &VaultSourceManifest,
source_id: &str,
path: &str,
) -> Result<()> {
let repository = source_id
.split_once(':')
.map(|(repository, _)| repository)
.ok_or_else(|| anyhow!("Vault source ID has no repository namespace"))?;
if !repository.eq_ignore_ascii_case(&manifest.repository_name) {
return Err(anyhow!(
"Vault provider crossed repository boundary: expected {}, received {source_id}",
manifest.repository_name
));
}
let normalized_path = path.replace('\\', "/");
if !normalized_path
.to_ascii_lowercase()
.starts_with(&manifest.source_root.to_ascii_lowercase())
{
return Err(anyhow!(
"Vault provider crossed source-root boundary: expected {}, received {path}",
manifest.source_root
));
}
Ok(())
}
fn authority_lane_for_source(manifest: &VaultSourceManifest, path: &str) -> Result<&'static str> {
match manifest.id.as_str() {
"aetheria" => Ok(authority_lane_for_path(path)),
"kalsa" => {
let normalized = path.replace('\\', "/").to_ascii_lowercase();
if normalized.starts_with("kalsa/public/") {
Ok("kalsa.public")
} else if normalized.starts_with("kalsa/spoilers/") {
Ok("kalsa.gm_canon")
} else if normalized == "kalsa/index.md" {
Ok("kalsa.navigation")
} else {
Err(anyhow!(
"Kalsa source path has no admitted authority lane: {path}"
))
}
}
other => Err(anyhow!("Vault {other} has no authority classifier")),
}
}
/// Classify source authority at the Vault boundary. Downstream models receive a
/// typed document role instead of having to infer authority from prose.
fn authority_lane_for_path(path: &str) -> &'static str {