feat(proof): classify Realtime finalization failure

[bizzybee90]

Purpose

Classify the existing fail-closed live_realtime_incomplete product-proof result with one fixed, sanitized Realtime lifecycle class so the next governed staging run can identify the narrow repair target without weakening acceptance.

Included scope

• Export one frozen primitive-only Realtime incomplete class contract.
• Classify only the existing finalization failure into cdp-unmatched, handshake-missing, cdp-open, mediated-open, pending-references, sent-frame-mismatch, received-frame-mismatch, or multiple.
• Normalize and attach the exact four-field diagnostic only to live_realtime_incomplete.
• Add producer and consumer tests for every class, ambiguity, hostile input, code binding, first-failure precedence, idempotence, disposal, and redaction.

Explicit exclusions

• No Realtime policy, join/frame/close acceptance, occurrence count, timeout, wait, retry, teardown, evidence eligibility, route coverage, or credential change.
• No app, schema, migration, RLS, grant, provider, staging-state, production, or customer-data change.
• No repair is inferred before the governed diagnostic rerun identifies a single fixed class.

Architecture placement

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

Dependencies and duplicate-system check: extends the existing finalize diagnostic latch and exact route-diagnostic normalizer; no second recorder, transport observer, or evidence schema is introduced.

Security and tenancy impact

• Authentication / authorization: unchanged; diagnostic-only after existing authenticated capture and finalization.
• Tenant isolation: unchanged; no identity is emitted, and the recorder continues using its existing exact tenant-bound policy.
• Service-role impact: none.
• Provider / webhook impact: none.
• Secrets impact: none; output is limited to four fixed allowlisted fields and excludes URLs, topics, frames, refs, IDs, headers, bodies, counts, errors, identities, and credentials.

Data impact

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

Verification

• Behavioural tests: live recorder 186/186; cloud Playwright 185/185; complete product-proof cloud suite 928 passed with one expected disposable-database skip; every fixed class, multi-class collapse, prior-failure precedence, hostile getters/Proxies, exact code binding, and redaction covered.
• CI / security review: scoped ESLint, TypeScript, Node syntax, and diff checks pass; post-implementation security audit has 0 critical/high/medium/low findings; fresh hosted exact-head gates and CodeRabbit approval are mandatory.

Release safety

• Deployment scope: private no-index preview only after protected exact-head merge, followed by one receipt-bound governed staging proof.
• Monitoring / stop conditions: stop on any hosted gate/review failure, unsafe diagnostic shape, changed top code, cleanup/postflight/recovery failure, or any result requiring acceptance/timing widening.
• Rollback or containment: revert commit 174c6639f629b699f7681f5c37e960c9e5ba224b; current exact main predecessor is bea447e7adf01f6a1f7e24dd5f43f2b3c11d99dc; failed governed proofs remain unpublished and cleanup/recovery remain authoritative.

Documentation and generated files

• Docs / diagrams / ADR updates: none; no architecture, gate, data, or evidence-eligibility 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; 492 of 615 added lines are adversarial producer/consumer tests needed to prove that fixed attribution cannot expose raw Realtime data, cross-bind error codes, or mask an earlier safety failure.

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

Summary by CodeRabbit

• New Features

  • Added diagnostics for incomplete realtime connections, including missing handshakes, unmatched links, open closures, and frame mismatches.
  • Realtime evidence now records when multiple incompletion conditions occur simultaneously.
  • Added a supported set of realtime incompletion categories for consistent reporting.

• Bug Fixes

  • Improved validation and redaction of realtime diagnostic data.
  • Prevented invalid, mismatched, duplicate, or incompatible diagnostics from being attached to failures.
  • Preserved existing network-failure diagnostics when realtime validation also fails.

[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: 4ce6bd45-2437-487e-8630-9959e6af7201

📥 Commits

Reviewing files that changed from the base of the PR and between 174c663 and a254b0c.

📒 Files selected for processing (1)

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

---

📝 Walkthrough

Walkthrough

The change adds bounded diagnostics for incomplete Realtime connections. Finalization classifies incomplete lifecycle states, while cloud Playwright validates and attaches matching diagnostics to route failure receipts. Tests cover contracts, sanitization, immutability, malformed inputs, and diagnostic precedence.

Changes

Realtime diagnostic flow

Layer / File(s)	Summary
Diagnostic contract and classification scripts/product-proof-live-evidence.mjs, scripts/product-proof-live-evidence.test.mjs	Defines the allowed incomplete classes and classifies unmatched CDP links, handshake gaps, open closures, pending references, frame mismatches, and multiple conditions. Tests verify the fixed class set and sanitized frozen diagnostics.
Finalization persistence and precedence scripts/product-proof-live-evidence.mjs, scripts/product-proof-live-evidence.test.mjs	Stores incomplete diagnostics during finalization, preserves earlier network-failure diagnostics, and verifies idempotent results and disposal behavior.
Route diagnostic validation and attachment scripts/product-proof-cloud-playwright.mjs, scripts/product-proof-cloud-playwright.test.mjs	Validates live_realtime_incomplete diagnostics and attaches matching schema-v2 receipts. Tests cover schema variants, hostile inputs, single-read access, incompatible codes, and duplicate attachment.

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

Sequence Diagram(s)

sequenceDiagram
  participant RealtimeConnection
  participant LiveEvidenceFinalization
  participant CloudPlaywright
  participant RouteFailureReceipt
  RealtimeConnection->>LiveEvidenceFinalization: provide lifecycle state
  LiveEvidenceFinalization->>LiveEvidenceFinalization: classify incomplete conditions
  LiveEvidenceFinalization->>CloudPlaywright: expose realtime incomplete diagnostic
  CloudPlaywright->>CloudPlaywright: validate and normalize diagnostic
  CloudPlaywright->>RouteFailureReceipt: attach matching failure receipt

Loading

Possibly related PRs

• bizzybee90/bizzybee-app#381: Modifies related Realtime evidence validation and completeness handling.
• bizzybee90/bizzybee-app#434: Modifies related Realtime/CDP lifecycle correlation and diagnostics.
• bizzybee90/bizzybee-app#424: Modifies related sanitized route failure diagnostic validation.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description follows the required template and clearly documents scope, impact, verification, release safety, and completion status.
Title check	✅ Passed	The title clearly summarizes the main change: classifying Realtime finalization failures.
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.

✨ 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-incomplete-20260810

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/product-proof-live-evidence.test.mjs`:
- Line 7902: Update rawDetailPattern in the generated-identifier assertion to
derive its match from the current loop variable, allowing all
mediated-${incompleteClass}-secret and cdp-${incompleteClass}-secret forms,
including multi-segment classes. Replace the fixed token alternation while
preserving matching for workspace-secret and realtime:public.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 743aeb33-3d86-42ee-8e5f-2595ed2b9fb3

📥 Commits

Reviewing files that changed from the base of the PR and between bea447e and 174c663.

📒 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