Skip to content

Add realtime generation lifecycle core - #1750

Draft
Zetazzz wants to merge 1 commit into
test/performance-harness-corefrom
agent/realtime-lifecycle-core
Draft

Add realtime generation lifecycle core#1750
Zetazzz wants to merge 1 commit into
test/performance-harness-corefrom
agent/realtime-lifecycle-core

Conversation

@Zetazzz

@Zetazzz Zetazzz commented Aug 17, 2026

Copy link
Copy Markdown
Contributor

Summary

Implements planning item F05 on top of the reusable performance harness in #1716.

  • makes CursorTracker startup, polling, heartbeat, stop, and cleanup concurrency explicit and idempotent
  • treats registration plus the initial drain as a strict readiness boundary and rolls back a failed start
  • waits for active cursor work before cleanup, suppresses late dispatch after stop, and surfaces retryable cleanup failures
  • adds a generation-scoped Grafast subscriber with exact topic ownership, fixed-capacity local queues, and awaited aggregate teardown
  • adds an activatable subscriber facade so a stable PostGraphile-facing identity can fail closed until its generation source is ready
  • moves cursor catch-up delivery behind an explicit RealtimePublisher capability, with batch topic/schema preflight and fatal shutdown
  • exposes credential-free build-time topic discovery plus a collector that rejects missing, empty, changed, malformed, or foreign topic sets
  • preserves the deprecated pgSubscriber adapter for existing callers while requiring an exact schema allowlist for new explicit publishers

Boundary

This PR is intentionally limited to the F05 lifecycle core in graphile-realtime-subscriptions.

It does not wire generation activation or publication into graphile-cache or the GraphQL server, install a shared PostgreSQL notification broker, change request admission, replace the existing subscription event gate, add pre-delivery RLS authorization, or implement server-side failed-generation retirement. Those remain F12, F24, and F44.

The existing realtime plugin behavior is unchanged unless a caller opts into the new onTopicsDiscovered build-time callback. No package metadata, lockfile, dependency patch, default preset, or unrelated package is changed.

F05 is a lifecycle foundation rather than a standalone enabled optimization, so this PR makes no isolated performance claim and does not add an F05 benchmark arm before the F12/F24 integration exists.

Validation

Passed:

  • graphile-realtime-subscriptions: 6 suites, 130 tests
  • lifecycle suite with Jest open-handle detection
  • real PostgreSQL realtime integration: 2 suites, 16 tests
  • graphile-realtime-subscriptions CJS and ESM builds
  • existing graphile-cache CJS and ESM consumer build
  • graphile-realtime-test CJS and ESM build
  • performance harness: 5 suites, 7 tests, plus CJS and ESM build
  • ESLint on all changed TypeScript files
  • pnpm install --frozen-lockfile
  • git diff --check

The diff was audited with zero-context, word, and ignore-whitespace views. It contains no repo-wide or unrelated formatting changes.

Refs constructive-io/constructive-planning#1693.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant