@artymclabin/qa-review 0.3.7

package/dist/client/types.d.ts

@@ -0,0 +1,87 @@
+export type QAReviewDevice = "💻" | "📱" | "💻📱";
+export interface QAReviewItem {
+    /** Stable id, used as the verdict-ledger key. */
+    id: string;
+    /** Short label shown on the review card. */
+    title: string;
+    /** Optional multi-line detail ("\n" renders as paragraph breaks). */
+    sub?: string;
+    /**
+     * CSS selector for the element to spotlight on the real page (e.g.
+     * `[data-qa="hero"]`). OMIT for an off-DOM "task item": it renders as a
+     * centered card (no spotlight) - for visit-this-page checks and decisions
+     * that have no single on-page anchor.
+     */
+    selector?: string;
+    /** Optional action link (task items): a button opening the URL in a new tab. */
+    action?: {
+        /** Button label. Default "Open". */
+        label?: string;
+        href: string;
+    };
+    /** Which viewport(s) this item is about (legacy display emoji). */
+    device?: QAReviewDevice;
+    /**
+     * Devices whose sign-off is REQUIRED for this item to count as approved
+     * (device-split approvals). Default: ["pc"]. The item stays pending until
+     * every listed device is approved; rejection is whole-item.
+     */
+    devices?: Array<"pc" | "mobile">;
+    /**
+     * Words/phrases INSIDE the anchored element to sub-highlight (secondary
+     * mark on top of the spotlight). Replaces "where to look" prose - keep the
+     * question terse and let the highlight point.
+     */
+    highlightWords?: string[];
+    /** Optional grouping label. */
+    section?: string;
+    /**
+     * When the reviewed element has design VARIATIONS to choose from, the overlay
+     * renders 1..count buttons that live-swap the element on the page via
+     * `onSelect` (dynamic preview) and records the chosen variant in the result.
+     */
+    variations?: {
+        count: number;
+        /** Current live variant (1-based) for button highlighting. */
+        current: number;
+        /** Apply a variant on the real page (updates the page's own state). */
+        onSelect: (variant: number) => void;
+    };
+}
+/** Off-DOM "task item" = no selector: centered card, no spotlight. */
+export declare function isTaskItem(item: Pick<QAReviewItem, "selector">): boolean;
+export type QAVerdict = "approve" | "reject";
+export interface QAResult {
+    id: string;
+    title: string;
+    verdict: QAVerdict;
+    note?: string;
+    /** Chosen variant (1-based) when the item had variations. */
+    variant?: number;
+}
+/** Session-snapshot payload POSTed to the submit endpoint. */
+export interface QASubmission {
+    /** What is being reviewed (e.g. "example-site:/pricing"). */
+    target: string;
+    /** Free-text reviewer name/label (server-side auth may override). */
+    reviewer?: string;
+    approved: number;
+    rejected: number;
+    total: number;
+    results: Array<QAResult | {
+        id: string;
+        title: string;
+        verdict: "skipped";
+    }>;
+}
+/** Theme hooks for the overlay chrome. Any CSS color value (vars included). */
+export interface QATheme {
+    /** Brand accent (spotlight ring, approve button, headings). */
+    accent: string;
+    /** Text color used ON accent-filled surfaces (usually the darkest bg). */
+    accentContrast: string;
+    /** Panel/card background. */
+    panelBg: string;
+    /** Input (textarea) background. */
+    inputBg: string;
+}

package/dist/client/types.js

@@ -0,0 +1,7 @@
+// Shared types for the on-page gamified QA review overlay.
+// A page supplies an array of QAReviewItem; <QAReviewOverlay> turns them into
+// an onboarding-style spotlight walkthrough with approve/reject stepping.
+/** Off-DOM "task item" = no selector: centered card, no spotlight. */
+export function isTaskItem(item) {
+    return !item.selector;
+}

package/dist/server/handlers.d.ts

