fix(staging): publish voice benchmark Realtime

[bizzybee90]

Purpose

Repair the exact staging Realtime publication omission proven by governed product-proof run 31569365811: public.voice_benchmark_runs returned the fixed subscription-not-enabled server-system classification on Channels desktop.

Included scope

• add one append-only migration whose sole mutation adds existing public.voice_benchmark_runs to existing supabase_realtime;
• add a protected exact-main, staging-only runner/workflow with exact pre/post table, RLS, grant, policy, replica-identity, publication and ledger checks;
• update the blank-database, current aggregate ledger, manifest normalization, shared-staging serialization and production-exclusion contracts;
• add focused hostile-state, idempotency, cross-tenant, anonymous-denial, historical-runner and redaction tests.

Explicit exclusions

• no production migration or Realtime membership change;
• no table, row, RLS policy, grant, replica identity, provider, billing, storage, application request or credential change;
• no generic SQL or generic publication mutation path;
• no governed proof acceptance or browser-policy widening.

Architecture placement

Current owner / directory: existing one-purpose staging migration controls under scripts/database/, .github/workflows/, supabase/migrations/, and their ADR/runbook contracts.

Dependencies and duplicate-system check: extends the separately trust-bound messages, workspace-channels and pipeline-incidents publication-repair pattern. The runner stays table-specific so a shared generic matcher cannot silently widen database mutation authority.

Security and tenancy impact

• Authentication / authorization: unchanged; authenticated SELECT and the exact existing policies are required before and after mutation.
• Tenant isolation: pgTAP proves two workspace principals see only their own benchmark row; anonymous and PUBLIC SELECT remain denied.
• Service-role impact: no grant or policy change; exact canonical service-role posture is only verified.
• Provider / webhook impact: none; provider mutations remain forbidden.
• Secrets impact: the database password is protected-Environment-only, pgpass-scoped, never emitted, and sanitized receipts expose only fixed fields/digests.

Data impact

• Schema / migration / RLS / grant impact: one staging-only publication-membership migration; no relation, row, RLS, grant, policy, or replica-identity change.
• Backfill, retention, or rollback: none; migration is idempotent and append-only. If postflight fails after application, preserve state and stop for a reviewed forward fix rather than rewriting history.

Verification

• Behavioural tests: 872/872 Vitest; 226 focused database/product-policy contracts; 131 production-exclusion/policy contracts; new runner + blank preflight 23/23; schema baseline 32/32; exact historical pipeline runner remains green.
• CI / security review: scoped ESLint, TypeScript, Node syntax, Prettier, diff/redaction checks and independent manual security review pass. The product-proof cloud suite passed 1,165 runnable tests with one known local real-Vite-build failure caused by the symlinked dependency tree; the same exact asset test is hosted-green on merged PR fix(proof): include route-owned Vite dynamic assets #505. Fresh hosted exact-head gates are mandatory.

Release safety

• Deployment scope: protected merge first, then one exact-main staging-only migration dispatch in the non-cancelling shared-staging lane.
• Monitoring / stop conditions: stop on source/base drift, any preflight/postflight mismatch, any member set other than exact 21-to-22, any mutation other than the single reviewed publication addition, cleanup failure, or any hosted gate/review failure.
• Rollback or containment: no member removal or migration-history rewrite. Preserve any applied ledger state and use a separate reviewed forward fix. Production remains invariant.

Documentation and generated files

• Docs / diagrams / ADR updates: ADR 0039, ADR index, deployment architecture, shared-staging ADR/runbook, and the one-purpose operator runbook updated.
• Generated-file or lockfile justification: forward-migration registry updated with the exact migration hash; no dependency or lockfile change.

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: 37 files and 3,956 insertions exceed the normal guideline because the one-purpose runner intentionally duplicates the independently reviewed trust boundary instead of creating generic database mutation authority; 1,556 lines are hostile/adversarial runner tests and the remainder includes the exact runner, blank preflight, pgTAP, workflow, migration, and mandatory repository-wide ledger/security pins. Runtime mutation remains one SQL statement.

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

