Story 2: build the Supabase realtime queue engine

[XonkelX]

Summary

Implements Story 2's persistent Supabase Realtime queue engine while preserving the Story 1 visual system.

• adds the local-first Supabase workflow and three persistent queue surfaces
• models public queue state separately from customer-private and staff-security data
• enforces RLS, database-owned authorization, transactional commands, revisions, and idempotency receipts
• treats queue-scoped Realtime changes as invalidations followed by authoritative snapshots
• centralizes anonymous sessions and stable request IDs for automatic network retries

Final architectural review

The complete Story 2 diff was reviewed for SQL security, SECURITY DEFINER search paths, RLS, grants, publications, actor derivation, queue/entry binding, concurrency, lock order, idempotency, anonymous SSR sessions, Realtime lifecycle, privacy, CI, environment handling, and documentation.

Review fixes in 95cac31:

• added forward migration 20260717230000_harden_request_id_serialization.sql
• serializes every use of a request UUID with a transaction advisory lock, including concurrent queue creation before a queue row exists
• explicitly rejects null request IDs
• added a stable-request-ID client helper; one automatic network retry reuses the original UUID while a new user action receives a new UUID
• expanded duplicate skip, pause, and close coverage plus command-type mismatch coverage
• added a simultaneous same-request queue-creation integration test

No already-applied migration was rewritten.

Architecture and security

• all eight exposed application tables have RLS enabled
• direct application-table mutations are denied to anon and authenticated
• all mutating RPCs derive the actor from auth.uid(); no client actor UUID or staff Boolean is accepted
• staff membership, queue state, and entry/queue relationships are checked inside PostgreSQL
• queue locking precedes entry changes; a partial unique index enforces one SERVING entry
• command receipts, events, revisions, and state mutations commit atomically
• Realtime publishes exactly queues and queue_entries
• public snapshots and Realtime rows contain no private customer names or staff credentials
• raw staff codes are returned once and only hashes are persisted
• application runtime uses no service-role key or database password
• tracked-source secret and absolute-path scans are clean; npm audit reports 0 vulnerabilities

Supabase Free project

• organization: FOG
• plan: Free
• project: next-queue
• region: us-east-1
• health: ACTIVE_HEALTHY
• anonymous authentication: enabled and validated
• migrations present: 20260717190000, 20260717191000, 20260717230000
• no Pro plan, trial, usage billing, payment method, paid compute, backups, custom domain, high availability, or add-on
• no Next.js application deployment was performed for Story 2

Validation

Complete local suite after the review fix:

• formatting: pass (format and format:check)
• ESLint: pass
• TypeScript: pass
• Vitest: 33/33
• pgTAP: 62/62
• isolated-client integration: 11/11
• focused Realtime: 9/9
• Playwright: 15/15
• database reset from empty local state: pass
• database lint: 0 findings
• generated database types: current
• production build: pass
• audit: 0 vulnerabilities
• git diff --check: pass

Hosted validation:

• original remote pgTAP: 58/58
• original hosted integration: 10/10 with four isolated anonymous identities
• original hosted multi-client Realtime Playwright: 2/2
• forward migration applied from committed source only
• post-fix hosted probe: anonymous auth passed; simultaneous same-actor/same-request creation produced one queue and one replay; authoritative queue IDs matched; command-type mismatch was rejected
• linked pgTAP rerun could not execute because the Supabase CLI linked-test role lacks USAGE on the managed extensions schema; no assertions or mutations ran in that failed invocation
• API-level post-fix validation and cleanup passed

Hosted coverage includes persistence, staff claims, private-name isolation, direct-write denial, actor and command request binding, idempotent replay, simultaneous staff serialization, one-serving-entry enforcement, lifecycle commands, access throttling, offline recovery, public-display convergence, and anonymous authentication.

Cleanup and final state

• post-fix synthetic queues removed
• post-fix anonymous validation user removed
• rows remaining in each of the eight application tables: 0
• Realtime-published tables: exactly 2
• no QA staff code or credential retained

Delivery status

This PR is ready for final review after CI. It remains open, unmerged, and undeployed until the explicit Phase 1 merge step.

[XonkelX]

Final architectural review complete: SQL security, RLS and grants, concurrency/lock ordering, idempotency and stable request IDs, anonymous-session handling, and the Realtime subscription lifecycle were reviewed. The committed migrations are remotely applied; remote Supabase authorization, concurrency, idempotency, privacy, multi-client Realtime, reconnect, and cleanup validation passed. Supabase remains Free with no paid feature enabled, and no application deployment was performed during Story 2. All three PR CI jobs are green.