feat(graphtrail): deprecate direct MiseLedger adapter (#392)

Co-authored-by: Codex <codex@openai.com>

Author: solomonneas

engines/code-graph/CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Deprecated
+- The direct `miseledger` Cargo feature, `graphtrail context --evidence`, and `graphtrail links` are deprecated but remain functional. Use `brigade code sync .`, `brigade code context "rate limiting" --markdown`, `brigade code impact dispatch --json`, `brigade evidence crawl plan --target .`, `brigade evidence search "dispatch"`, `brigade evidence search "dispatch" --code-reference '{"schema":"brigade.code-reference.v1","repository":"escoffier-labs/brigade","revision":{"commit":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"file_path":"src/brigade/receipts_cmd.py","qualified_name":"brigade.receipts_cmd._metadata_with_delta","symbol_kind":"function","source_span":{"start_line":788,"line_count":3}}'`, and `brigade evidence doctor --target .` for structured composition. An exact code reference is matched before lexical fallback. Compatibility lasts through at least two minor GraphTrail releases or 90 days after the first GraphTrail release containing this deprecation, whichever is longer. Removal cannot occur before that policy is satisfied. The standalone release pipeline is unchanged.
+
 ## [0.4.0] - 2026-07-17
 
 ### Fixed

engines/code-graph/README.md

@@ -187,6 +187,22 @@ cargo build --features codesearch --bin graphtrail-mcp
 cargo run --features miseledger -- links "dispatch" --json
 ```
 
+### MiseLedger adapter deprecation
+
+The direct `miseledger` Cargo feature, `graphtrail context --evidence`, and `graphtrail links` are deprecated but remain functional. Use Brigade for structured composition instead:
+
+```bash
+brigade code sync .
+brigade code context "rate limiting" --markdown
+brigade code impact dispatch --json
+brigade evidence crawl plan --target .
+brigade evidence search "dispatch"
+brigade evidence search "dispatch" --code-reference '{"schema":"brigade.code-reference.v1","repository":"escoffier-labs/brigade","revision":{"commit":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"file_path":"src/brigade/receipts_cmd.py","qualified_name":"brigade.receipts_cmd._metadata_with_delta","symbol_kind":"function","source_span":{"start_line":788,"line_count":3}}'
+brigade evidence doctor --target .
+```
+
+An exact code reference is matched before lexical fallback. GraphTrail will keep the direct adapter functional through at least two minor GraphTrail releases or 90 days after the first GraphTrail release containing this deprecation, whichever is longer. Removal cannot occur before that compatibility policy is satisfied. The direct adapter keeps its existing default database resolution and read-only FTS behavior during the compatibility window.
+
 When `codesearch` is enabled, GraphTrail also reads the shared Code Search index
 manifest from `CODE_INDEX_MANIFEST`, `XDG_DATA_HOME/code-index/manifest.json`, or
 `~/.local/share/code-index/manifest.json`. `CODE_SEARCH_URL` still wins when it is

engines/code-graph/build.rs

@@ -0,0 +1,9 @@
+fn main() {
+    println!("cargo:rerun-if-env-changed=CARGO_FEATURE_MISELEDGER");
+
+    if std::env::var_os("CARGO_FEATURE_MISELEDGER").is_some() {
+        println!(
+            "cargo:warning=GraphTrail's direct MiseLedger adapter is deprecated. Use `brigade code sync`, `brigade code context`, `brigade code impact`, `brigade evidence crawl`, `brigade evidence search`, and `brigade evidence doctor` instead. The adapter remains functional for at least two minor GraphTrail releases or 90 days after the first GraphTrail release containing this deprecation, whichever is longer. It will not be removed before that compatibility policy is satisfied."
+        );
+    }
+}

engines/code-graph/src/adapters/miseledger.rs

@@ -9,6 +9,13 @@ use anyhow::{Context, Result};
 use rusqlite::{Connection, OpenFlags, params};
 use serde::Serialize;
 
+/// Emitted once by each deprecated CLI command invocation, always on stderr.
+pub const DEPRECATION_WARNING: &str = "warning: GraphTrail's direct MiseLedger adapter is deprecated. Use `brigade code sync`, `brigade code context`, `brigade code impact`, `brigade evidence crawl`, `brigade evidence search`, and `brigade evidence doctor` instead. The adapter remains functional for at least two minor GraphTrail releases or 90 days after the first GraphTrail release containing this deprecation, whichever is longer. It will not be removed before that compatibility policy is satisfied.";
+
+pub fn emit_deprecation_warning() {
+    eprintln!("{DEPRECATION_WARNING}");
+}
+
 #[derive(Debug, Serialize)]
 pub struct EvidenceHit {
     pub item_id: String,

engines/code-graph/src/cli.rs

@@ -322,6 +322,10 @@ pub fn run(cli: Cli) -> Result<()> {
             #[cfg(feature = "miseledger")]
             evidence,
         } => {
+            #[cfg(feature = "miseledger")]
+            if evidence {
+                crate::adapters::miseledger::emit_deprecation_warning();
+            }
             let db_path = default_query_db_path(cli.db.clone());
             let conn = open_read_only(&db_path)?;
             #[cfg(feature = "codesearch")]
@@ -603,6 +607,7 @@ pub fn run(cli: Cli) -> Result<()> {
         }
         #[cfg(feature = "miseledger")]
         Command::Links { term, limit, json } => {
+            crate::adapters::miseledger::emit_deprecation_warning();
             let db = crate::adapters::miseledger::default_db_path();
             let hits = crate::adapters::miseledger::search_evidence(&db, &term, limit)?;
             if json {

engines/code-graph/tests/cli_read_only.rs

@@ -9,6 +9,9 @@ use std::time::SystemTime;
 use graphtrail::store::{init_schema, open_db, sync_repo};
 use sha2::{Digest, Sha256};
 
+#[cfg(feature = "miseledger")]
+const MISELEDGER_DEPRECATION_WARNING: &str = "warning: GraphTrail's direct MiseLedger adapter is deprecated. Use `brigade code sync`, `brigade code context`, `brigade code impact`, `brigade evidence crawl`, `brigade evidence search`, and `brigade evidence doctor` instead. The adapter remains functional for at least two minor GraphTrail releases or 90 days after the first GraphTrail release containing this deprecation, whichever is longer. It will not be removed before that compatibility policy is satisfied.";
+
 fn graphtrail() -> &'static str {
     env!("CARGO_BIN_EXE_graphtrail")
 }
@@ -50,6 +53,60 @@ def run():
     db
 }
 
+#[cfg(feature = "miseledger")]
+fn build_miseledger_db(root: &Path) -> PathBuf {
+    let db = root.join("miseledger.db");
+    let conn = rusqlite::Connection::open(&db).unwrap();
+    conn.execute_batch(
+        "CREATE VIRTUAL TABLE item_fts USING fts5(item_id, source_kind, body);\
+         INSERT INTO item_fts (item_id, source_kind, body) VALUES\
+             ('evidence-helper', 'session', 'helper helper');",
+    )
+    .unwrap();
+    conn.pragma_update(None, "wal_checkpoint", "TRUNCATE")
+        .unwrap();
+    db
+}
+
+#[cfg(feature = "miseledger")]
+fn build_evidence_context_miseledger_db(root: &Path) -> PathBuf {
+    let db = root.join("miseledger.db");
+    let conn = rusqlite::Connection::open(&db).unwrap();
+    conn.execute_batch(
+        "CREATE VIRTUAL TABLE item_fts USING fts5(item_id, source_kind, body);\
+         INSERT INTO item_fts (item_id, source_kind, body) VALUES\
+             ('evidence-task', 'session', 'evidence'),\
+             ('evidence-alpha', 'session', 'evidence_alpha'),\
+             ('evidence-beta', 'session', 'evidence_beta');",
+    )
+    .unwrap();
+    conn.pragma_update(None, "wal_checkpoint", "TRUNCATE")
+        .unwrap();
+    db
+}
+
+#[cfg(feature = "miseledger")]
+fn build_evidence_context_db(root: &Path) -> PathBuf {
+    fs::write(
+        root.join("evidence.py"),
+        r#"
+def evidence_alpha():
+    return 1
+
+def evidence_beta():
+    return evidence_alpha()
+"#,
+    )
+    .unwrap();
+    let db = root.join(".graphtrail").join("graphtrail.db");
+    let conn = open_db(&db).unwrap();
+    init_schema(&conn).unwrap();
+    sync_repo(&conn, root).unwrap();
+    conn.pragma_update(None, "wal_checkpoint", "TRUNCATE")
+        .unwrap();
+    db
+}
+
 fn snapshot_file(path: &Path) -> (Vec<u8>, SystemTime) {
     let bytes = fs::read(path).unwrap();
     let modified = fs::metadata(path).unwrap().modified().unwrap();
@@ -367,6 +424,147 @@ fn doctor_does_not_mutate_db_or_tree() {
     assert_eq!(before_tree, snapshot_tree(graph_dir.parent().unwrap()));
 }
 
+#[cfg(feature = "miseledger")]
+#[test]
+fn deprecated_miseledger_commands_warn_once_without_changing_json_or_databases() {
+    let graph_dir = tempfile::tempdir().unwrap();
+    let evidence_dir = tempfile::tempdir().unwrap();
+    let links_evidence_dir = tempfile::tempdir().unwrap();
+    let graph_db = build_evidence_context_db(graph_dir.path());
+    let evidence_db = build_evidence_context_miseledger_db(evidence_dir.path());
+    let links_evidence_db = build_miseledger_db(links_evidence_dir.path());
+    let before_graph = snapshot_tree(graph_dir.path());
+    let before_evidence = snapshot_tree(evidence_dir.path());
+    let before_links_evidence = snapshot_tree(links_evidence_dir.path());
+
+    let context_without_evidence = Command::new(graphtrail())
+        .current_dir(graph_dir.path())
+        .args([
+            "--db",
+            &graph_db.display().to_string(),
+            "context",
+            "evidence",
+            "--json",
+        ])
+        .env("MISELEDGER_DB", &evidence_db)
+        .output()
+        .unwrap();
+    assert!(
+        context_without_evidence.status.success(),
+        "context without --evidence failed: {context_without_evidence:?}"
+    );
+    assert!(
+        context_without_evidence.stderr.is_empty(),
+        "context without --evidence warned: {:?}",
+        String::from_utf8_lossy(&context_without_evidence.stderr)
+    );
+
+    let context_with_evidence = Command::new(graphtrail())
+        .current_dir(graph_dir.path())
+        .args([
+            "--db",
+            &graph_db.display().to_string(),
+            "context",
+            "evidence",
+            "--json",
+            "--evidence",
+        ])
+        .env("MISELEDGER_DB", &evidence_db)
+        .output()
+        .unwrap();
+    assert!(
+        context_with_evidence.status.success(),
+        "context with --evidence failed: {context_with_evidence:?}"
+    );
+    assert_eq!(
+        String::from_utf8(context_with_evidence.stderr).unwrap(),
+        format!("{MISELEDGER_DEPRECATION_WARNING}\n")
+    );
+    assert_eq!(
+        context_with_evidence.stdout, context_without_evidence.stdout,
+        "--evidence must not change context JSON output"
+    );
+    let context_json: serde_json::Value =
+        serde_json::from_slice(&context_with_evidence.stdout).unwrap();
+    assert_eq!(context_json["task"], "evidence");
+
+    let context_markdown_with_evidence = Command::new(graphtrail())
+        .current_dir(graph_dir.path())
+        .args([
+            "--db",
+            &graph_db.display().to_string(),
+            "context",
+            "evidence",
+            "--markdown",
+            "--evidence",
+        ])
+        .env("MISELEDGER_DB", &evidence_db)
+        .output()
+        .unwrap();
+    assert!(
+        context_markdown_with_evidence.status.success(),
+        "markdown context with --evidence failed: {context_markdown_with_evidence:?}"
+    );
+    assert_eq!(
+        String::from_utf8(context_markdown_with_evidence.stderr).unwrap(),
+        format!("{MISELEDGER_DEPRECATION_WARNING}\n")
+    );
+    let markdown = String::from_utf8(context_markdown_with_evidence.stdout).unwrap();
+    assert_eq!(markdown.matches("### `").count(), 3, "{markdown}");
+    for expected_link in [
+        "### `evidence`",
+        "- [session] `evidence-task` - [evidence]",
+        "### `evidence_alpha`",
+        "- [session] `evidence-alpha` - [evidence-alpha]",
+        "### `evidence_beta`",
+        "- [session] `evidence-beta` - [evidence-beta]",
+    ] {
+        assert!(markdown.contains(expected_link), "{markdown}");
+    }
+
+    let links = Command::new(graphtrail())
+        .args(["links", "helper", "--json"])
+        .env("MISELEDGER_DB", &links_evidence_db)
+        .output()
+        .unwrap();
+    assert!(links.status.success(), "links failed: {links:?}");
+    assert_eq!(
+        String::from_utf8(links.stderr).unwrap(),
+        format!("{MISELEDGER_DEPRECATION_WARNING}\n")
+    );
+    let links_json: serde_json::Value = serde_json::from_slice(&links.stdout).unwrap();
+    assert_eq!(links_json[0]["item_id"], "evidence-helper");
+
+    assert_eq!(before_graph, snapshot_tree(graph_dir.path()));
+    assert_eq!(before_evidence, snapshot_tree(evidence_dir.path()));
+    assert_eq!(
+        before_links_evidence,
+        snapshot_tree(links_evidence_dir.path())
+    );
+}
+
+#[cfg(not(feature = "miseledger"))]
+#[test]
+fn miseledger_commands_are_unavailable_without_the_feature_and_do_not_warn() {
+    let context_help = Command::new(graphtrail())
+        .args(["context", "--help"])
+        .output()
+        .unwrap();
+    assert!(context_help.status.success(), "{context_help:?}");
+    assert!(
+        !String::from_utf8_lossy(&context_help.stdout).contains("--evidence"),
+        "{context_help:?}"
+    );
+    assert!(context_help.stderr.is_empty(), "{context_help:?}");
+
+    let links = Command::new(graphtrail()).arg("links").output().unwrap();
+    assert!(!links.status.success(), "links unexpectedly succeeded");
+    assert!(
+        !String::from_utf8_lossy(&links.stderr).contains("direct MiseLedger adapter is deprecated"),
+        "miseledger-free build warned: {links:?}"
+    );
+}
+
 #[cfg(all(feature = "codesearch", feature = "miseledger"))]
 #[test]
 fn context_help_lists_join_layer_flags() {