feat: add RealtimeManager to bridge CursorTracker events into PgSubscriber

[pyramation]

Summary

Adds RealtimeManager, a new class in graphile-realtime-subscriptions that bridges the cursor-tracking polling system (CursorTracker + drain_changes()) into PostGraphile's live subscription delivery path via PgSubscriber.

How it works: When drain_changes() returns ChangeLogEntry objects, RealtimeManager converts them into the same "OP:rowId" NOTIFY payload format used by emit_change and emits them on PgSubscriber's internal EventEmitter. This means existing subscription plans (which use grafast's listen() step on the same EventEmitter) handle cursor-tracked events identically to real NOTIFY events — no changes needed to the plugin or subscription plans.

This enables at-least-once delivery: NOTIFY provides instant best-effort delivery, while cursor polling catches up on anything missed during disconnects or restarts. Duplicates are expected; clients should be idempotent.

New files:

• src/realtime-manager.ts — RealtimeManager class + helper functions (extractRowId, entryToNotifyPayload, entryToChannel)
• __tests__/realtime-manager.test.ts — 22 tests covering helpers, lifecycle, multi-table event dispatch, and error handling

Modified files:

• src/types.ts — adds RealtimeManagerOptions interface
• src/index.ts, src/plugin.ts — re-export RealtimeManager and RealtimeManagerOptions

Builds on PR #1110 (CursorTracker class). Server-level wiring (start/stop with server lifecycle) is a follow-up.

Review & Testing Checklist for Human

• Private API coupling in getEventEmitter() (realtime-manager.ts L139-152): Accesses PgSubscriber's private eventEmitter property via runtime property check. This is the core integration mechanism — verify it works against the actual @dataplan/pg@1.0.0 PgSubscriber class in a running server. If eventemitter3 changes its internal structure in a future @dataplan/pg release, this will silently fail (logged warning, events dropped).
• extractRowId assumes id field (L46-50): Hardcodes payload_after.id / payload_before.id. Tables with non-id primary keys (e.g., composite keys, uuid column named differently) will produce payloads without row IDs, causing subscription plans to see "INSERT" instead of "INSERT:uuid". Confirm this is acceptable or whether the row ID field should be configurable.
• pgSubscriber: unknown type (types.ts L120): Avoids a hard dep on @dataplan/pg types but sacrifices compile-time safety. Passing the wrong object will silently degrade (warn + no dispatch). Consider whether importing the PgSubscriber type (even as a dev/peer dep) would be better.
• Integration test with real PgSubscriber: All tests mock the EventEmitter. Recommend manually verifying with a real PostGraphile instance that cursor-polled events actually arrive at GraphQL subscription clients.

Notes

• 92/92 tests passing locally (22 new + 70 existing).
• TypeScript compiles clean (tsc --noEmit).
• The WithPgClient import in realtime-manager.ts is unused directly (only referenced through RealtimeManagerOptions) — may trigger an unused-import lint rule depending on config.

Link to Devin session: https://app.devin.ai/sessions/19485cf5cc58416a9f86068563d512f5
Requested by: @pyramation

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring