apunkt/vestige
1
0
Fork 0
mirror of https://github.com/samvallad33/vestige.git synced 2026-06-20 21:18:08 +02:00
Code Issues Projects Releases Packages Wiki Activity

Add ComposedGraph composition ledger

Browse source
This commit is contained in:
Sam Valladares 2026-06-18 15:59:57 -05:00
parent 16903f3ab4
commit efbea25133
11 changed files with 3375 additions and 59 deletions
Download patch file Download diff file Expand all files Collapse all files

3
README.md
View file

@ -244,7 +244,7 @@ This isn't a key-value store with an embedding model bolted on. Vestige implemen
---
## 🛠 25 MCP Tools
## 🛠 MCP Tools
### Context Packets
| Tool | What It Does |
@ -272,6 +272,7 @@ This isn't a key-value store with an embedding model bolted on. Vestige implemen
|------|-------------|
| `memory_health` | Retention dashboard — distribution, trends, recommendations |
| `memory_graph` | Knowledge graph export — force-directed layout, up to 200 nodes |
| `composed_graph` | Composition ledger — recent composed memory sets, neighbors, outcome labels, bounty/research lanes, and never-composed frontier candidates |
### Scoring & Dedup
| Tool | What It Does |

18
crates/vestige-core/src/lib.rs
View file

