Skip to content

[P1-5] Trajectory subscription stream: tokio broadcast + SDK trajectory.subscribe #39

@justrach

Description

@justrach

Parent: #34
Priority: P1 (live data flow — graff-memd needs this to react in real time)
Branch base: release/0.1.53

Why

Today TrajectoryRecorder writes to SQLite. graff-memd needs to subscribe to those events live without polling. Hermes does this in-process; we need a broadcast channel that crosses the N-API boundary.

Scope

Rust side

  • TrajectoryRecorder gets a tokio::sync::broadcast::Sender<TrajectoryEvent> alongside its repo write path. Every recorded event is also broadcast.
  • New API on forge_api::ForgeAPI: subscribe_trajectory(conversation_id: Option<ConversationId>) -> Receiver<TrajectoryEvent>.

SDK side (sdk/typescript/src/lib.rs + wire.rs)

  • #[napi] method on GraffApi: subscribeTrajectory(conversationId?: string): TrajectoryStream.
  • TrajectoryStream exposes .next() returning a JSON-serialized event (mirror ChatStreamHandle).
  • Public TS:
    graff.trajectory.subscribe(conversationId?: string): AsyncIterable<TrajectoryEvent>

Acceptance

  • Two subscribers see the same events
  • Subscriber that lags doesn't block the recorder (use RecvError::Lagged handling — emit a lag event and continue)
  • for await ... break cancels cleanly (no hanging tokio task)
  • Smoke test in examples/trajectory-subscribe.ts

Metadata

Metadata

Assignees

No one assigned

    Labels

    severity: highSignificant impact; core functionality is impaired.type: featureBrand new functionality, features, pages, workflows, endpoints, etc.work: complexThe situation is complex, emergent practices used.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions