4.3 KiB
4.3 KiB
Bridge Implementation Plan (MVP)
Goal
Implement bridge v1.1 to relay messages between agentchattr and authoritative runtimes (shard, prime) with handoff continuity, dedupe, and loop controls.
Scope (MVP)
- Poll/read messages from chattr
- Route envelopes to shard/prime adapters
- Receive adapter responses and post back to chattr
- Maintain conversation_id + mapping state
- Enforce dedupe + loop controls
- Basic observability + retries + DLQ
Out of Scope (post-MVP)
- Full event-driven webhooks replacing poll
- Advanced semantic fork classifier
- Multi-region HA / horizontal shard orchestration
Milestones
M0 — Repo + service skeleton
- Create
chattr-bridgerepo/folder - Language/runtime choice (Python FastAPI recommended for speed)
- Config loader (env + file)
- Health endpoints:
/healthz,/readyz,/metrics - Structured logging with correlation IDs
Deliverable:
- Service boots in dev with no routing enabled
M1 — State layer
- sqlite init + migrations
- Tables from spec v1.1:
- conversations
- surface_bindings
- message_map
- handoff_state
- relay_events
- retry_queue
- dead_letter
- Data access layer + transaction helpers
Deliverable:
- CRUD tests pass for all core state ops
M2 — Chattr client
- Poll loop (
BRIDGE_POLL_INTERVAL_MS) - Read channel messages with cursor
- Normalize into canonical envelope
- Post message API back into channel/thread
Deliverable:
- Echo test path (bridge reads and re-posts tagged test message)
M3 — Routing engine
- Mention detection
- Unmentioned fanout to both targets
- conversation_id start/reuse/fork logic
- dedupe key generation + lookup
- loop controls (hop/cycle/cooldown/self-echo)
Deliverable:
- Deterministic routing tests (table-driven)
M4 — Adapter integration
- HTTP adapter client for
/ingest - Ack/error handling per schema
- Retry backoff + DLQ integration
- Callback endpoint
/adapter/eventsfor async responses
Deliverable:
- Simulated adapter integration test suite green
M5 — Handoff continuity
- Build handoff packets on first route/surface switch
- Drift trigger checks (idle/messages/manual)
- Payload caps + truncation policy
Deliverable:
- Surface-switch continuity tests pass
M6 — k8s deployment
- Build/push image
- Apply
bridge-k8s-v1.yaml(with real image + secrets) - Wire network reachability to prime adapter
- Smoke tests in shard namespace
Deliverable:
- Running bridge pod with successful end-to-end relay
M7 — tuning pass
- Fanout response etiquette tuning under real usage
- Conversation fork heuristic conservative defaults
- Poll interval + timeout tuning
Deliverable:
- Ops baseline doc + tuned defaults
Suggested implementation layout
chattr-bridge/
app/
main.py
config.py
logging.py
metrics.py
api/
health.py
adapter_events.py
core/
envelope.py
routing.py
handoff.py
dedupe.py
loop_guard.py
conversation.py
clients/
chattr_client.py
adapter_client.py
store/
db.py
migrations/
models.py
repo.py
workers/
poller.py
retry_worker.py
tests/
unit/
integration/
Dockerfile
pyproject.toml
README.md
Integration order recommendation
- Shard adapter first (local/easier control)
- Prime adapter second (validate network/auth path)
- Enable fanout after both stable
Operational checklist
- Secrets injected (signing key, chattr token)
- DB PVC mounted + writable
- Prime adapter reachable from bridge pod
- TLS/auth validated if adapter external
- Retry/DLQ dashboards visible
- Alert on adapter error rate and queue depth
Risk watchlist
- Poll jitter causing duplicate reads -> mitigate with robust dedupe
- Fanout noise causing duplicate-value responses -> runtime etiquette + post-hoc tuning
- Over-eager forking -> keep fork heuristic conservative; prefer reuse unless explicit fork
- Prime adapter reachability -> solve early before broad rollout
MVP completion definition
MVP is complete when:
- dingo -> chattr unmentioned message reaches both adapters
- valid 0/1/2 responses handled cleanly
- explicit mention routing works
- conversation_id continuity + handoff behavior verified
- no relay loops under stress test
- bridge survives restart without state loss