Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

84.2 KB
Raw Blame
/**
 * IRL GPS Pins — place 3D agents at real-world GPS coordinates.
 *
 * GET    /api/irl/pins?lat=&lng=&radius=40         nearby pins (public, tight proximity)
 * GET    /api/irl/pins/mine?deviceToken=           my pins (device token or auth)
 * GET    /api/irl/pins?mine=1                      my pins (auth required)
 * POST   /api/irl/pins  { lat, lng, heading, avatarUrl, avatarName, caption, agentId }
 * PATCH  /api/irl/pins  { id, caption, avatarUrl, avatarName, lat, lng }  edit pin (auth required)
 * PATCH  /api/irl/pins  { id, deviceToken, calibrate:{ lat, lng, anchorYawDeg, anchorHeightM } }
 *                                                  owner-gated, bounds-checked pose nudge (A3)
 * PATCH  /api/irl/pins  { deviceToken, calibrateRoom:{ roomId, dEastM, dNorthM, dYawDeg } }
 *                                                  owner-gated, bounds-checked whole-room align (R2)
 * DELETE /api/irl/pins?id=                         remove own pin (device_token or auth)
 * DELETE /api/irl/pins?all=1&deviceToken=          purge every pin from this device → { deleted }
 * POST   /api/irl/pins/interact { pinId, event, deviceToken }  log a tap/view
 */

import { cors, json, wrap, rateLimited } from '../_lib/http.js';
import { sql } from '../_lib/db.js';
import { getSessionUser } from '../_lib/auth.js';
import { limits, clientIp, limitFailClosedRead } from '../_lib/rate-limit.js';
import { WORD_BLACKLIST } from '../../src/profanity.js';
import { guardianConfig, assess, decide } from '../_lib/granite-guardian.js';
import { encodeGeohash } from '../_lib/geohash.js';
import { validateAppearance } from '../_lib/accessories.js';
import { cacheGet, cacheSet } from '../_lib/cache.js';
import { sendOpsAlert } from '../_lib/alerts.js';
import { sha256 } from '../_lib/crypto.js';
import { readDeviceToken } from '../_lib/irl-auth.js';
import { verifyFixToken, fixEnforced } from '../_lib/irl-presence.js';
import { calibrateRoomOrigin, pinAbsoluteFromOrigin } from '../../src/irl/room-anchor.js';
import { logIrlEvent } from '../_lib/irl-analytics.js';

// ── Moderation, safety & density caps (D4) ──────────────────────────────────
// Everything below makes the public, shared IRL world safe to launch: content
// gating on caption/name, a $THREE-only coin guard, an x402 endpoint allow-list,
// per-area density caps, and per-owner active-pin caps. Each rejection returns a
// designed error code the client surfaces as an actionable message.

const CAPTION_MAX = 140;          // public caption hard length cap
const NAME_MAX    = 40;           // avatar name hard length cap
const GEOCELL_PRECISION = 7;      // ~153m × 153m density cell
const MAX_PINS_PER_CELL = 40;     // density ceiling per geocell7
const MAX_PINS_PER_OWNER_ANON   = 20;  // active pins for an anonymous device
const MAX_PINS_PER_OWNER_SIGNED = 60;  // higher ceiling once accountable (signed in)

// $THREE is the only coin three.ws references (contract below). The off-brand
// guard is written generically — it never names a competing ticker — so this
// codebase stays clean of other coins while still rejecting shills.
const THREE_MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';

// Always-on hard gate: lower-case substring match against the shared slur/severe
// list. No external dependency, fails closed and fast — the floor under the
// smarter Guardian tier. Reused verbatim from the pump.fun feed filter.
export function hardBlocked(text) {
	const t = String(text || '').toLowerCase();
	return WORD_BLACKLIST.some((w) => t.includes(w));
}

// Off-brand-coin guard: reject text that shills a token other than $THREE — a
// `$TICKER` cashtag that isn't $THREE, or a pump.fun-style mint address (…pump)
// that isn't the $THREE contract. Generic by construction so no competitor is
// ever written into source; $THREE (cashtag or contract) is explicitly allowed.
//
// The cashtag match is deliberately greedy and carries NO trailing word-boundary:
// a `{1,9}` + `\b` pattern silently missed every ticker longer than ten characters
// (the boundary could never be satisfied mid-word, so the whole cashtag went
// unmatched and the caption sailed through the guard). Matching the run of ticker
// characters as far as it goes means a long ticker is caught like a short one, and
// a genuine `$THREE` still compares equal after the `$` is stripped.
export function namesOffBrandCoin(text) {
	const t = String(text || '');
	const cashtags = t.match(/\$[A-Za-z][A-Za-z0-9]*/g) || [];
	if (cashtags.some((c) => c.slice(1).toUpperCase() !== 'THREE')) return true;
	const tokens = t.match(/\b[1-9A-HJ-NP-Za-km-z]{32,48}\b/g) || [];
	if (tokens.some((m) => /pump$/.test(m) && m !== THREE_MINT)) return true;
	return false;
}

// Tier-1 content decision over caption + name. Returns the offending field +
// reason, or null when clean. Pure string work — the cheapest, most decisive gate.
function contentReject(caption, name) {
	if (hardBlocked(caption)) return { field: 'caption', reason: 'blocked' };
	if (hardBlocked(name))    return { field: 'avatarName', reason: 'blocked' };
	if (namesOffBrandCoin(caption)) return { field: 'caption', reason: 'coin' };
	if (namesOffBrandCoin(name))    return { field: 'avatarName', reason: 'coin' };
	return null;
}

// Tier-2 AI content risk over the free-text caption — Granite Guardian. Best-
// effort by design (Rule 9): when watsonx isn't configured, or the classifier
// errors/times out, we DON'T block — the always-on wordlist already caught the
// hard cases, and a missing key must never 500 a placement.
//
// Resilience (task 12): a dead moderation upstream would otherwise cost EVERY
// placement its full timeout. Once a check fails, we cache the "degraded" state
// for ~60s and skip the upstream entirely during that window — so one failure
// doesn't make the next minute of placements each wait the timeout. The per-
// request timeout is tight (2s) so even the first failure after recovery can't
// stall the POST. Both failure modes fail OPEN (allow the placement) with a log.
const GUARDIAN_TIMEOUT_MS    = 2000;   // tight per-request bound on the upstream
const GUARDIAN_DEGRADE_MS    = 60_000; // skip-upstream window after a failure
let _guardianDegradedUntil   = 0;      // epoch-ms; >now ⇒ short-circuit to allow

// Exposed for tests + the cron-style recovery path: report whether the Guardian
// short-circuit is currently engaged, and clear it (e.g. after a probe succeeds).
export function guardianDegraded(now = Date.now()) {
	return _guardianDegradedUntil > now;
}
export function resetGuardianDegraded() {
	_guardianDegradedUntil = 0;
}

async function guardianFlags(caption) {
	const text = String(caption || '').trim();
	if (!text) return false;
	const cfg = guardianConfig();
	if (!cfg.configured) return false;
	// Short-circuit while the upstream is known-degraded: no network call, so the
	// caption is allowed immediately rather than paying the timeout again.
	if (guardianDegraded()) return false;
	try {
		const ctrl = new AbortController();
		const timer = setTimeout(() => ctrl.abort(), GUARDIAN_TIMEOUT_MS);
		try {
			const verdicts = await assess(cfg, {
				input: text,
				risks: ['harm', 'social_bias', 'violence', 'sexual_content'],
				signal: ctrl.signal,
			});
			// A clean pass clears any lingering degraded window — the upstream is back.
			_guardianDegradedUntil = 0;
			return decide(verdicts).decision === 'block';
		} finally {
			clearTimeout(timer);
		}
	} catch (err) {
		// Open the degraded window so the next ~60s of placements skip the upstream
		// instead of each eating the timeout. Fail open (allow) — the hard wordlist
		// already ran, and a moderation outage must never 500 or stall a placement.
		_guardianDegradedUntil = Date.now() + GUARDIAN_DEGRADE_MS;
		console.warn('[irl/pins] guardian content check degraded:', err?.message || err);
		return false;
	}
}

// x402 pay-endpoint allow-list (D4). A pin's advertised "pay" target is handed to
// every nearby viewer's Pay button, so an arbitrary external URL is a drain/scam
// vector. On top of safeRemoteUrl's https + no-private-host checks, the host must
// be first-party three.ws infrastructure (or an operator-extended allow-list via
// IRL_X402_ALLOWED_HOSTS). Relative same-origin paths are always first-party.
// Registered-agent endpoints still flow to the Pay button via the trusted
// server-resolved agent-card path (card.x402_endpoint), which this never gates.
// Built-in first-party hosts — the floor under any operator override. The
// allow-list is NEVER empty: an unset/blank/malformed IRL_X402_ALLOWED_HOSTS
// falls back to these defaults rather than producing an empty list (which would
// reject every absolute endpoint — fail-safe, but it would also silently break
// every legit first-party pay target). A valid host token is a bare hostname
// (letters/digits/dots/hyphens, no scheme/path/port), so a fat-fingered
// "https://x" entry is dropped instead of poisoning the match.
const X402_DEFAULT_HOSTS = ['three.ws', 'www.three.ws', '3d-agent.vercel.app', 'three.ws'];
const X402_HOST_RE = /^[a-z0-9.-]+$/;

// Parse + validate the configured allow-list. Returns ONLY well-formed bare
// hostnames; when an operator override is set but yields no valid host, we log
// once and fall back to the built-in first-party hosts so a misconfig can never
// silently disable first-party pay targets nor accept an external one.
function parseAllowedHosts(raw) {
	const configured = String(raw ?? '').trim();
	const parsed = configured
		.split(',')
		.map((h) => h.trim().toLowerCase())
		.filter((h) => h && X402_HOST_RE.test(h));
	if (configured && !parsed.length) {
		console.warn(
			'[irl/pins] IRL_X402_ALLOWED_HOSTS is set but parsed to no valid host; ' +
				'falling back to built-in first-party hosts. External x402 endpoints ' +
				'are only accepted for first-party / allow-listed hosts.',
		);
	}
	// Always return a non-empty set: configured-valid hosts, else the defaults.
	return parsed.length ? parsed : X402_DEFAULT_HOSTS.slice();
}

const X402_ALLOWED_HOSTS = parseAllowedHosts(process.env.IRL_X402_ALLOWED_HOSTS);

export function safePaymentEndpoint(raw) {
	// allowRelative so a same-origin path (unambiguously first-party three.ws)
	// passes; safeRemoteUrl still enforces https + no-private-host on absolute URLs.
	const base = safeRemoteUrl(raw, { allowRelative: true });
	if (!base.ok) return { ok: false };
	if (base.value == null) return { ok: true, value: null };
	if (base.value.startsWith('/')) return { ok: true, value: base.value };
	let host;
	try { host = new URL(base.value).hostname.toLowerCase(); } catch { return { ok: false }; }
	// Empty allow-list (defensive — parseAllowedHosts never returns one) must
	// reject every absolute host: fail safe, never silently accept an external one.
	if (!X402_ALLOWED_HOSTS.length) return { ok: false };
	const allowed = X402_ALLOWED_HOSTS.some((h) => host === h || host.endsWith(`.${h}`));
	return allowed ? { ok: true, value: base.value } : { ok: false };
}