@ -155,13 +155,15 @@ pub use fsrs::{
};
// Configuration (vestige.toml output profiles / defaults)
pub use config::{OutputConfig, OutputDefaults, OutputProfile, VestigeConfig, CONFIG_FILE};
pub use config::{CONFIG_FILE, OutputConfig, OutputDefaults, OutputProfile, VestigeConfig};
// Storage layer
pub use storage::{
ConnectionRecord, ConsolidationHistoryRecord, DreamHistoryRecord, InsightRecord,
IntentionRecord, PORTABLE_ARCHIVE_FORMAT, PortableArchive, PortableImportMode,
PortableImportReport, Result, SmartIngestResult, StateTransitionRecord, Storage, StorageError,
CompositionEventRecord, CompositionMemberRecord, CompositionNeighborRecord,
CompositionOutcomeRecord, ConnectionRecord, ConsolidationHistoryRecord, DreamHistoryRecord,
InsightRecord, IntentionRecord, NeverComposedCandidate, PORTABLE_ARCHIVE_FORMAT,
PortableArchive, PortableImportMode, PortableImportReport, Result, SmartIngestResult,
StateTransitionRecord, Storage, StorageError,
};
// Consolidation (sleep-inspired memory processing)
@ -220,6 +222,9 @@ pub use advanced::{
LabileState,
Language,
MaintenanceType,
// Merge / Supersede controls (Phase 3)
MatchClass,
MatchSignals,
// Memory chains
MemoryChainBuilder,
// Memory compression
@ -230,18 +235,15 @@ pub use advanced::{
MemoryPath,
MemoryReplay,
MemorySnapshot,
// Merge / Supersede controls (Phase 3)
MatchClass,
MatchSignals,
MergeCandidate,
MergeOperation,
MergePlan,
MergePolicy,
MergeStrategy,
Modification,
PlanKind,
Pattern,
PatternType,
PlanKind,
PredictedMemory,
PredictionContext,
PredictionErrorConfig,

98
crates/vestige-core/src/storage/migrations.rs
View file

@ -74,6 +74,11 @@ pub const MIGRATIONS: &[Migration] = &[
description: "v2.1.25 Merge/Supersede: reversible operation log, merge plans, bitemporal lineage, protected pins",
up: MIGRATION_V14_UP,
},
Migration {
version: 15,
description: "ComposedGraph: composition events, members, outcomes",
up: MIGRATION_V15_UP,
},
];
/// A database migration
@ -813,6 +818,67 @@ CREATE INDEX IF NOT EXISTS idx_merge_operations_survivor ON merge_operations(sur
UPDATE schema_version SET version = 14, applied_at = datetime('now');
"#;
/// V15: ComposedGraph persistence for memory composition outcomes.
///
/// These tables record which memories were used together, which tool/query
/// produced the composition, and what happened afterward. `memory_id` values
/// are intentionally historical references instead of foreign keys to
/// `knowledge_nodes`: purging or superseding a memory must not erase the fact
/// that a bounty lane or reasoning path was previously composed.
const MIGRATION_V15_UP: &str = r#"
CREATE TABLE IF NOT EXISTS composition_events (
id TEXT PRIMARY KEY,
created_at TEXT NOT NULL,
tool TEXT NOT NULL,
mode TEXT NOT NULL DEFAULT 'deep_reference',
query TEXT,
query_hash TEXT,
confidence REAL,
status TEXT,
output_preview TEXT,
metadata TEXT NOT NULL DEFAULT '{}'
);
CREATE INDEX IF NOT EXISTS idx_composition_events_created_at ON composition_events(created_at);
CREATE INDEX IF NOT EXISTS idx_composition_events_tool ON composition_events(tool);
CREATE INDEX IF NOT EXISTS idx_composition_events_mode ON composition_events(mode);
CREATE INDEX IF NOT EXISTS idx_composition_events_query_hash ON composition_events(query_hash);
CREATE TABLE IF NOT EXISTS composition_members (
event_id TEXT NOT NULL,
memory_id TEXT NOT NULL,
role TEXT NOT NULL, -- primary | supporting | contradicting | superseded | related
rank INTEGER NOT NULL DEFAULT 0,
trust REAL,
score REAL,
preview TEXT,
metadata TEXT NOT NULL DEFAULT '{}',
PRIMARY KEY (event_id, memory_id, role),
FOREIGN KEY (event_id) REFERENCES composition_events(id) ON DELETE CASCADE
);
CREATE INDEX IF NOT EXISTS idx_composition_members_memory ON composition_members(memory_id);
CREATE INDEX IF NOT EXISTS idx_composition_members_role ON composition_members(role);
CREATE TABLE IF NOT EXISTS composition_outcomes (
id TEXT PRIMARY KEY,
event_id TEXT NOT NULL,
outcome_type TEXT NOT NULL,
labeled_at TEXT NOT NULL,
label_source TEXT NOT NULL DEFAULT 'tool',
confidence_delta REAL,
notes TEXT,
metadata TEXT NOT NULL DEFAULT '{}',
FOREIGN KEY (event_id) REFERENCES composition_events(id) ON DELETE CASCADE
);
CREATE INDEX IF NOT EXISTS idx_composition_outcomes_event ON composition_outcomes(event_id);
CREATE INDEX IF NOT EXISTS idx_composition_outcomes_type ON composition_outcomes(outcome_type);
CREATE INDEX IF NOT EXISTS idx_composition_outcomes_labeled_at ON composition_outcomes(labeled_at);
UPDATE schema_version SET version = 15, applied_at = datetime('now');
"#;
/// Get current schema version from database
pub fn get_current_version(conn: &rusqlite::Connection) -> rusqlite::Result<u32> {
conn.query_row(
@ -829,7 +895,9 @@ pub fn get_current_version(conn: &rusqlite::Connection) -> rusqlite::Result<u32>
fn add_column_if_missing(conn: &rusqlite::Connection, sql: &str) -> rusqlite::Result<()> {
match conn.execute(sql, []) {
Ok(_) => Ok(()),
Err(rusqlite::Error::SqliteFailure(_, Some(msg))) if msg.contains("duplicate column name") => {
Err(rusqlite::Error::SqliteFailure(_, Some(msg)))
if msg.contains("duplicate column name") =>
{
Ok(())
}
Err(e) => Err(e),
@ -890,17 +958,17 @@ mod tests {
/// version after `apply_migrations` runs all migrations end-to-end, and
/// neither of the dead tables V11 drops must exist afterwards.
#[test]
fn test_apply_migrations_advances_to_v14_and_drops_dead_tables() {
fn test_apply_migrations_advances_to_v15_and_drops_dead_tables() {
let conn = rusqlite::Connection::open_in_memory().expect("open in-memory");
// Pre-requisite: schema_version must be bootstrapped by V1.
apply_migrations(&conn).expect("apply_migrations succeeds");
// 1. schema_version advanced to V14
// 1. schema_version advanced to V15
let version = get_current_version(&conn).expect("read schema_version");
assert_eq!(
version, 14,
"schema_version must be 14 after all migrations"
version, 15,
"schema_version must be 15 after all migrations"
);
// 2. knowledge_edges is gone (V11 drops it)
@ -967,7 +1035,23 @@ mod tests {
assert_eq!(rows, 1, "{table} table must be created by V14");
}
// 7. knowledge_nodes gains `protected` + `superseded_by` (V14)
// 7. ComposedGraph tables exist (V15)
for table in [
"composition_events",
"composition_members",
"composition_outcomes",
] {
let rows: i64 = conn
.query_row(
"SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=?1",
[table],
|row| row.get(0),
)
.expect("query sqlite_master");
assert_eq!(rows, 1, "{table} table must be created by V15");
}
// 8. knowledge_nodes gains `protected` + `superseded_by` (V14)
let node_cols: Vec<String> = {
let mut stmt = conn
.prepare("PRAGMA table_info(knowledge_nodes)")
@ -1006,6 +1090,6 @@ mod tests {
apply_migrations(&conn).expect("V11 replay must be idempotent");
let version = get_current_version(&conn).expect("read schema_version");
assert_eq!(version, 14, "schema_version back at 14 after replay");
assert_eq!(version, 15, "schema_version back at 15 after replay");
}
}

8
crates/vestige-core/src/storage/mod.rs
View file

@ -16,7 +16,9 @@ pub use portable::{
PortableTable, PortableValue,
};
pub use sqlite::{
ConnectionRecord, ConsolidationHistoryRecord, DreamHistoryRecord, FilePortableSyncBackend,
InsightRecord, IntentionRecord, PortableSyncBackend, PortableSyncReport, Result,
SmartIngestResult, StateTransitionRecord, Storage, StorageError,
CompositionEventRecord, CompositionMemberRecord, CompositionNeighborRecord,
CompositionOutcomeRecord, ConnectionRecord, ConsolidationHistoryRecord, DreamHistoryRecord,
FilePortableSyncBackend, InsightRecord, IntentionRecord, NeverComposedCandidate,
PortableSyncBackend, PortableSyncReport, Result, SmartIngestResult, StateTransitionRecord,
Storage, StorageError,
};

1968
crates/vestige-core/src/storage/sqlite.rs
View file

File diff suppressed because it is too large Load diff

2
crates/vestige-mcp/README.md
View file

@ -61,7 +61,7 @@ The server exposes the current unified MCP tools from
- `search`, `smart_ingest`, `memory`, `codebase`, `intention`
- `deep_reference`, `cross_reference`, `contradictions`
- `dream`, `explore_connections`, `predict`
- `memory_health`, `memory_graph`, `system_status`
- `memory_health`, `memory_graph`, `composed_graph`, `system_status`
- `importance_score`, `find_duplicates`
- `consolidate`, `memory_timeline`, `memory_changelog`
- `backup`, `export`, `restore`, `gc`, `suppress`

19
crates/vestige-mcp/src/server.rs
View file

@ -443,6 +443,12 @@ impl McpServer {
input_schema: tools::graph::schema(),
..Default::default()
},
ToolDescription {
name: "composed_graph".to_string(),
description: Some("ComposedGraph memory topology. Reads durable composition events, members, and outcome labels; returns recent/already-composed lanes, neighbors, never-composed pairs, bounty-mode lanes, and lets users label outcomes such as helpful, submitted, accepted, rejected, duplicate_risk, needs_poc, or dead_end.".to_string()),
input_schema: tools::composed_graph::schema(),
..Default::default()
},
// ================================================================
// DEEP REFERENCE (v2.0.4+) — replaces cross_reference
// ================================================================
@ -959,7 +965,8 @@ impl McpServer {
// TEMPORAL TOOLS (v1.2+)
// ================================================================
"memory_timeline" => {
tools::timeline::execute(&self.storage, &self.output_config, request.arguments).await
tools::timeline::execute(&self.storage, &self.output_config, request.arguments)
.await
}
"memory_changelog" => tools::changelog::execute(&self.storage, request.arguments).await,
@ -1032,6 +1039,9 @@ impl McpServer {
// ================================================================
"memory_health" => tools::health::execute(&self.storage, request.arguments).await,
"memory_graph" => tools::graph::execute(&self.storage, request.arguments).await,
"composed_graph" => {
tools::composed_graph::execute(&self.storage, request.arguments).await
}
"deep_reference" | "cross_reference" => {
tools::cross_reference::execute(&self.storage, &self.cognitive, request.arguments)
.await
@ -1796,10 +1806,10 @@ mod tests {
let result = response.result.unwrap();
let tools = result["tools"].as_array().unwrap();
// v2.1.25: 32 tools (25 from v2.1.21 + 7 Phase 3 merge/supersede tools:
// 33 tools: 25 from v2.1.21 + 7 Phase 3 merge/supersede tools:
// merge_candidates, plan_merge, plan_supersede, apply_plan, merge_undo,
// protect, merge_policy)
assert_eq!(tools.len(), 32, "Expected exactly 32 tools in v2.1.25");
// protect, merge_policy, composed_graph)
assert_eq!(tools.len(), 33, "Expected exactly 33 tools");
let tool_names: Vec<&str> = tools.iter().map(|t| t["name"].as_str().unwrap()).collect();
@ -1874,6 +1884,7 @@ mod tests {
// Autonomic tools (v1.9)
assert!(tool_names.contains(&"memory_health"));
assert!(tool_names.contains(&"memory_graph"));
assert!(tool_names.contains(&"composed_graph"));
// Deep reference + cross_reference alias (v2.0.4)
assert!(tool_names.contains(&"deep_reference"));

906
crates/vestige-mcp/src/tools/composed_graph.rs Normal file
View file

@ -0,0 +1,906 @@
//! composed_graph tool — durable composition history and bounty-mode lane queue.
use chrono::Utc;
use serde::Deserialize;
use serde_json::Value;
use std::sync::Arc;
use uuid::Uuid;
use vestige_core::{CompositionOutcomeRecord, Storage};
const OUTCOME_TYPES: &[&str] = &[
"helpful",
"dead_end",
"submitted",
"accepted",
"rejected",
"duplicate_risk",
"needs_poc",
"bad_severity",
"user_promoted",
"user_demoted",
"closed_by_scope",
"closed_by_duplicate",
"closed_by_false_assumption",
"closed_by_user",
"expired_lane",
];
pub fn schema() -> Value {
serde_json::json!({
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": ["recent", "get", "memory", "neighbors", "never_composed", "bounty_mode", "label"],
"description": "ComposedGraph action to run."
},
"event_id": {
"type": "string",
"description": "Composition event id for get/label actions."
},
"memory_id": {
"type": "string",
"description": "Memory id for memory/neighbors actions."
},
"limit": {
"type": "integer",
"description": "Maximum rows to return (default 10, max 100).",
"default": 10,
"minimum": 1,
"maximum": 100
},
"tags": {
"type": "array",
"items": { "type": "string" },
"description": "Optional tag filter for never_composed and bounty_mode."
},
"outcome_type": {
"type": "string",
"enum": ["helpful", "dead_end", "submitted", "accepted", "rejected", "duplicate_risk", "needs_poc", "bad_severity", "user_promoted", "user_demoted", "closed_by_scope", "closed_by_duplicate", "closed_by_false_assumption", "closed_by_user", "expired_lane"],
"description": "Outcome label for label action."
},
"notes": {
"type": "string",
"description": "Optional outcome notes."
},
"label_source": {
"type": "string",
"description": "Where the outcome label came from (default: user)."
},
"confidence_delta": {
"type": "number",
"description": "Optional confidence adjustment for this outcome."
}
},
"required": ["action"]
})
}
#[derive(Debug, Deserialize)]
#[serde(rename_all = "snake_case")]
struct ComposedGraphArgs {
action: String,
event_id: Option<String>,
memory_id: Option<String>,
limit: Option<i32>,
tags: Option<Vec<String>>,
outcome_type: Option<String>,
notes: Option<String>,
label_source: Option<String>,
confidence_delta: Option<f64>,
}
pub async fn execute(storage: &Arc<Storage>, args: Option<Value>) -> Result<Value, String> {
let args: ComposedGraphArgs = match args {
Some(value) => {
serde_json::from_value(value).map_err(|e| format!("Invalid arguments: {}", e))?
}
None => return Err("Missing arguments".to_string()),
};
let limit = args.limit.unwrap_or(10).clamp(1, 100);
match args.action.as_str() {
"recent" => recent(storage, limit),
"get" => {
let event_id = args
.event_id
.as_deref()
.ok_or_else(|| "event_id is required for get".to_string())?;
get(storage, event_id)
}
"memory" => {
let memory_id = args
.memory_id
.as_deref()
.ok_or_else(|| "memory_id is required for memory".to_string())?;
memory(storage, memory_id, limit)
}
"neighbors" => {
let memory_id = args
.memory_id
.as_deref()
.ok_or_else(|| "memory_id is required for neighbors".to_string())?;
neighbors(storage, memory_id, limit)
}
"never_composed" => never_composed(storage, limit, args.tags.as_deref()),
"bounty_mode" => bounty_mode(storage, limit, args.tags.as_deref()),
"label" => label(storage, &args),
other => Err(format!("Unknown composed_graph action: {}", other)),
}
}
fn recent(storage: &Storage, limit: i32) -> Result<Value, String> {
let events = storage
.get_recent_composition_events(limit)
.map_err(|e| e.to_string())?;
Ok(serde_json::json!({
"action": "recent",
"events": events,
}))
}
fn get(storage: &Storage, event_id: &str) -> Result<Value, String> {
let event = storage
.get_composition_event(event_id)
.map_err(|e| e.to_string())?
.ok_or_else(|| format!("composition event not found: {}", event_id))?;
let members = storage
.get_composition_members(event_id)
.map_err(|e| e.to_string())?;
let outcomes = storage
.get_composition_outcomes(event_id)
.map_err(|e| e.to_string())?;
Ok(serde_json::json!({
"action": "get",
"event": event,
"members": members,
"outcomes": outcomes,
}))
}
fn memory(storage: &Storage, memory_id: &str, limit: i32) -> Result<Value, String> {
let events = storage
.get_compositions_for_memory(memory_id, limit)
.map_err(|e| e.to_string())?;
Ok(serde_json::json!({
"action": "memory",
"memoryId": memory_id,
"events": events,
}))
}
fn neighbors(storage: &Storage, memory_id: &str, limit: i32) -> Result<Value, String> {
let neighbors = storage
.get_composition_neighbors(memory_id, limit)
.map_err(|e| e.to_string())?;
Ok(serde_json::json!({
"action": "neighbors",
"memoryId": memory_id,
"neighbors": neighbors,
}))
}
fn never_composed(storage: &Storage, limit: i32, tags: Option<&[String]>) -> Result<Value, String> {
let candidates = storage
.get_never_composed_candidates(limit, tags)
.map_err(|e| e.to_string())?;
Ok(serde_json::json!({
"action": "never_composed",
"candidates": candidates,
}))
}
fn bounty_mode(storage: &Storage, limit: i32, tags: Option<&[String]>) -> Result<Value, String> {
const PAGE_SIZE: i32 = 100;
const MAX_SCAN_EVENTS: i32 = 1_000;
let mut offset = 0;
let mut scanned = 0;
let mut already_composed = Vec::new();
let mut closed_doors = Vec::new();
let mut duplicate_risk_lanes = Vec::new();
let mut needs_poc_lanes = Vec::new();
loop {
let events = storage
.get_recent_composition_events_page(PAGE_SIZE, offset)
.map_err(|e| e.to_string())?;
if events.is_empty() {
break;
}
scanned += events.len() as i32;
for event in events {
let outcomes = storage
.get_composition_outcomes(&event.id)
.map_err(|e| e.to_string())?;
let members = storage
.get_composition_members(&event.id)
.map_err(|e| e.to_string())?;
if !composition_matches_tags(storage, &event, &members, tags)? {
continue;
}
let item = serde_json::json!({
"event": event,
"members": members,
"outcomes": outcomes,
});
let outcome_types = item["outcomes"]
.as_array()
.map(|values| {
values
.iter()
.filter_map(|value| value.get("outcomeType").and_then(|v| v.as_str()))
.collect::<Vec<_>>()
})
.unwrap_or_default();
if outcome_types.iter().any(|kind| {
matches!(
*kind,
"dead_end"
| "rejected"
| "bad_severity"
| "closed_by_scope"
| "closed_by_duplicate"
| "closed_by_false_assumption"
| "closed_by_user"
| "expired_lane"
)
}) {
push_limited(&mut closed_doors, item.clone(), limit);
}
if outcome_types
.iter()
.any(|kind| matches!(*kind, "duplicate_risk" | "closed_by_duplicate"))
{
push_limited(&mut duplicate_risk_lanes, item.clone(), limit);
}
if outcome_types.iter().any(|kind| *kind == "needs_poc") {
push_limited(&mut needs_poc_lanes, item.clone(), limit);
}
if already_composed.len() < limit as usize {
already_composed.push(item);
}
if bounty_mode_lanes_full(
limit,
&already_composed,
&closed_doors,
&duplicate_risk_lanes,
&needs_poc_lanes,
) {
break;
}
}
if bounty_mode_lanes_full(
limit,
&already_composed,
&closed_doors,
&duplicate_risk_lanes,
&needs_poc_lanes,
) || scanned >= MAX_SCAN_EVENTS
{
break;
}
offset += PAGE_SIZE;
}
let never = storage
.get_never_composed_candidates(limit, tags)
.map_err(|e| e.to_string())?;
let top_weird_combinations = never.iter().take(3).cloned().collect::<Vec<_>>();
Ok(serde_json::json!({
"action": "bounty_mode",
"alreadyComposedLanes": already_composed,
"neverComposedLanes": never,
"closedDoors": closed_doors,
"duplicateRiskLanes": duplicate_risk_lanes,
"needsPocLanes": needs_poc_lanes,
"topWeirdCombinations": top_weird_combinations,
"guardrails": [
"never-composed lane is not a finding",
"composition score is not severity",
"submit/reportable still needs source refs, scope fit, and PoC evidence"
]
}))
}
fn push_limited(items: &mut Vec<Value>, item: Value, limit: i32) {
if items.len() < limit as usize {
items.push(item);
}
}
fn bounty_mode_lanes_full(
limit: i32,
already_composed: &[Value],
closed_doors: &[Value],
duplicate_risk_lanes: &[Value],
needs_poc_lanes: &[Value],
) -> bool {
let limit = limit as usize;
already_composed.len() >= limit
&& closed_doors.len() >= limit
&& duplicate_risk_lanes.len() >= limit
&& needs_poc_lanes.len() >= limit
}
fn composition_matches_tags(
storage: &Storage,
event: &vestige_core::CompositionEventRecord,
members: &[vestige_core::CompositionMemberRecord],
tags: Option<&[String]>,
) -> Result<bool, String> {
let Some(tags) = tags else {
return Ok(true);
};
if tags.is_empty() {
return Ok(true);
}
if json_value_has_tag(&event.metadata, tags) {
return Ok(true);
}
for member in members {
if json_value_has_tag(&member.metadata, tags) {
return Ok(true);
}
if let Some(node) = storage
.get_node(&member.memory_id)
.map_err(|e| e.to_string())?
&& node.tags.iter().any(|tag| tag_matches_filter(tag, tags))
{
return Ok(true);
}
}
Ok(false)
}
fn json_value_has_tag(value: &Value, tags: &[String]) -> bool {
value
.get("tags")
.and_then(|tags_value| tags_value.as_array())
.is_some_and(|values| {
values.iter().any(|value| {
value
.as_str()
.is_some_and(|tag| tag_matches_filter(tag, tags))
})
})
}
fn tag_matches_filter(tag: &str, filters: &[String]) -> bool {
filters
.iter()
.any(|wanted| tag == wanted || tag.starts_with(&format!("{wanted}:")))
}
fn label(storage: &Storage, args: &ComposedGraphArgs) -> Result<Value, String> {
let event_id = args
.event_id
.as_deref()
.ok_or_else(|| "event_id is required for label".to_string())?;
let outcome_type = args
.outcome_type
.as_deref()
.ok_or_else(|| "outcome_type is required for label".to_string())?;
if !OUTCOME_TYPES.contains(&outcome_type) {
return Err(format!("unsupported outcome_type: {}", outcome_type));
}
if storage
.get_composition_event(event_id)
.map_err(|e| e.to_string())?
.is_none()
{
return Err(format!("composition event not found: {}", event_id));
}
let outcome = CompositionOutcomeRecord {
id: Uuid::new_v4().to_string(),
event_id: event_id.to_string(),
outcome_type: outcome_type.to_string(),
labeled_at: Utc::now(),
label_source: args
.label_source
.clone()
.unwrap_or_else(|| "user".to_string()),
confidence_delta: args.confidence_delta,
notes: args.notes.clone(),
metadata: serde_json::json!({}),
};
storage
.record_composition_outcome(&outcome)
.map_err(|e| e.to_string())?;
Ok(serde_json::json!({
"action": "label",
"eventId": event_id,
"outcome": outcome,
}))
}
#[cfg(test)]
mod tests {
use super::*;
use tempfile::TempDir;
use vestige_core::{
CompositionEventRecord, CompositionMemberRecord, CompositionOutcomeRecord, IngestInput,
};
fn test_storage() -> (Arc<Storage>, TempDir) {
let dir = TempDir::new().unwrap();
let storage = Storage::new(Some(dir.path().join("test.db"))).unwrap();
(Arc::new(storage), dir)
}
fn ingest(storage: &Storage, content: &str, tags: &[&str]) -> String {
storage
.ingest(IngestInput {
content: content.to_string(),
node_type: "fact".to_string(),
tags: tags.iter().map(|tag| tag.to_string()).collect(),
..Default::default()
})
.unwrap()
.id
}
#[tokio::test]
async fn test_composed_graph_get_label_and_bounty_mode() {
let (storage, _dir) = test_storage();
let first = ingest(
&storage,
"Oracle drift bounty lane",
&["protocolgate", "boundary-oracle", "settlement"],
);
let second = ingest(
&storage,
"Withdrawal queue bounty lane",
&["protocolgate", "boundary-queue", "settlement"],
);
let third = ingest(
&storage,
"Keeper role bounty lane",
&["protocolgate", "boundary-role", "settlement"],
);
let event = CompositionEventRecord {
id: "composed-graph-test".to_string(),
created_at: Utc::now(),
tool: "deep_reference".to_string(),
mode: "bounty".to_string(),
query: Some("oracle withdrawal".to_string()),
query_hash: Some("test".to_string()),
confidence: Some(0.8),
status: Some("resolved".to_string()),
output_preview: Some("compose oracle and withdrawal queue".to_string()),
metadata: serde_json::json!({}),
};
storage
.save_composition(
&event,
&[
CompositionMemberRecord {
event_id: event.id.clone(),
memory_id: first.clone(),
role: "primary".to_string(),
rank: 0,
trust: Some(0.8),
score: Some(0.9),
preview: None,
metadata: serde_json::json!({}),
},
CompositionMemberRecord {
event_id: event.id.clone(),
memory_id: second.clone(),
role: "supporting".to_string(),
rank: 1,
trust: Some(0.7),
score: Some(0.8),
preview: None,
metadata: serde_json::json!({}),
},
],
&[],
)
.unwrap();
let unrelated = ingest(&storage, "Personal planning lane", &["personal"]);
storage
.save_composition(
&CompositionEventRecord {
id: "unrelated-composed-graph-test".to_string(),
created_at: Utc::now() + chrono::Duration::seconds(10),
tool: "deep_reference".to_string(),
mode: "planning".to_string(),
query: Some("personal planning".to_string()),
query_hash: Some("unrelated".to_string()),
confidence: Some(0.4),
status: Some("resolved".to_string()),
output_preview: Some("unrelated composition".to_string()),
metadata: serde_json::json!({}),
},
&[CompositionMemberRecord {
event_id: "unrelated-composed-graph-test".to_string(),
memory_id: unrelated,
role: "primary".to_string(),
rank: 0,
trust: Some(0.4),
score: Some(0.2),
preview: None,
metadata: serde_json::json!({}),
}],
&[CompositionOutcomeRecord {
id: "unrelated-composed-graph-outcome".to_string(),
event_id: "unrelated-composed-graph-test".to_string(),
outcome_type: "needs_poc".to_string(),
labeled_at: Utc::now(),
label_source: "test".to_string(),
confidence_delta: None,
notes: None,
metadata: serde_json::json!({}),
}],
)
.unwrap();
let get_result = execute(
&storage,
Some(serde_json::json!({
"action": "get",
"event_id": event.id
})),
)
.await
.unwrap();
assert_eq!(get_result["members"].as_array().unwrap().len(), 2);
let label_result = execute(
&storage,
Some(serde_json::json!({
"action": "label",
"event_id": "composed-graph-test",
"outcome_type": "submitted",
"notes": "submitted in test"
})),
)
.await
.unwrap();
assert_eq!(
label_result["outcome"]["outcomeType"].as_str(),
Some("submitted")
);
let closed_label_result = execute(
&storage,
Some(serde_json::json!({
"action": "label",
"event_id": "composed-graph-test",
"outcome_type": "closed_by_scope",
"notes": "closed in test"
})),
)
.await
.unwrap();
assert_eq!(
closed_label_result["outcome"]["outcomeType"].as_str(),
Some("closed_by_scope")
);
let duplicate_label_result = execute(
&storage,
Some(serde_json::json!({
"action": "label",
"event_id": "composed-graph-test",
"outcome_type": "closed_by_duplicate",
"notes": "duplicate family in test"
})),
)
.await
.unwrap();
assert_eq!(
duplicate_label_result["outcome"]["outcomeType"].as_str(),
Some("closed_by_duplicate")
);
let bounty = execute(
&storage,
Some(serde_json::json!({
"action": "bounty_mode",
"tags": ["protocolgate"],
"limit": 1
})),
)
.await
.unwrap();
let already = bounty["alreadyComposedLanes"].as_array().unwrap();
assert_eq!(already.len(), 1);
assert!(
already[0]["event"]["id"].as_str() == Some("composed-graph-test"),
"tag-scoped bounty_mode should skip newer unrelated events before truncating"
);
assert_eq!(bounty["closedDoors"].as_array().unwrap().len(), 1);
assert_eq!(bounty["duplicateRiskLanes"].as_array().unwrap().len(), 1);
assert!(bounty["needsPocLanes"].as_array().unwrap().is_empty());
assert!(
bounty["neverComposedLanes"]
.as_array()
.unwrap()
.iter()
.any(|candidate| {
let first_id = candidate["firstId"].as_str().unwrap_or_default();
let second_id = candidate["secondId"].as_str().unwrap_or_default();
[first_id, second_id].contains(&third.as_str())
})
);
}
#[tokio::test]
async fn test_bounty_mode_paginates_tag_filter_and_matches_namespaced_tags() {
let (storage, _dir) = test_storage();
let tagged = ingest(
&storage,
"Older tagged composition lane",
&["project:vestige", "composition"],
);
let unrelated = ingest(&storage, "Newer unrelated lane", &["unrelated"]);
let base_time = Utc::now();
storage
.save_composition(
&CompositionEventRecord {
id: "older-tagged-composition".to_string(),
created_at: base_time,
tool: "deep_reference".to_string(),
mode: "research".to_string(),
query: Some("older tagged lane".to_string()),
query_hash: Some("fnv1a64:older".to_string()),
confidence: Some(0.8),
status: Some("resolved".to_string()),
output_preview: None,
metadata: serde_json::json!({}),
},
&[CompositionMemberRecord {
event_id: "older-tagged-composition".to_string(),
memory_id: tagged,
role: "primary".to_string(),
rank: 0,
trust: Some(0.8),
score: Some(0.9),
preview: None,
metadata: serde_json::json!({}),
}],
&[],
)
.unwrap();
for idx in 0..101 {
let event_id = format!("newer-unrelated-composition-{idx}");
storage
.save_composition(
&CompositionEventRecord {
id: event_id.clone(),
created_at: base_time + chrono::Duration::seconds(i64::from(idx + 1)),
tool: "deep_reference".to_string(),
mode: "planning".to_string(),
query: Some(format!("newer unrelated lane {idx}")),
query_hash: Some(format!("fnv1a64:newer-{idx}")),
confidence: Some(0.3),
status: Some("resolved".to_string()),
output_preview: None,
metadata: serde_json::json!({}),
},
&[CompositionMemberRecord {
event_id,
memory_id: unrelated.clone(),
role: "primary".to_string(),
rank: 0,
trust: Some(0.3),
score: Some(0.2),
preview: None,
metadata: serde_json::json!({}),
}],
&[],
)
.unwrap();
}
let bounty = execute(
&storage,
Some(serde_json::json!({
"action": "bounty_mode",
"tags": ["project"],
"limit": 1
})),
)
.await
.unwrap();
let already = bounty["alreadyComposedLanes"].as_array().unwrap();
assert_eq!(already.len(), 1);
assert_eq!(
already[0]["event"]["id"].as_str(),
Some("older-tagged-composition"),
"tag-filtered bounty_mode should page past newer unrelated events and match namespaced tags"
);
}
#[tokio::test]
async fn test_bounty_mode_uses_member_tag_snapshot_after_purge() {
let (storage, _dir) = test_storage();
let tagged = ingest(
&storage,
"Tagged member that will be purged",
&["project:vestige", "composition"],
);
storage
.save_composition(
&CompositionEventRecord {
id: "purged-tagged-member-composition".to_string(),
created_at: Utc::now(),
tool: "deep_reference".to_string(),
mode: "research".to_string(),
query: Some("purged tagged lane".to_string()),
query_hash: Some("fnv1a64:purged".to_string()),
confidence: Some(0.6),
status: Some("closed".to_string()),
output_preview: None,
metadata: serde_json::json!({}),
},
&[CompositionMemberRecord {
event_id: "purged-tagged-member-composition".to_string(),
memory_id: tagged.clone(),
role: "primary".to_string(),
rank: 0,
trust: Some(0.7),
score: Some(0.8),
preview: Some("Tagged member that will be purged".to_string()),
metadata: serde_json::json!({}),
}],
&[CompositionOutcomeRecord {
id: "purged-tagged-member-outcome".to_string(),
event_id: "purged-tagged-member-composition".to_string(),
outcome_type: "closed_by_scope".to_string(),
labeled_at: Utc::now(),
label_source: "test".to_string(),
confidence_delta: Some(-0.2),
notes: None,
metadata: serde_json::json!({}),
}],
)
.unwrap();
storage
.purge_node(&tagged, Some("test purge"))
.expect("purge should succeed");
let get_result = execute(
&storage,
Some(serde_json::json!({
"action": "get",
"event_id": "purged-tagged-member-composition"
})),
)
.await
.unwrap();
assert!(
get_result["members"][0].get("preview").is_none()
|| get_result["members"][0]["preview"].is_null(),
"purge should scrub member preview from composed_graph get"
);
let bounty = execute(
&storage,
Some(serde_json::json!({
"action": "bounty_mode",
"tags": ["project"],
"limit": 1
})),
)
.await
.unwrap();
let already = bounty["alreadyComposedLanes"].as_array().unwrap();
assert_eq!(already.len(), 1);
assert_eq!(
already[0]["event"]["id"].as_str(),
Some("purged-tagged-member-composition"),
"tag-filtered bounty_mode should use composition member tag snapshots after source memory purge"
);
assert_eq!(bounty["closedDoors"].as_array().unwrap().len(), 1);
}
#[tokio::test]
async fn test_bounty_mode_guardrail_buckets_are_not_truncated_by_already_limit() {
let (storage, _dir) = test_storage();
let neutral = ingest(&storage, "Neutral release lane", &["project:vestige"]);
let closed = ingest(&storage, "Closed release lane", &["project:vestige"]);
let base_time = Utc::now();
storage
.save_composition(
&CompositionEventRecord {
id: "older-closed-lane".to_string(),
created_at: base_time,
tool: "deep_reference".to_string(),
mode: "release".to_string(),
query: Some("older closed lane".to_string()),
query_hash: Some("fnv1a64:older-closed".to_string()),
confidence: Some(0.3),
status: Some("closed".to_string()),
output_preview: None,
metadata: serde_json::json!({}),
},
&[CompositionMemberRecord {
event_id: "older-closed-lane".to_string(),
memory_id: closed,
role: "primary".to_string(),
rank: 0,
trust: Some(0.5),
score: Some(0.4),
preview: None,
metadata: serde_json::json!({}),
}],
&[CompositionOutcomeRecord {
id: "older-closed-outcome".to_string(),
event_id: "older-closed-lane".to_string(),
outcome_type: "closed_by_false_assumption".to_string(),
labeled_at: base_time,
label_source: "test".to_string(),
confidence_delta: Some(-0.3),
notes: None,
metadata: serde_json::json!({}),
}],
)
.unwrap();
storage
.save_composition(
&CompositionEventRecord {
id: "newer-neutral-lane".to_string(),
created_at: base_time + chrono::Duration::seconds(1),
tool: "deep_reference".to_string(),
mode: "release".to_string(),
query: Some("newer neutral lane".to_string()),
query_hash: Some("fnv1a64:newer-neutral".to_string()),
confidence: Some(0.7),
status: Some("resolved".to_string()),
output_preview: None,
metadata: serde_json::json!({}),
},
&[CompositionMemberRecord {
event_id: "newer-neutral-lane".to_string(),
memory_id: neutral,
role: "primary".to_string(),
rank: 0,
trust: Some(0.8),
score: Some(0.8),
preview: None,
metadata: serde_json::json!({}),
}],
&[],
)
.unwrap();
let bounty = execute(
&storage,
Some(serde_json::json!({
"action": "bounty_mode",
"tags": ["project"],
"limit": 1
})),
)
.await
.unwrap();
assert_eq!(
bounty["alreadyComposedLanes"][0]["event"]["id"].as_str(),
Some("newer-neutral-lane")
);
assert_eq!(
bounty["closedDoors"][0]["event"]["id"].as_str(),
Some("older-closed-lane"),
"guardrail buckets should keep scanning after alreadyComposedLanes reaches limit"
);
}
}

252
crates/vestige-mcp/src/tools/cross_reference.rs
View file

@ -20,9 +20,10 @@ use serde::Deserialize;
use serde_json::Value;
use std::sync::Arc;
use tokio::sync::Mutex;
use uuid::Uuid;
use crate::cognitive::CognitiveEngine;
use vestige_core::Storage;
use vestige_core::{CompositionEventRecord, CompositionMemberRecord, Storage};
/// Input schema for deep_reference / cross_reference tool
pub fn schema() -> Value {
@ -509,6 +510,7 @@ pub async fn execute(
"confidence": 0.0,
"guidance": "No memories found. Use smart_ingest to add memories.",
"memoriesAnalyzed": 0,
"compositionWriteStatus": "skipped_empty",
}));
}
@ -820,6 +822,7 @@ pub async fn execute(
"id": s.id,
"preview": s.content.chars().take(200).collect::<String>(),
"trust": (s.trust * 100.0).round() / 100.0,
"relevanceScore": ((composite(s) * 100.0).round() / 100.0),
"date": s.updated_at.to_rfc3339(),
"role": if i == 0 { "primary" } else { "supporting" },
})
@ -925,9 +928,163 @@ pub async fn execute(
response["related_insights"] = serde_json::json!(related_insights);
}
match persist_deep_reference_composition(storage, &args.query, &intent, &response) {
Ok(Some(event_id)) => {
response["composition_event_id"] = serde_json::json!(event_id);
response["compositionWriteStatus"] = serde_json::json!("persisted");
}
Ok(None) => {
response["compositionWriteStatus"] = serde_json::json!("skipped_empty");
}
Err(err) => {
tracing::warn!(
"Failed to persist deep_reference composition event: {}",
err
);
response["compositionWriteStatus"] = serde_json::json!("failed");
}
}
Ok(response)
}
fn persist_deep_reference_composition(
storage: &Arc<Storage>,
query: &str,
intent: &QueryIntent,
response: &Value,
) -> Result<Option<String>, String> {
let event_id = Uuid::new_v4().to_string();
let event = CompositionEventRecord {
id: event_id.clone(),
created_at: Utc::now(),
tool: "deep_reference".to_string(),
mode: "deep_reference".to_string(),
query: Some(query.to_string()),
query_hash: Some(query_hash(query)),
confidence: response.get("confidence").and_then(|v| v.as_f64()),
status: response
.get("status")
.and_then(|v| v.as_str())
.map(ToOwned::to_owned),
output_preview: response
.get("guidance")
.and_then(|v| v.as_str())
.map(|value| preview_text(value, 280)),
metadata: serde_json::json!({
"intent": format!("{:?}", intent),
"memoriesAnalyzed": response.get("memoriesAnalyzed").and_then(|v| v.as_u64()).unwrap_or(0),
"activationExpanded": response.get("activationExpanded").and_then(|v| v.as_u64()).unwrap_or(0),
"reasoningPreview": response.get("reasoning").and_then(|v| v.as_str()).map(|value| preview_text(value, 600)),
}),
};
let mut members = Vec::new();
if let Some(evidence) = response.get("evidence").and_then(|v| v.as_array()) {
for (idx, item) in evidence.iter().enumerate() {
let Some(memory_id) = item.get("id").and_then(|v| v.as_str()) else {
continue;
};
let role = item
.get("role")
.and_then(|v| v.as_str())
.unwrap_or(if idx == 0 { "primary" } else { "supporting" });
members.push(CompositionMemberRecord {
event_id: event_id.clone(),
memory_id: memory_id.to_string(),
role: role.to_string(),
rank: idx as i32,
trust: item.get("trust").and_then(|v| v.as_f64()),
score: item
.get("relevanceScore")
.or_else(|| item.get("relevance_score"))
.and_then(|v| v.as_f64()),
preview: None,
metadata: serde_json::json!({
"roleSource": "deep_reference_evidence",
"evidenceRank": idx,
"date": item.get("date").and_then(|v| v.as_str()),
}),
});
}
}
if let Some(contradictions) = response.get("contradictions").and_then(|v| v.as_array()) {
for (idx, contradiction) in contradictions.iter().enumerate() {
for side in ["stronger", "weaker"] {
let Some(item) = contradiction.get(side) else {
continue;
};
let Some(memory_id) = item.get("id").and_then(|v| v.as_str()) else {
continue;
};
members.push(CompositionMemberRecord {
event_id: event_id.clone(),
memory_id: memory_id.to_string(),
role: "contradicting".to_string(),
rank: idx as i32,
trust: item.get("trust").and_then(|v| v.as_f64()),
score: contradiction.get("topic_overlap").and_then(|v| v.as_f64()),
preview: None,
metadata: serde_json::json!({
"roleSource": "deep_reference_contradiction",
"side": side,
"date": item.get("date").and_then(|v| v.as_str()),
}),
});
}
}
}
if let Some(superseded) = response.get("superseded").and_then(|v| v.as_array()) {
for (idx, item) in superseded.iter().enumerate() {
let Some(memory_id) = item.get("id").and_then(|v| v.as_str()) else {
continue;
};
members.push(CompositionMemberRecord {
event_id: event_id.clone(),
memory_id: memory_id.to_string(),
role: "superseded".to_string(),
rank: idx as i32,
trust: item.get("trust").and_then(|v| v.as_f64()),
score: None,
preview: None,
metadata: serde_json::json!({
"roleSource": "deep_reference_superseded",
"superseded_by": item.get("superseded_by").and_then(|v| v.as_str()),
"date": item.get("date").and_then(|v| v.as_str()),
}),
});
}
}
if members.is_empty() {
return Ok(None);
}
storage
.save_composition(&event, &members, &[])
.map_err(|e| e.to_string())?;
Ok(Some(event_id))
}
fn query_hash(query: &str) -> String {
let mut hash = 0xcbf29ce484222325u64;
for byte in query.as_bytes() {
hash ^= u64::from(*byte);
hash = hash.wrapping_mul(0x100000001b3);
}
format!("fnv1a64:{hash:016x}")
}
fn preview_text(value: &str, max: usize) -> String {
let collapsed = value.replace('\n', " ");
if collapsed.len() <= max {
return collapsed;
}
format!("{}...", &collapsed[..collapsed.floor_char_boundary(max)])
}
// ============================================================================
// TESTS
// ============================================================================
@ -1010,6 +1167,99 @@ mod tests {
);
}
#[tokio::test]
async fn test_deep_reference_persists_composition_event() {
let (storage, _dir) = test_storage().await;
let primary_id = ingest_one(
&storage,
"ProtocolGate control-plane composition tracks global invariant local gate bypasses.",
&["protocolgate", "boundary-scope"],
)
.await;
let supporting_id = ingest_one(
&storage,
"ProtocolGate global invariant local gate research used Aave account-global health factor and route-local validation.",
&["protocolgate", "boundary-scope"],
)
.await;
let result = execute(
&storage,
&test_cognitive(),
Some(serde_json::json!({
"query": "ProtocolGate global invariant local gate",
"depth": 10
})),
)
.await
.expect("execute should succeed");
let event_id = result["composition_event_id"]
.as_str()
.expect("deep_reference should return persisted event id");
assert_eq!(result["compositionWriteStatus"].as_str(), Some("persisted"));
let event = storage
.get_composition_event(event_id)
.unwrap()
.expect("composition event should be stored");
assert_eq!(event.tool, "deep_reference");
assert_eq!(
event.query.as_deref(),
Some("ProtocolGate global invariant local gate")
);
let members = storage.get_composition_members(event_id).unwrap();
assert!(members.iter().any(|member| member.memory_id == primary_id));
assert!(
members
.iter()
.any(|member| member.memory_id == supporting_id)
);
assert!(members.iter().any(|member| member.role == "primary"));
assert!(
members.iter().any(|member| {
member.memory_id == primary_id
&& member.score.is_some()
&& member.metadata["roleSource"] == "deep_reference_evidence"
}),
"persisted members should retain relevance score and role source"
);
}
#[tokio::test]
async fn test_deep_reference_skips_empty_composition_event() {
let (storage, _dir) = test_storage().await;
let result = execute(
&storage,
&test_cognitive(),
Some(serde_json::json!({
"query": "no memories exist for this query",
"depth": 10
})),
)
.await
.expect("execute should succeed");
assert_eq!(
result["compositionWriteStatus"].as_str(),
Some("skipped_empty")
);
assert!(
result.get("composition_event_id").is_none(),
"empty evidence should not create a composition event"
);
assert!(
storage
.get_recent_composition_events(10)
.unwrap()
.is_empty(),
"ledger should stay empty when no memories participated"
);
}
// ========================================================================
// Confidence sanity: must vary with query relevance.
// ========================================================================

1
crates/vestige-mcp/src/tools/mod.rs
View file

@ -41,6 +41,7 @@ pub mod graph;
pub mod health;
// v2.1: Cross-reference (connect the dots)
pub mod composed_graph;
pub mod contradictions;
pub mod cross_reference;

159
docs/COMPOSED_GRAPH.md Normal file
View file

@ -0,0 +1,159 @@
# ComposedGraph
ComposedGraph records memory combinations as durable reasoning events.
Most memory systems store facts, entities, or relationships. ComposedGraph stores a
different object: which memories were used together, why they were used, and what
happened afterward.
## Model
`composition_events` stores the reasoning envelope:
- tool and mode, such as `deep_reference` or `bounty`
- query and query hash
- confidence, status, and output preview
- metadata for intent, analyzed memory count, activation expansion, and reasoning preview
`composition_members` stores the participating memories:
- memory id
- role, such as `primary`, `supporting`, `contradicting`, or `superseded`
- rank, trust, relevance score, preview, and metadata
`composition_outcomes` stores later labels:
- `helpful`
- `dead_end`
- `submitted`
- `accepted`
- `rejected`
- `duplicate_risk`
- `needs_poc`
- `bad_severity`
- `user_promoted`
- `user_demoted`
- `closed_by_scope`
- `closed_by_duplicate`
- `closed_by_false_assumption`
- `closed_by_user`
- `expired_lane`
Member memory ids are intentionally historical references, not foreign keys into
`knowledge_nodes`. Purging or superseding a memory should not erase the fact that
it once participated in a reasoning path.
## MCP Tool
Use `composed_graph` for read/write access to the composition ledger.
```json
{ "action": "recent", "limit": 10 }
```
```json
{ "action": "get", "event_id": "<composition-event-id>" }
```
```json
{ "action": "memory", "memory_id": "<memory-id>", "limit": 10 }
```
```json
{ "action": "neighbors", "memory_id": "<memory-id>", "limit": 10 }
```
```json
{ "action": "never_composed", "tags": ["project:vestige"], "limit": 10 }
```
```json
{
"action": "label",
"event_id": "<composition-event-id>",
"outcome_type": "helpful",
"notes": "This combination led to the accepted fix."
}
```
## Never-Composed Frontier
`never_composed` returns pairs that have not yet appeared together in a
composition event.
The ranking is intentionally not just shared-tag matching. It combines:
- exact shared tags
- shared meaningful content terms
- boundary tags such as `boundary-*`, `oracle`, `queue`, `settlement`, `upgrade`,
`pause`, `accounting`, or `scope`
- node-type diversity
- FSRS retention strength
- composition novelty, so memories that have not already been heavily composed
still get surfaced
- prior composition outcomes from either member, so previously accepted,
duplicate-risk, or dead-end lanes shape the frontier without hiding it
Each candidate includes:
- `score`
- `noveltyScore`
- `bridgeScore`
- `trustScore`
- `outcomeScoreAdjustment`
- `sharedTags`
- `boundaryTags`
- `sharedTerms`
- `priorOutcomes`
- `outcomeSignal`, such as `clean`, `prior_success`, `prior_duplicate_risk`,
`prior_closed_door`, or `mixed_prior_outcomes`
- node types
- previews
- a short reason
- a `compositionQuestion` that an agent can answer before taking action
The output is a frontier queue, not a finding. A never-composed pair means
"worth investigating," not "true," "novel," or "reportable."
Prior outcomes are also guardrails, not verdicts: a duplicate-risk signal should
make the agent check duplicate families first, while a success signal should make
it inspect why the older composition worked.
Closed-door labels should be specific when possible. Prefer `closed_by_scope`,
`closed_by_duplicate`, `closed_by_false_assumption`, `closed_by_user`, or
`expired_lane` over a generic `dead_end` when the reason is known.
## Bounty / Research Mode
`bounty_mode` is a higher-level read shape for investigative workflows. It returns:
- recent already-composed lanes
- never-composed lanes
- closed doors
- duplicate-risk lanes
- lanes that need proof-of-concept work
- top weird combinations
This is useful for security research, bug triage, architecture work, and product
strategy because failed or duplicate compositions are preserved instead of being
rediscovered repeatedly.
## Deep Reference Integration
`deep_reference` persists composition events automatically when it has evidence
members. Empty evidence does not create a ledger event.
The response includes:
- `composition_event_id` when persisted
- `compositionWriteStatus`, usually `persisted` or `skipped_empty`
## Design Direction
The next useful upgrades are:
- triple or n-ary candidate mining, not only pairs
- structural-fit scoring for analogies, separate from surface similarity
- trust-zone scoring so a composition is limited by its weakest provenance
- temporal replay: "what combinations were available when this decision was made?"
- evaluation tasks where success requires combining memories that were never
previously co-composed