feat(ads): short impression codes so paid terminal ads fit the box

[ralyodio]

Follow-up to #175, which fixed the house ad's click URL but explicitly left the paid one. This finishes it.

The problem

A paid terminal ad printed:

https://crawlproof.com/a/2b1f0c94-8a1e-4c3d-9b77-1f0a2c3d4e5f          61 chars
https://crawlproof.com/a/2b1f0c94-8a1e-4c3d-9b77-1f0a2c3d4e5f?s=motd   68 chars

A 44-col box has 40 usable columns, so this was always pushed outside the frame. Now 37 chars:

https://crawlproof.com/a/zCjQTqLAGEJJ

Two changes

1. A 12-character base62 code addresses the impression. The length is derived, not picked:

cols 44 → inner 40 usable columns
  − 25   "https://crawlproof.com/a/"
  =====
    15   columns available for the code   → 12, keeping 3 for a longer origin

12 base62 chars ≈ 71 bits. That matters: the code is the only thing between a stranger and a click charge on someone else's campaign, since /a/<code> meters against the campaign on the impression row. Deliberately well above the ~42 bits a 7-char code would have given. Generated with rejection sampling — a plain byte % 62 would skew the first four symbols and quietly cost entropy the budget is already tight on. (Verified: 200k codes, 0 collisions, all 62 symbols, max 1.21% deviation from uniform.)

2. The surface tag moves onto the impression row. As &s=<tag> it cost up to 35 more columns — a sanitized tag can be 32 chars, so no code length could have saved it. /a/<code> reads it back off the row for utm_content, and it's now queryable for per-surface reporting.

Compatibility — please check this part

Old URLs must keep working. Click URLs printed before this change are sitting in people's MOTDs, SSH banners and BBS screens and are never reissued. /a/<id> still accepts UUIDs, and ?s= is still read as a fallback.

Deploy ordering. Migrations here are applied by hand (no CI step), so the app can land before the schema. If a naive version shipped first, every paid impression insert would fail on the unknown columns and take all paid serving down. So:

• Both columns are additive, nullable, if not exists.
• The insert retries without them when they're missing.
• The click URL falls back to the UUID form when the code couldn't be stored.

Either apply order is safe. A wide URL is cosmetic; a dropped impression is a lost sale. There's a test for exactly this (keeps serving when the migration has not been applied yet).

Action required

supabase/migrations/20260731130000_ad_impression_short_codes.sql needs applying. I did not apply it — and note I couldn't confirm which Supabase project is production: impressions from live API calls don't land in the project named crawlproof.com (ywcizjsgrcmhgyplldac). Worth resolving before you apply.

Verification

• npm run typecheck clean.
• Full suite 1251 passed, 7 skipped (1233 + 18 new).
• New tests confirmed to fail on master — 6 of 18 with serve.ts and /a/[id] reverted.
• Paid click URL verified inside the frame at cols 44/52/60/72/120, verbatim, nothing dangling.

🤖 Generated with Claude Code

[github-actions]

vu1nz Security Review

0 finding(s) in PR #?

No security issues found.