Summary by CodeRabbit

• New Features

  • Added staging support for publishing voice_benchmark_runs through Supabase Realtime.
  • Added a protected, manually triggered workflow with validation, dry-run checks, and sanitized result artifacts.
  • Repair is idempotent and preserves required table security, access policies, and publication settings.

• Documentation

  • Added deployment guidance, operational runbook instructions, and architecture decision documentation.
  • Updated staging concurrency guidance to include the new workflow.

• Tests

  • Added comprehensive validation for publication membership, security controls, migration state, and realtime behavior.

[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: 8514df47-56bf-440b-a35c-1bbd70d3b995

📥 Commits

Reviewing files that changed from the base of the PR and between f41e4c4 and 2b754ed.

📒 Files selected for processing (3)

• docs/architecture/deployment.md
• scripts/database/run-staging-realtime-voice-benchmark-runs-publication.mjs
• scripts/database/run-staging-realtime-voice-benchmark-runs-publication.test.mjs

---

📝 Walkthrough

Walkthrough

This PR adds a protected staging-only repair for the public.voice_benchmark_runs Supabase Realtime publication. It adds the migration, runner, workflow, contracts, tests, ledger updates, production exclusions, concurrency controls, and operational documentation.

Changes

Voice benchmark publication repair

Layer / File(s)	Summary
Publication contracts and guarded migration scripts/database/realtime-voice-benchmark-runs-publication-contract.mjs, supabase/migrations/..., supabase/tests/database/..., scripts/database/realtime-voice-benchmark-runs-publication-blank-preflight.sql	Defines publication membership, validates table security and grants, adds the missing member, and tests idempotence and access policies.
Protected staging runner and verification scripts/database/run-staging-realtime-voice-benchmark-runs-publication.mjs, scripts/database/run-staging-realtime-voice-benchmark-runs-publication.test.mjs	Adds source, target, TLS, ledger, posture, dry-run, apply, receipt, cleanup, and failure validation.
Workflow admission and migration registry wiring .github/workflows/*, scripts/database/staging-migration-ledger.mjs, scripts/database/production-cutoff-readiness.mjs, supabase/baseline/forward-migrations.json, scripts/database/*test.mjs	Registers the migration for staging, excludes it from production batches, updates ledger counts and digests, and runs focused checks.
Baseline and Realtime manifest contracts scripts/database/build-schema-baseline.mjs, scripts/database/normalize-staging-realtime-messages-manifest.mjs, docs/database/*, scripts/database/*publication.test.mjs	Adds voice_benchmark_runs to staging publication contracts and updates normalization and baseline expectations.
Operational documentation and shared-staging topology docs/adr/*, docs/architecture/deployment.md, docs/runbooks/*, scripts/staging-shared-environment-concurrency.test.mjs	Documents the repair and expands serialized shared-staging coverage from eleven to twelve workflows.

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ReleaseCaptain
  participant GitHubActions
  participant PublicationRunner
  participant StagingDatabase
  ReleaseCaptain->>GitHubActions: dispatch with approved staging inputs
  GitHubActions->>GitHubActions: validate actor, source SHA, project, and provider-mutation flags
  GitHubActions->>PublicationRunner: run schema, contract, dry-run, and apply checks
  PublicationRunner->>StagingDatabase: inspect migration and security posture
  PublicationRunner->>StagingDatabase: apply the single publication repair when pending
  StagingDatabase-->>PublicationRunner: return final publication and security posture
  PublicationRunner-->>GitHubActions: write redacted success or failure receipt
  GitHubActions-->>ReleaseCaptain: upload the seven-day result artifact

Loading

Possibly related PRs

• bizzybee90/bizzybee-app#492: Implements a parallel protected staging Realtime publication repair with the same shared validation patterns.
• bizzybee90/bizzybee-app#499: Adds a related staging-only Realtime publication repair for another table.
• bizzybee90/bizzybee-app#350: Uses similar protected staging migration workflow and exact-source validation controls.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the staging Realtime publication repair for voice benchmark data.
Description check	✅ Passed	The description covers all required sections with clear scope, security, data, verification, release safety, documentation, and completion details.
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 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-staging-voice-benchmark-runs-realtime-publication-20260812

Note

This review was completed with usage-based billing: files reviewed beyond your plan's included limits are billed at $0.25/file. Track spend and usage in your billing settings.

---

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

[coderabbitai]

Caution

CodeRabbit couldn't update its existing comment. The review summary may be out of date.

Error details

putComment timed out

[coderabbitai]

Actionable comments posted: 2

🤖 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 `@docs/architecture/deployment.md`:
- Around line 75-76: Update the production-exclusion sentence in the deployment
documentation to say “All four migrations,” matching the four-entry Realtime
repair exclusion list and ADR 0039; keep the surrounding production-scope
wording unchanged.

In `@scripts/database/run-staging-realtime-voice-benchmark-runs-publication.mjs`:
- Around line 463-466: Update both select_policy_inventory predicates in the
benchmark publication query to use the canonical single authenticated policy
identity returned by the query, or remove the redundant predicates and rely on
policy_inventory. Ensure pending and applied checks accept the valid database
state represented by “workspace members can read voice benchmark runs.”

🪄 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: 9c64fce4-63e5-4955-8ad9-8f04e829a1b6

📥 Commits

Reviewing files that changed from the base of the PR and between 6d3ad5d and 95df93e.

📒 Files selected for processing (37)

• .github/workflows/schema-baseline.yml
• .github/workflows/staging-realtime-voice-benchmark-runs-publication.yml
• docs/adr/0030-serialize-shared-staging-operations.md
• docs/adr/0039-protected-staging-realtime-voice-benchmark-runs-publication.md
• docs/adr/README.md
• docs/architecture/deployment.md
• docs/database/production-cutoff-readiness-contract.json
• docs/database/staging-realtime-messages-manifest-delta.json
• docs/runbooks/staging-realtime-voice-benchmark-runs-publication.md
• docs/runbooks/staging-release-security-migration.md
• scripts/database/build-schema-baseline.mjs
• scripts/database/build-schema-baseline.test.mjs
• scripts/database/normalize-staging-realtime-messages-manifest.mjs
• scripts/database/normalize-staging-realtime-messages-manifest.test.mjs
• scripts/database/product-proof-aggregate-capture.sql
• scripts/database/production-cutoff-readiness.mjs
• scripts/database/production-cutoff-readiness.test.mjs
• scripts/database/production-forward-migrations.test.mjs
• scripts/database/realtime-pipeline-incidents-publication-blank-preflight.test.mjs
• scripts/database/realtime-voice-benchmark-runs-publication-blank-preflight.sql
• scripts/database/realtime-voice-benchmark-runs-publication-blank-preflight.test.mjs
• scripts/database/realtime-voice-benchmark-runs-publication-contract.mjs
• scripts/database/run-product-proof-aggregate-capture.mjs
• scripts/database/run-product-proof-aggregate-capture.test.mjs
• scripts/database/run-staging-realtime-pipeline-incidents-publication.test.mjs
• scripts/database/run-staging-realtime-voice-benchmark-runs-publication.mjs
• scripts/database/run-staging-realtime-voice-benchmark-runs-publication.test.mjs
• scripts/database/run-staging-reconciliation-integration.mjs
• scripts/database/run-staging-reconciliation-integration.test.mjs
• scripts/database/staging-migration-ledger.mjs
• scripts/database/staging-reconciliation-disposable-fixture.sql
• scripts/database/verify-schema-baseline.test.mjs
• scripts/product-proof-network-policy.test.mjs
• scripts/staging-shared-environment-concurrency.test.mjs
• supabase/baseline/forward-migrations.json
• supabase/migrations/20260812062315_repair_product_proof_voice_benchmark_runs_realtime_publication.sql
• supabase/tests/database/realtime_voice_benchmark_runs_publication.pgtap.sql