2026-08-14 11:20:56 +02:00
use std ::path ::Path ;
use anyhow ::{ Result , anyhow } ;
use cultcache_rs ::{ CultCache , CultCacheEnvelope , DatabaseEntry } ;
use epiphany_state_model ::{
2026-08-14 11:52:11 +02:00
EpiphanyBacklogItem , EpiphanyEvidenceRecord , EpiphanyInvariant ,
EpiphanyInvestigationCheckpoint , EpiphanyModeState , EpiphanyObjectiveDraft ,
EpiphanyObservation , EpiphanyPlanningCapture , EpiphanyPlanningState , EpiphanyRoadmapStream ,
EpiphanySubgoal ,
2026-08-14 11:20:56 +02:00
} ;
use serde ::{ Deserialize , Serialize } ;
use sha2 ::{ Digest , Sha256 } ;
use crate ::{ EpiphanyMindDocumentVersion , runtime_spine_cache } ;
pub const MIND_SCHEMA_EPOCH : & str = " epiphany.mind.epoch.v1 " ;
pub const MIND_OBJECTIVE_KEY : & str = " objective " ;
pub const MIND_FOCUS_KEY : & str = " focus " ;
pub const MIND_MODE_KEY : & str = " mode " ;
#[ derive(Clone, Debug, PartialEq, Eq, DatabaseEntry) ]
#[ cultcache(type = " epiphany.mind.identity.v1 " , schema = " EpiphanyMindIdentity " ) ]
pub struct EpiphanyMindIdentity {
#[ cultcache(key = 0) ]
pub schema_epoch : String ,
#[ cultcache(key = 1) ]
pub runtime_id : String ,
}
#[ derive(Clone, Debug, PartialEq, Eq, DatabaseEntry) ]
2026-08-14 11:52:11 +02:00
#[ cultcache(
type = " epiphany.mind.objective.v1 " ,
schema = " EpiphanyMindObjectiveDocument "
) ]
2026-08-14 11:20:56 +02:00
pub struct EpiphanyMindObjectiveDocument {
#[ cultcache(key = 0) ]
pub objective : String ,
}
#[ derive(Clone, Debug, PartialEq, Eq, DatabaseEntry) ]
#[ cultcache(type = " epiphany.mind.focus.v1 " , schema = " EpiphanyMindFocusDocument " ) ]
pub struct EpiphanyMindFocusDocument {
#[ cultcache(key = 0) ]
pub active_subgoal_id : Option < String > ,
#[ cultcache(key = 1) ]
pub investigation_checkpoint_id : Option < String > ,
}
#[ derive(Clone, Debug, PartialEq, DatabaseEntry) ]
#[ cultcache(type = " epiphany.mind.mode.v1 " , schema = " EpiphanyMindModeDocument " ) ]
pub struct EpiphanyMindModeDocument {
#[ cultcache(key = 0) ]
pub mode : EpiphanyModeState ,
}
#[ derive(Clone, Debug, PartialEq, DatabaseEntry) ]
2026-08-14 11:52:11 +02:00
#[ cultcache(
type = " epiphany.mind.subgoal.v1 " ,
schema = " EpiphanyMindSubgoalDocument "
) ]
2026-08-14 11:20:56 +02:00
pub struct EpiphanyMindSubgoalDocument {
#[ cultcache(key = 0) ]
pub value : EpiphanySubgoal ,
}
#[ derive(Clone, Debug, PartialEq, DatabaseEntry) ]
2026-08-14 11:52:11 +02:00
#[ cultcache(
type = " epiphany.mind.invariant.v1 " ,
schema = " EpiphanyMindInvariantDocument "
) ]
2026-08-14 11:20:56 +02:00
pub struct EpiphanyMindInvariantDocument {
#[ cultcache(key = 0) ]
pub value : EpiphanyInvariant ,
}
#[ derive(Clone, Debug, PartialEq, DatabaseEntry) ]
2026-08-14 11:52:11 +02:00
#[ cultcache(
type = " epiphany.mind.observation.v1 " ,
schema = " EpiphanyMindObservationDocument "
) ]
2026-08-14 11:20:56 +02:00
pub struct EpiphanyMindObservationDocument {
#[ cultcache(key = 0) ]
pub value : EpiphanyObservation ,
}
#[ derive(Clone, Debug, PartialEq, DatabaseEntry) ]
2026-08-14 11:52:11 +02:00
#[ cultcache(
type = " epiphany.mind.evidence.v1 " ,
schema = " EpiphanyMindEvidenceDocument "
) ]
2026-08-14 11:20:56 +02:00
pub struct EpiphanyMindEvidenceDocument {
#[ cultcache(key = 0) ]
pub value : EpiphanyEvidenceRecord ,
}
#[ derive(Clone, Debug, PartialEq, DatabaseEntry) ]
#[ cultcache(
type = " epiphany.mind.investigation_checkpoint.v1 " ,
schema = " EpiphanyMindInvestigationCheckpointDocument "
) ]
pub struct EpiphanyMindInvestigationCheckpointDocument {
#[ cultcache(key = 0) ]
pub value : EpiphanyInvestigationCheckpoint ,
}
#[ derive(Clone, Debug, PartialEq, DatabaseEntry) ]
2026-08-14 11:52:11 +02:00
#[ cultcache(
type = " epiphany.mind.planning_capture.v1 " ,
schema = " EpiphanyMindPlanningCaptureDocument "
) ]
2026-08-14 11:20:56 +02:00
pub struct EpiphanyMindPlanningCaptureDocument {
#[ cultcache(key = 0) ]
pub value : EpiphanyPlanningCapture ,
}
#[ derive(Clone, Debug, PartialEq, DatabaseEntry) ]
2026-08-14 11:52:11 +02:00
#[ cultcache(
type = " epiphany.mind.backlog_item.v1 " ,
schema = " EpiphanyMindBacklogItemDocument "
) ]
2026-08-14 11:20:56 +02:00
pub struct EpiphanyMindBacklogItemDocument {
#[ cultcache(key = 0) ]
pub value : EpiphanyBacklogItem ,
}
#[ derive(Clone, Debug, PartialEq, DatabaseEntry) ]
2026-08-14 11:52:11 +02:00
#[ cultcache(
type = " epiphany.mind.roadmap_stream.v1 " ,
schema = " EpiphanyMindRoadmapStreamDocument "
) ]
2026-08-14 11:20:56 +02:00
pub struct EpiphanyMindRoadmapStreamDocument {
#[ cultcache(key = 0) ]
pub value : EpiphanyRoadmapStream ,
}
#[ derive(Clone, Debug, PartialEq, DatabaseEntry) ]
2026-08-14 11:52:11 +02:00
#[ cultcache(
type = " epiphany.mind.objective_draft.v1 " ,
schema = " EpiphanyMindObjectiveDraftDocument "
) ]
2026-08-14 11:20:56 +02:00
pub struct EpiphanyMindObjectiveDraftDocument {
#[ cultcache(key = 0) ]
pub value : EpiphanyObjectiveDraft ,
}
#[ derive(Clone, Debug, PartialEq, Serialize, Deserialize) ]
pub struct EpiphanyMindView {
pub projection_digest : String ,
pub source_documents : Vec < EpiphanyMindDocumentVersion > ,
pub objective : Option < String > ,
pub active_subgoal_id : Option < String > ,
pub subgoals : Vec < EpiphanySubgoal > ,
pub invariants : Vec < EpiphanyInvariant > ,
pub observations : Vec < EpiphanyObservation > ,
pub evidence : Vec < EpiphanyEvidenceRecord > ,
pub investigation_checkpoint : Option < EpiphanyInvestigationCheckpoint > ,
pub mode : Option < EpiphanyModeState > ,
pub planning : EpiphanyPlanningState ,
2026-08-14 11:52:11 +02:00
pub repo_model : Option < crate ::EpiphanyRepoModelView > ,
2026-08-14 11:20:56 +02:00
}
pub ( crate ) fn register_mind_document_types ( cache : & mut CultCache ) -> Result < ( ) > {
cache . register_entry_type ::< EpiphanyMindIdentity > ( ) ? ;
cache . register_entry_type ::< EpiphanyMindObjectiveDocument > ( ) ? ;
cache . register_entry_type ::< EpiphanyMindFocusDocument > ( ) ? ;
cache . register_entry_type ::< EpiphanyMindModeDocument > ( ) ? ;
cache . register_entry_type ::< EpiphanyMindSubgoalDocument > ( ) ? ;
cache . register_entry_type ::< EpiphanyMindInvariantDocument > ( ) ? ;
cache . register_entry_type ::< EpiphanyMindObservationDocument > ( ) ? ;
cache . register_entry_type ::< EpiphanyMindEvidenceDocument > ( ) ? ;
cache . register_entry_type ::< EpiphanyMindInvestigationCheckpointDocument > ( ) ? ;
cache . register_entry_type ::< EpiphanyMindPlanningCaptureDocument > ( ) ? ;
cache . register_entry_type ::< EpiphanyMindBacklogItemDocument > ( ) ? ;
cache . register_entry_type ::< EpiphanyMindRoadmapStreamDocument > ( ) ? ;
cache . register_entry_type ::< EpiphanyMindObjectiveDraftDocument > ( ) ? ;
2026-08-14 11:52:11 +02:00
crate ::repo_model_documents ::register_repo_model_document_types ( cache ) ? ;
2026-08-14 16:19:35 +02:00
cache . register_entry_type ::< crate ::RepoFrontierPlanDecisionReceipt > ( ) ? ;
cache . register_entry_type ::< crate ::RepoFrontierRelinquishmentReceipt > ( ) ? ;
cache . register_entry_type ::< crate ::RepoFrontierExecutionAmendmentReceipt > ( ) ? ;
cache . register_entry_type ::< crate ::AtlasSurfaceOffer > ( ) ? ;
cache . register_entry_type ::< crate ::AtlasDependencyClaim > ( ) ? ;
cache . register_entry_type ::< crate ::AtlasDependencyVerification > ( ) ? ;
cache . register_entry_type ::< crate ::AtlasDependencyImpact > ( ) ? ;
2026-08-14 11:20:56 +02:00
Ok ( ( ) )
}
pub ( crate ) fn validate_mind_write_envelope ( envelope : & CultCacheEnvelope ) -> Result < ( ) > {
2026-08-14 11:52:11 +02:00
if let Some ( expected_key ) = crate ::repo_model_documents ::repo_model_write_key ( envelope ) ? {
if envelope . key ! = expected_key {
return Err ( anyhow! (
" RepoModel document semantic identity does not match its envelope key "
) ) ;
}
return Ok ( ( ) ) ;
}
2026-08-14 16:19:35 +02:00
let expected_key = if envelope . r#type = = crate ::RepoFrontierPlanDecisionReceipt ::TYPE {
rmp_serde ::from_slice ::< crate ::RepoFrontierPlanDecisionReceipt > ( & envelope . payload ) ?
. decision_id
} else if envelope . r#type = = crate ::RepoFrontierRelinquishmentReceipt ::TYPE {
rmp_serde ::from_slice ::< crate ::RepoFrontierRelinquishmentReceipt > ( & envelope . payload ) ?
. receipt_id
} else if envelope . r#type = = crate ::RepoFrontierExecutionAmendmentReceipt ::TYPE {
rmp_serde ::from_slice ::< crate ::RepoFrontierExecutionAmendmentReceipt > ( & envelope . payload ) ?
. receipt_id
} else if envelope . r#type = = crate ::AtlasSurfaceOffer ::TYPE {
let value : crate ::AtlasSurfaceOffer = rmp_serde ::from_slice ( & envelope . payload ) ? ;
value . validate ( ) ? ;
value . surface_id . to_string ( )
} else if envelope . r#type = = crate ::AtlasDependencyClaim ::TYPE {
let value : crate ::AtlasDependencyClaim = rmp_serde ::from_slice ( & envelope . payload ) ? ;
value . validate ( ) ? ;
value . claim_id . to_string ( )
} else if envelope . r#type = = crate ::AtlasDependencyVerification ::TYPE {
let value : crate ::AtlasDependencyVerification = rmp_serde ::from_slice ( & envelope . payload ) ? ;
value . validate ( ) ? ;
value . claim_id . to_string ( )
} else if envelope . r#type = = crate ::AtlasDependencyImpact ::TYPE {
let value : crate ::AtlasDependencyImpact = rmp_serde ::from_slice ( & envelope . payload ) ? ;
value . validate ( ) ? ;
value . impact_id . to_string ( )
} else if envelope . r#type = = EpiphanyMindIdentity ::TYPE {
2026-08-14 11:20:56 +02:00
let value : EpiphanyMindIdentity = rmp_serde ::from_slice ( & envelope . payload ) ? ;
if value . schema_epoch ! = MIND_SCHEMA_EPOCH | | value . runtime_id . trim ( ) . is_empty ( ) {
return Err ( anyhow! ( " Mind identity write is invalid " ) ) ;
}
MIND_SCHEMA_EPOCH . to_string ( )
} else if envelope . r#type = = EpiphanyMindObjectiveDocument ::TYPE {
let value : EpiphanyMindObjectiveDocument = rmp_serde ::from_slice ( & envelope . payload ) ? ;
if value . objective . trim ( ) . is_empty ( ) {
return Err ( anyhow! ( " Mind objective cannot be empty " ) ) ;
}
MIND_OBJECTIVE_KEY . to_string ( )
} else if envelope . r#type = = EpiphanyMindFocusDocument ::TYPE {
let _ : EpiphanyMindFocusDocument = rmp_serde ::from_slice ( & envelope . payload ) ? ;
MIND_FOCUS_KEY . to_string ( )
} else if envelope . r#type = = EpiphanyMindModeDocument ::TYPE {
let _ : EpiphanyMindModeDocument = rmp_serde ::from_slice ( & envelope . payload ) ? ;
MIND_MODE_KEY . to_string ( )
} else if envelope . r#type = = EpiphanyMindSubgoalDocument ::TYPE {
2026-08-14 11:52:11 +02:00
rmp_serde ::from_slice ::< EpiphanyMindSubgoalDocument > ( & envelope . payload ) ?
. value
. id
2026-08-14 11:20:56 +02:00
} else if envelope . r#type = = EpiphanyMindInvariantDocument ::TYPE {
2026-08-14 11:52:11 +02:00
rmp_serde ::from_slice ::< EpiphanyMindInvariantDocument > ( & envelope . payload ) ?
. value
. id
2026-08-14 11:20:56 +02:00
} else if envelope . r#type = = EpiphanyMindObservationDocument ::TYPE {
2026-08-14 11:52:11 +02:00
rmp_serde ::from_slice ::< EpiphanyMindObservationDocument > ( & envelope . payload ) ?
. value
. id
2026-08-14 11:20:56 +02:00
} else if envelope . r#type = = EpiphanyMindEvidenceDocument ::TYPE {
2026-08-14 11:52:11 +02:00
rmp_serde ::from_slice ::< EpiphanyMindEvidenceDocument > ( & envelope . payload ) ?
. value
. id
2026-08-14 11:20:56 +02:00
} else if envelope . r#type = = EpiphanyMindInvestigationCheckpointDocument ::TYPE {
rmp_serde ::from_slice ::< EpiphanyMindInvestigationCheckpointDocument > ( & envelope . payload ) ?
. value
. checkpoint_id
} else if envelope . r#type = = EpiphanyMindPlanningCaptureDocument ::TYPE {
2026-08-14 11:52:11 +02:00
rmp_serde ::from_slice ::< EpiphanyMindPlanningCaptureDocument > ( & envelope . payload ) ?
. value
. id
2026-08-14 11:20:56 +02:00
} else if envelope . r#type = = EpiphanyMindBacklogItemDocument ::TYPE {
2026-08-14 11:52:11 +02:00
rmp_serde ::from_slice ::< EpiphanyMindBacklogItemDocument > ( & envelope . payload ) ?
. value
. id
2026-08-14 11:20:56 +02:00
} else if envelope . r#type = = EpiphanyMindRoadmapStreamDocument ::TYPE {
2026-08-14 11:52:11 +02:00
rmp_serde ::from_slice ::< EpiphanyMindRoadmapStreamDocument > ( & envelope . payload ) ?
. value
. id
2026-08-14 11:20:56 +02:00
} else if envelope . r#type = = EpiphanyMindObjectiveDraftDocument ::TYPE {
2026-08-14 11:52:11 +02:00
rmp_serde ::from_slice ::< EpiphanyMindObjectiveDraftDocument > ( & envelope . payload ) ?
. value
. id
2026-08-14 11:20:56 +02:00
} else {
return Err ( anyhow! (
" Mind mutation cannot write non-canonical document type {:?} " ,
envelope . r#type
) ) ;
} ;
if expected_key . trim ( ) . is_empty ( ) | | envelope . key ! = expected_key {
return Err ( anyhow! (
" Mind document semantic identity does not match its envelope key "
) ) ;
}
Ok ( ( ) )
}
pub fn assemble_mind_view ( store_path : impl AsRef < Path > ) -> Result < EpiphanyMindView > {
let mut cache = runtime_spine_cache ( store_path . as_ref ( ) ) ? ;
cache . pull_all_backing_stores ( ) ? ;
let identity = cache
. get ::< EpiphanyMindIdentity > ( MIND_SCHEMA_EPOCH ) ?
. ok_or_else ( | | anyhow! ( " writable Mind store has no v1 identity " ) ) ? ;
if identity . schema_epoch ! = MIND_SCHEMA_EPOCH {
2026-08-14 11:52:11 +02:00
return Err ( anyhow! (
" writable Mind store has an unsupported schema epoch "
) ) ;
2026-08-14 11:20:56 +02:00
}
let objective = cache
. get ::< EpiphanyMindObjectiveDocument > ( MIND_OBJECTIVE_KEY ) ?
. map ( | document | document . objective ) ;
let focus = cache . get ::< EpiphanyMindFocusDocument > ( MIND_FOCUS_KEY ) ? ;
let mode = cache
. get ::< EpiphanyMindModeDocument > ( MIND_MODE_KEY ) ?
. map ( | document | document . mode ) ;
let mut subgoals = values ::< EpiphanyMindSubgoalDocument , _ > ( & cache , | value | value . value ) ? ;
let mut invariants = values ::< EpiphanyMindInvariantDocument , _ > ( & cache , | value | value . value ) ? ;
let mut observations =
values ::< EpiphanyMindObservationDocument , _ > ( & cache , | value | value . value ) ? ;
let mut evidence = values ::< EpiphanyMindEvidenceDocument , _ > ( & cache , | value | value . value ) ? ;
2026-08-14 11:52:11 +02:00
let checkpoints =
values ::< EpiphanyMindInvestigationCheckpointDocument , _ > ( & cache , | value | value . value ) ? ;
2026-08-14 11:20:56 +02:00
let mut captures =
values ::< EpiphanyMindPlanningCaptureDocument , _ > ( & cache , | value | value . value ) ? ;
let mut backlog_items =
values ::< EpiphanyMindBacklogItemDocument , _ > ( & cache , | value | value . value ) ? ;
let mut roadmap_streams =
values ::< EpiphanyMindRoadmapStreamDocument , _ > ( & cache , | value | value . value ) ? ;
let mut objective_drafts =
values ::< EpiphanyMindObjectiveDraftDocument , _ > ( & cache , | value | value . value ) ? ;
2026-08-14 11:52:11 +02:00
let repo_model = if cache
. get ::< crate ::EpiphanyRepoModelIdentityDocument > ( crate ::REPO_MODEL_IDENTITY_KEY ) ?
. is_some ( )
{
Some ( crate ::assemble_repo_model_view ( store_path . as_ref ( ) ) ? )
} else {
None
} ;
2026-08-14 11:20:56 +02:00
subgoals . sort_by ( | left , right | left . id . cmp ( & right . id ) ) ;
invariants . sort_by ( | left , right | left . id . cmp ( & right . id ) ) ;
observations . sort_by ( | left , right | left . id . cmp ( & right . id ) ) ;
evidence . sort_by ( | left , right | left . id . cmp ( & right . id ) ) ;
captures . sort_by ( | left , right | left . id . cmp ( & right . id ) ) ;
backlog_items . sort_by ( | left , right | left . id . cmp ( & right . id ) ) ;
roadmap_streams . sort_by ( | left , right | left . id . cmp ( & right . id ) ) ;
objective_drafts . sort_by ( | left , right | left . id . cmp ( & right . id ) ) ;
let investigation_checkpoint = match focus
. as_ref ( )
. and_then ( | document | document . investigation_checkpoint_id . as_deref ( ) )
{
Some ( id ) = > Some (
checkpoints
. into_iter ( )
. find ( | checkpoint | checkpoint . checkpoint_id = = id )
. ok_or_else ( | | anyhow! ( " Mind focus cites a missing investigation checkpoint " ) ) ? ,
) ,
None = > None ,
} ;
let mut source_documents = canonical_mind_versions ( & cache . snapshot_envelopes ( ) ) ? ;
source_documents . sort_by ( | left , right | {
2026-08-14 11:52:11 +02:00
( & left . document_type , & left . document_key ) . cmp ( & ( & right . document_type , & right . document_key ) )
2026-08-14 11:20:56 +02:00
} ) ;
let projection_digest = digest_versions ( & source_documents ) ? ;
Ok ( EpiphanyMindView {
projection_digest ,
source_documents ,
objective ,
active_subgoal_id : focus . and_then ( | document | document . active_subgoal_id ) ,
subgoals ,
invariants ,
observations ,
evidence ,
investigation_checkpoint ,
mode ,
planning : EpiphanyPlanningState {
workspace_root : None ,
captures ,
backlog_items ,
roadmap_streams ,
objective_drafts ,
} ,
2026-08-14 11:52:11 +02:00
repo_model ,
2026-08-14 11:20:56 +02:00
} )
}
fn values < T , V > ( cache : & CultCache , take : impl Fn ( T ) -> V ) -> Result < Vec < V > >
where
T : DatabaseEntry ,
{
Ok ( cache . get_all ::< T > ( ) ? . into_iter ( ) . map ( take ) . collect ( ) )
}
fn canonical_mind_versions (
envelopes : & [ CultCacheEnvelope ] ,
) -> Result < Vec < EpiphanyMindDocumentVersion > > {
envelopes
. iter ( )
. filter ( | envelope | envelope . r#type . starts_with ( " epiphany.mind. " ) )
. map ( | envelope | EpiphanyMindDocumentVersion ::from_envelope ( " epiphany-mind " , envelope ) )
. collect ( )
}
fn digest_versions ( versions : & [ EpiphanyMindDocumentVersion ] ) -> Result < String > {
let mut digest = Sha256 ::new ( ) ;
digest . update ( b " epiphany.mind_view.v1 \0 " ) ;
digest . update ( rmp_serde ::to_vec_named ( versions ) ? ) ;
Ok ( format! ( " sha256: {:x} " , digest . finalize ( ) ) )
}
#[ cfg(test) ]
mod tests {
use super ::* ;
use crate ::{ RuntimeSpineInitOptions , initialize_runtime_spine } ;
#[ test ]
fn keyed_mind_view_is_deterministic_and_has_no_global_revision ( ) -> Result < ( ) > {
let temp = tempfile ::tempdir ( ) ? ;
let store = temp . path ( ) . join ( " mind.cc " ) ;
initialize_runtime_spine (
& store ,
RuntimeSpineInitOptions {
runtime_id : " mind-view " . into ( ) ,
display_name : " Mind view " . into ( ) ,
created_at : " 2026-08-14T00:00:00Z " . into ( ) ,
} ,
) ? ;
let mut cache = runtime_spine_cache ( & store ) ? ;
cache . put (
MIND_OBJECTIVE_KEY ,
& EpiphanyMindObjectiveDocument {
objective : " Build a concurrent Mind " . into ( ) ,
} ,
) ? ;
for id in [ " subgoal-b " , " subgoal-a " ] {
cache . put (
id ,
& EpiphanyMindSubgoalDocument {
value : EpiphanySubgoal {
id : id . into ( ) ,
title : id . into ( ) ,
status : " active " . into ( ) ,
summary : None ,
} ,
} ,
) ? ;
}
let first = assemble_mind_view ( & store ) ? ;
let second = assemble_mind_view ( & store ) ? ;
assert_eq! ( first , second ) ;
assert_eq! ( first . objective . as_deref ( ) , Some ( " Build a concurrent Mind " ) ) ;
assert_eq! (
first
. subgoals
. iter ( )
. map ( | subgoal | subgoal . id . as_str ( ) )
. collect ::< Vec < _ > > ( ) ,
[ " subgoal-a " , " subgoal-b " ]
) ;
assert! ( first . projection_digest . starts_with ( " sha256: " ) ) ;
Ok ( ( ) )
}
}