test(serve): validate Karvi harvest integration (/api/decide + /api/note + /api/events/karvi)

[fagemx]

Context

Karvi 深度整合（karvi#766, karvi#767）將開始 harvest decisions/lessons/events 到 Edda。需要在 Edda 側驗證三個 endpoint 都能正確處理 Karvi 的呼叫模式。

What Needs to Happen

1. POST /api/decide（karvi#766）

• Karvi 送 { "decision": "runtime.spawn=cmd.exe", "reason": "verified in #598" }
• 驗證：event 寫入 ledger.db，auto-supersede 同 key 的舊 decision
• 回傳：{ "event_id": "evt_...", "superseded": "evt_..." | null }

2. POST /api/note（karvi#766）

• Karvi 送 { "text": "[GH-598] spawn fix pattern", "role": "system", "tags": ["auto-harvest", "lesson"] }
• 驗證：event 寫入 ledger.db with tags
• 回傳：{ "event_id": "evt_..." }

3. POST /api/events/karvi（karvi#767）

• Karvi 送 { "version": "karvi.event.v1", "event_id": "karvi-GH-598-plan-0", "event_type": "step_completed", "occurred_at": "...", "task_id": "GH-598", "step_id": "GH-598:plan" }
• 驗證：idempotent — 同 event_id 重送回 200 + status: "duplicate"
• 回傳：{ "event_id": "...", "status": "created" | "duplicate" }

4. 整合 smoke test

• 連續送 decide → note → events/karvi，確認都寫入成功
• edda ask "runtime" 能查到剛寫的 decision

Definition of Done

• POST /api/decide → ledger.db 有新 decision event
• POST /api/note → ledger.db 有新 note event with tags
• POST /api/events/karvi → ledger.db 有 karvi event
• 重送同 event_id → 200 + duplicate
• edda ask "runtime" 回傳包含 harvest 的 decision

Smoke Test

# 1. Decide
curl -X POST http://localhost:3463/api/decide \
  -H "Content-Type: application/json" \
  -d '{"decision":"test.harvest=works","reason":"integration test"}'

# 2. Note
curl -X POST http://localhost:3463/api/note \
  -H "Content-Type: application/json" \
  -d '{"text":"test harvest note","role":"system","tags":["auto-harvest","test"]}'

# 3. Karvi event
curl -X POST http://localhost:3463/api/events/karvi \
  -H "Content-Type: application/json" \
  -d '{"version":"karvi.event.v1","event_id":"karvi-test-001","event_type":"step_completed","occurred_at":"2026-03-20T12:00:00Z","task_id":"T-test","step_id":"T-test:plan"}'

# 4. Query back
curl "http://localhost:3463/api/decisions?q=test.harvest"

References

• Karvi harvest: feat(kernel): harvest decisions and lessons to Edda on task completion karvi#766, feat(kernel): push step execution events to Edda /api/events/karvi karvi#767
• Edda tags filter: feat(serve): add tags query filter to GET /api/decisions #338 (related but separate)
• Endpoint handlers: crates/edda-serve/src/lib.rs:1602-1823

---

Decomposed from fagemx/karvi planning pack by plan-decompose

[fagemx]

Research: Karvi Harvest Integration Tests (GH-342)

Overview

Issue #342 requires adding integration tests for three HTTP endpoints that Karvi will use to harvest decisions, lessons, and events into Edda:

1. POST /api/decide -- decision harvesting
2. POST /api/note -- lesson/note harvesting
3. POST /api/events/karvi -- execution event ingestion

Plus an integration smoke test combining all three + query verification.

Current State Analysis

Existing Tests in edda-serve/src/lib.rs

Test	What it covers	Gap
post_note_creates_event (L3780)	Basic note creation, returns evt_ prefixed ID	Does NOT test role, tags fields
post_note_rejects_bad_json (L5487)	Bad JSON → 400	Validation only
post_decide_creates_event (L3808)	Basic decide, returns evt_ ID, superseded is null	Does NOT test auto-supersede with same key
post_decide_rejects_bad_json (L5514)	Bad JSON → 400	Validation only
post_decide_rejects_missing_equals (L5540)	No = in decision → 400	Validation only
karvi_event_creates_execution_event (L4049)	Full payload, checks ledger fields	Good coverage
karvi_event_idempotent (L4084)	Duplicate event_id → 200 + "duplicate"	Good coverage
karvi_event_rejects_bad_version (L4132)	Bad version → 400	Good coverage
karvi_event_rejects_bad_event_type (L4168)	Bad event_type → 400	Good coverage
karvi_event_with_decision_ref (L4204)	Provenance link created	Good coverage

Missing Test Coverage (Issue Requirements)

1. POST /api/note with Karvi-style payload: role: "system", tags: ["auto-harvest", "lesson"] -- verify tags are written to ledger
2. POST /api/decide auto-supersede: Two decides with same key, different value → second returns superseded: "evt_..."
3. End-to-end smoke test: decide → note → karvi event → query back via GET /api/decisions?q=...
4. Query roundtrip: Verify edda ask "runtime" (or GET /api/decisions?q=runtime) returns harvested decision

Endpoint Implementation Details

POST /api/note (L1626-1649):

• NoteBody { text, role?, tags? }
• Defaults: role="user", tags=[]
• Returns: { event_id } with 201
• Uses new_note_event() from edda-core

POST /api/decide (L1666-1723):

• DecideBody { decision, reason? }
• Parses key=value from decision string
• Auto-supersede: calls find_active_decision(branch, key), if found with different value → adds provenance with rel: SUPERSEDES
• Returns: { event_id, superseded? } with 201

POST /api/events/karvi (L1763-1833):

• KarviEventBody { version, event_id, event_type, occurred_at, ... }
• Validates version="karvi.event.v1" and event_type in ["step_completed", "step_failed", "step_cancelled"]
• Uses append_event_idempotent for dedup
• Returns: { event_id, status: "created"|"duplicate" } with 201/200

GET /api/decisions (L774-808):

• Query params: q, limit, all, branch, after, before, tags
• Delegates to edda_ask::ask() which does keyword/domain/exact-key matching
• Returns AskResult { query, input_type, decisions, timeline, ... }

Test Infrastructure

• Tests use tempfile::tempdir() + setup_workspace() + router(tmp.path())
• tower::ServiceExt::oneshot() for single-request testing
• Router::new().merge(router(...)) + .clone() for multi-request tests (see L4238)
• Helper: karvi_event_json(event_id, event_type) at L4030

Key Functions Used

• edda_ledger::Ledger::open(path) -- open ledger for verification
• ledger.get_event(event_id) -- fetch event by ID
• ledger.iter_events() -- list all events
• ledger.find_active_decision(branch, key) -- find active decision by key
• edda_ask::ask(&ledger, query, &opts, None) -- query decisions

References

• Endpoint handlers: crates/edda-serve/src/lib.rs:1612-1833
• Test module: crates/edda-serve/src/lib.rs:3682+
• Test setup helper: crates/edda-serve/src/lib.rs:3699-3705
• karvi_event_json helper: crates/edda-serve/src/lib.rs:4030-4046
• edda-ask query engine: crates/edda-ask/src/lib.rs
• Event constructors: crates/edda-core/src/event.rs

[fagemx]

Innovation: Karvi Harvest Integration Tests (GH-342)

Approach Options

Option A: Individual Unit-Style Tests (one test per gap)

Add 4 new tests:

1. post_note_with_karvi_role_and_tags -- verify role="system" and tags persist
2. post_decide_auto_supersedes_same_key -- two decides, same key, check superseded field
3. karvi_harvest_smoke_test -- sequential decide→note→karvi_event
4. karvi_harvest_queryback -- decide then GET /api/decisions?q=... returns it

Pros: Focused, isolated, easy to debug failures
Cons: Smoke test requires multi-request setup (needs Router clone pattern)

Option B: Single Large Integration Test

One test that runs the full Karvi harvest flow: decide → note → karvi_event → query back.

Pros: Mirrors real-world usage, fewer test functions
Cons: Hard to diagnose which step failed, doesn't test edge cases (auto-supersede)

Option C: Hybrid (Recommended)

Individual tests for specific behaviors (tags, auto-supersede) + one end-to-end smoke test combining all three endpoints with a query roundtrip.

Pros: Best of both -- edge cases are isolated, integration is verified
Cons: More code, but all straightforward

Recommended: Option C

This matches the issue's Definition of Done items exactly:

DoD item	Test
POST /api/decide → ledger.db has new decision event	Already covered by post_decide_creates_event
POST /api/note → ledger.db has new note event with tags	NEW: post_note_with_karvi_tags
POST /api/events/karvi → ledger.db has karvi event	Already covered by karvi_event_creates_execution_event
Duplicate event_id → 200 + duplicate	Already covered by karvi_event_idempotent
edda ask "runtime" returns harvested decision	NEW: karvi_harvest_decide_queryback

Additional tests beyond DoD:

• NEW: post_decide_auto_supersedes_same_key -- validates Karvi re-deciding same key
• NEW: karvi_harvest_full_smoke -- sequential decide → note → karvi_event in one workspace

Implementation Notes

Multi-Request Pattern

For tests needing multiple requests to the same workspace, use the established pattern from get_decision_outcomes_returns_metrics (L4234):

let app = Router::new().merge(router(tmp.path()));
// First request
app.clone().oneshot(...).await;
// Second request
app.clone().oneshot(...).await;

Query Roundtrip

Use edda_ask::ask() directly against the ledger (like existing tests) rather than going through HTTP, since the HTTP layer for GET /api/decisions is already tested. This avoids needing Router::clone() after POST requests.

Alternatively, use HTTP GET /api/decisions?q=... for full end-to-end, which is more aligned with the issue's smoke test curl examples.

Tags Verification

After POST /api/note, open the ledger and call get_event(event_id) to verify:

• event.tags contains the expected tags
• event.payload or event.role matches "system"

[fagemx]

Plan: Karvi Harvest Integration Tests (GH-342)

Summary

Add 4 new integration tests to crates/edda-serve/src/lib.rs to validate the Karvi harvest call pattern against the three endpoints (decide, note, events/karvi) plus query roundtrip.

New Tests

Test 1: post_note_with_karvi_tags

File: crates/edda-serve/src/lib.rs (in mod tests)

Purpose: Verify POST /api/note with Karvi-style payload preserves role and tags in the ledger.

Steps:

1. Create temp workspace with setup_workspace()
2. POST to /api/note with body:

   {"text": "[GH-598] spawn fix pattern", "role": "system", "tags": ["auto-harvest", "lesson"]}

3. Assert response status = 201
4. Parse response, extract event_id
5. Open ledger, call get_event(event_id)
6. Assert event.payload["role"] == "system"
7. Assert event.payload["tags"] contains "auto-harvest" and "lesson"

Test 2: post_decide_auto_supersedes_same_key

File: crates/edda-serve/src/lib.rs (in mod tests)

Purpose: Verify that two POST /api/decide calls with the same key but different values produce a superseded field in the second response.

Steps:

1. Create temp workspace
2. Create Router::new().merge(router(tmp.path())) (for .clone())
3. POST first decide: {"decision": "runtime.spawn=sh", "reason": "initial"}
4. Assert 201, extract first event_id, confirm superseded is null
5. POST second decide: {"decision": "runtime.spawn=cmd.exe", "reason": "verified in #598"}
6. Assert 201, extract second event_id
7. Assert superseded equals the first event_id
8. Open ledger, verify only the second decision is active for key "runtime.spawn" via find_active_decision

Test 3: karvi_harvest_full_smoke

File: crates/edda-serve/src/lib.rs (in mod tests)

Purpose: End-to-end smoke test: sequentially send decide → note → karvi event, then verify all three are in the ledger.

Steps:

1. Create temp workspace
2. Create cloneable app router
3. POST decide: {"decision": "test.harvest=works", "reason": "integration test"}
4. Assert 201
5. POST note: {"text": "test harvest note", "role": "system", "tags": ["auto-harvest", "test"]}
6. Assert 201
7. POST karvi event using karvi_event_json("karvi-smoke-001", "step_completed")
8. Assert 201
9. Open ledger, verify 3 events exist (note from decide, note, execution_event)
   • Actually: new_decision_event creates a note-type event first, then adds decision payload. So count total events: at least 2 (decision creates 1 note+decision event, note creates 1, karvi creates 1 = 3 events total)
10. Verify each event_id is retrievable from ledger

Test 4: karvi_harvest_decide_queryback

File: crates/edda-serve/src/lib.rs (in mod tests)

Purpose: Verify that a decision created via POST /api/decide is queryable via GET /api/decisions?q=...

Steps:

1. Create temp workspace
2. Create cloneable app router
3. POST decide: {"decision": "runtime.spawn=cmd.exe", "reason": "verified in #598"}
4. Assert 201
5. GET /api/decisions?q=runtime
6. Assert 200
7. Parse response, check decisions array contains an entry with key: "runtime.spawn" and value: "cmd.exe"

Implementation Details

Router Clone Pattern

For tests 2-4, use the multi-request pattern:

let app = Router::new().merge(router(tmp.path()));
let resp1 = app.clone().oneshot(...).await.unwrap();
let resp2 = app.clone().oneshot(...).await.unwrap();

Test Location

All tests go inside the existing mod tests block in crates/edda-serve/src/lib.rs, after the existing karvi tests (after L4232).

No New Dependencies

All required types and functions are already imported in the test module:

• super::* brings in all handler types
• axum::body::Body, axum::http::Request, tower::ServiceExt
• Ledger::open() for verification
• edda_ask for query roundtrip (already a dependency of edda-serve)

Verification Strategy

cargo test -p edda-serve post_note_with_karvi_tags
cargo test -p edda-serve post_decide_auto_supersedes_same_key
cargo test -p edda-serve karvi_harvest_full_smoke
cargo test -p edda-serve karvi_harvest_decide_queryback
cargo clippy -p edda-serve -- -Dwarnings

Definition of Done Mapping

DoD item	Test
POST /api/decide → ledger has decision event	post_decide_creates_event (existing) + post_decide_auto_supersedes_same_key (new)
POST /api/note → ledger has note event with tags	post_note_with_karvi_tags (new)
POST /api/events/karvi → ledger has karvi event	karvi_event_creates_execution_event (existing) + karvi_harvest_full_smoke (new)
Duplicate event_id → 200 + duplicate	karvi_event_idempotent (existing)
edda ask "runtime" returns harvested decision	karvi_harvest_decide_queryback (new)

Estimated Effort

~100-120 lines of test code total. All patterns are well-established in the existing test suite. No production code changes needed.

[fagemx]

Work completed. PR created: #347

Added 4 integration tests:

• post_note_with_karvi_tags — role/tags persistence
• post_decide_auto_supersedes_same_key — auto-supersede verification
• karvi_harvest_full_smoke — end-to-end decide+note+karvi_event
• karvi_harvest_decide_queryback — decide then query roundtrip

All 90 tests passing, clippy clean.