Files

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-bridge repo/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/events for 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

  1. Shard adapter first (local/easier control)
  2. Prime adapter second (validate network/auth path)
  3. 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