feat: add NOTIFY payload parsing, overflow detection, and per-subscriber throttling

[pyramation]

Summary

Updates the graphile-realtime-subscriptions plugin to parse the new NOTIFY payload format (TG_OP:id1,id2,... or INVALIDATE) from the emit_change trigger (introduced in constructive-db PR #1094), and adds two layers of overflow protection.

Key changes:

• parseNotifyPayload() — parses INSERT:uuid1,uuid2 or INVALIDATE into a structured { event, rowIds, overflow } object
• EventThrottle — per-table event rate limiter using a 1-second window; returns deliver / overflow / drop to control event delivery
• New payload fields — rowId: UUID and overflow: Boolean! added to the generated XxxSubscriptionPayload GraphQL type
• Full collection mode fix — instead of passing null to resource.get(), the plugin now extracts the first row ID from the parsed payload when no id argument is provided (single-record mode still takes precedence via subscribedId)
• Configurable threshold — overflowThreshold option on createRealtimeSubscriptionsPlugin() (default: DEFAULT_OVERFLOW_THRESHOLD = 50)

Review & Testing Checklist for Human

• Throttle scope mismatch: The EventThrottle instance is created once per table inside buildPlans() (schema build time). This means all subscribers to the same table share the same throttle counter. The doc comment says "per-subscriber, per-table" but the implementation is per-table-globally. Verify this is acceptable or if a per-connection throttle is needed.
• resource.get({ id: null }): When the throttle drops an event ($parsed is null) or for INVALIDATE/DELETE with no row IDs, $rowId resolves to null and resource.get({ id: null }) is called. Confirm Grafast/PostGraphile returns null gracefully here rather than throwing.
• Grafast lambda behavior: The plugin uses lambda() extensively for payload transformation. The unit tests mock lambda as a synchronous function call. Verify the actual Grafast lambda step handles null return values (for dropped events) correctly in a real pipeline—particularly that the subscription doesn't hang or error.
• Window semantics: EventThrottle uses a fixed tumbling window (resets every 1000ms), not a true sliding window. At window boundaries, up to 2× threshold events could pass within a 1-second span. Decide if this is acceptable.

Recommended test plan: Deploy both this PR and constructive-db #1094 together, then:

1. Subscribe to a @realtime table via GraphQL and verify INSERT:uuid payloads produce { event: "INSERT", rowId: "...", overflow: false }
2. Run a bulk INSERT of >50 rows and verify the subscription receives { event: "INVALIDATE", overflow: true } instead of 50+ individual events
3. Fire >50 rapid single-row changes within 1 second and verify the plugin-side throttle triggers INVALIDATE

Notes

• Companion DB-side change: constructive-db PR feat(graphile-test): add setUserContext utility for RLS testing #1094 (modifies the emit_change trigger to include row IDs and send INVALIDATE for >50 rows)
• parseNotifyPayload and EventThrottle are exported from plugin.ts for direct unit testing

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