Module stream_subscribe 

RFC-019 Stage A — cross-backend stream-cursor subscription surface.

EngineBackend::subscribe_{lease_history,completion,signal_delivery, instance_tags} return a StreamSubscription — a pinned tokio_stream::Stream of Result<StreamEvent, EngineError>. The cursor is an opaque byte blob the consumer persists across crashes and hands back on resume; the first byte identifies the backend family + version so cursors stay stable across backend upgrades.

This module defines the wire types only — no trait default is here; defaults live on the EngineBackend trait in crate::engine_backend. Real impls live in ff-backend-valkey (Valkey XREAD BLOCK-backed lease_history) and ff-backend-postgres (LISTEN/NOTIFY-backed completion) per RFC-019 §Implementation Plan.

Four-family allow-list (RFC-019 §Open Questions #5, owner- adjudicated 2026-04-24): new families require an RFC amendment.

Structs

StreamCursor

Opaque, backend-versioned cursor. Consumers persist the bytes, hand them back on resume. The first byte MUST encode a backend-family + version prefix so cursors stay stable across backend upgrades (Valkey: 0x01, Postgres: 0x02, …). The remainder is backend- specific.

StreamEvent

Per-event payload.

Enums

StreamFamily

Event families covered by the v0.9 allow-list (RFC-019 §Open Questions #5). #[non_exhaustive] so v0.10+ families land without breaking consumer match blocks, but the owner-adjudicated stance is that new families require an RFC amendment — this is not a generic escape hatch.

Constants

POSTGRES_CURSOR_PREFIX

Postgres family prefix byte.

VALKEY_CURSOR_PREFIX

Valkey family prefix byte (RFC-019 §Backend Semantics Appendix).

Functions

decode_postgres_event_cursor

Decode a Postgres event cursor back to event_id. None = start-from-tail.

decode_valkey_cursor

Decode a Valkey cursor back to (ms, seq). Returns None for the empty / tail-from-now cursor. Returns Err for malformed bytes (wrong prefix, truncated).

encode_postgres_event_cursor

Encode a Postgres event_id (i64, from ff_completion_event) into a cursor.

encode_valkey_cursor

Encode a Valkey stream id (ms, seq) into a cursor.

Type Aliases

StreamSubscription

Shape of a subscription stream.