fix(serve,ledger): add .context() to error propagation in critical paths

[fagemx]

Problem

Error context enrichment is nearly zero across the codebase:

Crate	Bare `?`	`.context()`	Ratio
edda-ledger	613	1	0.16%
edda-cli	546	6	1.1%
edda-serve	215	9	4.2%

When a production error occurs, the error message only contains the lowest-level detail (e.g., "no such column") with no information about which endpoint, decision key, project, or operation triggered it. Debugging is extremely difficult.

Scope

Prioritize adding .context() in:

1. edda-serve handlers — each ? should include the endpoint name and key request params
2. edda-ledger public API — each Ledger::* method should wrap errors with the method name and key args
3. edda-cli commands — each cmd_*.rs execute function should context-wrap ledger calls

Examples

// Before
let ledger = Ledger::open(&root)?;

// After
let ledger = Ledger::open(&root)
    .context(format!("opening ledger at {}", root.display()))?;

// Before (edda-serve handler)
let decisions = ledger.active_decisions()?;

// After
let decisions = ledger.active_decisions()
    .context("GET /api/decisions: fetching active decisions")?;

Notes

• anyhow is already a workspace dependency — .context() is available everywhere
• Start with the most-changed files (serve lib.rs, sqlite_store.rs, ledger.rs)
• This is incremental — doesn't need to be done all at once

[fagemx]

Research: Error Context Enrichment (GH-377)

Problem Statement

Error context enrichment across the edda codebase is nearly zero. When a production error occurs, the error message only contains the lowest-level detail (e.g., "no such column") with no information about which endpoint, decision key, project, or operation triggered it.

Current State Analysis

Bare ? vs .context() Counts

File	Bare ?	.context()	Lines
edda-serve/src/lib.rs	160	0	7,983
edda-ledger/src/sqlite_store.rs	260	0	7,003
edda-ledger/src/ledger.rs	16	0	1,220
edda-cli/src/cmd_draft.rs	98	3	1,692
edda-cli/src/cmd_bridge.rs	34	0	1,524
edda-cli/src/cmd_pair.rs	25	0	224
edda-cli/src/cmd_conduct.rs	20	2	510
edda-cli/src/cmd_blob.rs	18	1	641
Other CLI commands	~200	0	varies

Total: ~800+ bare ? across the three target areas, with only 6 .context() calls.

Error Flow Architecture

edda-serve

• AppError enum (lib.rs:72-88): Validation(String), NotFound(String), Conflict(String), Unauthorized(String), Internal(#[from] anyhow::Error)
• IntoResponse impl (lib.rs:114-129): maps each variant to HTTP status + JSON body { error, code }
• From impls: serde_json::Error, serde_yaml::Error, globset::Error, std::io::Error all go to Internal
• Bare ? in handlers propagates anyhow::Error (from ledger calls) -> AppError::Internal -> HTTP 500 with just the low-level error string
• Example: let ledger = state.open_ledger()?; in get_status (L718) -- if this fails, the error says "no such table: events" with zero context about which endpoint triggered it

edda-ledger

• Ledger struct (ledger.rs): thin wrapper over SqliteStore, every method is self.sqlite.method_name() with no context
• SqliteStore (sqlite_store.rs): direct rusqlite calls with bare ? on conn.prepare(), stmt.query_map(), conn.execute(), etc.
• Error chain: rusqlite::Error -> anyhow::Error -> caller (serve or CLI)
• Example: self.sqlite.active_decisions(domain, key_pattern, after, before, None) -- if SQL fails, you get "no such column: village_id" with no indication that Ledger::active_decisions was called

edda-cli

• cmd_*.rs pattern: each has pub fn execute(...) returning anyhow::Result<()>
• Only 6 .context() calls across all commands (in cmd_blob.rs, cmd_conduct.rs, cmd_draft.rs)
• Most bare ? are on ledger method calls

Dependency Status

• anyhow is already a workspace dependency with workspace = true in both edda-serve/Cargo.toml and edda-ledger/Cargo.toml
• anyhow::Context trait is only imported in 3 CLI files currently
• No additional dependencies needed

Key Observations

1. Ledger is a pure delegation layer: ledger.rs has 40+ methods that are all self.sqlite.method_name() one-liners. Adding context here is the highest-leverage point because it enriches errors for ALL callers (serve, CLI, MCP, bridge).

2. sqlite_store.rs is the deepest layer: 260 bare ? here are mostly on rusqlite operations (prepare, execute, query_map). Adding context at this level would be verbose and many of these are internal operations where the Ledger wrapper's context is sufficient.

3. edda-serve handlers follow a pattern: Almost every handler starts with let ledger = state.open_ledger()?; then calls ledger methods. The handler function name = the endpoint name, so adding context at the handler level directly maps to debugging output.

4. The AppError::Internal variant preserves the full anyhow chain: Since Internal(#[from] anyhow::Error), any .context() added upstream will be preserved in the error response.

Files Changed Recently (Highest Risk)

From recent git activity:

• edda-serve/src/lib.rs -- frequently changing, most handlers
• edda-ledger/src/sqlite_store.rs -- schema migrations, new tables
• edda-ledger/src/ledger.rs -- new API methods

Existing .context() Patterns

// cmd_blob.rs:378
.context("expected exactly one blob match")?

// cmd_conduct.rs:185
.context("phase referenced in topo order not found in plan")?

// cmd_draft.rs:1028
.context("stage not found in draft")?

These are used for Option::None -> Error conversions via .ok_or() pattern, not for enriching propagated errors. The issue is specifically about adding context to ? error propagation.

[fagemx]

Innovation: Error Context Enrichment Strategies (GH-377)

Approach Evaluation

Approach A: Context at Ledger Wrapper Layer Only

Add .context() to every Ledger method in ledger.rs, wrapping the self.sqlite.* delegation calls.

Example:

pub fn active_decisions(&self, domain: Option<&str>, ...) -> anyhow::Result<Vec<DecisionRow>> {
    self.sqlite.active_decisions(domain, key_pattern, after, before, None)
        .context("Ledger::active_decisions")
}

Pros:

• Highest leverage: enriches errors for ALL callers (serve, CLI, MCP, bridge, aggregate)
• Only ~45 methods to change in one file
• Minimal code churn
• Method name alone is often sufficient to diagnose the problem

Cons:

• No handler/endpoint context (which HTTP route triggered it?)
• No parameter context (which key/domain was queried?)
• Single layer of context may not be enough for complex failures

Verdict: Necessary but not sufficient.

Approach B: Context at Serve Handler Layer Only

Add .context() to every ? in handler functions, including the endpoint name.

Example:

async fn get_decisions(...) -> Result<Json<AskResult>, AppError> {
    let ledger = state.open_ledger()
        .context("GET /api/decisions: opening ledger")?;
    let decisions = ledger.active_decisions(...)
        .context("GET /api/decisions: fetching active decisions")?;
}

Pros:

• Direct mapping to endpoint debugging
• HTTP route name in every error
• Easy to correlate with access logs

Cons:

• Only helps server errors, not CLI errors
• Very verbose in handlers with many ? calls (some have 5-10)
• Risk of stale context strings when endpoints change
• Doesn't help MCP or bridge callers

Verdict: High value for serve, but too narrow scope.

Approach C: Context at Both Ledger and Handler Layers (Recommended)

Layer context at two levels:

1. Ledger wrapper: method name + key arguments
2. Serve handlers: endpoint name at the handler boundary (first and last ? calls)

This creates a context chain: GET /api/decisions > Ledger::active_decisions > sqlite error

Example error output:

GET /api/decisions: fetching decisions

Caused by:
    0: Ledger::active_decisions(domain=Some("db"))
    1: no such column: village_id

Pros:

• Full error chain from endpoint to SQL
• Ledger context helps ALL callers
• Handler context is lightweight (one wrapper per handler)
• Natural anyhow chain rendering

Cons:

• More changes across two files
• Need to decide which parameters to include in context strings

Verdict: Best balance of coverage and effort.

Approach D: Macro-Based Context Injection

Create a macro that auto-wraps delegated calls with context:

macro_rules! delegate_with_context {
    ($self:ident, $method:ident $(, $arg:expr)*) => {
        $self.sqlite.$method($($arg),*)
            .context(concat!("Ledger::", stringify!($method)))
    };
}

Pros:

• Zero boilerplate for Ledger methods
• Context string auto-generated from method name
• Can't forget to add context

Cons:

• Macro obscures the code
• Can't include parameter values in context
• Unusual pattern for the project
• YAGNI concern: a macro for something done once

Verdict: Over-engineered for this use case.

Recommended Strategy: Approach C (Two-Layer Context)

Layer 1: Ledger Public API (ledger.rs)

For each Ledger method, wrap the delegation with .context() including:

• Method name
• Key identifying parameter (if applicable)

Pattern for simple delegation:

pub fn head_branch(&self) -> anyhow::Result<String> {
    self.sqlite.head_branch()
        .context("Ledger::head_branch")
}

Pattern for methods with key params:

pub fn active_decisions(&self, domain: Option<&str>, ...) -> anyhow::Result<Vec<DecisionRow>> {
    self.sqlite.active_decisions(domain, key_pattern, after, before, None)
        .context(format!("Ledger::active_decisions(domain={:?})", domain))
}

Guideline: Include the first "identifying" parameter (key, event_id, branch, domain) but not filter/limit params to keep context strings readable.

Layer 2: Serve Handlers (lib.rs)

For each handler, add context to the open_ledger() call and the primary data-fetching call.

Pattern:

async fn get_decisions(...) -> Result<Json<AskResult>, AppError> {
    let ledger = state.open_ledger()
        .context("GET /api/decisions")?;
    // ... validation ...
    let result = edda_ask::ask(&ledger, q, opts)
        .context("GET /api/decisions: querying")?;
}

Not every ? needs context -- focus on:

1. open_ledger() calls (always)
2. Primary ledger method calls (the main data operation)
3. Complex multi-step operations (mutations with multiple writes)

Layer 3: CLI Commands (Incremental)

For each cmd_*.rs execute function, wrap the Ledger::open() call and the primary operation.

Pattern:

pub fn execute(repo_root: &Path) -> anyhow::Result<()> {
    let ledger = Ledger::open(repo_root)
        .context("cmd_status: opening ledger")?;
    // ... primary operation with context ...
}

Priority by bare ? count: cmd_draft.rs (98), cmd_bridge.rs (34), cmd_pair.rs (25), cmd_conduct.rs (20), cmd_blob.rs (18).

Context String Convention

Proposed format: "<component>::<method>(<key_param>=<value>)"

• Ledger: "Ledger::active_decisions(domain=Some(\"db\"))"
• Serve: "GET /api/decisions" or "POST /api/decide"
• CLI: "cmd_status: opening ledger" or "cmd_draft: loading draft"

Risk Assessment

• Zero runtime cost when no error: .context() only allocates when the error path is taken
• No API changes: all return types remain anyhow::Result<T>
• No behavioral changes: only error messages change
• Backward compatible: existing error handling in callers is unaffected

[fagemx]

Plan: Error Context Enrichment (GH-377)

Strategy

Two-layer context enrichment using Approach C from the innovation phase:

1. Layer 1 (Ledger): Add .context() to all Ledger public methods in ledger.rs -- enriches ALL callers
2. Layer 2 (Serve): Add .context() to serve handler open_ledger() and primary data calls with endpoint name
3. Layer 3 (CLI): Add .context() to top-5 CLI commands by bare ? count

Implementation Steps

Step 1: Add .context() to Ledger public API (crates/edda-ledger/src/ledger.rs)

Files: crates/edda-ledger/src/ledger.rs
Changes: ~45 methods, each adding .context() to the self.sqlite.* delegation call

1. Add use anyhow::Context; import
2. For each public method, wrap the delegation:

Method	Context String
open	Already has descriptive bail -- no change needed
open_or_init	Already calls open -- no change needed
open_path	Already calls open -- no change needed
head_branch	"Ledger::head_branch"
set_head_branch	"Ledger::set_head_branch"
append_event	format!("Ledger::append_event({})", event.event_id)
append_event_idempotent	format!("Ledger::append_event_idempotent({})", event.event_id)
last_event_hash	"Ledger::last_event_hash"
iter_events	"Ledger::iter_events"
get_event	format!("Ledger::get_event({})", event_id)
iter_events_by_type	format!("Ledger::iter_events_by_type({})", event_type)
iter_branch_events	format!("Ledger::iter_branch_events({})", branch)
iter_events_filtered	format!("Ledger::iter_events_filtered(branch={})", branch)
find_related_commits	"Ledger::find_related_commits"
find_related_notes	"Ledger::find_related_notes"
events_after_rowid	"Ledger::events_after_rowid"
rowid_for_event_id	format!("Ledger::rowid_for_event_id({})", event_id)
branches_json	"Ledger::branches_json"
set_branches_json	"Ledger::set_branches_json"
active_decisions	format!("Ledger::active_decisions(domain={:?})", domain)
active_decisions_limited	format!("Ledger::active_decisions_limited(domain={:?})", domain)
decision_timeline	format!("Ledger::decision_timeline(key={})", key)
domain_timeline	format!("Ledger::domain_timeline(domain={})", domain)
list_domains	"Ledger::list_domains"
village_stats	format!("Ledger::village_stats({})", village_id)
detect_village_patterns	format!("Ledger::detect_village_patterns({})", village_id)
find_active_decision	format!("Ledger::find_active_decision(branch={}, key={})", branch, key)
query_active_with_paths	"Ledger::query_active_with_paths"
query_by_paths	"Ledger::query_by_paths"
shared_decisions	"Ledger::shared_decisions"
is_already_imported	"Ledger::is_already_imported"
insert_imported_decision	"Ledger::insert_imported_decision"
insert_dep	format!("Ledger::insert_dep({} -> {})", source_key, target_key)
deps_of	format!("Ledger::deps_of({})", key)
dependents_of	format!("Ledger::dependents_of({})", key)
active_dependents_of	format!("Ledger::active_dependents_of({})", key)
decision_outcomes	format!("Ledger::decision_outcomes({})", decision_event_id)
executions_for_decision	format!("Ledger::executions_for_decision({})", decision_event_id)
transitive_dependents_of	format!("Ledger::transitive_dependents_of({})", key)
get_decision_by_event_id	format!("Ledger::get_decision_by_event_id({})", event_id)
causal_chain	format!("Ledger::causal_chain({})", event_id)
get_task_brief	format!("Ledger::get_task_brief({})", task_id)
list_task_briefs	"Ledger::list_task_briefs"
get_bundle	format!("Ledger::get_bundle({})", bundle_id)
list_bundles	"Ledger::list_bundles"
insert_device_token	"Ledger::insert_device_token"
validate_device_token	"Ledger::validate_device_token"
list_device_tokens	"Ledger::list_device_tokens"
revoke_device_token	format!("Ledger::revoke_device_token({})", device_name)
revoke_all_device_tokens	"Ledger::revoke_all_device_tokens"
insert_snapshot	"Ledger::insert_snapshot"
query_snapshots	"Ledger::query_snapshots"
snapshots_by_context_hash	format!("Ledger::snapshots_by_context_hash({})", context_hash)
insert_suggestion	"Ledger::insert_suggestion"
list_suggestions_by_status	format!("Ledger::list_suggestions_by_status({})", status)
get_suggestion	format!("Ledger::get_suggestion({})", id)
update_suggestion_status	format!("Ledger::update_suggestion_status({})", id)
verify_chain	"Ledger::verify_chain"

Also add context to init functions at the bottom of the file:

• init_workspace, init_head, init_branches_json

Guideline: Use static string when no identifying parameter, format!() when there's a key/id parameter.

Step 2: Add .context() to serve handlers (crates/edda-serve/src/lib.rs)

Files: crates/edda-serve/src/lib.rs
Changes: ~35 handler functions, adding context to open_ledger() and primary operation calls

1. Add use anyhow::Context; import
2. For each handler, add .context("VERB /api/path") to state.open_ledger()?
3. For primary data-fetching ledger calls, add .context("VERB /api/path: operation")?

Priority handlers (most used, highest debugging value):

Handler	Route	Context to add
get_status	GET /api/status	open_ledger, head_branch, rebuild_branch
get_context	GET /api/context	open_ledger, head_branch, render_context
get_decisions	GET /api/decisions	open_ledger, ask
post_decisions_batch	POST /api/decisions/batch	open_ledger
get_decision_outcomes	GET /api/decisions/:id/outcomes	open_ledger, decision_outcomes
get_decision_chain	GET /api/decisions/:id/chain	open_ledger, causal_chain
get_log	GET /api/log	open_ledger, head_branch, iter_events_filtered
get_drafts	GET /api/drafts	open_ledger
post_note	POST /api/note	open_ledger, append_event
post_decide	POST /api/decide	open_ledger, append_event
post_karvi_event	POST /api/events/karvi	open_ledger, append_event_idempotent
post_telemetry	POST /api/telemetry	open_ledger, append_event
get_telemetry	GET /api/telemetry	open_ledger, iter_events_by_type
get_telemetry_stats	GET /api/telemetry/stats	open_ledger, iter_events_by_type
post_snapshot	POST /api/snapshot	open_ledger, insert_snapshot
get_snapshots	GET /api/snapshots	open_ledger, query_snapshots
get_village_stats	GET /api/villages/:id/stats	open_ledger, village_stats
get_patterns	GET /api/patterns	open_ledger, detect_village_patterns
get_recap	GET /api/recap	open_ledger
get_overview	GET /api/overview	open_ledger
get_projects	GET /api/projects	open_ledger
get_actors	GET /api/actors	open_ledger
get_actor	GET /api/actors/:name	open_ledger
get_quality_metrics	GET /api/metrics/quality	open_ledger
get_metrics_overview	GET /api/metrics/overview	open_ledger
get_metrics_trends	GET /api/metrics/trends	open_ledger
post_scope_check	POST /api/scope/check	open_ledger
get_scope_whitelist	GET /api/scope/whitelist	open_ledger
post_authz_check	POST /api/authz/check	open_ledger
get_tool_tier	GET /api/tool-tier/:name	open_ledger
post_approval_check	POST /api/approval/check	open_ledger
post_sync	POST /api/sync	open_ledger
get_briefs	GET /api/briefs	open_ledger
get_brief	GET /api/briefs/:id	open_ledger
get_dashboard	GET /api/dashboard	open_ledger
get_event_stream	GET /api/events/stream	open_ledger
Auth: auth_middleware	all routes	open_ledger, validate_device_token
Pairing: create_pairing, complete_pairing, etc.	/api/pair/*	open_ledger

Step 3: Add .context() to top-5 CLI commands

Files: crates/edda-cli/src/cmd_draft.rs, cmd_bridge.rs, cmd_pair.rs, cmd_conduct.rs, cmd_blob.rs

For each, add context to:

1. Ledger::open() / Ledger::open_or_init() calls
2. Primary ledger operation calls (the main execute() body)

Not every ? needs context -- focus on the "open ledger" and "primary operation" boundaries.

Note: cmd_bridge.rs has special patterns (subprocess spawning, bridge operations) that may need bridge-specific context rather than ledger context.

Testing Strategy

1. Compilation check: cargo check -p edda-ledger -p edda-serve -p edda-cli
2. Clippy: cargo clippy -p edda-ledger -p edda-serve -p edda-cli
3. Existing tests: cargo test --workspace -- all existing tests must pass (no behavioral change)
4. Manual verification: Induce an error (e.g., corrupt DB) and verify the error chain includes context
5. No new tests needed: This is a non-behavioral change (only error messages change)

Execution Order

1. Step 1 first (ledger.rs) -- highest leverage, all callers benefit
2. Step 2 second (serve lib.rs) -- second layer for HTTP debugging
3. Step 3 third (CLI commands) -- incremental, can be separate PR if needed

Risk Mitigation

• No API changes: all return types stay anyhow::Result<T>
• No runtime cost: .context() only allocates on the error path
• Incremental: each step can be merged independently
• Easy rollback: removing .context() is trivial

Estimated Scope

Step	File(s)	Lines Changed	Complexity
1	ledger.rs	~100 lines (45 methods + import)	Low
2	serve/lib.rs	~80 lines (35 handlers x ~2 calls each)	Low
3	5 CLI files	~30 lines	Low
Total	7 files	~210 lines	Low

[fagemx]

Work completed. PR created: #381

All local checks passing (fmt, clippy, full workspace tests).