@@ -0,0 +1,31 @@
+import { type QAReviewStorage } from "./storage.js";
+/** Result of a successful authorization. */
+export interface QAAuthUser {
+    /** Persisted as the session reviewer (overrides any client-sent value). */
+    reviewer?: string;
+    /** Returned by the access probe for UI display. */
+    displayName?: string;
+}
+export interface QAReviewHandlerOptions {
+    /**
+     * Install scope - one database can serve many sites/apps; every row is
+     * scoped to this value (e.g. "example-site").
+     */
+    site: string;
+    /**
+     * Auth gate, BYO: return a user to allow, null/undefined to reject (401).
+     * Runs on EVERY endpoint. For an unauthenticated local tool use
+     * `async () => ({})`.
+     */
+    authorize: (req: Request) => Promise<QAAuthUser | null | undefined>;
+    /** Storage adapter. Default: Postgres via QA_REVIEW_DATABASE_URL. */
+    storage?: QAReviewStorage;
+}
+export interface QAReviewHandlers {
+    stateGET: (req: Request) => Promise<Response>;
+    statePOST: (req: Request) => Promise<Response>;
+    submitPOST: (req: Request) => Promise<Response>;
+    sessionsGET: (req: Request) => Promise<Response>;
+    accessGET: (req: Request) => Promise<Response>;
+}
+export declare function createQAReviewHandlers(opts: QAReviewHandlerOptions): QAReviewHandlers;

package/dist/server/handlers.js