// Validate a URL that will be handed to every nearby viewer's browser — the
// avatar GLB (→ GLTFLoader) and the x402 pay endpoint (→ Pay button). Same-origin
// relative paths (avatars live under /api/avatars/…) are always allowed; absolute
// URLs must be https and must not point at localhost / private / loopback hosts,
// so a placement can't aim other users' devices at an internal or attacker host.
// Returns { ok: true, value } or { ok: false }. `value` is the normalized string.
function safeRemoteUrl(raw, { allowRelative = true } = {}) {
	if (raw == null || raw === '') return { ok: true, value: null };
	const v = String(raw).trim();
	if (!v) return { ok: true, value: null };
	if (allowRelative && v.startsWith('/') && !v.startsWith('//')) return { ok: true, value: v };
	let u;
	try { u = new URL(v); } catch { return { ok: false }; }
	if (u.protocol !== 'https:') return { ok: false };
	if (u.username || u.password) return { ok: false };
	const host = u.hostname.toLowerCase();
	if (
		host === 'localhost' || host.endsWith('.local') || host.endsWith('.internal') ||
		host === '0.0.0.0' || host === '::1' ||
		/^127\./.test(host) || /^10\./.test(host) || /^192\.168\./.test(host) ||
		/^169\.254\./.test(host) || /^172\.(1[6-9]|2\d|3[01])\./.test(host)
	) return { ok: false };
	return { ok: true, value: u.toString() };
}

// Coarsen a coordinate before it leaves the server in the PUBLIC nearby feed.
// A phone GPS fix is accurate to ~5 m, so the sub-millimetre tail of a float64
// degree is both useless for AR placement and a privacy hazard: an exact
// 9-decimal reading is precise enough to fingerprint one device/fix and exposes
// more than "an agent stands roughly here." 5 decimals ≈ 1.1 m — finer than GPS
// error, ample to render the agent as you walk up — and the room frame
// (rel_east_m / rel_north_m) still carries the exact intra-room layout untouched.
// Distance is computed from the RAW coordinates before rounding, so proximity
// filtering and the surfaced distance_m stay accurate.
const PUBLIC_COORD_DP = 5;
function roundCoord(v) {
	if (typeof v !== 'number' || !Number.isFinite(v)) return v;
	const f = 10 ** PUBLIC_COORD_DP;
	return Math.round(v * f) / f;
}

// Haversine distance in meters between two GPS points
function haversineDist(lat1, lng1, lat2, lng2) {
	const R = 6371000;
	const dLat = (lat2 - lat1) * Math.PI / 180;
	const dLng = (lng2 - lng1) * Math.PI / 180;
	const a =
		Math.sin(dLat / 2) ** 2 +
		Math.cos(lat1 * Math.PI / 180) * Math.cos(lat2 * Math.PI / 180) *
		Math.sin(dLng / 2) ** 2;
	return R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
}

// Rate-limit calls fail OPEN here (task 12). The shared limiter already degrades
// internally for these non-critical buckets, but a Redis client can still reject
// (or the limiter object can throw synchronously) — and an unhandled rejection
// inside the handler would 500 the whole request. These write paths are bounded
// by the DB caps (density / per-owner / report dedupe) downstream, so a limiter
// outage should never block a legitimate placement: we log once and allow.
// `name` ties the warning to the bucket; the cooldown keeps an outage that hits
// every request from itself flooding the logs.
const _rlWarnedAt = new Map();
const RL_WARN_COOLDOWN_MS = 60_000;
async function limitOrFailOpen(name, fn, ...args) {
	try {
		return await fn(...args);
	} catch (err) {
		const last = _rlWarnedAt.get(name) || 0;
		const now = Date.now();
		if (now - last >= RL_WARN_COOLDOWN_MS) {
			_rlWarnedAt.set(name, now);
			console.warn(`[irl/pins] rate limiter "${name}" failed, allowing request (fail-open):`, err?.message || err);
		}
		// Allow: a synthetic success verdict so the caller proceeds unthrottled.
		return { success: true, reason: 'rate_limiter_degraded' };
	}
}

// ── Sweep anomaly detection (H7) ─────────────────────────────────────────────
// A real /irl user stays in ~1 geocell: they poll the same spot every ~10 s. A
// scraper reading many DISTINCT cells in a short window is sweep-shaped, even if
// each individual cell stays under the per-minute rate limit (a slow, methodical
// grid never trips a burst counter). We track the set of distinct geocells a caller
// reads within SWEEP_WINDOW_S in the shared cache (short TTL, capped) and fire ONE
// deduped, COORDINATE-FREE ops alert when the count crosses SWEEP_CELL_THRESHOLD.
//
// Privacy discipline (mirrors redactUrl): the cache key and the alert carry only a
// SHA-256 hash of the caller IP and the distinct-cell COUNT — never a coordinate,
// never a raw IP, never a geocell value. The whole path is best-effort and wrapped
// so it can never delay or fail the read it observes.
const SWEEP_WINDOW_S = 120;       // rolling observation window
const SWEEP_CELL_THRESHOLD = 12;  // distinct cells in the window that looks like a grid sweep
const SWEEP_CELLS_TRACKED_MAX = 64; // cap the stored set so one caller can't bloat a cache entry

export async function recordCellRead(ip, cell) {
	if (!ip || !cell) return;
	try {
		const ipHash = (await sha256(ip)).slice(0, 16);
		const key = `irl:sweep:${ipHash}`;
		const prev = (await cacheGet(key)) || { cells: [], alerted: false };
		const cells = Array.isArray(prev.cells) ? prev.cells : [];
		if (!cells.includes(cell)) {
			if (cells.length < SWEEP_CELLS_TRACKED_MAX) cells.push(cell);
		}
		const distinct = cells.length;
		let alerted = prev.alerted === true;
		if (distinct >= SWEEP_CELL_THRESHOLD && !alerted) {
			alerted = true; // latch so we alert once per window, not every cell after the threshold
			// Coordinate-free, IP-hash only. Deduped by the hash so a sustained sweep
			// from one caller is one alert per dedup window, not a flood.
			sendOpsAlert(
				'IRL sweep suspected',
				`A single caller read ${distinct}+ distinct geocells from the /irl nearby feed within ${SWEEP_WINDOW_S}s (ip_hash ${ipHash}). Possible bulk location-harvest attempt; no coordinates logged.`,
				{ signature: `irl-sweep:${ipHash}` },
			).catch(() => {});
		}
		// Refresh the rolling window on every read so an active sweep keeps the entry warm.
		await cacheSet(key, { cells, alerted }, SWEEP_WINDOW_S);
	} catch {
		/* best-effort telemetry — never block or fail the read */
	}
}

let _tableReady = false;
// Exported so every other surface that READS irl_pins can provision it through the
// one definition that owns it. api/irl/world-lines.js joins this table on its two
// coordinate feeds and used to 500 with a bare `relation "irl_pins" does not exist`
// on a database where no pin had ever been placed. Re-declaring the DDL there would
// have forked the schema; this shares it, and the module-level _tableReady flag makes
// the second caller a no-op.
export async function ensurePinsSchema() {
	return ensureTable();
}
async function ensureTable() {
	if (_tableReady) return;
	// Critical bootstrap — the base table + proximity/expiry indexes. These are
	// idempotent (`IF NOT EXISTS`) and, on an already-provisioned database, a cheap
	// catalog check that takes no exclusive lock. A failure here is a genuine DB
	// fault (no connection, no CREATE grant) and is allowed to surface.
	await sql`
		CREATE TABLE IF NOT EXISTS irl_pins (
			id            UUID DEFAULT gen_random_uuid() PRIMARY KEY,
			user_id       UUID,
			agent_id      UUID,
			device_token  TEXT,
			lat           DOUBLE PRECISION NOT NULL,
			lng           DOUBLE PRECISION NOT NULL,
			heading       FLOAT DEFAULT 0,
			avatar_url    TEXT,
			avatar_name   TEXT,
			caption       TEXT,
			x402_endpoint TEXT,
			placed_at     TIMESTAMPTZ DEFAULT NOW(),
			expires_at    TIMESTAMPTZ DEFAULT (NOW() + INTERVAL '7 days')
		)
	`;
	await sql`CREATE INDEX IF NOT EXISTS irl_pins_lat_lng ON irl_pins (lat, lng)`;
	await sql`CREATE INDEX IF NOT EXISTS irl_pins_expires ON irl_pins (expires_at)`;
	// Incremental migrations — every column/index below ships idempotently so a
	// fresh database self-provisions. On a LIVE database they are already applied,
	// so re-running them is pure redundancy: each `ALTER TABLE` / `CREATE INDEX`
	// takes an ACCESS EXCLUSIVE lock that can time out when many cold starts race,
	// and a least-privilege runtime role may lack DDL grants outright. Neither must
	// ever gate a read or write — the schema is already in place. Run them
	// best-effort, mark the table ready regardless, and let any genuine schema gap
	// surface as a precise error on the actual query rather than a blanket 500 here.
	try {
		await runMigrations();
	} catch (err) {
		console.error('[irl/pins] schema migrations skipped (already applied or no DDL grant)', {
			reason: err?.message || String(err),
		});
	}
	_tableReady = true;
}

