@unbrained/pm-web 2026.9.26 → 2026.10.5

package/public/sw.js

@@ -23,6 +23,11 @@ const BUILD_TIMESTAMP = '__BUILD_TIME__';
 const CACHE_NAME = 'pm-web-' + (BUILD_TIMESTAMP !== '__BUILD_TIME__' ? BUILD_TIMESTAMP : Date.now().toString(36));
 const MUTATION_DB = 'pm-web-offline';
 const MUTATION_STORE = 'mutations';
+// The signed-in account the page broadcasts lives in its own store so the
+// mutation records and the session can be written and read independently,
+// exactly like a real browser would keep them.
+const SESSION_STORE = 'session';
+const SESSION_KEY = 'current';
 const STATIC_ASSETS = [
     '/',
     '/styles.css',
@@ -40,6 +45,7 @@ const STATIC_ASSETS = [
     '/src/i18n.js',
     '/src/i18n/de.json',
     '/src/i18n/en.json',
+    '/src/offline-recovery.js',
     '/src/state.js',
     '/src/theme.js',
     '/src/types.js',
@@ -101,18 +107,57 @@ const OFFLINE_HTML = `<!DOCTYPE html>
   </div>
 </body>
 </html>`;
+/**
+ * Extract the workspace (project id) a queued API path targets, or `null` for
+ * account-level mutations.
+ *
+ * Every project-scoped mutation the SPA issues lives under
+ * `/projects/<projectId>/…`, so the first path segment after `/projects/` is
+ * the workspace the record is bound to. The value is stamped at queue time
+ * and replayed verbatim in MUTATIONS_BLOCKED reports, so an operator can see
+ * which workspace a stranded record belongs to without re-deriving it.
+ *
+ * @param path - The queued API path (relative to `/api`).
+ * @returns The project id the path targets, or `null` when the path is account-level.
+ */
+function workspaceFromPath(path) {
+    const match = /^\/projects\/([^/]+)/.exec(path);
+    return match ? match[1] : null;
+}
+/**
+ * Generate a fresh idempotency key for one queued mutation.
+ *
+ * The key is a random UUID-shaped string so a replayed record can be
+ * deduplicated server-side even when the response to the first attempt was
+ * lost after the server committed. It is generated before the first attempt and
+ * persisted with the record so every retry of the same record reuses the
+ * same key and a genuinely different mutation never collides with it.
+ *
+ * @returns A random 128-bit key formatted as a UUID string.
+ */
+function newIdempotencyKey() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
 /** Open (creating on first run) the IndexedDB database backing the offline
  * mutation queue, ensuring the `mutations` object store and its timestamp
  * index exist. Resolves with the ready database handle. */
 function openMutationDB() {
     return new Promise((resolve, reject) => {
-        const request = indexedDB.open(MUTATION_DB, 1);
+        const request = indexedDB.open(MUTATION_DB, 2);
         request.onupgradeneeded = () => {
             const db = request.result;
             if (!db.objectStoreNames.contains(MUTATION_STORE)) {
                 const store = db.createObjectStore(MUTATION_STORE, { keyPath: 'id', autoIncrement: true });
                 store.createIndex('timestamp', 'timestamp', { unique: false });
             }
+            // Version 2 added the session store; an existing version-1 database is
+            // upgraded in place so a returning browser keeps its queued mutations.
+            if (!db.objectStoreNames.contains(SESSION_STORE)) {
+                db.createObjectStore(SESSION_STORE, { keyPath: 'key' });
+            }
         };
         request.onsuccess = () => resolve(request.result);
         request.onerror = () => reject(request.error);
@@ -131,14 +176,72 @@ function transactionDone(tx) {
         tx.onerror = () => reject(tx.error ?? new Error('IDB transaction error'));
     });
 }
+/**
+ * Read the account the page last broadcast as signed in, or `null` when no
+ * session is known.
+ *
+ * The session lives in its own IndexedDB store so it survives service-worker
+ * restarts: a worker can be killed at any time, and a mutation queued after a
+ * restart must still be stamped with the account that is signed in, not with
+ * whatever in-memory state a freshly booted worker happens to have.
+ *
+ * @returns The persisted user id, or `null` when nothing was broadcast or the
+ *   store cannot be read (both mean ownership is unknown, never guessed).
+ */
+async function readSession() {
+    try {
+        const db = await openMutationDB();
+        const tx = db.transaction(SESSION_STORE, 'readonly');
+        const store = tx.objectStore(SESSION_STORE);
+        const session = await new Promise((resolve, reject) => {
+            const request = store.get(SESSION_KEY);
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+        });
+        return session?.userId ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist the account the page reports as signed in (or `null` on logout).
+ *
+ * Called from the AUTH_SESSION message so every later queueMutation stamps its
+ * records with this account. A storage failure leaves the previous value in
+ * place rather than silently clearing ownership.
+ *
+ * @param userId - The signed-in user id, or `null` when nobody is signed in.
+ */
+async function saveSession(userId) {
+    const db = await openMutationDB();
+    const tx = db.transaction(SESSION_STORE, 'readwrite');
+    tx.objectStore(SESSION_STORE).put({ key: SESSION_KEY, userId });
+    await transactionDone(tx);
+}
 /**
  * Queue a mutation for later replay. Returns `true` only when the mutation has
  * been durably persisted to IndexedDB; `false` when persistence failed so the
  * caller can respond with an explicit error instead of claiming it was queued.
+ *
+ * The record is durably bound to the account the page last broadcast as signed
+ * in and to the workspace its path targets, and carries a fresh idempotency
+ * key, so a flush can never replay it under a different signed-in user and a
+ * retried record can never be applied twice server-side. When no session is
+ * known the record is still queued, with `ownerId: null`: ownership is
+ * recorded as unknown and the record is surfaced for explicit recovery
+ * instead of being guessed (and replayed under whoever happens to be signed
+ * in next).
+ *
+ * @param originatingAccount - Identity captured before the first attempt;
+ *   direct queue calls without an attempt read the current stored session.
  */
-async function queueMutation(method, path, body) {
+async function queueMutation(method, path, body, idempotencyKey = newIdempotencyKey(), originatingAccount) {
+    if (/^\/auth(?:\/|\?|$)/i.test(path))
+        return false;
     try {
         const db = await openMutationDB();
+        const ownerId = originatingAccount === undefined ? await readSession() : originatingAccount;
         const tx = db.transaction(MUTATION_STORE, 'readwrite');
         const store = tx.objectStore(MUTATION_STORE);
         const record = {
@@ -146,6 +249,9 @@ async function queueMutation(method, path, body) {
             path,
             body: body !== undefined ? JSON.stringify(body) : null,
             timestamp: Date.now(),
+            ownerId,
+            workspace: workspaceFromPath(path),
+            idempotencyKey,
         };
         store.add(record);
         // Await the transaction commit (not just the request dispatch) so the
@@ -199,22 +305,65 @@ async function clearMutation(id) {
         return false;
     }
 }
-/** Replay queued mutations to the API in order, removing each on success and
- * stopping at the first failure so it can retry later, then post-message the
+/**
+ * Decide whether one queued mutation may be replayed under the current
+ * session, and if not, why.
+ *
+ * The three refusals are deliberately distinct so a surfaced report tells the
+ * user what to do: `no-session` means nobody is signed in (log in and flush
+ * again), `unknown-owner` means the record predates ownership tracking (adopt
+ * it explicitly), and `owner-mismatch` means the record belongs to a different
+ * account and must wait for that account — it is never reassigned silently.
+ *
+ * @param mut - The queued mutation as IndexedDB returns it.
+ * @param currentUserId - The account `/api/auth/me` reports as signed in, or
+ *   `null` when nobody is.
+ * @returns The refusal reason, or `null` when the record may be replayed.
+ */
+function replayBlockReason(mut, currentUserId) {
+    if (/^\/auth(?:\/|\?|$)/i.test(mut.path))
+        return 'auth-route';
+    if (currentUserId === null)
+        return 'no-session';
+    // Legacy records queued before ownership tracking have no ownerId at all.
+    if (mut.ownerId === undefined || mut.ownerId === null)
+        return 'unknown-owner';
+    if (mut.ownerId !== currentUserId)
+        return 'owner-mismatch';
+    return null;
+}
+/** Replay each workspace in FIFO order, removing successes, then post-message the
  * connected clients with how many were replayed or remain. A storage read
  * failure is never treated as a drained queue: the initial read failure
  * aborts the flush, and a final read failure reports a partial result rather
- * than claiming all mutations were replayed. */
-async function flushMutationQueue() {
+ * than claiming all mutations were replayed.
+ *
+ * Identity is authoritative from the server: `/api/auth/me` names the account
+ * that is signed in, and only records that account queued are replayed.
+ * Records owned by a different account, records whose ownership is unknown
+ * (legacy, or queued with no known session), and every record while logged
+ * out are never replayed and never deleted — they are kept and surfaced via
+ * MUTATIONS_BLOCKED so the page can offer explicit recovery. An owned failed
+ * or attention record blocks only later records in its workspace. Account-level
+ * work is a barrier across workspaces: it cannot overtake earlier unresolved
+ * owned work, and unresolved account-level work blocks all later owned work.
+ * Different owners have separate ordering. Replayed records carry their key,
+ * so a retry after an ambiguous (lost) response is applied exactly once
+ * server-side. */
+async function replayQueuedMutations() {
     const read = await getQueuedMutations();
     if (!read.ok) {
         console.warn('Failed to read mutation queue:', read.error);
         return;
     }
     const mutations = read.mutations;
-    if (mutations.length === 0)
+    if (mutations.length === 0) {
+        const clients = await sw.clients.matchAll();
+        clients.forEach((client) => { client.postMessage({ type: 'MUTATIONS_BLOCKED', blocked: [] }); });
         return;
+    }
     let replayCsrfToken;
+    let currentUserId = null;
     try {
         const bootstrap = await fetch('/api/auth/me', {
             method: 'GET',
@@ -226,19 +375,51 @@ async function flushMutationQueue() {
             console.warn('Cannot replay offline mutations without a CSRF bootstrap token');
             return;
         }
+        // The bootstrap response is also the authoritative identity check: the
+        // signed-in account decides which records may replay. A 401 (or any
+        // unparseable body) means nobody is signed in, so every record is kept.
+        const me = await bootstrap.json().catch(() => null);
+        const bootstrapUserId = me?.user?.id;
+        currentUserId = typeof bootstrapUserId === 'string' ? bootstrapUserId : null;
     }
     catch {
         // The network failed during token bootstrap; preserve the entire queue.
         return;
     }
+    const blocked = [];
+    const blockedWorkspaces = new Set();
     let replayed = 0;
     for (const mut of mutations) {
+        // Derive legacy scope from the path rather than assuming it is independent.
+        const workspace = workspaceFromPath(mut.path);
+        const reason = replayBlockReason(mut, currentUserId)
+            ?? (mut.state === 'needs-attention' ? mut.attentionReason ?? 'outcome-unknown' : null)
+            ?? (blockedWorkspaces.has(null) || (workspace === null ? blockedWorkspaces.size > 0 : blockedWorkspaces.has(workspace))
+                ? 'workspace-order' : null);
+        if (reason) {
+            // Never replayed, never deleted: kept for its owner and surfaced so the
+            // page can offer explicit recovery. Skipping does not stop the loop, so
+            // blocked records cannot wedge unrelated owned records behind them.
+            blocked.push({
+                id: mut.id,
+                method: mut.method,
+                path: mut.path,
+                ownerId: mut.ownerId ?? null,
+                workspace,
+                reason,
+            });
+            if (mut.ownerId === currentUserId && currentUserId !== null)
+                blockedWorkspaces.add(workspace);
+            continue;
+        }
         try {
             const opts = {
                 method: mut.method,
                 headers: {
                     'Content-Type': 'application/json',
                     'X-CSRF-Token': replayCsrfToken,
+                    'X-PM-Expected-Account': mut.ownerId,
+                    ...(mut.idempotencyKey ? { 'Idempotency-Key': mut.idempotencyKey } : {}),
                 },
                 credentials: 'include',
             };
@@ -256,8 +437,30 @@ async function flushMutationQueue() {
             }
             else {
                 console.warn('Offline mutation failed:', mut.method, mut.path, res.status);
-                // Stop processing on first failure — try again later
-                break;
+                const body = await res.json().catch(() => null);
+                let attention;
+                if (body?.code === 'PM_IDEMPOTENCY_OUTCOME_UNKNOWN')
+                    attention = 'outcome-unknown';
+                if (res.status >= 500) {
+                    mut.serverFailures = (mut.serverFailures ?? 0) + 1;
+                    if (mut.serverFailures >= 3)
+                        attention = 'repeated-5xx';
+                }
+                else if (!attention && mut.serverFailures) {
+                    mut.serverFailures = 0;
+                }
+                if (attention) {
+                    mut.state = 'needs-attention';
+                    mut.attentionReason = attention;
+                    blocked.push({ id: mut.id, method: mut.method, path: mut.path,
+                        ownerId: mut.ownerId ?? null, workspace, reason: attention });
+                }
+                // Persist before allowing independent workspace replay; failure stops the flush.
+                const db = await openMutationDB();
+                const tx = db.transaction(MUTATION_STORE, 'readwrite');
+                tx.objectStore(MUTATION_STORE).put(mut);
+                await transactionDone(tx);
+                blockedWorkspaces.add(workspace);
             }
         }
         catch {
@@ -268,6 +471,10 @@ async function flushMutationQueue() {
     // Notify clients about replayed mutations
     const remainingRead = await getQueuedMutations();
     const clients = await sw.clients.matchAll();
+    // Empty reports remove a previously rendered or dismissed recovery set.
+    clients.forEach((client) => {
+        client.postMessage({ type: 'MUTATIONS_BLOCKED', blocked });
+    });
     if (!remainingRead.ok) {
         // Could not re-read the queue — do NOT claim all mutations were replayed.
         // Report a partial result with the known replayed count so unreplayed
@@ -294,12 +501,87 @@ async function flushMutationQueue() {
         clients.forEach((client) => {
             client.postMessage({
                 type: 'MUTATIONS_PARTIAL',
-                replayed: mutations.length - remaining.length,
+                replayed,
                 remaining: remaining.length,
             });
         });
     }
 }
+/** Pending queue operations share one chain across messages, sync and online events. */
+let queueOperation = Promise.resolve();
+/** Serialize queue adoption and replay, recovering the chain after an operation fails. */
+function runQueueOperation(operation) {
+    const pending = queueOperation.then(async () => {
+        await sessionUpdate.catch(() => { });
+        await operation();
+    });
+    queueOperation = pending.catch(() => { });
+    return pending;
+}
+/** Flush under the same single-flight chain used for explicit recovery. */
+function flushMutationQueue() {
+    return runQueueOperation(replayQueuedMutations);
+}
+/**
+ * Explicitly rebind unknown-owner records to the signed-in account.
+ *
+ * The page offers this after a flush surfaces records with the `unknown-owner`
+ * reason: the signed-in user states that this queued work is theirs. Only
+ * records whose ownership is unknown are adoptable — a record already owned by
+ * another account is never reassigned, because its true owner may still
+ * return to replay it.
+ *
+ * @param ids - Only these record ids are adopted, or all unknown records when absent.
+ * @param ownerId - The approving page's account, verified against the server session.
+ * @returns Whether the current server session approved adoption.
+ */
+function adoptUnknownOwnerRecords(ids, ownerId) {
+    return updateRecoveryRecords(ownerId, (store, mut) => {
+        if ((mut.ownerId === undefined || mut.ownerId === null)
+            && (ids === undefined || ids.includes(mut.id))
+            && !/^\/auth(?:\/|\?|$)/i.test(mut.path)) {
+            store.put({ ...mut, ownerId, idempotencyKey: mut.idempotencyKey || newIdempotencyKey() });
+        }
+    });
+}
+/** Adopt records through the common queue-operation chain used by flushes. */
+function rebindUnknownOwnerRecords(ids, ownerId) {
+    return runQueueOperation(async () => { await adoptUnknownOwnerRecords(ids, ownerId); });
+}
+/** Apply owner-approved retry with a fresh key or discard atomically; never change another owner's work. */
+function recoverAttentionRecord(id, ownerId, action) {
+    return updateRecoveryRecords(ownerId, (store, mut) => {
+        if (mut.id !== id || mut.ownerId !== ownerId || mut.state !== 'needs-attention')
+            return;
+        if (action === 'discard')
+            store.delete(id);
+        else
+            store.put({ ...mut, state: 'queued', attentionReason: undefined, serverFailures: 0, idempotencyKey: newIdempotencyKey() });
+    });
+}
+/** Verify the approving account, then read and update recovery records in one live IndexedDB transaction. */
+async function updateRecoveryRecords(ownerId, update) {
+    const approval = await fetch('/api/auth/me', {
+        credentials: 'include', cache: 'no-store', headers: { 'X-PM-Expected-Account': ownerId },
+    });
+    if (!approval.ok)
+        return false;
+    const me = await approval.json().catch(() => null);
+    if (me?.user?.id !== ownerId)
+        return false;
+    const db = await openMutationDB();
+    const tx = db.transaction(MUTATION_STORE, 'readwrite');
+    const done = transactionDone(tx);
+    const store = tx.objectStore(MUTATION_STORE);
+    const request = store.getAll();
+    request.onsuccess = () => {
+        for (const mut of request.result) {
+            update(store, mut);
+        }
+    };
+    await done;
+    return true;
+}
 // ── Install ──
 sw.addEventListener('install', (event) => {
     event.waitUntil(caches.open(CACHE_NAME).then((cache) => Promise.all(STATIC_ASSETS.map((asset) => cache.add(asset).catch(() => null)))));
@@ -315,22 +597,43 @@ sw.addEventListener('fetch', (event) => {
     const url = new URL(event.request.url);
     // API calls: try network, queue mutations if offline
     if (url.pathname.startsWith('/api/') || url.pathname.startsWith('/healthz')) {
+        // Session responses must reach the browser with their live cookie changes.
+        // Remove caller keys too; failed auth requests are never queued.
+        if (/^\/api\/auth(?:\/|$)/i.test(url.pathname)) {
+            const headers = new Headers(event.request.headers);
+            headers.delete('Idempotency-Key');
+            headers.delete('X-PM-Expected-Account');
+            event.respondWith(fetch(new Request(event.request, { headers })));
+            return;
+        }
         // Queue write operations (POST, PUT, PATCH, DELETE) when offline
         if (event.request.method !== 'GET' && event.request.method !== 'HEAD') {
-            event.respondWith(fetch(event.request).catch(async () => {
-                // Network failed — queue the mutation for later.
-                let body = undefined;
-                try {
-                    body = await event.request.clone().json();
-                }
-                catch { /* no body */ }
-                const queued = await queueMutation(event.request.method, url.pathname.replace('/api', ''), body);
-                if (queued) {
-                    return new Response(JSON.stringify({ queued: true, message: 'Request queued for when you are back online' }), { status: 202, headers: { 'Content-Type': 'application/json' } });
-                }
-                // Persistence failed — do not claim the mutation was queued.
-                return new Response(JSON.stringify({ error: 'Offline and unable to queue mutation', queued: false }), { status: 503, headers: { 'Content-Type': 'application/json' } });
-            }));
+            const headers = new Headers(event.request.headers);
+            if (!headers.has('Idempotency-Key'))
+                headers.set('Idempotency-Key', newIdempotencyKey());
+            event.respondWith((async () => {
+                await sessionUpdate.catch(() => { });
+                // Capture identity before sending, never after a lost response.
+                const ownerId = headers.get('X-PM-Expected-Account') ?? await readSession();
+                if (ownerId !== null)
+                    headers.set('X-PM-Expected-Account', ownerId);
+                const request = new Request(event.request, { headers });
+                const queuedRequest = request.clone();
+                return fetch(request).catch(async () => {
+                    // Network failed — queue the mutation for later.
+                    let body = undefined;
+                    try {
+                        body = await queuedRequest.json();
+                    }
+                    catch { /* no body */ }
+                    const queued = await queueMutation(event.request.method, url.pathname.replace('/api', '') + url.search, body, headers.get('Idempotency-Key') ?? newIdempotencyKey(), ownerId);
+                    if (queued) {
+                        return new Response(JSON.stringify({ queued: true, message: 'Request queued for when you are back online' }), { status: 202, headers: { 'Content-Type': 'application/json' } });
+                    }
+                    // Persistence failed — do not claim the mutation was queued.
+                    return new Response(JSON.stringify({ error: 'Offline and unable to queue mutation', queued: false }), { status: 503, headers: { 'Content-Type': 'application/json' } });
+                });
+            })());
             return;
         }
         // GET/HEAD API calls: network-only, return offline JSON error
@@ -418,6 +721,8 @@ sw.addEventListener('fetch', (event) => {
         }
     })());
 });
+// Serialise session writes and recovery so adoption cannot read an older login.
+let sessionUpdate = Promise.resolve();
 // ── Messages ──
 sw.addEventListener('message', (event) => {
     const data = event.data;
@@ -429,7 +734,48 @@ sw.addEventListener('message', (event) => {
         caches.open(CACHE_NAME).then((cache) => cache.addAll(urls).catch(() => { }));
     }
     if (data && data.type === 'FLUSH_QUEUE') {
-        void flushMutationQueue();
+        event.waitUntil(sessionUpdate.then(() => flushMutationQueue()).catch(() => {
+            console.warn('Failed to flush offline mutations');
+        }));
+    }
+    if (data && data.type === 'AUTH_SESSION') {
+        // The page names the signed-in account so queued mutations are bound to
+        // it. `null` (logout) is a valid broadcast: it means ownership of later
+        // queues is unknown, never the next signed-in account.
+        const userId = typeof data.userId === 'string' ? data.userId : null;
+        sessionUpdate = sessionUpdate.catch(() => { }).then(() => saveSession(userId));
+        event.waitUntil(sessionUpdate.catch(() => {
+            console.warn('Failed to persist offline session');
+        }));
+    }
+    if (data && data.type === 'REBIND_RECORDS') {
+        // Explicit recovery: adopt unknown-owner records for the signed-in
+        // account. The ids are optional; without them every unknown-owner record
+        // is adopted.
+        const ids = Array.isArray(data.ids)
+            ? data.ids.filter((id) => typeof id === 'number')
+            : undefined;
+        const ownerId = data.ownerId;
+        if (typeof ownerId !== 'string' || ownerId.length === 0)
+            return;
+        event.waitUntil(runQueueOperation(async () => {
+            if (await adoptUnknownOwnerRecords(ids, ownerId))
+                await replayQueuedMutations();
+        }).catch(() => {
+            console.warn('Failed to adopt offline mutations');
+        }));
+    }
+    if (data && data.type === 'RECOVER_RECORD') {
+        const { id, ownerId, action } = data;
+        if (typeof id !== 'number' || !Number.isSafeInteger(id) || typeof ownerId !== 'string' || ownerId.length === 0
+            || (action !== 'retry-new' && action !== 'discard'))
+            return;
+        event.waitUntil(runQueueOperation(async () => {
+            if (await recoverAttentionRecord(id, ownerId, action))
+                await replayQueuedMutations();
+        }).catch(() => {
+            console.warn('Failed to recover offline mutation');
+        }));
     }
 });
 // ── Background sync ──
@@ -459,5 +805,12 @@ sw.addEventListener('online', () => {
 // rather than keeping both.
 const __testGlobals = globalThis;
 if (__testGlobals.__swTestHarness) {
-    __testGlobals.__swInternals = { getQueuedMutations, flushMutationQueue, queueMutation, clearMutation };
+    __testGlobals.__swInternals = {
+        getQueuedMutations,
+        flushMutationQueue,
+        queueMutation,
+        clearMutation,
+        saveSession,
+        rebindRecords: rebindUnknownOwnerRecords,
+    };
 }

package/sql/schema.sql

@@ -101,6 +101,31 @@ CREATE TABLE IF NOT EXISTS pm_github_item_links (
 );
 CREATE INDEX IF NOT EXISTS pm_github_item_links_project ON pm_github_item_links(project_id);
 
+-- Idempotency keys: one row per (account, key) recording the outcome of a
+-- mutating request that carried that key, so a retry after an ambiguous (lost)
+-- response replays the stored outcome instead of re-executing. A NULL
+-- status_code marks an execution still in flight (or crashed before
+-- responding); see src/idempotency.ts for the unknown-outcome policy.
+CREATE TABLE IF NOT EXISTS pm_idempotency_keys (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES pm_users(id) ON DELETE CASCADE,
+  idempotency_key TEXT NOT NULL,
+  method TEXT NOT NULL,
+  path TEXT NOT NULL,
+  request_fingerprint TEXT NOT NULL,
+  outcome_state TEXT NOT NULL DEFAULT 'pending' CHECK (outcome_state IN ('pending', 'completed', 'outcome_unknown')),
+  status_code INTEGER,
+  response_body TEXT,
+  response_content_type TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  UNIQUE (user_id, idempotency_key)
+);
+
+CREATE INDEX IF NOT EXISTS idx_pm_idempotency_created_at ON pm_idempotency_keys (created_at) WHERE status_code IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_pm_idempotency_settled_at ON pm_idempotency_keys (updated_at) WHERE status_code IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_pm_idempotency_pending_at ON pm_idempotency_keys (created_at) WHERE status_code IS NULL;
+
 -- Bootstrap admin promotion is now applied at runtime via PM_WEB_BOOTSTRAP_ADMIN_EMAIL (see src/db.ts).
 
 -- Update trigger