@@ -0,0 +1,186 @@
+// Framework-agnostic handler factory for the QA review endpoints. Every
+// handler is a plain `(req: Request) => Promise<Response>` (Web standard), so
+// they mount 1:1 in Next.js route handlers, Remix, Hono, or any Node server
+// that speaks fetch primitives.
+//
+// Endpoint semantics (the durable verdict ledger):
+//   state GET  ?target=...                       -> { ok, verdicts: {itemId: {verdict,note,variant}} }
+//   state POST { target, itemId, verdict, ... }  -> merge-upsert one item
+//   state POST { target, itemId, verdict: null } -> invalidate that ONE item
+//        (the only way to make an approved item reappear). With a
+//        `revisitReason` the row is KEPT (prior verdict + note + fingerprint
+//        preserved, reason recorded) so the card can tell the reviewer WHY it
+//        is back; without a reason the row is deleted (undo).
+//   🚨 Deliberately NO reset-all operation: the ledger is never wiped in bulk.
+//   submit POST { target, results, ... }         -> insert one session snapshot
+//   sessions GET ?target=&limit=                 -> list recent session summaries
+//   access GET                                   -> { ok, displayName? } (auth probe)
+import { createPostgresStorage, } from "./storage.js";
+import { codenameFor } from "../shared/codename.js";
+/** Hard sanity caps so a bad client cannot bloat the tables. */
+const MAX_KEY = 200;
+const MAX_TITLE = 500;
+const MAX_TEXT = 4000;
+const MAX_RESULTS = 200;
+const json = (body, status = 200) => new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+});
+export function createQAReviewHandlers(opts) {
+    const storage = opts.storage ?? createPostgresStorage();
+    const site = opts.site;
+    const guard = async (req) => {
+        try {
+            return (await opts.authorize(req)) ?? null;
+        }
+        catch {
+            return null; // fail closed
+        }
+    };
+    return {
+        async stateGET(req) {
+            const user = await guard(req);
+            if (!user)
+                return json({ ok: false }, 401);
+            const target = new URL(req.url).searchParams.get("target") || "";
+            if (!target)
+                return json({ ok: false, error: "Missing target." }, 400);
+            try {
+                const verdicts = await storage.getState(site, target);
+                // Attach the deterministic codename per item so agents/humans can
+                // reference items by name ("I'm QA-ing red-apple").
+                for (const [itemId, v] of Object.entries(verdicts)) {
+                    v.codename = codenameFor(target, itemId);
+                }
+                return json({ ok: true, verdicts });
+            }
+            catch (e) {
+                console.error("[qa-review/state] read failed:", e);
+                return json({ ok: false, error: "Database read failed." }, 500);
+            }
+        },
+        async statePOST(req) {
+            const user = await guard(req);
+            if (!user)
+                return json({ ok: false }, 401);
+            let body;
+            try {
+                body = await req.json();
+            }
+            catch {
+                return json({ ok: false, error: "Invalid JSON." }, 400);
+            }
+            const target = typeof body.target === "string" ? body.target.slice(0, MAX_KEY) : "";
+            const itemId = typeof body.itemId === "string" ? body.itemId.slice(0, MAX_KEY) : "";
+            if (!target || !itemId) {
+                return json({ ok: false, error: "Missing target or itemId." }, 400);
+            }
+            try {
+                // verdict === null -> invalidate this single item. A revisitReason
+                // keeps the row with re-queue context (0.3.3); no reason = plain
+                // delete (undo semantics).
+                if (body.verdict === null) {
+                    const reason = typeof body.revisitReason === "string" ? body.revisitReason.trim().slice(0, 500) : "";
+                    if (reason) {
+                        await storage.invalidateState(site, target, itemId, reason);
+                        return json({ ok: true, invalidated: itemId, revisitReason: reason });
+                    }
+                    await storage.deleteState(site, target, itemId);
+                    return json({ ok: true, deleted: itemId });
+                }
+                const patch = {};
+                if (body.verdict !== undefined) {
+                    if (body.verdict !== "approve" && body.verdict !== "reject") {
+                        return json({ ok: false, error: "Invalid verdict." }, 400);
+                    }
+                    patch.verdict = body.verdict;
+                }
+                if (body.note !== undefined)
+                    patch.note = String(body.note).slice(0, MAX_TEXT) || null;
+                if (body.variant !== undefined)
+                    patch.variant = typeof body.variant === "number" ? body.variant : null;
+                if (body.fp !== undefined)
+                    patch.fp = String(body.fp).slice(0, 128) || null;
+                if (body.approvedDevices !== undefined) {
+                    patch.approvedDevices = Array.isArray(body.approvedDevices)
+                        ? body.approvedDevices.filter((d) => d === "pc" || d === "mobile")
+                        : null;
+                }
+                await storage.upsertState(site, target, itemId, patch);
+                return json({ ok: true });
+            }
+            catch (e) {
+                console.error("[qa-review/state] write failed:", e);
+                return json({ ok: false, error: "Database write failed." }, 500);
+            }
+        },
+        async submitPOST(req) {
+            const user = await guard(req);
+            if (!user)
+                return json({ ok: false, error: "Not authorized." }, 401);
+            let body;
+            try {
+                body = await req.json();
+            }
+            catch {
+                return json({ ok: false, error: "Invalid JSON body." }, 400);
+            }
+            if (!body || typeof body.target !== "string" || !body.target || !Array.isArray(body.results)) {
+                return json({ ok: false, error: "Missing target or results." }, 400);
+            }
+            if (body.results.length > MAX_RESULTS) {
+                return json({ ok: false, error: "Too many results." }, 400);
+            }
+            // Normalize/validate per-item rows; never trust client-side shapes blindly.
+            const results = body.results.map((raw) => {
+                const r = (raw ?? {});
+                return {
+                    id: String(r.id ?? "").slice(0, MAX_KEY),
+                    title: String(r.title ?? "").slice(0, MAX_TITLE),
+                    verdict: r.verdict === "approve" || r.verdict === "reject" ? r.verdict : "skipped",
+                    note: typeof r.note === "string" && r.note ? r.note.slice(0, MAX_TEXT) : undefined,
+                    variant: typeof r.variant === "number" ? r.variant : undefined,
+                };
+            });
+            try {
+                const { id } = await storage.insertSession(site, {
+                    target: body.target.slice(0, MAX_KEY),
+                    // Reviewer from the VERIFIED auth result wins over the client payload.
+                    reviewer: user.reviewer ?? (typeof body.reviewer === "string" ? body.reviewer.slice(0, MAX_TITLE) : null),
+                    approved: results.filter((r) => r.verdict === "approve").length,
+                    rejected: results.filter((r) => r.verdict === "reject").length,
+                    total: results.length,
+                    results,
+                });
+                return json({ ok: true, reviewId: id });
+            }
+            catch (e) {
+                console.error("[qa-review/submit] DB write failed:", e);
+                return json({ ok: false, error: "Database write failed - use Copy JSON as fallback." }, 500);
+            }
+        },
+        async sessionsGET(req) {
+            const user = await guard(req);
+            if (!user)
+                return json({ ok: false, sessions: [] }, 401);
+            const url = new URL(req.url);
+            const target = url.searchParams.get("target") || undefined;
+            const limitRaw = Number(url.searchParams.get("limit"));
+            const limit = Number.isFinite(limitRaw) && limitRaw > 0 ? Math.min(limitRaw, 500) : 100;
+            try {
+                const sessions = await storage.listSessions(site, target, limit);
+                return json({ ok: true, sessions });
+            }
+            catch (e) {
+                console.error("[qa-review/sessions] read failed:", e);
+                return json({ ok: false, error: "Read failed.", sessions: [] }, 500);
+            }
+        },
+        async accessGET(req) {
+            const user = await guard(req);
+            if (!user)
+                return json({ ok: false }, 401);
+            return json({ ok: true, displayName: user.displayName });
+        },
+    };
+}

package/dist/server/index.d.ts

@@ -0,0 +1,3 @@
+export { createQAReviewHandlers, type QAReviewHandlers, type QAReviewHandlerOptions, type QAAuthUser, } from "./handlers.js";
+export { createPostgresStorage, type PostgresStorageOptions, type QAReviewStorage, type StoredVerdict, type StoredVerdictMap, type VerdictPatch, type NewSession, type SessionResultRow, type SessionSummary, } from "./storage.js";
+export { codenameFor, findByCodename, formatQARef, type CodenameEntry, } from "../shared/codename.js";

package/dist/server/index.js

@@ -0,0 +1,3 @@
+export { createQAReviewHandlers, } from "./handlers.js";
+export { createPostgresStorage, } from "./storage.js";
+export { codenameFor, findByCodename, formatQARef, } from "../shared/codename.js";

package/dist/server/storage.d.ts

@@ -0,0 +1,78 @@
+export interface StoredVerdict {
+    verdict?: string;
+    note?: string;
+    variant?: number;
+    /** Content fingerprint at verdict time (NOT-ALTERED poka-yoke). */
+    fp?: string;
+    /** Per-device approvals ("pc"/"mobile") for device-split items. */
+    approvedDevices?: string[];
+    /** Deterministic two-word codename (computed, not stored). */
+    codename?: string;
+    /** Why the item was re-queued (set by the invalidation call). */
+    revisitReason?: string;
+    /** Verdict that was in effect before the invalidation. */
+    prevVerdict?: string;
+}
+/** item id -> stored verdict. */
+export type StoredVerdictMap = Record<string, StoredVerdict>;
+export interface VerdictPatch {
+    verdict?: string;
+    note?: string | null;
+    variant?: number | null;
+    fp?: string | null;
+    approvedDevices?: string[] | null;
+}
+export interface SessionResultRow {
+    id: string;
+    title: string;
+    verdict: "approve" | "reject" | "skipped";
+    note?: string;
+    variant?: number;
+}
+export interface NewSession {
+    target: string;
+    reviewer: string | null;
+    approved: number;
+    rejected: number;
+    total: number;
+    results: SessionResultRow[];
+}
+export interface SessionSummary {
+    id: string;
+    site: string;
+    target: string;
+    reviewer: string | null;
+    approved: number;
+    rejected: number;
+    total: number;
+    createdAt: string;
+}
+/** Pluggable storage contract (the Postgres adapter is the shipped default). */
+export interface QAReviewStorage {
+    getState(site: string, target: string): Promise<StoredVerdictMap>;
+    upsertState(site: string, target: string, itemId: string, patch: VerdictPatch): Promise<void>;
+    deleteState(site: string, target: string, itemId: string): Promise<void>;
+    /**
+     * Invalidate WITH context (0.3.3): clear the verdict + device approvals so
+     * the item re-queues, but KEEP the row - prior verdict moves to
+     * prev_verdict, the note and fingerprint stay, and revisit_reason records
+     * why it is back. (Plain deleteState remains the no-context undo.)
+     */
+    invalidateState(site: string, target: string, itemId: string, revisitReason: string): Promise<void>;
+    insertSession(site: string, session: NewSession): Promise<{
+        id: string;
+    }>;
+    listSessions(site: string, target?: string, limit?: number): Promise<SessionSummary[]>;
+}
+export interface PostgresStorageOptions {
+    /** Postgres connection string. Default: process.env.QA_REVIEW_DATABASE_URL. */
+    databaseUrl?: string;
+    /** Max pool size (serverless-friendly default: 1). */
+    max?: number;
+}
+/**
+ * Postgres-backed storage. Lazily connects and provisions its schema exactly
+ * once per process (transaction + advisory lock, so parallel cold starts on
+ * serverless cannot race each other).
+ */
+export declare function createPostgresStorage(opts?: PostgresStorageOptions): QAReviewStorage;

