Wayfinder: Instrumenta v1 implementation plan

[Teagan42]

Destination

An implementation plan for Instrumenta v1 ready to hand to build agents: PR slicing and dependency order, library choices, image contract, UI stack, testing fixtures, and any Conduit-side prerequisites. The spec (#198) fixes what; this map fixes how to build it without further design work.

The way is clear. Six PRs, dependency graph mapped, merge order set. See #219 for the full plan.

Notes

Domain: MCP (Anthropic Model Context Protocol); Conduit link protocol (spec-0005); linked-service lifecycle (spec-0010). Sibling services services/memoria/ and services/vox/ are the house-style reference.

Skills every session should consult: mattpocock-skills:grilling, mattpocock-skills:domain-modeling, claude-api (whenever MCP SDK / model / Anthropic API details are in play).

Standing preferences: FastAPI + httpx + pytest, static/ HTML+HTMX for UI (no SPA), mirror Memoria directory layout and single-HTTP-seam test style. Repository-pattern backends (no ORM). cryptography.fernet for secrets. In-process asyncio supervisor for stdio upstreams. mcp Python SDK for both server and client roles.

Decisions so far

• Conduit caches tools/list once, ignores list_changed — instrumentas filter-on-unreachable has no effect in Conduit today.
• mcp SDK can host streamable-HTTP + SSE on one FastAPI app — technically yes; SDK marks SSE superseded.
• Ship streamable-HTTP only for v1, drop SSE — per-transport toggle removed from config schema; single /mcp endpoint.
• Drop filter-on-unreachable for v1 — tools advertised always; calls to unreachable upstreams fail loud.
• Instrumenta UI: top-tabs, Vox conventions — Variant B winner; CSS custom properties, prefers-color-scheme, zero CDN deps, dl.kv sections, origin badges, compact server rows.
• PR slicing: 6-PR plan with dependency graph — Items API, Audit, dev.sh, Stdio supervisor, HTMX UI, Upstream forwarding. PRs 1–4 independent; PR 5 waits on all; PR 6 waits on PR 1+4.

Not yet specified

• Retention policy for the audit log. Spec says bounded row count; actual N and pruning cadence are fog until real-world call volume is known. Does not block implementation.
• Rollout / release-notes wording for Conduit users when Instrumenta first appears as a LinkedServiceKind tab. Marketing concern, not engineering.
• Per-server timeout defaults beyond the spec "sensible default (e.g. 30s)". The plan picks 30s as the default; can be tuned post-ship.

Out of scope

• Postgres backend (sqlite default ships first)
• Hot-reload of upstreams (snapshot-once correct for v1)
• API key auth on mutating routes (deferred)
• shell.exec dangerous tool (deferred)
• Layered stdio images (instrumenta-node, instrumenta-python)
• Audit log retention/pruning
• UI-toggleable global concurrency cap
• Secret key rotation tooling

[Teagan42]

Skeleton PR #206 merged. Frontier for next session: aggregator + built-in tools (spec #198 covers scope; decisions #203/#204 already resolved).