async function runMigrations() {
	// view_count — deduplicated visitor count; incremented by /api/irl/interactions
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS view_count BIGINT NOT NULL DEFAULT 0`;
	// Anchor pose — added 2026-06 for IRL-Live world anchoring (A2). Persisting the
	// full pose (floor height, orientation, GPS-fix trust) is the prerequisite for
	// WebXR anchors (A1), shared-spot reconciliation (A3), and gyro-lock replay (A4).
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS anchor_height_m DOUBLE PRECISION`;
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS anchor_yaw_deg  DOUBLE PRECISION`;
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS anchor_quat     JSONB`;            // [x,y,z,w], optional richer orientation
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS gps_accuracy_m  DOUBLE PRECISION`;
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS altitude_m      DOUBLE PRECISION`;
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS anchor_source   TEXT`;             // 'webxr' | 'gyro-gps'
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS anchor_scale    DOUBLE PRECISION`; // pinch-resized render scale (0.25–4), NULL = natural size
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS vps_provider    TEXT`;             // reserved for visual positioning
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS vps_id          TEXT`;             // reserved
	// Moderation + density (D4). geocell7 is the ~150m density key (precision-7
	// geohash); hidden_at marks a pin queued out of public view after enough
	// distinct reporters — set, never deleted, so the owner can appeal and the
	// review console can restore it.
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS geocell7  TEXT`;
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS hidden_at TIMESTAMPTZ`;
	await sql`CREATE INDEX IF NOT EXISTS irl_pins_geocell7 ON irl_pins (geocell7) WHERE hidden_at IS NULL`;
	// Remote outfit change (C6) — a placed agent owns its look independent of the
	// source avatar so an owner can re-skin it for EVERY nearby viewer.
	//   avatar_manifest : the editable appearance — { colors, hidden, accessories }
	//                     (the same shape the avatar studio produces).
	//   avatar_base_url : the un-dressed GLB the manifest bakes ONTO, captured once
	//                     on the first outfit edit. Re-baking always starts from this
	//                     clean base so garment hides / accessories never stack across
	//                     edits (avatar_url stays the derived, baked GLB served today).
	//   avatar_version  : bumped on every outfit change — the cheap signal the nearby
	//                     feed/viewer diffs to swap a re-skinned pin's GLB, and a
	//                     cache-bust companion to the hash-keyed baked URL.
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS avatar_manifest JSONB`;
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS avatar_base_url TEXT`;
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS avatar_version  INTEGER NOT NULL DEFAULT 0`;
	// Room frame — shared room-relative anchoring. A pin in a ROOM stores its
	// EXACT offset (rel_east_m / rel_north_m, metres) from a shared origin
	// (origin_lat/lng/yaw) instead of relying on its own ~10 m-noisy GPS, so a
	// cluster keeps its room-scale layout identical for every viewer and the whole
	// room calibrates with one nudge. lat/lng stay populated (the GPS index +
	// legacy clients); room_id NULL = a standalone pre-room pin. See
	// src/irl/room-anchor.js for the geometry these columns feed.
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS room_id        TEXT`;
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS rel_east_m     DOUBLE PRECISION`;
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS rel_north_m    DOUBLE PRECISION`;
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS origin_lat     DOUBLE PRECISION`;
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS origin_lng     DOUBLE PRECISION`;
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS origin_yaw_deg DOUBLE PRECISION`;
	await sql`CREATE INDEX IF NOT EXISTS irl_pins_room ON irl_pins (room_id) WHERE room_id IS NOT NULL AND hidden_at IS NULL`;
	// Placement consent + approximate placement (H4). A placer chooses whether the
	// agent sits at their EXACT spot ('precise') or is deliberately blurred to a
	// random point within fuzz_radius_m of it ('approximate') — so a user can share
	// "an agent near here" without pinning their precise real-world location. The
	// CLIENT computes the fuzzed lat/lng it sends; the server stores the consent +
	// the radius it was blurred by, so the choice is auditable (the privacy center
	// surfaces it) and the dashboard can show "placed approximately (±Nm)". A legacy
	// pin with neither column set reads as a 'precise' placement (the prior default).
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS placement_kind TEXT`;
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS fuzz_radius_m  DOUBLE PRECISION`;
	// Privacy center (H5). `published` is the owner-controlled visibility flag: an
	// unpublished pin is suppressed from EVERY public nearby read (and stops
	// accepting new interactions) while the owner keeps the row to republish later
	// — distinct from hidden_at (moderation) and expiry (lifetime). DEFAULT TRUE so
	// every existing + future placement is public unless the owner unpublishes it.
	await sql`ALTER TABLE irl_pins ADD COLUMN IF NOT EXISTS published BOOLEAN NOT NULL DEFAULT TRUE`;
}

// ── Calibration bounds (A3) ─────────────────────────────────────────────────
// A nudge is a fine-tune, never a teleport. The client clamps to ±3 m / ±45°;
// the server re-validates with a small margin so a corrected pose can never be
// abused to move someone's agent across the map. Diagonal of a 3 m N + 3 m E
// drag is ~4.24 m, so 5 m is the tightest ceiling that never rejects a legit nudge.
const CAL_MAX_MOVE_M  = 5;    // ground-move ceiling, metres
const CAL_MAX_YAW_DEG = 46;   // yaw-nudge ceiling, degrees
const CAL_MAX_RISE_M  = 3;    // floor-height nudge ceiling, metres

// ── Room frame bounds ───────────────────────────────────────────────────────
// A room id is a short slug (the client derives one per shared-anchor cluster).
// A relative offset is clamped to a building-scale ceiling so the render frame
// can't be bent into a cross-map jump, while still covering any real venue.
const ROOM_ID_RE = /^[a-z0-9-]{1,64}$/;
const REL_MAX_M  = 500;

// ── Placement consent (H4) ──────────────────────────────────────────────────
// 'precise' pins the agent at the placer's exact spot; 'approximate' blurs it to
// a random point within fuzz_radius_m of the real spot (the CLIENT computes the
// fuzzed coordinate it sends — the server only stores the consent + the radius it
// was blurred by). The radius is clamped to a sane band: below FUZZ_MIN_M the blur
// is pointless (under GPS error), above FUZZ_MAX_M it stops being "near here". A
// missing/invalid placement reads as 'precise' so old clients are unaffected.
const PLACEMENT_KINDS = new Set(['precise', 'approximate']);
const FUZZ_MIN_M = 10;    // below this the blur is within GPS error — meaningless
const FUZZ_MAX_M = 500;   // above this it stops meaning "an agent near here"

// ── Placement visibility ────────────────────────────────────────────────────
// `published = false` means PRIVATE: the pin still renders for its OWNER (so you
// can place an agent at home and walk around it in AR) but is withheld from every
// other reader's nearby / room / world-line feed. It is deliberately distinct from
// `hidden_at`, the moderation + expiry hide that withholds a pin from EVERYONE,
// owner included — an owner testing a placement needs to see their own agent.
//
// Why this matters: proof-of-presence (IRL_FIX_SECRET) binds a read to a claimed
// fix, but the mint trusts caller-supplied coordinates, so it raises the cost of a
// geographic sweep without making one impossible. A private pin is not a cost —
// it is an absence: no sweep, at any budget, returns a coordinate that the query
// never selects. That is the only control that holds against a patient attacker.
//
// IRL_DEFAULT_PRIVATE flips the default for new placements. While /irl is
// pre-launch and its operators are testing from their own homes, a placement is
// private unless it explicitly asks to be public — the safe default is the one
// that cannot leak a home address by omission.
const VISIBILITIES = new Set(['public', 'private']);

function defaultsToPrivate() {
	const v = String(process.env.IRL_DEFAULT_PRIVATE ?? '').trim().toLowerCase();
	return v === '1' || v === 'true' || v === 'yes';
}

// Resolve a placement's visibility from the request body, falling back to the
// deployment default. An unrecognised value is never silently treated as public.
export function readVisibility(body) {
	const raw = String(body?.visibility ?? '').trim().toLowerCase();
	if (VISIBILITIES.has(raw)) return raw;
	return defaultsToPrivate() ? 'private' : 'public';
}

// Pin ids are server-minted UUIDs (gen_random_uuid()), and `irl_pins.id` is a UUID
// COLUMN. Validate the format at the top of every mutation path so an oversized /
// garbage id is a clean 400 and never reaches the DB query or a log line. The SQL is
// already parameterized (this is not the injection guard), it's input hygiene, and
// it lets a "not a pin id" request fail fast with a clear message.
//
// Strict UUID, nothing else. A looser "URL-safe opaque id" fallback used to be
// accepted here on the theory that the guard should only reject *dangerous* shapes,
// but the column disagrees: Postgres rejects any non-UUID text with `invalid input
// syntax for type uuid`, which surfaced as a 500 for every well-formed-looking id
// (`PATCH {id:'pin-1'}`, `DELETE ?id=not-a-uuid`) instead of the 400 this guard
// exists to return. api/irl/report.js has always used the strict form; this matches
// it, and privacy.js (which imports this) inherits the fix.
const PIN_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
export function isValidPinId(id) {
	if (typeof id !== 'string' || !id) return false;
	return PIN_UUID_RE.test(id);
}

// Smallest signed distance between two compass bearings, 0–180°.
function circularYawDelta(a, b) {
	let d = ((a - b) % 360 + 360) % 360;
	if (d > 180) d -= 360;
	return Math.abs(d);
}

// A pin is gone from the public world once it has expired (anonymous pins lapse
// after 7 days) or been moderation-hidden. Owner-gated mutations (calibrate /
// outfit / delete) must refuse to touch such a row — re-saving a pose or re-skin
// onto a pin no nearby viewer can see is a silent no-op the owner would mistake
// for success (task 13). `expires_at` NULL = a permanent (signed-in) pin.
export function isExpiredOrHidden(pin, now = Date.now()) {
	if (!pin) return false;
	if (pin.hidden_at != null) return true;
	if (pin.expires_at == null) return false;
	const t = new Date(pin.expires_at).getTime();
	return Number.isFinite(t) && t <= now;
}

// Owner-gated render-scale update. A pinch during the WebXR placement session
// lands AFTER the pin was persisted on the placement tap, so the final size
// arrives as this small follow-up PATCH. Same ownership + liveness gates as
// calibrate; the clamp matches the POST path and the client gesture bounds.
async function handleScale(res, { id, session, body, deviceToken = null }) {
	const raw = Number(body.scale);
	if (!Number.isFinite(raw) || raw <= 0) {
		return json(res, 400, { error: 'invalid scale' });
	}
	const scale = Math.min(4, Math.max(0.25, raw));

	const [pin] = await sql`
		SELECT id, user_id, device_token, expires_at, hidden_at
		FROM irl_pins
		WHERE id = ${id}
	`;
	if (!pin) return json(res, 404, { error: 'not found' });
	const owns =
		(!!session?.id && !!pin.user_id && pin.user_id === session.id) ||
		(!!pin.device_token && !!deviceToken && pin.device_token === deviceToken);
	if (!owns) return json(res, 403, { error: 'only the owner can resize this agent' });
	if (isExpiredOrHidden(pin)) return json(res, 404, { error: 'not found' });

	// Scale 1 is "natural size" — store NULL so legacy readers see no change.
	const stored = scale === 1 ? null : scale;
	const [updated] = await sql`
		UPDATE irl_pins SET anchor_scale = ${stored}
		WHERE id = ${id}
		RETURNING id, anchor_scale
	`;
	return json(res, 200, { pin: updated });
}

// Owner-gated, bounds-checked pose correction. Mutates the A2 pose columns so the
// re-fetch every nearby viewer already runs picks up the corrected spot. (Pushing
// the correction to already-loaded viewers in realtime rides on D1; a re-fetch
// suffices here.) Calibration touches no coin and no third-party token.
async function handleCalibrate(res, { id, session, body, deviceToken = null }) {
	const cal = (body.calibrate && typeof body.calibrate === 'object') ? body.calibrate : {};

	const [pin] = await sql`
		SELECT id, user_id, device_token, lat, lng, heading, anchor_yaw_deg, anchor_height_m,
		       room_id, rel_east_m, rel_north_m, expires_at, hidden_at
		FROM irl_pins
		WHERE id = ${id}
	`;
	if (!pin) return json(res, 404, { error: 'not found' });

	// Ownership: the authenticated owner (user_id) or the anonymous device that
	// placed it (device_token). Anything else is denied — never silently allowed.
	const owns =
		(!!session?.id && !!pin.user_id && pin.user_id === session.id) ||
		(!!pin.device_token && !!deviceToken && pin.device_token === deviceToken);
	if (!owns) return json(res, 403, { error: 'only the owner can calibrate this agent' });

	// An expired / moderation-hidden pin is gone from the public world — refuse to
	// mutate it rather than re-saving a pose nobody will ever see (task 13).
	if (isExpiredOrHidden(pin)) return json(res, 404, { error: 'not found' });

	// New ground position — required, validated, range-checked.
	const newLat = parseFloat(cal.lat);
	const newLng = parseFloat(cal.lng);
	if (!isFinite(newLat) || newLat < -90 || newLat > 90 ||
		!isFinite(newLng) || newLng < -180 || newLng > 180) {
		return json(res, 400, { error: 'invalid calibrate coordinates' });
	}
	const moved = haversineDist(pin.lat, pin.lng, newLat, newLng);
	if (moved > CAL_MAX_MOVE_M) {
		return json(res, 422, { error: 'calibration move too large', max_m: CAL_MAX_MOVE_M });
	}

	// New yaw — optional; bounded against the stored bearing.
	let newYaw = null;
	if (Number.isFinite(cal.anchorYawDeg)) {
		newYaw = ((cal.anchorYawDeg % 360) + 360) % 360;
		const storedYaw = Number.isFinite(pin.anchor_yaw_deg) ? pin.anchor_yaw_deg : (pin.heading ?? 0);
		if (circularYawDelta(newYaw, storedYaw) > CAL_MAX_YAW_DEG) {
			return json(res, 422, { error: 'calibration rotation too large', max_deg: CAL_MAX_YAW_DEG });
		}
	}

	// New floor height — optional; bounded against the stored height.
	let newHeight = null;
	if (Number.isFinite(cal.anchorHeightM)) {
		newHeight = cal.anchorHeightM;
		const baseH = Number.isFinite(pin.anchor_height_m) ? pin.anchor_height_m : 0;
		if (Math.abs(newHeight - baseH) > CAL_MAX_RISE_M || Math.abs(newHeight) > 50) {
			return json(res, 422, { error: 'calibration height too large', max_m: CAL_MAX_RISE_M });
		}
	}

	// New room-frame offset — optional; only meaningful for a room pin, where the
	// render path (pinWorldPos) resolves position from rel_east_m/rel_north_m, NOT the
	// absolute lat/lng. A WebXR "refine on floor" re-places one agent by sending its
	// fresh offset; without persisting it the sharpened spot would snap back on the
	// next viewer re-fetch. Bounded by the SAME ground-move ceiling against the stored
	// offset, so refine sharpens a placement and never slides it across the room. A
	// non-room pin (no room_id) ignores rel — its absolute lat/lng above is authoritative.
	let newRelEast = null, newRelNorth = null;
	if (pin.room_id && Number.isFinite(cal.relEast) && Number.isFinite(cal.relNorth)) {
		const baseE = Number.isFinite(pin.rel_east_m) ? pin.rel_east_m : 0;
		const baseN = Number.isFinite(pin.rel_north_m) ? pin.rel_north_m : 0;
		if (Math.hypot(cal.relEast - baseE, cal.relNorth - baseN) > CAL_MAX_MOVE_M) {
			return json(res, 422, { error: 'calibration move too large', max_m: CAL_MAX_MOVE_M });
		}
		newRelEast = Math.max(-REL_MAX_M, Math.min(REL_MAX_M, cal.relEast));
		newRelNorth = Math.max(-REL_MAX_M, Math.min(REL_MAX_M, cal.relNorth));
	}

	// Persist. heading stays in sync with anchor_yaw_deg so legacy clients (which
	// only read `heading`) still render the corrected bearing.
	const headingToStore = newYaw != null ? Math.round(newYaw) : null;
	// A manual yaw recalibration SUPERSEDES the captured surface orientation. The
	// render-back path (pinYawRad, irl-floor-anchor task 02) prefers anchor_quat over
	// anchor_yaw_deg for exact facing, so a stale quat would silently override the
	// owner's nudge — the correction would never show. Clear anchor_quat whenever the
	// owner sets a new yaw, retiring the now-wrong capture so anchor_yaw_deg is the
	// authoritative source again. A height-only / move-only calibrate keeps the quat.
	const clearQuat = newYaw != null;
	const [row] = await sql`
		UPDATE irl_pins SET
			lat             = ${newLat},
			lng             = ${newLng},
			anchor_yaw_deg  = COALESCE(${newYaw}, anchor_yaw_deg),
			heading         = COALESCE(${headingToStore}, heading),
			anchor_height_m = COALESCE(${newHeight}, anchor_height_m),
			rel_east_m      = COALESCE(${newRelEast}, rel_east_m),
			rel_north_m     = COALESCE(${newRelNorth}, rel_north_m),
			anchor_quat     = CASE WHEN ${clearQuat} THEN NULL ELSE anchor_quat END
		WHERE id = ${id}
		  AND hidden_at IS NULL
		  AND (expires_at IS NULL OR expires_at > NOW())
		RETURNING id, lat, lng, heading, anchor_yaw_deg, anchor_height_m,
		          rel_east_m, rel_north_m, anchor_quat, gps_accuracy_m
	`;
	// A lapse between the SELECT above and this write (e.g. expiry / a reaping cron)
	// leaves no row — surface that as not-found instead of returning { pin: null }.
	if (!row) return json(res, 404, { error: 'not found' });
	// The corrected spot reaches nearby viewers on their next proximity poll — pin
	// positions are never broadcast as a roster, only read by someone standing near it.
	return json(res, 200, { pin: row, calibrated: true });
}

// One-gesture ROOM calibrate (R2). The headline alignment tool: instead of
// nudging each agent (A3), the owner grabs the WHOLE cluster and slides / twists
// it onto its true real-world spot once. Every agent is rigidly tied to the
// shared origin via its rel_east_m/rel_north_m, so moving the origin moves them
// all together with the internal layout intact — never a per-agent shear. We
// translate the origin by a true-north metre offset and rotate the frame about
// it (reusing the A3 calibration ceilings), then re-derive each agent's absolute
// lat/lng (the GPS index nearby reads use) from its UNCHANGED room offset. A
// cluster rotation also turns each agent's facing by the same angle so the rig
// stays internally consistent. Owner-gated across EVERY pin in the room: one
// stranger's agent in the cluster denies the whole move — we never slide someone
// else's agent across the map. No coin or third-party token is involved.
async function handleCalibrateRoom(res, { session, body, deviceToken = null }) {
	const cal = (body.calibrateRoom && typeof body.calibrateRoom === 'object') ? body.calibrateRoom : {};
	const roomId = String(cal.roomId || '');
	if (!ROOM_ID_RE.test(roomId)) return json(res, 400, { error: 'invalid room id' });

	const dEastM  = Number(cal.dEastM);
	const dNorthM = Number(cal.dNorthM);
	const dYawDeg = Number(cal.dYawDeg);
	if (![dEastM, dNorthM, dYawDeg].every(Number.isFinite)) {
		return json(res, 400, { error: 'invalid room calibrate offsets' });
	}
	// Bounds reuse the A3 ceilings: a move is the ground translation magnitude, a
	// rotation the absolute yaw delta. Reject larger with the existing 422 codes.
	if (Math.hypot(dEastM, dNorthM) > CAL_MAX_MOVE_M) {
		return json(res, 422, { error: 'calibration move too large', max_m: CAL_MAX_MOVE_M });
	}
	if (Math.abs(dYawDeg) > CAL_MAX_YAW_DEG) {
		return json(res, 422, { error: 'calibration rotation too large', max_deg: CAL_MAX_YAW_DEG });
	}

	// Every live pin in the room. A calibrate only ever touches the public, visible
	// cluster — an expired / moderation-hidden pin is gone from the world (task 13),
	// same stance as the per-pin path.
	const pins = await sql`
		SELECT id, user_id, device_token, rel_east_m, rel_north_m,
		       origin_lat, origin_lng, origin_yaw_deg, heading, anchor_yaw_deg
		FROM irl_pins
		WHERE room_id = ${roomId}
		  AND hidden_at IS NULL
		  AND (expires_at IS NULL OR expires_at > NOW())
	`;
	if (!pins.length) return json(res, 404, { error: 'room not found' });

	// Ownership: EVERY pin must belong to the caller — the authenticated owner
	// (user_id) or the anonymous device that placed it (device_token). Null-guarded
	// so a NULL user_id / empty device token can never match. Deny the whole move
	// if any agent is a stranger's; never move an agent we don't own.
	const owns = (p) =>
		(!!session?.id && !!p.user_id && p.user_id === session.id) ||
		(!!p.device_token && !!deviceToken && p.device_token === deviceToken);
	if (!pins.every(owns)) {
		return json(res, 403, { error: 'only the room owner can align this room' });
	}

	// Resolve the new origin once (it is denormalized identically across the cluster)
	// via the shared geodesy, then re-derive each agent's absolute lat/lng + facing
	// from its unchanged room-frame offset so nearby reads stay correct.
	const baseRow = pins[0];
	const next = calibrateRoomOrigin({
		originLat: Number(baseRow.origin_lat), originLng: Number(baseRow.origin_lng),
		originYawDeg: Number(baseRow.origin_yaw_deg) || 0,
		dEastM, dNorthM, dYawDeg,
	});
	const rotated = dYawDeg !== 0;
	const ids = [], lats = [], lngs = [], yaws = [];
	for (const p of pins) {
		const abs = pinAbsoluteFromOrigin({
			originLat: next.originLat, originLng: next.originLng, originYawDeg: next.originYawDeg,
			relEast: Number(p.rel_east_m) || 0, relNorth: Number(p.rel_north_m) || 0,
		});
		const baseYaw = Number.isFinite(p.anchor_yaw_deg) ? p.anchor_yaw_deg
			: (Number.isFinite(p.heading) ? p.heading : 0);
		ids.push(p.id);
		lats.push(abs.lat);
		lngs.push(abs.lng);
		yaws.push((((baseYaw + dYawDeg) % 360) + 360) % 360);
	}

	// One atomic write: set the shared origin for the whole cluster and join each
	// agent's re-derived lat/lng + facing by id via unnest, scoped to the verified
	// room. A rotation clears anchor_quat (the captured surface orientation is now
	// wrong — same as the per-pin path) so anchor_yaw_deg is authoritative again.
	const rows = await sql`
		UPDATE irl_pins AS t SET
			origin_lat     = ${next.originLat},
			origin_lng     = ${next.originLng},
			origin_yaw_deg = ${next.originYawDeg},
			lat            = v.lat,
			lng            = v.lng,
			heading        = ROUND(v.yaw)::int,
			anchor_yaw_deg = v.yaw,
			anchor_quat    = CASE WHEN ${rotated} THEN NULL ELSE anchor_quat END
		FROM (
			SELECT * FROM unnest(${ids}::uuid[], ${lats}::float8[], ${lngs}::float8[], ${yaws}::float8[])
				AS u(id, lat, lng, yaw)
		) AS v
		WHERE t.id = v.id AND t.room_id = ${roomId}
		RETURNING t.id
	`;
	// The aligned cluster reaches nearby viewers on their next proximity poll — pin
	// positions are never broadcast as a roster.
	return json(res, 200, {
		ok: true,
		roomId,
		moved: rows.length,
		origin: { lat: next.originLat, lng: next.originLng, yawDeg: next.originYawDeg },
	});
}

// ── Remote outfit change (C6) ───────────────────────────────────────────────
// Re-skin a placed agent for EVERY nearby viewer. The owner sends the appearance
// manifest ({ colors, hidden, accessories }); we validate it against the same
// slot/preset allow-list the studio uses, bake a new GLB onto the pin's clean
// BASE avatar (never the prior bake — so layers/accessories can't stack), store
// it on the first-party CDN, bump avatar_version, and persist. Every nearby
// viewer's loadNearbyPins poll then diffs the version and swaps the GLB. A
// null/empty manifest reverts the pin to its bare base avatar.
async function handleOutfitChange(res, { id, session, body }) {
	const manifest = body.avatar_manifest ?? body.avatarManifest ?? null;
	if (manifest !== null && (typeof manifest !== 'object' || Array.isArray(manifest))) {
		return json(res, 400, { error: 'avatar_manifest must be an object or null' });
	}
	// Validate shape + preset/slot allow-list BEFORE baking, so an invented slot
	// or preset is a clean 400 and never burns a bake.
	if (manifest) {
		const err = validateAppearance(manifest);
		if (err) return json(res, 400, { error: err });
	}

	// Owner-gated: only the authenticated owner re-skins their agent. (Appearance
	// is never editable from an anonymous device token — same stance as the
	// avatar/location edits below.)
	const [pin] = await sql`
		SELECT id, user_id, avatar_url, avatar_base_url, avatar_version, expires_at, hidden_at
		FROM irl_pins
		WHERE id = ${id}
	`;
	if (!pin) return json(res, 404, { error: 'not found' });
	if (!pin.user_id || pin.user_id !== session.id) {
		return json(res, 403, { error: "only the owner can change this agent's outfit" });
	}
	// An expired / moderation-hidden pin is gone from the public world — refuse to
	// burn a bake re-skinning a row no nearby viewer can see (task 13).
	if (isExpiredOrHidden(pin)) return json(res, 404, { error: 'not found' });

	// The base GLB the manifest dresses. Captured once (the agent as it looked
	// before any outfit edit) so re-bakes always start from a clean model.
	const baseUrl = pin.avatar_base_url || pin.avatar_url;
	if (!baseUrl) return json(res, 422, { error: 'this agent has no avatar to dress' });

	let newAvatarUrl = baseUrl;
	try {
		// Lazy import: irl-bake → bake.js pulls in sharp (native libvips). Loading
		// it only on this path keeps every other pins route alive even where the
		// native module can't load.
		const { bakePinOutfit, isBakeable } = await import('../_lib/irl-bake.js');
		if (manifest && isBakeable(manifest)) {
			const baked = await bakePinOutfit({ pinId: id, baseUrl, manifest });
			newAvatarUrl = baked.url;
		}
		// else: cleared / empty manifest → serve the bare base GLB again.
	} catch (err) {
		// Log the full detail server-side; NEVER echo err.message to the client — a
		// bake/upstream error can carry filesystem paths, R2/CDN URLs, or libvips
		// internals. The client gets a generic, actionable message only (task 13).
		console.error('[irl/pins] outfit bake failed', { pinId: id, message: err?.message });
		return json(res, 502, { error: 'could not bake the new outfit' });
	}

	const [row] = await sql`
		UPDATE irl_pins SET
			avatar_manifest = ${manifest ? JSON.stringify(manifest) : null}::jsonb,
			avatar_base_url = COALESCE(avatar_base_url, ${baseUrl}),
			avatar_url      = ${newAvatarUrl},
			avatar_version  = avatar_version + 1
		WHERE id = ${id} AND user_id = ${session.id}
		  AND hidden_at IS NULL
		  AND (expires_at IS NULL OR expires_at > NOW())
		RETURNING id, lat, lng, avatar_url, avatar_manifest, avatar_version
	`;
	if (!row) return json(res, 404, { error: 'not found' });

	// The re-skin reaches co-located viewers on their next proximity poll, which
	// diffs avatar_version and swaps the GLB. There is no realtime fan-out: a pin's
	// data only travels to a viewer who is physically near it.
	return json(res, 200, { pin: row });
}

export default wrap(async (req, res) => {
	cors(req, res, { methods: ['GET', 'POST', 'PATCH', 'DELETE', 'OPTIONS'] });
	if (req.method === 'OPTIONS') return res.end();

	await ensureTable();

	// Every public GET read (the nearby feed + my-pins) is IP rate-limited so the
	// tight proximity feed can't be systematically gridded into a bulk location
	// scrape. This read FAILS CLOSED (H7): if the limiter can't decide, we deny with
	// a retryable `rate_limiter_unavailable` rather than open an unmetered scrape
	// window: an unbounded location read is the exact hole the limit exists to
	// close. The generic 240/min read ceiling applies to every GET here; the
	// coordinate-returning nearby branch below adds the tighter, dedicated
	// `irlNearbyIp` bucket (60/min) that the H7 sweep-cost numbers are computed
	// against. See docs/irl/THREAT-MODEL.md.
	if (req.method === 'GET') {
		const rl = await limitFailClosedRead('publicIp', limits.publicIp, clientIp(req));
		if (!rl.success) return rateLimited(res, rl);
	}

	// ── GET — my pins by device token (anonymous) or session (auth) ──────────
	// Path: /api/irl/pins/mine?deviceToken=…  — lets a visitor browse and manage
	// the pins they placed from this device even after a reload, without login.
	if (req.method === 'GET' && req.url?.includes('/mine')) {
		const session  = await getSessionUser(req).catch(() => null);
		// Null-guard both identifiers BEFORE the query: an empty/missing device token
		// or a NULL session id must never become a clause that matches another
		// owner's pins. (A bare `device_token = ''` would otherwise leak every
		// legacy NULL/empty-token anonymous pin — and its lat/lng — to any caller.)
		const ownerId  = session?.id ?? null;
		// Header-first (H2): the device token never rides in the URL where it would
		// land in access logs / history. readDeviceToken null-guards empty values.
		const ownerDev = readDeviceToken(req);
		if (!ownerDev && !ownerId) {
			return json(res, 400, { error: 'deviceToken required' });
		}
		// INVARIANT: coordinates leave here ONLY for the caller's OWN pins —
		// strictly scoped to their session id or the device token they hold. Each
		// arm is null-guarded so a missing identifier can never widen the match.
		const rows = await sql`
			SELECT id, lat, lng, avatar_name, caption, placed_at, expires_at, view_count,
			       placement_kind, fuzz_radius_m
			FROM irl_pins
			WHERE ((${ownerId}::uuid IS NOT NULL AND user_id = ${ownerId}::uuid)
			    OR (${ownerDev}::text IS NOT NULL AND device_token = ${ownerDev}))
			  AND hidden_at IS NULL
			  AND (expires_at IS NULL OR expires_at > NOW())
			ORDER BY placed_at DESC
			LIMIT 20
		`;
		return json(res, 200, { pins: rows });
	}

	// ── GET — my pins (auth, query-param form) ────────────────────────────────
	if (req.method === 'GET' && req.query.mine === '1') {
		const session = await getSessionUser(req).catch(() => null);
		if (!session) return json(res, 401, { error: 'not authenticated' });
		const rows = await sql`
			SELECT id, lat, lng, heading, avatar_url, avatar_name, caption, agent_id,
			       placed_at, expires_at, view_count,
			       anchor_height_m, anchor_yaw_deg, anchor_quat, anchor_scale,
			       gps_accuracy_m, altitude_m, anchor_source,
			       avatar_manifest, avatar_base_url, avatar_version,
			       placement_kind, fuzz_radius_m
			FROM irl_pins
			WHERE user_id = ${session.id}
			  AND hidden_at IS NULL
			ORDER BY placed_at DESC
			LIMIT 100
		`;
		return json(res, 200, { pins: rows });
	}

	// ── GET — nearby pins (the ONLY way another agent's location is revealed) ──
	// A placed agent is private by location: its coordinates reach a viewer only
	// through this read, and only when that viewer is physically within a tight
	// radius of it — so an agent is "stumbled upon" in AR by someone standing near
	// it, never handed out as a browseable roster/map. There is no bbox/window
	// feed and no realtime broadcast of pins: the radius is hard-capped small, the
	// caller's own lat/lng is required, and the read is IP rate-limited above so a
	// scripted grid-sweep can't reconstruct the map.
	//
	// PRIVACY CONTRACT (L4): the caller's own lat/lng are used ONLY to run the
	// proximity query and are NEVER logged. A proximity READ is not persisted —
	// the only stored coordinates are the deliberate placements in irl_pins; the
	// rate-limit counter keys on IP, not position. Do not add any console log of
	// req.query / lat / lng on this path. Privacy-minded clients additionally
	// coarsen the origin they send (see discoveryOrigin() in src/irl.js), so the
	// exact device position need never reach the server at all.

	// ── GET — marker room read (Epic M) ──────────────────────────────────────
	// Indoor colocalization can't use the GPS proximity feed: GPS is ±20–50 m
	// inside a building and never agrees phone-to-phone. Instead a MARKER room is
	// keyed by a QR both phones can see — its id (`m-<hash>`) is derived from the
	// QR payload (src/irl/marker-anchor.js markerRoomId), so a viewer who scanned
	// the marker can read its pins by room_id with NO location at all. This is
	// capability-gated by knowing the QR: the id is unguessable without having
	// physically seen the marker, which is the same "be present to discover"
	// contract the proximity feed enforces with GPS. Restricted to marker rooms
	// (`m-` prefix) so a GPS room (`r-…`) can never be read here, bypassing its
	// fix-token gate. Still IP rate-limited by the publicIp ceiling applied above.
	if (req.method === 'GET' && req.query.room != null) {
		const roomId = String(req.query.room);
		if (!ROOM_ID_RE.test(roomId)) {
			return json(res, 400, { error: 'invalid room id' });
		}
		if (!roomId.startsWith('m-')) {
			// GPS rooms are readable only through the fix-gated proximity feed.
			return json(res, 404, { error: 'not a marker room' });
		}

		const session = await getSessionUser(req).catch(() => null);
		const myId    = session?.id ?? null;
		const myTok   = readDeviceToken(req);

		const rows = await sql`
			SELECT id, user_id, device_token, agent_id, lat, lng, heading,
			       avatar_url, avatar_name, caption, x402_endpoint, placed_at, view_count,
			       anchor_height_m, anchor_yaw_deg, anchor_quat, anchor_scale,
			       gps_accuracy_m, altitude_m, anchor_source, avatar_version,
			       placement_kind, fuzz_radius_m, published,
			       vps_provider, vps_id,
			       room_id, rel_east_m, rel_north_m, origin_lat, origin_lng, origin_yaw_deg
			FROM irl_pins
			WHERE room_id = ${roomId}
			  AND hidden_at IS NULL
			  AND (published IS NOT FALSE
			    OR (${myId}::uuid IS NOT NULL AND user_id = ${myId}::uuid)
			    OR (${myTok}::text IS NOT NULL AND device_token = ${myTok}::text))
			  AND (expires_at IS NULL OR expires_at > NOW())
			ORDER BY placed_at DESC
			LIMIT 50
		`;

		// Same allow-list projection as the nearby feed: NEVER expose user_id or
		// device_token. The marker frame (rel_east_m / rel_north_m) is the render-
		// authoritative pose; lat/lng is only a coarse index here, so coarsen it.
		const pins = rows.map(r => ({
			id:              r.id,
			agent_id:        r.agent_id,
			lat:             roundCoord(r.lat),
			lng:             roundCoord(r.lng),
			heading:         r.heading,
			avatar_url:      r.avatar_url,
			avatar_name:     r.avatar_name,
			caption:         r.caption,
			x402_endpoint:   r.x402_endpoint,
			placed_at:       r.placed_at,
			view_count:      r.view_count,
			anchor_height_m: r.anchor_height_m,
			anchor_yaw_deg:  r.anchor_yaw_deg,
			anchor_quat:     r.anchor_quat,
			anchor_scale:    r.anchor_scale,
			gps_accuracy_m:  r.gps_accuracy_m,
			altitude_m:      r.altitude_m,
			anchor_source:   r.anchor_source,
			vps_provider:    r.vps_provider ?? null,
			vps_id:          r.vps_id ?? null,
			room_id:         r.room_id ?? null,
			rel_east_m:      r.rel_east_m,
			rel_north_m:     r.rel_north_m,
			origin_lat:      roundCoord(r.origin_lat),
			origin_lng:      roundCoord(r.origin_lng),
			origin_yaw_deg:  r.origin_yaw_deg,
			avatar_version:  Number(r.avatar_version) || 0,
			placement_kind:  r.placement_kind === 'approximate' ? 'approximate' : 'precise',
			fuzz_radius_m:   Number.isFinite(r.fuzz_radius_m) ? r.fuzz_radius_m : null,
			// A private pin only ever reaches its owner, so this is always 'public'
			// for a stranger — it exists so the owner's UI can badge their own pins.
			visibility:      r.published === false ? 'private' : 'public',
			is_mine: (!!myId && r.user_id === myId) || (!!myTok && r.device_token === myTok),
		}));

		return json(res, 200, { pins, room_id: roomId });
	}

	if (req.method === 'GET') {
		const lat    = parseFloat(req.query.lat);
		const lng    = parseFloat(req.query.lng);
		// Tight proximity gate: default 40 m, hard-capped at 60 m. Large enough to
		// render an agent as you walk up and point your camera at its spot, small
		// enough that one read only ever exposes the handful right where you stand.
		// A missing radius defaults to 40; a PRESENT but non-finite radius (e.g.
		// ?radius=abc) is rejected — clamping NaN would silently yield NaN deltas and
		// an always-empty feed, masking a malformed request behind a 200.
		const rawRadius = req.query.radius;
		const parsedRadius = rawRadius == null || rawRadius === '' ? 40 : parseFloat(rawRadius);
		if (!Number.isFinite(parsedRadius)) {
			return json(res, 400, { error: 'invalid radius' });
		}
		const radius = Math.min(60, Math.max(10, parsedRadius));

		if (!isFinite(lat) || !isFinite(lng)) {
			return json(res, 400, { error: 'lat and lng are required' });
		}

		// Dedicated coordinate-read budget (H7), on top of the generic GET ceiling
		// above. This is the number the threat model's grid-sweep cost is computed
		// from, so it lives in its own bucket rather than riding the shared public
		// read limit, which is tuned for page-load fan-out and has been raised for
		// reasons that have nothing to do with location privacy. Fails CLOSED.
		const nearbyRl = await limitFailClosedRead('irlNearbyIp', limits.irlNearbyIp, clientIp(req));
		if (!nearbyRl.success) return rateLimited(res, nearbyRl);

		// Proof-of-presence (H3): bind the read to a genuine fix. The caller mints a
		// short-lived, HMAC-signed token from their real GPS via POST /fix-token; this
		// read only answers for the coarse area that token was minted in, so a viewer
		// can't browse pins at a location they aren't standing near (the actual product
		// contract). Enforced only when IRL_FIX_SECRET is set — dev/preview without it
		// works unchanged so local testing isn't gated (the mode is logged once at the
		// mint endpoint's cold start). Failure → 401 fix_required, which the client
		// turns into the "Getting your location…" designed state, never a blank screen.
		if (fixEnforced()) {
			const fixHeader = req.headers['x-irl-fix'];
			const fixToken = Array.isArray(fixHeader) ? fixHeader[0] : fixHeader;
			const v = await verifyFixToken(fixToken, lat, lng);
			if (!v.ok) {
				return json(res, 401, {
					error: 'fix_required',
					reason: v.reason,
					error_description: 'a fresh location fix is required to read nearby agents',
				});
			}
		}

		// Bounding-box pre-filter (fast index scan), then haversine in app
		const latDelta = radius / 110540;
		const lngDelta = radius / (111320 * Math.cos(lat * Math.PI / 180));

		// Resolve the caller so we can tell them which nearby pins are THEIRS without
		// ever exposing other people's owner identifiers.
		const session = await getSessionUser(req).catch(() => null);
		const myId    = session?.id ?? null;
		const myTok   = readDeviceToken(req);

		const rows = await sql`
			SELECT id, user_id, device_token, agent_id, lat, lng, heading,
			       avatar_url, avatar_name, caption, x402_endpoint, placed_at, view_count,
			       anchor_height_m, anchor_yaw_deg, anchor_quat, anchor_scale,
			       gps_accuracy_m, altitude_m, anchor_source, avatar_version,
			       placement_kind, fuzz_radius_m, published,
			       room_id, rel_east_m, rel_north_m, origin_lat, origin_lng, origin_yaw_deg
			FROM irl_pins
			WHERE lat BETWEEN ${lat - latDelta} AND ${lat + latDelta}
			  AND lng BETWEEN ${lng - lngDelta} AND ${lng + lngDelta}
			  AND hidden_at IS NULL
			  AND (published IS NOT FALSE
			    OR (${myId}::uuid IS NOT NULL AND user_id = ${myId}::uuid)
			    OR (${myTok}::text IS NOT NULL AND device_token = ${myTok}::text))
			  AND (expires_at IS NULL OR expires_at > NOW())
			ORDER BY placed_at DESC
			LIMIT 50
		`;

		// Explicit allow-list projection: NEVER return user_id or device_token in the
		// public feed (a stable owner UUID + precise coords is a deanonymization /
		// location-tracking vector). Surface only an is_mine boolean computed here.
		const pins = rows
			.map(r => ({
				id:             r.id,
				agent_id:       r.agent_id,
				// Coarsened to ~1.1 m (PUBLIC_COORD_DP) — strips false precision a
				// co-located reader could harvest while staying finer than GPS error.
				lat:            roundCoord(r.lat),
				lng:            roundCoord(r.lng),
				heading:        r.heading,
				avatar_url:     r.avatar_url,
				avatar_name:    r.avatar_name,
				caption:        r.caption,
				x402_endpoint:  r.x402_endpoint,
				placed_at:      r.placed_at,
				view_count:     r.view_count,
				anchor_height_m: r.anchor_height_m,
				anchor_yaw_deg:  r.anchor_yaw_deg,
				anchor_quat:     r.anchor_quat,
				anchor_scale:    r.anchor_scale,
				gps_accuracy_m:  r.gps_accuracy_m,
				altitude_m:      r.altitude_m,
				anchor_source:   r.anchor_source,
				// Room frame — when present (room_id non-null), the viewer renders this
				// agent from its exact offset relative to the shared origin instead of
				// its own GPS, so the room-scale layout holds for everyone. Null on
				// legacy standalone pins → the client falls back to lat/lng.
				room_id:         r.room_id ?? null,
				rel_east_m:      r.rel_east_m,
				rel_north_m:     r.rel_north_m,
				// The room origin is a GPS index too — coarsen it like lat/lng; the
				// exact intra-room layout rides the relative offsets above, not the origin.
				origin_lat:      roundCoord(r.origin_lat),
				origin_lng:      roundCoord(r.origin_lng),
				origin_yaw_deg:  r.origin_yaw_deg,
				// C6 — cheap re-skin signal: the viewer diffs this against its loaded
				// pin and swaps the GLB when it bumps. (The editable manifest/base URL
				// stay owner-private — viewers only ever need the rendered avatar_url.)
				avatar_version:  Number(r.avatar_version) || 0,
				// Placement consent (H4): the kind + blur radius drive the owner's
				// Exact/Approximate badge. A legacy pin (NULL column) reads as 'precise'.
				// This is a flag, not a coordinate — for an approximate pin the true spot
				// was never stored, so surfacing "≈ approximate (~Nm)" leaks nothing.
				placement_kind:  r.placement_kind === 'approximate' ? 'approximate' : 'precise',
				fuzz_radius_m:   Number.isFinite(r.fuzz_radius_m) ? r.fuzz_radius_m : null,
				// A private pin only ever reaches its owner, so this is always 'public'
				// for a stranger — it exists so the owner's UI can badge their own pins.
				visibility:      r.published === false ? 'private' : 'public',
				is_mine: (!!myId && r.user_id === myId) || (!!myTok && r.device_token === myTok),
				distance_m: Math.round(haversineDist(lat, lng, r.lat, r.lng)),
			}))
			.filter(r => r.distance_m <= radius)
			.sort((a, b) => a.distance_m - b.distance_m);

		// Sweep anomaly detection (H7): record which geocell this caller just read.
		// Reading many DISTINCT cells in a short window is sweep-shaped even when each
		// cell stays under the rate limit; this fires a deduped, coordinate-free ops
		// alert past the threshold. Best-effort and fire-and-forget — never awaited
		// into the response path, never carries a coordinate.
		recordCellRead(clientIp(req), encodeGeohash(lat, lng, GEOCELL_PRECISION));
		// Usage analytics (fire-and-forget, never awaited into the response path —
		// same discipline as recordCellRead above). See api/_lib/irl-analytics.js.
		logIrlEvent({ type: 'nearby_fetch', lat, lng, deviceToken: myTok, metadata: { count: pins.length } });

		return json(res, 200, { pins });
	}

	// ── POST — create pin ─────────────────────────────────────────────────────
	// D4 gate order, cheapest/most-decisive first: coords → content (pure string,
	// fails closed) → URL/coin safety → rate limit (1 Redis cmd, protects the DB
	// from a flood) → density + per-owner caps (DB counts) → insert. Each rejection
	// carries a designed error code the client renders as an actionable message.
	if (req.method === 'POST') {
		const ip = clientIp(req);
		const rl = await limitOrFailOpen('irlPinIp', limits.irlPinIp, ip);
		if (!rl.success) return rateLimited(res, rl);

		const body = req.body ?? {};
		const lat  = parseFloat(body.lat);
		const lng  = parseFloat(body.lng);

		if (!isFinite(lat) || !isFinite(lng)) {
			return json(res, 400, { error: 'lat and lng are required' });
		}
		if (lat < -90 || lat > 90 || lng < -180 || lng > 180) {
			return json(res, 400, { error: 'invalid coordinates' });
		}

		// Clamp text to its public length cap, then run the tier-1 content gate.
		const caption    = body.caption    != null ? String(body.caption).slice(0, CAPTION_MAX)    : null;
		const avatarName = body.avatarName != null ? String(body.avatarName).slice(0, NAME_MAX)    : null;
		const bad = contentReject(caption, avatarName);
		if (bad) {
			return json(res, 422, {
				error: 'content',
				field: bad.field,
				message: bad.reason === 'coin'
					? 'A pin can only reference $THREE — the only coin on three.ws.'
					: 'That text isn’t allowed on a public pin.',
			});
		}
		// Tier-2 AI risk on the borderline caption (no-op when Guardian unconfigured).
		if (caption && (await guardianFlags(caption))) {
			return json(res, 422, {
				error: 'content',
				field: 'caption',
				message: 'That caption was flagged by our content filter. Try rewording it.',
			});
		}

		// Validate the URLs handed to every nearby viewer (avatar GLB + x402 pay).
		const avatarUrlChk = safeRemoteUrl(body.avatarUrl);
		if (!avatarUrlChk.ok) return json(res, 400, { error: 'invalid avatarUrl' });
		// x402 pay target must be a first-party / allow-listed payment host — never an
		// arbitrary external drain (D4). Same-origin relative paths are first-party.
		const x402Chk = safePaymentEndpoint(body.x402Endpoint);
		if (!x402Chk.ok) {
			return json(res, 422, {
				error: 'endpoint',
				field: 'x402Endpoint',
				message: 'Pay endpoints must be hosted on three.ws.',
			});
		}
		// Empty-string device token would otherwise become a shared anonymous owner.
		// readDeviceToken accepts the header (H2) or body, null-guarding empties.
		const deviceToken = readDeviceToken(req);

		const session   = await getSessionUser(req).catch(() => null);
		const userId    = session?.id ?? null;

		// Placement token bucket (D4) — per (device + IP), tighter than the coarse
		// per-IP gate above. Burst (5/min) + sustained (30/h). Fails open + logs on a
		// Redis outage (non-critical) so an infra hiccup never blocks a real placement.
		const rateKey = `${deviceToken ?? userId ?? 'anon'}:${ip}`;
		const [burst, hourly] = await Promise.all([
			limitOrFailOpen('irlPinBurst', limits.irlPinBurst, rateKey),
			limitOrFailOpen('irlPinHourly', limits.irlPinHourly, rateKey),
		]);
		const throttled = !burst.success ? burst : !hourly.success ? hourly : null;
		if (throttled) {
			const retryAfter = Math.max(1, Math.ceil((throttled.reset - Date.now()) / 1000));
			res.setHeader?.('Retry-After', String(retryAfter));
			return json(res, 429, {
				error: 'rate',
				retryAfter,
				message: 'You’re placing agents too fast. Wait a moment and try again.',
			});
		}

		// Density cap — one fine geocell (~150m) can hold only so many agents, so a
		// single actor can't carpet-bomb a venue. Counts only live, non-hidden pins.
		const cell7 = encodeGeohash(lat, lng, GEOCELL_PRECISION);
		if (cell7) {
			const [{ n }] = await sql`
				SELECT count(*)::int AS n FROM irl_pins
				WHERE geocell7 = ${cell7}
				  AND hidden_at IS NULL
				  AND (expires_at IS NULL OR expires_at > NOW())
			`;
			if (n >= MAX_PINS_PER_CELL) {
				return json(res, 429, {
					error: 'area_full',
					message: 'This area already has the maximum number of agents. Try another spot.',
				});
			}
		}

		// Per-owner active-pin cap — a signed-in owner is accountable, so gets a
		// higher ceiling than an anonymous device. Null-guarded so a NULL user_id or
		// empty device token can't collide owners.
		const ownerCap = userId ? MAX_PINS_PER_OWNER_SIGNED : MAX_PINS_PER_OWNER_ANON;
		const [{ n: owned }] = await sql`
			SELECT count(*)::int AS n FROM irl_pins
			WHERE ((${userId}::uuid IS NOT NULL AND user_id = ${userId}::uuid)
			    OR (${deviceToken}::text IS NOT NULL AND device_token = ${deviceToken}))
			  AND hidden_at IS NULL
			  AND (expires_at IS NULL OR expires_at > NOW())
		`;
		if (owned >= ownerCap) {
			return json(res, 429, {
				error: 'pin_limit',
				limit: ownerCap,
				message: 'You’ve reached your active pin limit. Remove an old pin to place a new one.',
			});
		}

		// Authenticated users get permanent pins; anonymous expire in 7 days.
		const expiresAt = userId ? null : new Date(Date.now() + 7 * 24 * 3600 * 1000).toISOString();

		// Anchor pose (A2) — optional, back-compat: old clients send no `anchor`,
		// every pose column inserts NULL. New clients send a reproducible pose so
		// later sessions / other users can reconstruct where the agent stands.
		const pose          = (body.anchor && typeof body.anchor === 'object') ? body.anchor : {};
		// Reject absurd floor height (> ±50 m above/below eye) to NULL, not noise.
		const anchorHeightM = Number.isFinite(pose.heightM) && Math.abs(pose.heightM) <= 50
			? pose.heightM : null;
		const anchorYawDeg  = Number.isFinite(pose.yawDeg)
			? ((pose.yawDeg % 360) + 360) % 360 : null;
		const anchorQuat    = Array.isArray(pose.quat) && pose.quat.length === 4 &&
			pose.quat.every(Number.isFinite)
			? JSON.stringify(pose.quat) : null;
		// Clamp GPS accuracy to a sane 0–500 m range (a worse fix is meaningless here).
		const gpsAccuracyM  = Number.isFinite(pose.gpsAccuracyM)
			? Math.min(500, Math.max(0, pose.gpsAccuracyM)) : null;
		const altitudeM     = Number.isFinite(pose.altitudeM) ? pose.altitudeM : null;
		// Pinch-resized render scale — clamped to the same band the client gesture
		// enforces (desk figurine ↔ statue). Absent/1 stores NULL = natural size.
		const anchorScale   = Number.isFinite(pose.scale) && pose.scale > 0 && pose.scale !== 1
			? Math.min(4, Math.max(0.25, pose.scale)) : null;
		// 'webxr' (A1) · 'gyro-gps' (absolute compass heading) · 'gyro-gps:rel'
		// (page-relative heading only — A3 down-weights its cross-user bearing) ·
		// 'map' (L2: a point chosen on the map, not a live fix — its bearing isn't
		// compass-trustworthy, same down-weighting as ':rel') · 'marker' (Epic M: a
		// visual QR marker is the shared origin; GPS is only a coarse index and the
		// frame is reconstructed live per viewer from the marker, not from compass).
		const anchorSource  = pose.source === 'webxr' ? 'webxr'
			: pose.source === 'map' ? 'map'
			: pose.source === 'marker' ? 'marker'
			: pose.source === 'gyro-gps:rel' ? 'gyro-gps:rel' : 'gyro-gps';

		// Visual-positioning identity (Epic M) — the long-reserved vps_* columns,
		// now first written by the marker path: provider is the positioning system
		// ('qr' for a QR marker) and id is its opaque token (the marker payload).
		// Both phones derive the room_id from this same token, so it is the key that
		// lets a second viewer read the room with no GPS. Length-clamped; absent on
		// every non-marker placement (every existing caller), leaving the columns NULL.
		const vps          = (body.vps && typeof body.vps === 'object') ? body.vps : {};
		const vpsProvider  = anchorSource === 'marker' && typeof vps.provider === 'string'
			? vps.provider.slice(0, 32) : null;
		const vpsId        = anchorSource === 'marker' && typeof vps.id === 'string'
			? vps.id.slice(0, 256) : null;

		// Room frame (optional) — when the client places into a shared room it sends
		// the exact offset from the room origin. We persist origin + offset as the
		// render-authoritative pose; lat/lng above stays the GPS index. An invalid or
		// absent block leaves every room column NULL → a standalone pin, so old
		// clients and single-drop placements are unaffected. (See src/irl/room-anchor.js.)
		const room       = (body.room && typeof body.room === 'object') ? body.room : {};
		const roomOk     = ROOM_ID_RE.test(String(room.id || '')) &&
			Number.isFinite(room.originLat) && room.originLat >= -90  && room.originLat <= 90 &&
			Number.isFinite(room.originLng) && room.originLng >= -180 && room.originLng <= 180 &&
			!(room.originLat === 0 && room.originLng === 0) &&
			Number.isFinite(room.relEast) && Number.isFinite(room.relNorth);
		const clampRel   = (v) => Math.max(-REL_MAX_M, Math.min(REL_MAX_M, v));
		const roomIdVal  = roomOk ? String(room.id) : null;
		const relEastM   = roomOk ? clampRel(room.relEast)  : null;
		const relNorthM  = roomOk ? clampRel(room.relNorth) : null;
		const originLatV = roomOk ? room.originLat : null;
		const originLngV = roomOk ? room.originLng : null;
		const originYawV = roomOk && Number.isFinite(room.originYawDeg)
			? ((room.originYawDeg % 360) + 360) % 360 : null;

		// Placement consent (H4) — record whether the placer pinned their exact spot
		// or deliberately blurred it. The client computes the fuzzed lat/lng it sends;
		// we store the consent kind + the radius the blur used. An 'approximate' pin
		// must carry a fuzz radius (clamped to the sane band); a missing/invalid
		// placement (or an old client that sends neither) defaults to 'precise' with
		// no radius, so behaviour is unchanged for every existing caller.
		const rawKind        = String(body.placement ?? body.placementKind ?? body.placement_kind ?? '').toLowerCase();
		const placementKind  = PLACEMENT_KINDS.has(rawKind) ? rawKind : 'precise';
		const rawFuzz        = Number(body.fuzzRadiusM ?? body.fuzz_radius_m);
		const fuzzRadiusM    = placementKind === 'approximate' && Number.isFinite(rawFuzz)
			? Math.min(FUZZ_MAX_M, Math.max(FUZZ_MIN_M, rawFuzz))
			: null;

		const visibility = readVisibility(body);

		const [pin] = await sql`
			INSERT INTO irl_pins
				(user_id, agent_id, device_token, lat, lng, heading,
				 avatar_url, avatar_name, caption, x402_endpoint, expires_at,
				 anchor_height_m, anchor_yaw_deg, anchor_quat, anchor_scale,
				 gps_accuracy_m, altitude_m, anchor_source, geocell7,
				 room_id, rel_east_m, rel_north_m, origin_lat, origin_lng, origin_yaw_deg,
				 placement_kind, fuzz_radius_m, vps_provider, vps_id, published)
			VALUES (
				${userId},
				${body.agentId    ?? null},
				${deviceToken},
				${lat}, ${lng},
				${parseFloat(body.heading) || 0},
				${avatarUrlChk.value},
				${avatarName},
				${caption},
				${x402Chk.value},
				${expiresAt},
				${anchorHeightM},
				${anchorYawDeg},
				${anchorQuat},
				${anchorScale},
				${gpsAccuracyM},
				${altitudeM},
				${anchorSource},
				${cell7 || null},
				${roomIdVal},
				${relEastM},
				${relNorthM},
				${originLatV},
				${originLngV},
				${originYawV},
				${placementKind},
				${fuzzRadiusM},
				${vpsProvider},
				${vpsId},
				${visibility === 'public'}
			)
			RETURNING *
		`;

		// No realtime fan-out: a new placement is never broadcast as a roster. It
		// surfaces to a viewer only on their next proximity poll, and only once they
		// are physically within the nearby radius of where it was dropped.
		logIrlEvent({ type: 'pin_created', pinId: pin.id, lat, lng, deviceToken, metadata: { mode: anchorSource } });
		return json(res, 201, { pin: { ...pin, permanent: expiresAt === null } });
	}

	// ── PATCH — edit pin fields ───────────────────────────────────────────────
	// Authenticated owners can update: caption, avatar_url, avatar_name, lat, lng.
	// Anonymous device-token owners can only update caption (no location/avatar changes
	// from anonymous sessions for safety).
	if (req.method === 'PATCH') {
		const rl = await limitOrFailOpen('irlPinIp', limits.irlPinIp, clientIp(req));
		if (!rl.success) return rateLimited(res, rl);

		const session = await getSessionUser(req).catch(() => null);
		const body = req.body ?? {};

		// ── Room calibrate — one-gesture align of an entire owned cluster (R2) ──
		// Routed BEFORE the per-pin `id` gate: a room calibrate is scoped by roomId,
		// not a single pin id. Owner-gated for both authenticated owners and the
		// anonymous device that placed the room; ownership + bounds are enforced
		// inside handleCalibrateRoom.
		if (body.calibrateRoom && typeof body.calibrateRoom === 'object') {
			return handleCalibrateRoom(res, { session, body, deviceToken: readDeviceToken(req) });
		}

		const { id } = body;
		if (!id) return json(res, 400, { error: 'id required' });
		// Reject a malformed pin id up front (covers calibrate / outfit / field-edit):
		// the id is a server-minted UUID, so anything else is a bad request, not a
		// row that happens not to exist.
		if (!isValidPinId(id)) return json(res, 400, { error: 'invalid pin id' });

		// ── Calibrate — a small, owner-gated pose correction (A3) ─────────────
		// Owner-gated for both authenticated owners and the anonymous device that
		// placed the pin, so it routes BEFORE the auth gate below; ownership and
		// nudge bounds are enforced inside handleCalibrate.
		if (body.calibrate && typeof body.calibrate === 'object') {
			return handleCalibrate(res, { id, session, body, deviceToken: readDeviceToken(req) });
		}

		// ── Resize — owner-gated pinch scale follow-up (same gate as calibrate) ──
		// Routed before the auth gate below: the anonymous placing device may resize
		// its own agent; ownership is enforced inside handleScale.
		if ('scale' in body && !('caption' in body) && !('avatarUrl' in body) && !('lat' in body)) {
			return handleScale(res, { id, session, body, deviceToken: readDeviceToken(req) });
		}

		// Field edits (caption / avatar / location / heading / x402) require auth.
		if (!session) return json(res, 401, { error: 'not authenticated' });

		// ── Outfit change (C6) — re-skin a placed agent for all nearby viewers ──
		// A manifest PATCH bakes a new GLB + bumps avatar_version; routed before
		// the simple field-edit SET below because it has its own bake/persist path.
		if ('avatar_manifest' in body || 'avatarManifest' in body) {
			return handleOutfitChange(res, { id, session, body });
		}

		// Build update SET clause only for fields the caller provided
		const updates = {};
		if ('caption' in body)    updates.caption    = body.caption ?? null;
		if ('avatarUrl' in body)  updates.avatarUrl  = body.avatarUrl ?? null;
		if ('avatarName' in body) updates.avatarName = body.avatarName ?? null;
		if ('lat' in body)        updates.lat        = parseFloat(body.lat);
		if ('lng' in body)        updates.lng        = parseFloat(body.lng);
		// heading: re-aim the avatar remotely (normalize to 0–359°)
		if ('heading' in body && isFinite(parseFloat(body.heading))) {
			updates.heading = ((Math.round(parseFloat(body.heading)) % 360) + 360) % 360;
		}
		// x402Endpoint: attach or update a paid endpoint so visitors can pay the agent IRL
		if ('x402Endpoint' in body) updates.x402Endpoint = body.x402Endpoint ?? null;

		if (!Object.keys(updates).length) {
			return json(res, 400, { error: 'no updatable fields provided' });
		}

		// Validate new lat/lng if provided
		if ('lat' in updates && (!isFinite(updates.lat) || updates.lat < -90 || updates.lat > 90)) {
			return json(res, 400, { error: 'invalid lat' });
		}
		if ('lng' in updates && (!isFinite(updates.lng) || updates.lng < -180 || updates.lng > 180)) {
			return json(res, 400, { error: 'invalid lng' });
		}

		// Validate URL fields if the caller is changing them (relative avatar URLs ok).
		if ('avatarUrl' in updates) {
			const c = safeRemoteUrl(updates.avatarUrl);
			if (!c.ok) return json(res, 400, { error: 'invalid avatarUrl' });
			updates.avatarUrl = c.value;
		}
		if ('x402Endpoint' in updates) {
			// Enforce the SAME first-party / allow-listed payment-host gate as POST —
			// safePaymentEndpoint, not bare safeRemoteUrl. Editing a pin must not be a
			// back door to point its Pay button at an arbitrary external drain host
			// (the exact vector the POST allow-list closes). Relative same-origin paths
			// stay first-party; a null/'' clears the endpoint.
			const c = safePaymentEndpoint(updates.x402Endpoint);
			if (!c.ok) {
				return json(res, 422, {
					error: 'endpoint',
					field: 'x402Endpoint',
					message: 'Pay endpoints must be hosted on three.ws.',
				});
			}
			updates.x402Endpoint = c.value;
		}

		// Present-flag each text field so an explicit clear (null) actually writes
		// NULL. COALESCE treats null as "no change", silently dropping a clear and
		// desyncing the dashboard (which optimistically cleared the field) from the
		// row every nearby viewer fetches. lat/lng/heading keep COALESCE since 0 is a
		// valid value there and they are never "cleared".
		const has = (k) => k in updates;
		const [row] = await sql`
			UPDATE irl_pins SET
				caption       = CASE WHEN ${has('caption')}      THEN ${updates.caption      ?? null}::text ELSE caption       END,
				avatar_url    = CASE WHEN ${has('avatarUrl')}    THEN ${updates.avatarUrl    ?? null}::text ELSE avatar_url    END,
				avatar_name   = CASE WHEN ${has('avatarName')}   THEN ${updates.avatarName   ?? null}::text ELSE avatar_name   END,
				x402_endpoint = CASE WHEN ${has('x402Endpoint')} THEN ${updates.x402Endpoint ?? null}::text ELSE x402_endpoint END,
				lat           = COALESCE(${updates.lat     ?? null}, lat),
				lng           = COALESCE(${updates.lng     ?? null}, lng),
				heading       = COALESCE(${updates.heading ?? null}, heading)
			WHERE id = ${id} AND user_id = ${session.id}
			RETURNING id, caption, avatar_url, avatar_name, lat, lng, heading, x402_endpoint
		`;
		if (!row) return json(res, 404, { error: 'not found' });

		// The edit reaches nearby viewers on their next proximity poll — never as a
		// broadcast. A pin's fields only travel to someone physically near it.
		return json(res, 200, { pin: row });
	}

	// ── DELETE — remove own pin ───────────────────────────────────────────────
	if (req.method === 'DELETE') {
		const rl = await limitOrFailOpen('irlPinIp', limits.irlPinIp, clientIp(req));
		if (!rl.success) return rateLimited(res, rl);

		const id          = req.query.id;
		// Header/body-first (H2): the device credential leaves the URL.
		const deviceToken = readDeviceToken(req);
		const purgeAll    = req.query.all === '1' || req.query.all === 'true';

		// ── Bulk purge — every pin from this device token, in one round-trip ──────
		// Strictly scoped to a non-empty device token: the `IS NOT NULL` guard means
		// a NULL/empty token matches nothing, so this can only ever delete the
		// caller's own anonymous pins — never another device's, never a NULL-token
		// row. Auth-only callers manage their permanent pins from the dashboard, so
		// this branch requires a device token.
		if (purgeAll) {
			if (!deviceToken) return json(res, 400, { error: 'deviceToken required for bulk delete' });
			const rows = await sql`
				DELETE FROM irl_pins
				WHERE device_token IS NOT NULL AND device_token = ${deviceToken}
				RETURNING id
			`;
			return json(res, 200, { ok: true, deleted: rows.length });
		}

		if (!id) return json(res, 400, { error: 'id required' });
		// A delete id is a server-minted UUID — reject a malformed one before it
		// reaches the query or a log line.
		if (!isValidPinId(id)) return json(res, 400, { error: 'invalid pin id' });

		const session = await getSessionUser(req).catch(() => null);
		const userId  = session?.id ?? null;

		// Must prove ownership: an authenticated user_id OR the placing device_token.
		// (A bare anonymous caller with neither must not be able to delete anything.)
		if (!userId && !deviceToken) {
			return json(res, 401, { error: 'authentication or device token required' });
		}

		// Match strictly by owner. Each branch is null-guarded so a NULL user_id or a
		// NULL/empty device_token can NEVER match a row — closing the prior
		// `device_token IS NULL AND $userId IS NULL` clause that let an anonymous
		// caller delete every pin whose device_token happened to be NULL.
		const result = await sql`
			DELETE FROM irl_pins
			WHERE id = ${id}
			  AND (expires_at IS NULL OR expires_at > NOW())
			  AND (
			    (${userId}::uuid IS NOT NULL AND user_id = ${userId}::uuid)
			    OR (${deviceToken}::text IS NOT NULL AND device_token = ${deviceToken}::text)
			  )
			RETURNING id, lat, lng
		`;

		if (!result.length) {
			return json(res, 404, { error: 'pin not found or not yours' });
		}
		// A removed pin simply stops appearing in nearby viewers' next proximity
		// poll; there is no realtime remove broadcast to fan out.
		return json(res, 200, { ok: true });
	}

	json(res, 405, { error: 'method not allowed' });
});