package/dist/server/storage.js

@@ -0,0 +1,245 @@
+// Storage layer for the QA review server handlers.
+//
+// The Postgres adapter SELF-PROVISIONS its own tables on first use via a tiny
+// versioned migration runner (drizzle-style `__migrations` bookkeeping table,
+// all names prefixed `qa_review_`), so consumers never hand-write migrations.
+// A `site` scope column lets ONE database serve many installs.
+import postgres from "postgres";
+/* ------------------------- self-provisioning DDL --------------------------- */
+// Append-only list; NEVER edit an applied entry - add a new one. Applied ids
+// are tracked in qa_review_migrations (advisory-locked, concurrency-safe).
+const MIGRATIONS = [
+    {
+        id: 1,
+        ddl: `
+      CREATE TABLE IF NOT EXISTS qa_review_state (
+        site text NOT NULL,
+        target text NOT NULL,
+        item_id text NOT NULL,
+        verdict text,
+        note text,
+        variant integer,
+        updated_at timestamptz NOT NULL DEFAULT now(),
+        PRIMARY KEY (site, target, item_id)
+      );
+      CREATE TABLE IF NOT EXISTS qa_review_sessions (
+        id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+        site text NOT NULL,
+        target text NOT NULL,
+        reviewer text,
+        approved integer NOT NULL DEFAULT 0,
+        rejected integer NOT NULL DEFAULT 0,
+        total integer NOT NULL DEFAULT 0,
+        results jsonb NOT NULL,
+        created_at timestamptz NOT NULL DEFAULT now()
+      );
+      CREATE INDEX IF NOT EXISTS qa_review_sessions_site_target_idx
+        ON qa_review_sessions (site, target);
+      CREATE INDEX IF NOT EXISTS qa_review_sessions_created_idx
+        ON qa_review_sessions (created_at);
+    `,
+    },
+    {
+        id: 2,
+        // 0.3.0: NOT-ALTERED fingerprints + device-split approvals.
+        ddl: `
+      ALTER TABLE qa_review_state ADD COLUMN IF NOT EXISTS fp text;
+      ALTER TABLE qa_review_state ADD COLUMN IF NOT EXISTS approved_pc boolean;
+      ALTER TABLE qa_review_state ADD COLUMN IF NOT EXISTS approved_mobile boolean;
+    `,
+    },
+    {
+        id: 3,
+        // 0.3.3: re-queue context (revisit reason + prior verdict).
+        ddl: `
+      ALTER TABLE qa_review_state ADD COLUMN IF NOT EXISTS revisit_reason text;
+      ALTER TABLE qa_review_state ADD COLUMN IF NOT EXISTS prev_verdict text;
+    `,
+    },
+];
+/** Arbitrary but stable advisory-lock key for provisioning. */
+const PROVISION_LOCK_KEY = 727_001_337;
+function sslSetting(url) {
+    if (process.env.NODE_ENV === "production")
+        return "require";
+    try {
+        const host = new URL(url).hostname;
+        const isLocal = host === "localhost" || host === "127.0.0.1" || host === "::1";
+        return isLocal ? undefined : "require";
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Postgres-backed storage. Lazily connects and provisions its schema exactly
+ * once per process (transaction + advisory lock, so parallel cold starts on
+ * serverless cannot race each other).
+ */
+export function createPostgresStorage(opts = {}) {
+    let sql = null;
+    let provisioned = null;
+    function connect() {
+        if (sql)
+            return sql;
+        const url = opts.databaseUrl ?? process.env.QA_REVIEW_DATABASE_URL;
+        if (!url) {
+            throw new Error("qa-review: no database URL. Pass databaseUrl or set QA_REVIEW_DATABASE_URL.");
+        }
+        sql = postgres(url, {
+            max: opts.max ?? 1,
+            prepare: false,
+            connect_timeout: 10,
+            ssl: sslSetting(url),
+        });
+        return sql;
+    }
+    function ensureProvisioned() {
+        if (provisioned)
+            return provisioned;
+        provisioned = (async () => {
+            const db = connect();
+            await db.begin(async (tx) => {
+                await tx `SELECT pg_advisory_xact_lock(${PROVISION_LOCK_KEY})`;
+                await tx `
+          CREATE TABLE IF NOT EXISTS qa_review_migrations (
+            id integer PRIMARY KEY,
+            applied_at timestamptz NOT NULL DEFAULT now()
+          )
+        `;
+                const applied = await tx `SELECT id FROM qa_review_migrations`;
+                const done = new Set(applied.map((r) => r.id));
+                for (const m of MIGRATIONS) {
+                    if (done.has(m.id))
+                        continue;
+                    await tx.unsafe(m.ddl);
+                    await tx `INSERT INTO qa_review_migrations (id) VALUES (${m.id})`;
+                }
+            });
+        })();
+        // Allow a retry on transient failure instead of caching the rejection.
+        provisioned.catch(() => {
+            provisioned = null;
+        });
+        return provisioned;
+    }
+    async function ready() {
+        await ensureProvisioned();
+        return connect();
+    }
+    return {
+        async getState(site, target) {
+            const db = await ready();
+            const rows = await db `
+        SELECT item_id, verdict, note, variant, fp, approved_pc, approved_mobile, revisit_reason, prev_verdict
+        FROM qa_review_state
+        WHERE site = ${site} AND target = ${target}
+      `;
+            const map = {};
+            for (const r of rows) {
+                const devices = [
+                    ...(r.approved_pc ? ["pc"] : []),
+                    ...(r.approved_mobile ? ["mobile"] : []),
+                ];
+                map[r.item_id] = {
+                    verdict: r.verdict ?? undefined,
+                    note: r.note ?? undefined,
+                    variant: r.variant ?? undefined,
+                    fp: r.fp ?? undefined,
+                    approvedDevices: devices.length ? devices : undefined,
+                    revisitReason: r.revisit_reason ?? undefined,
+                    prevVerdict: r.prev_verdict ?? undefined,
+                };
+            }
+            return map;
+        },
+        async upsertState(site, target, itemId, patch) {
+            const db = await ready();
+            // Merge-upsert: only the provided fields overwrite; absent fields keep
+            // their stored value (COALESCE on excluded values via conditional set).
+            const verdict = patch.verdict === undefined ? null : patch.verdict;
+            const hasVerdict = patch.verdict !== undefined;
+            const note = patch.note === undefined ? null : patch.note;
+            const hasNote = patch.note !== undefined;
+            const variant = patch.variant === undefined ? null : patch.variant;
+            const hasVariant = patch.variant !== undefined;
+            const fp = patch.fp === undefined ? null : patch.fp;
+            const hasFp = patch.fp !== undefined;
+            const hasDevices = patch.approvedDevices !== undefined;
+            const approvedPc = hasDevices ? (patch.approvedDevices?.includes("pc") ?? false) : null;
+            const approvedMobile = hasDevices ? (patch.approvedDevices?.includes("mobile") ?? false) : null;
+            await db `
+        INSERT INTO qa_review_state (site, target, item_id, verdict, note, variant, fp, approved_pc, approved_mobile, updated_at)
+        VALUES (${site}, ${target}, ${itemId}, ${verdict}, ${note}, ${variant}, ${fp}, ${approvedPc}, ${approvedMobile}, now())
+        ON CONFLICT (site, target, item_id) DO UPDATE SET
+          verdict = CASE WHEN ${hasVerdict} THEN EXCLUDED.verdict ELSE qa_review_state.verdict END,
+          note = CASE WHEN ${hasNote} THEN EXCLUDED.note ELSE qa_review_state.note END,
+          variant = CASE WHEN ${hasVariant} THEN EXCLUDED.variant ELSE qa_review_state.variant END,
+          fp = CASE WHEN ${hasFp} THEN EXCLUDED.fp ELSE qa_review_state.fp END,
+          approved_pc = CASE WHEN ${hasDevices} THEN EXCLUDED.approved_pc ELSE qa_review_state.approved_pc END,
+          approved_mobile = CASE WHEN ${hasDevices} THEN EXCLUDED.approved_mobile ELSE qa_review_state.approved_mobile END,
+          revisit_reason = CASE WHEN ${hasVerdict} THEN NULL ELSE qa_review_state.revisit_reason END,
+          prev_verdict = CASE WHEN ${hasVerdict} THEN NULL ELSE qa_review_state.prev_verdict END,
+          updated_at = now()
+      `;
+        },
+        async deleteState(site, target, itemId) {
+            const db = await ready();
+            await db `
+        DELETE FROM qa_review_state
+        WHERE site = ${site} AND target = ${target} AND item_id = ${itemId}
+      `;
+        },
+        async invalidateState(site, target, itemId, revisitReason) {
+            const db = await ready();
+            // Keep the row: verdict -> prev_verdict, approvals cleared, note + fp
+            // retained (the fingerprint anchors the NOT-ALTERED comparison), reason
+            // recorded. Upsert so a reason can also be attached to a never-reviewed
+            // item ("reassess this" guidance).
+            await db `
+        INSERT INTO qa_review_state (site, target, item_id, revisit_reason, updated_at)
+        VALUES (${site}, ${target}, ${itemId}, ${revisitReason}, now())
+        ON CONFLICT (site, target, item_id) DO UPDATE SET
+          prev_verdict = COALESCE(qa_review_state.verdict, qa_review_state.prev_verdict),
+          verdict = NULL,
+          approved_pc = NULL,
+          approved_mobile = NULL,
+          revisit_reason = ${revisitReason},
+          updated_at = now()
+      `;
+        },
+        async insertSession(site, session) {
+            const db = await ready();
+            const [row] = await db `
+        INSERT INTO qa_review_sessions (site, target, reviewer, approved, rejected, total, results)
+        VALUES (
+          ${site}, ${session.target}, ${session.reviewer},
+          ${session.approved}, ${session.rejected}, ${session.total},
+          ${db.json(session.results)}
+        )
+        RETURNING id
+      `;
+            return { id: row.id };
+        },
+        async listSessions(site, target, limit = 100) {
+            const db = await ready();
+            const rows = await db `
+        SELECT id, site, target, reviewer, approved, rejected, total, created_at
+        FROM qa_review_sessions
+        WHERE site = ${site} ${target ? db `AND target = ${target}` : db ``}
+        ORDER BY created_at DESC
+        LIMIT ${limit}
+      `;
+            return rows.map((r) => ({
+                id: r.id,
+                site: r.site,
+                target: r.target,
+                reviewer: r.reviewer,
+                approved: r.approved,
+                rejected: r.rejected,
+                total: r.total,
+                createdAt: r.created_at instanceof Date ? r.created_at.toISOString() : String(r.created_at),
+            }));
+        },
+    };
+}

package/dist/shared/codename.d.ts

@@ -0,0 +1,16 @@
+/** FNV-1a 32-bit (deterministic across platforms/sessions). */
+export declare function fnv1a(str: string): number;
+/** Stable two-word codename for a (target, itemId) pair, e.g. "red-apple". */
+export declare function codenameFor(target: string, itemId: string): string;
+export interface CodenameEntry {
+    target: string;
+    itemId: string;
+}
+/**
+ * Resolve a spoken/written codename ("red-apple", "red apple", "Red Apple")
+ * back to items. Returns ALL matches (codename space is 4096; collisions are
+ * possible across many items).
+ */
+export declare function findByCodename<T extends CodenameEntry>(codename: string, entries: readonly T[]): T[];
+/** Canonical copy-reference line for an item ("Copy ref" button payload). */
+export declare function formatQARef(target: string, itemId: string, title: string): string;