diagnose(proof): classify Realtime join limit

[bizzybee90]

Purpose

Convert the governed staging proof's generic live_realtime_join_limit_exceeded stop into a fixed, sanitized, source-owned topic-class diagnostic so the next proof can identify the exact canonical Realtime subscription without exposing raw topic or tenant data.

Exact failing proof: run 31672684850, attempt 1, source f5d381a573d2f74ed1223e81af693ed83eb6a2b5; tenant-a / reviews / desktop-1440x900.

Included scope

• Add a diagnostic-only producer for the existing Realtime join-limit stop.
• Emit only {adapter:'realtime', phase:'join', reason_code:'join_limit_exceeded', topic_class:<fixed source class>} when attribution is exact.
• Validate and code-bind that exact shape in the cloud adapter.
• Enforce route/viewport/context compatibility for the fixed topic class.
• Add producer and consumer adversarial tests for exact attribution, schema-v1 fallback, first-write behavior, one-read getters, hostile objects, cross-code rejection, route binding, and redaction.

Explicit exclusions

• No join-limit, request-policy, occurrence, timeout, route-coverage, or acceptance change.
• No Supabase schema, migration, RLS, grant, provider, credential, staging, or production change.
• No raw topic, URL, workspace/user identity, Phoenix ref, subscription, payload, token, count, limit, header, body, or error detail.

Architecture placement

Current owner / directory: existing product-proof live recorder and cloud Playwright diagnostic adapter under scripts/.

Dependencies and duplicate-system check: reuses the recorder's existing independent source-owned realtimeTopicClass classifier and the cloud adapter's established exact-shape/code-binding pipeline; no new subsystem or shared acceptance matcher.

Security and tenancy impact

• Authentication / authorization: read-only diagnostic classification only; no auth/grant change.
• Tenant isolation: topic attribution requires the exact internal normalized policy and expected route/workspace binding; malformed or unclassified topics stay schema v1.
• Service-role impact: none.
• Provider / webhook impact: none.
• Secrets impact: none; exact-output and hostile-object tests prove no raw Realtime or tenant values enter the diagnostic.

Data impact

• Schema / migration / RLS / grant impact: none.
• Backfill, retention, or rollback: none; one-commit code rollback only.

Verification

• Behavioural tests: focused new tests 2/2; complete live + cloud suites 598/598; broader product-proof cloud suite 1,170 passed / 1 expected skip / 0 failed.
• CI / security review: scoped ESLint, all four node --check, git diff --check, npm audit (0 vulnerabilities), and independent security review (0 findings) pass locally; fresh exact-head hosted gates and CodeRabbit review mandatory.

Release safety

• Deployment scope: no deployment in this PR; after protected merge, private no-index preview then one governed staging proof bound to the exact new receipt.
• Monitoring / stop conditions: stop on any gate/review failure, head/base drift, unsafe attribution, cleanup/postflight/recovery failure, or any proof result other than the fixed sanitized contract.
• Rollback or containment: revert the single diagnostic commit; prior failed proof cleanup/postflight/recovery passed and published zero artifacts.

Documentation and generated files

• Docs / diagrams / ADR updates: none; no architecture, evidence eligibility, or gate change.
• Generated-file or lockfile justification: none.

Completion check

• Starts from current origin/main.
• No valuable work remains only in a dirty worktree, stash, or local-only branch.
• Source branch will be retired under the branch policy after merge.
• Any PR-size or branch-retention exception is documented below, or neither applies.

Policy exceptions (leave blank when none apply)

PR-size exception rationale: four files and one coherent diagnostic-only safety change; 476 insertions / 21 deletions, with the majority in adversarial producer/consumer tests required to prove attribution cannot widen behavior or disclose raw Realtime data.

Retained branch reason / owner / review date / maximum retention date:

Summary by CodeRabbit

• New Features

  • Added diagnostics for Realtime join-limit failures, including the affected topic class and join phase.
  • Improved failure reporting with validated, topic-specific diagnostic details.
  • Added safeguards to redact sensitive identifiers and preserve the first recorded diagnostic.

• Bug Fixes

  • Prevented malformed, unsupported, duplicated, or cross-topic diagnostics from being attached to failures.
  • Ensured unclassified topics continue to fail without emitting invalid diagnostics.

• Tests

  • Added comprehensive coverage for join-limit failures, diagnostic validation, redaction, and error-handling scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a600bdcf-0040-4a64-8264-28fd172751a4

📥 Commits

Reviewing files that changed from the base of the PR and between f5d381a and f23b1f3.

📒 Files selected for processing (4)

• scripts/product-proof-cloud-playwright.mjs
• scripts/product-proof-cloud-playwright.test.mjs
• scripts/product-proof-live-evidence.mjs
• scripts/product-proof-live-evidence.test.mjs

---

📝 Walkthrough

Walkthrough

The change adds Realtime join-limit diagnostics to live evidence recording. Cloud Playwright now validates their schema, topic classification, route binding, redaction, and attachment rules. Tests cover classified and invalid topic scenarios.

Changes

Realtime join-limit diagnostics

Layer / File(s)	Summary
Generate join-limit evidence scripts/product-proof-live-evidence.mjs, scripts/product-proof-live-evidence.test.mjs	The join handler records a validated topic diagnostic before raising live_realtime_join_limit_exceeded. Tests cover Phoenix references, topic classification, first-write behavior, terminal handling, and redaction.
Validate and route diagnostics scripts/product-proof-cloud-playwright.mjs, scripts/product-proof-cloud-playwright.test.mjs	Cloud Playwright distinguishes join-limit payloads, validates their fields, enforces topic-specific routes, and rejects malformed, duplicated, incompatible, or cross-route diagnostics. Tests cover schema fallback and hostile inputs.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Mergeability Score: ⚪ Minimal · up to f23b1

This PR adds a localized, sanitized diagnostic for an existing Realtime join-limit stop without changing limits, access controls, or deployment behavior; no actionable merge-blocking risk remains after normal checks and review.

Possibly related PRs

• bizzybee90/bizzybee-app#424: Introduced the route-failure diagnostic system extended by this change.
• bizzybee90/bizzybee-app#473: Added structured Realtime diagnostics in the same producer and consumer paths.
• bizzybee90/bizzybee-app#490: Extended Realtime failure diagnostics and route validation in the same files.

Sequence Diagram(s)

sequenceDiagram
  participant RealtimeTopic
  participant JoinHandler
  participant DiagnosticRecorder
  participant CloudPlaywright
  participant RouteFailure
  RealtimeTopic->>JoinHandler: overflow join
  JoinHandler->>DiagnosticRecorder: validated topic diagnostic
  JoinHandler->>RealtimeTopic: live_realtime_join_limit_exceeded
  DiagnosticRecorder->>CloudPlaywright: diagnostic payload
  CloudPlaywright->>CloudPlaywright: validate schema and route
  CloudPlaywright->>RouteFailure: attach validated diagnostic

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes the primary change: classifying Realtime join-limit failures for diagnostics.
Description check	✅ Passed	The description covers the required sections, scope, security, data impact, verification, release safety, and completion details.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/diagnose-product-proof-realtime-join-limit-20260813

---

_{Comment @coderabbitai help to get the list of available commands.}