feat(timeline): kb.timeline — entity chronological trajectory (#313)

[dhgoal]

closes #313.

kb.read_entity returns an entity and its claims as a flat set; kb.neighbors expands graph adjacency at a point in time. neither answers "what did the kb learn about this entity, in what order?" — a trajectory. the raw material is already on disk: claims and relations carry created_at, and decision time is recoverable from the append-only audit log. this orders an entity's approved claims and relations along that time axis.

surface

kb.timeline(entity_id, order=effective|decided, since, until, types, limit, session_id)
vouch timeline <entity-id> [--order decided] [--since ...] [--until ...] [--types decision,fact] [--limit N] [--json]

• order — effective orders by the artifact's own created_at (when the fact entered the kb); decided recovers approval time from the audit log's approve events (object_ids = [proposal_id, result_id], event created_at = decision time), falling back to created_at for artifacts written outside the proposal path.
• entries — {when, kind, id, summary, status}, oldest first (most-recent-last). status is the claim's current ClaimStatus; a superseded/archived claim still appears, flagged. relations have no status field, so status = null.
• filters — since/until bound the chosen timestamp (reusing metrics.parse_since, so iso dates and durations both work); types filters on claim type (fact, decision, …), relation type, or the literal claim / relation; limit keeps the most recent N entries, still in chronological order.
• only approved durable artifacts are read (list_claims / list_relations); pending proposals never appear.

review gate & scope

pure read. no propose_*, no kb.approve, no mutation — a viewport over already-reviewed artifacts, exactly like read_entity / neighbors. tests/test_timeline.py::test_timeline_writes_nothing asserts a scoring run appends no audit event. all ordering/reconstruction logic lives in a new src/vouch/timeline.py; storage.py stays pure i/o. everything is local — no network.

per the per-tool convention, kb.timeline attaches the _meta.vouch_salience sidebar inline (via salience.attach_salience, as kb_context does) when a session_id is passed; it's a no-op otherwise.

registered at all four sites so test_capabilities passes: @mcp.tool() kb_timeline in server.py, _h_timeline + HANDLERS["kb.timeline"] in jsonl_server.py, METHODS in capabilities.py, and vouch timeline in cli.py.

what breaks for an existing .vouch/

nothing. purely additive read surface over already-committed artifacts.

tests

tests/test_timeline.py (15 tests): effective vs decided ordering (a claim created earliest but decided latest sorts opposite ways under the two axes), the since/until/types/limit filters, superseded-still-visible-and-flagged, entity-scoping (a second entity's claim is excluded), missing-entity and bad-order errors, the no-mutation invariant, the four-site registration, the jsonl handler, and the cli table/json/missing paths. make check green (pytest, mypy, ruff).

note

sibling to the open #351 (vouch digest); the two touch cli.py and the ## [Unreleased] changelog in different spots and are independent — whichever merges first, the other rebases cleanly.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 3c7f9762-6056-4f82-9574-63b5ba87ba0c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}