feat(pinballmap): tie guard for duplicate same-title cabinets (PP-o355.15)

[timothyfroehlich]

Summary

Server-side only, no UI. Unblocks PP-o355.20 (auto-link), which may not set listed = true until the rule deciding which cabinet may hold a listing exists.

resolveListingHolder() is the single exported source of that rule, so auto-link consumes it rather than re-deriving it — two implementations would drift, and the partial unique index would start rejecting writes one of them believed were legal.

1. An existing listing is knowledge, so the incumbent wins outright. We created that lmx, so we know whose it is: no tie, however many same-title cabinets share its availability, and even if the incumbent's own availability has drifted into an invalid one (that's a §6 hard flag for the dashboard, not an ambiguity — deliberately kept separate).
2. Nobody listed → drop availabilities that make Listed invalid (pending_arrival, removed), rank the rest by MACHINE_PRESENCE_RANK, return either the sole best or a tie descriptor.

A tie only ever means we decline to choose. No banner, no hidden actions, no paused syncing — a human clicking "list this one" is the disambiguation. A tie with nobody listed renders identically to "not listed", and that invisibility is the point (refresher §7).

findListingTies() exposes the reportable condition for the admin dashboard (PP-o355.7) without building any page here.

The 23505 backstop was two real defects, not one

Both reproduced by the new integration test before being fixed:

• machines has two unique constraints and both raise SQLSTATE 23505, so createMachineAction answered a duplicate-listing collision with "Initials are already taken" — an actively wrong diagnosis for a request whose initials were fine and unique.
• updateMachineAction had no 23505 catch at all, so the same collision surfaced as a generic 500.

Both now name the cabinet that already holds the listing.

One thing worth a careful look

getPostgresErrorConstraint() reads both driver spellings, and that is load-bearing rather than defensive:

• postgres-js (production) exposes constraint_name — node_modules/postgres/src/connection.js:46 maps wire field n.
• PGlite (every integration test) inherits pg-protocol's camelCase and exposes constraint.

Reading one spelling passes one environment and silently fails the other. The first cut of this fix did exactly that — green in unit tests, dead in the integration suite — which is how the asymmetry was found. Both are now covered by explicit unit tests.

Test Plan

• 14 unit tests on resolveListingHolder / findListingTies across the incumbent/no-incumbent × tie/no-tie matrix, plus degenerate inputs — written before the implementation.
• 6 unit tests on getPostgresErrorConstraint, including both driver spellings and the two-constraints-one-SQLSTATE case.
• 3 integration tests (PGlite): the collision names the incumbent, updateMachineAction returns VALIDATION not a 500, and a genuine initials collision still reports as an initials problem (regression guard).
• pnpm run preflight — typecheck, lint, 2024 unit tests, build, 518 integration tests all pass.

Note on smoke E2E: preflight's Mobile Safari smoke reports pre-existing responsive-overflow failures on /m/[initials] tab routes. Bisected to confirm they are not from this branch (which touches no UI) and not a regression from #1762 — 87552bad, the commit before #1762 merged, fails worse (3 failed vs 1 failed + 2 flaky today). Filed as PP-h490, including the reason nobody noticed: Mobile Safari smoke runs only in the post-merge, non-required test-e2e-comprehensive job.

Related Issues

PP-o355.15 (epic PP-o355). Unblocks PP-o355.20.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Y39wAcWjeH7BKkB8p96eqo

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
pin-point	Ready	Preview	Aug 1, 2026 10:24pm

[Copilot]

Pull request overview

Adds a single, reusable rule for choosing (or declining to choose) which PinPoint machine “holds” a PinballMap listing when multiple cabinets share the same catalog title, and hardens machine write paths to correctly diagnose PinballMap listing unique-index collisions (instead of misreporting them as initials conflicts or surfacing 500s).

Changes:

• Introduces resolveListingHolder() / findListingTies() to centralize the tie/selection rule for same-title cabinets.
• Adds getPostgresErrorConstraint() to distinguish which unique constraint triggered a 23505 across both postgres-js and PGlite driver shapes.
• Updates machine create/update actions to return a specific, user-actionable VALIDATION error on duplicate PinballMap listing collisions, plus new unit + integration coverage.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/test/integration/pinballmap-listing-conflict.test.ts	New PGlite integration coverage for the 23505 backstop and correct error messaging.
src/lib/pinballmap/listing-holder.ts	Implements the pure selection/tie rule for determining a listing holder among same-title cabinets.
src/lib/pinballmap/listing-holder.test.ts	Unit tests covering incumbent/candidate/tie/none outcomes and fleet-wide tie reporting.
src/lib/db/postgres-errors.ts	Adds a constraint-name extractor that works across both postgres-js and PGlite error shapes.
src/lib/db/postgres-errors.test.ts	Unit tests for constraint-name extraction and for distinguishing multiple 23505 sources.
src/app/(app)/m/actions.ts	Differentiates duplicate-listing collisions from initials collisions and returns actionable VALIDATION results.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[timothyfroehlich]

Scope grew after the first review — summary of what landed since

Three commits after 7595a826, all from review findings rather than new scope:

50d4e5ea — cover every listing write path. The first cut fixed createMachineAction and updateMachineAction and stopped there. Two more paths write pinballmapListed:

• linkPinballmapEntryAction — the real listing entry point — returned err("SERVER", …) for a duplicate lister, with a comment deferring the fix to this very bead. It's user-correctable (unlist the other cabinet), so SERVER made the UI treat it as a crash. Now VALIDATION, naming the incumbent.
• The verify/heal transaction set pinballmapListed: true with no catch at all. Cabinets A and B share a title, A is listed and holds the lmx, B is linked but unlisted → verifying B heals it onto A's lmx → the index rejects it → 500. That is the duplicate-title case this bead exists for, in the one path I'd missed.

Recognition + message extracted to ~/lib/pinballmap/listing-conflict so all four paths share one implementation. They had drifted into three different answers to the same failure — the drift resolveListingHolder exists to prevent, reproduced in the error handling.

Also in 50d4e5ea: stopped overstating the guard. resolveListingHolder has no production caller yet — it ships ahead of PP-o355.20 deliberately, because auto-link may not set listed = true until the rule exists. But the comments described it in the present tense as the primary defense and the 23505 catch as a last resort. At head that catch is the only defense, and the module docblock and test header now say so, so nobody trusts a guard that isn't running.

e080333e — self-review catch. Routing the two PBM-only catches through isPbmListingConflict narrowed them from "any 23505" to "23505 with a matching constraint name", and getPostgresErrorConstraint returns undefined when a driver drops the field — putting a correctable condition back to a 500, contradicting the caveat I'd written telling callers to keep a general fallback. Those two writes touch only listing columns, so the bare code is correct there. The narrow check stays in create/update, which must tell the initials and listing constraints apart.

Review status

Copilot returned the quota-limited placeholder on head 50d4e5ea (it delivered real reviews earlier today on #1762, #1794 and this PR's 7595a826, then hit the daily budget). The reviewed gate correctly treats that as absent.

/code-review medium ran against 7595a826 and its findings are what 50d4e5ea addresses; I reviewed the delta since by hand, which is where e080333e came from.

CI green, threads resolved, no UI files touched (no screenshots needed). —Claude-PbmListUnlist