@snagset/server 0.0.1

package/dist/db/migrations/0002_maintenance_claim.sql

@@ -0,0 +1,109 @@
+-- ─────────────────────────────────────────────────────────────────────────
+-- 08 §9.2's MAINTENANCE CLAIM (D56) — the second disjunct every org policy
+-- needs before scheduled work can see a single row.
+--
+-- THE BUG THIS FIXES, measured rather than reasoned:
+--
+--   0001 writes  USING (org_id = current_setting('app.org_id', true)::uuid)
+--
+-- The reaper (05 §3.11) is cross-tenant by definition: it expires every org's
+-- nonces, downgrades every project past its grace window, reaps every orphaned
+-- blob. It therefore runs with no app.org_id set — and with nothing set,
+-- current_setting(..., true) returns NULL, org_id = NULL evaluates to NULL,
+-- NULL is not true, and every row is filtered out. The job commits, reports
+-- success, and has done nothing.
+--
+-- On the test database: as the owner, one project. As a role without
+-- BYPASSRLS and no app.org_id, zero. The failure is INVISIBLE wherever the
+-- connecting role bypasses RLS, which includes every Neon connection string
+-- (D50) — so it works in development and silently stops working on every
+-- correctly configured self-host. That is the worst shape a bug can have.
+--
+-- WHY THIS IS A SEPARATE FILE AND NOT A REGENERATED 0001.
+--
+-- The policies are not in 05 §3 — the generator adds them (see its header), so
+-- changing them means changing the generator, which changes 0001, which
+-- changes its checksum, which makes migrate.ts refuse to start against any
+-- database that already applied it. By the time this was written that included
+-- a dogfood instance holding real review data. A migration is exactly the tool
+-- for "the schema needs to change and the old one is already out there", and
+-- reaching for the generator instead would have traded somebody's data for a
+-- tidier diff.
+--
+-- THE SECOND BUG IN THE SAME PREDICATE, found while testing the first.
+--
+-- After a transaction that did set_config('app.org_id', ..., true) commits,
+-- current_setting('app.org_id', true) does NOT go back to NULL — it returns
+-- the EMPTY STRING. So the next query on that pooled connection evaluates
+-- ''::uuid and raises "invalid input syntax for type uuid". Not zero rows: an
+-- error. Every request the server serves sets that variable, and every
+-- connection is reused, so on a deployment where the policy is actually
+-- evaluated this is not an edge case — it is the second request onwards.
+--
+-- Invisible for the same reason as the first bug: a role with BYPASSRLS never
+-- evaluates the predicate, so the whole class of defect is undetectable on the
+-- database this was developed against. Both are fixed here, because both are
+-- the same sentence written wrong, and a migration that fixed only the one we
+-- went looking for would leave the worse one in place.
+--
+-- WHY A LOOP AND NOT 31 HAND-WRITTEN STATEMENTS.
+--
+-- The predicate differs per table (orgs matches on id, users through
+-- memberships, everything else on org_id), so hand-writing them means
+-- transcribing three variants across 31 tables — the transcription error this
+-- repo generates its migration to avoid. Reading each policy's CURRENT
+-- expression back out of the catalogue and appending one disjunct is both
+-- shorter and incapable of getting a predicate wrong.
+-- ─────────────────────────────────────────────────────────────────────────
+
+DO $$
+DECLARE
+  p        record;
+  existing text;
+BEGIN
+  FOR p IN
+    SELECT c.relname AS table_name, pol.polname AS policy_name,
+           pg_get_expr(pol.polqual, pol.polrelid) AS qual
+    FROM pg_policy pol
+    JOIN pg_class c ON c.oid = pol.polrelid
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE n.nspname = 'public'
+      AND pol.polname = c.relname || '_org'
+    ORDER BY c.relname
+  LOOP
+    existing := p.qual;
+
+    -- Fix one: an unset variable reads as '' rather than NULL, and ''::uuid
+    -- raises. NULLIF turns it back into the NULL the predicate was written
+    -- assuming, which compares as unknown and filters the row out quietly —
+    -- which is what "no tenant context" should do.
+    existing := replace(
+      existing,
+      'current_setting(''app.org_id''::text, true)',
+      'NULLIF(current_setting(''app.org_id''::text, true), ''''::text)'
+    );
+
+    -- Fix two: the maintenance claim. Idempotent by inspection rather than by
+    -- IF NOT EXISTS: re-running this migration is not the case that matters
+    -- (the ledger stops that), but a database that reached this shape another
+    -- way must not end up with the disjunct twice.
+    IF existing NOT LIKE '%app.maintenance%' THEN
+      existing := existing ||
+        ' OR current_setting(''app.maintenance'', true) = ''on''';
+    END IF;
+
+    IF existing = p.qual THEN
+      CONTINUE;
+    END IF;
+
+    EXECUTE format(
+      'DROP POLICY %I ON public.%I',
+      p.policy_name, p.table_name
+    );
+    EXECUTE format(
+      'CREATE POLICY %I ON public.%I USING (%s)',
+      p.policy_name, p.table_name, existing
+    );
+  END LOOP;
+END
+$$;

package/dist/db/migrations/0003_email_provider.sql

@@ -0,0 +1,35 @@
+-- ─────────────────────────────────────────────────────────────────────────
+-- `email` joins snag_provider, so notification mail can ride the outbox
+-- (L1.4, plan/03 §M2-32: "Delivered through M2-31's outbox, so a retry never
+-- double-sends").
+--
+-- The outbox already carries exactly the guarantee email needs and nothing
+-- else in this system does: UNIQUE (provider, dedupe_key) makes re-enqueueing
+-- a no-op, and the status machine makes a delivered row un-redeliverable. A
+-- second table beside it would be that mechanism written twice, and the second
+-- copy is the one that gets the retry semantics subtly wrong.
+--
+-- WHY 05 §3's ENUM BLOCK IS NOT EDITED, for the second time.
+--
+-- §3 is the sole schema source and 0001 is generated from it — so editing the
+-- enum there regenerates 0001, changes its checksum, and makes migrate.ts
+-- refuse to start against every database that already applied it. The
+-- convention `migrate.ts` documents is that 0001 stays regenerable UNTIL M2-35
+-- freezes schemaVersion, after which §3 describes the current schema and the
+-- generator's check becomes "0001 plus every later file EQUALS §3".
+--
+-- This is the SECOND migration to work around that boundary (0002 was the
+-- first), and two is the point at which it stops being an exception. The
+-- freeze is now overdue: until it happens, §3 describes the schema a FRESH
+-- database gets before its later migrations run, which is a subtly different
+-- thing from the schema, and a reader has no way to tell from §3 alone. A
+-- prose note beside the enum in §3 points here; it sits outside the fenced
+-- block, so the generator does not see it and 0001 is unchanged.
+--
+-- ADD VALUE IF NOT EXISTS is transaction-safe on PostgreSQL 12+ (08 §2.2
+-- targets 14+) provided the new value is not USED in the same transaction.
+-- Nothing here uses it; the first use is the first notification, which is a
+-- different transaction entirely.
+-- ─────────────────────────────────────────────────────────────────────────
+
+ALTER TYPE snag_provider ADD VALUE IF NOT EXISTS 'email';

package/dist/db/migrations/0004_unsubscribe.sql

@@ -0,0 +1,24 @@
+-- ─────────────────────────────────────────────────────────────────────────
+-- Reviewer notifications need an off switch — B2, and the FIRST migration
+-- written under the frozen schema (D71).
+--
+-- Until now the only notification was `comment.created` → the project owner,
+-- whose address we verified at claim time. Growing that to reviewers changes
+-- the character of the system: their addresses are self-declared, so a
+-- product that mails them on a stranger's trigger and offers no way out is an
+-- open relay with better manners. The subscription rule is "created or
+-- replied" (derivable, no schema) and the exit is this column.
+--
+-- WHY IT IS A TIMESTAMP. Every other state on `reviewers` is one —
+-- `blocked_at`, `erased_at`, `identity_valid_after` — and a deliverability
+-- complaint asks "when did they opt out", which a boolean cannot answer.
+--
+-- WHY NO INDEX. It is read one row at a time, always beside the reviewer the
+-- notification is about, on a table already keyed by id. An index here would
+-- be write cost for a read that never scans.
+--
+-- Under D71, §3 describes the CURRENT schema, so the column is added there in
+-- the same commit as this file and `pnpm schema:diff:check` asserts the two
+-- agree. That check is what makes this the last migration anybody has to
+-- reason about by reading two places at once.
+ALTER TABLE reviewers ADD COLUMN IF NOT EXISTS notifications_off_at timestamptz;

package/dist/db/rls.js

@@ -0,0 +1,58 @@
+export async function rlsStatus(sql) {
+    const [role] = await sql `
+    SELECT rolname AS name, rolbypassrls AS bypass
+    FROM pg_roles WHERE rolname = current_user
+  `;
+    // `_migrations` is ours and holds no tenant data; the pre-tenant
+    // `setup_tokens` has no org_id to scope by (05 §3.2). Everything else with an
+    // org_id column is expected to be protected, which is the check foundations
+    // §14.2 asks for stated as a query rather than as a convention.
+    const tables = await sql `
+    SELECT c.relname                                        AS name,
+           c.relforcerowsecurity                            AS forced,
+           (SELECT count(*)::int FROM pg_policy p WHERE p.polrelid = c.oid) AS policies
+    FROM pg_class c
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE n.nspname = 'public'
+      AND c.relkind = 'r'
+      AND EXISTS (
+        SELECT 1 FROM pg_attribute a
+        WHERE a.attrelid = c.oid AND a.attname = 'org_id' AND NOT a.attisdropped
+      )
+    ORDER BY c.relname
+  `;
+    const unprotected = tables.filter((t) => t.policies === 0).map((t) => t.name);
+    const notForced = tables.filter((t) => t.policies > 0 && !t.forced).map((t) => t.name);
+    const bypass = role?.bypass ?? false;
+    const effective = !bypass && !unprotected.length && !notForced.length && tables.length > 0;
+    let warning = null;
+    if (bypass) {
+        warning =
+            `row-level security is NOT in force: the role "${role?.name}" has BYPASSRLS, ` +
+                `which overrides every policy migration 0001 created. Managed Postgres often ` +
+                `grants it to the owner role in the connection string it hands you (Neon's ` +
+                `neondb_owner does). Requests are still scoped by org_id in the application, ` +
+                `so this is a lost safety net rather than an open door — to get it back, create ` +
+                `a role without BYPASSRLS, grant it the tables, and point DATABASE_URL at it.`;
+    }
+    else if (unprotected.length) {
+        warning =
+            `row-level security is incomplete: ${unprotected.length} table(s) carry org_id ` +
+                `with no policy (${unprotected.slice(0, 5).join(", ")}). Re-run migrations.`;
+    }
+    else if (notForced.length) {
+        warning =
+            `row-level security does not apply to the table owner on ${notForced.length} ` +
+                `table(s) (${notForced.slice(0, 5).join(", ")}), and a self-host connects as ` +
+                `the owner. Re-run migrations.`;
+    }
+    return {
+        effective,
+        role: role?.name ?? "unknown",
+        roleBypassesRls: bypass,
+        notForced,
+        unprotected,
+        warning,
+    };
+}
+//# sourceMappingURL=rls.js.map

package/dist/db/rls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rls.js","sourceRoot":"","sources":["../../src/db/rls.ts"],"names":[],"mappings":"AAgDA,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAiB;IAC/C,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,GAAG,CAAqC;;;GAG5D,CAAC;IAEF,iEAAiE;IACjE,8EAA8E;IAC9E,4EAA4E;IAC5E,gEAAgE;IAChE,MAAM,MAAM,GAAG,MAAM,GAAG,CAAuD;;;;;;;;;;;;;GAa9E,CAAC;IAEF,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC9E,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACvF,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,CAAC;IACrC,MAAM,SAAS,GAAG,CAAC,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IAE3F,IAAI,OAAO,GAAkB,IAAI,CAAC;IAClC,IAAI,MAAM,EAAE,CAAC;QACX,OAAO;YACL,iDAAiD,IAAI,EAAE,IAAI,mBAAmB;gBAC9E,8EAA8E;gBAC9E,4EAA4E;gBAC5E,8EAA8E;gBAC9E,iFAAiF;gBACjF,8EAA8E,CAAC;IACnF,CAAC;SAAM,IAAI,WAAW,CAAC,MAAM,EAAE,CAAC;QAC9B,OAAO;YACL,qCAAqC,WAAW,CAAC,MAAM,yBAAyB;gBAChF,mBAAmB,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,uBAAuB,CAAC;IACjF,CAAC;SAAM,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC;QAC5B,OAAO;YACL,2DAA2D,SAAS,CAAC,MAAM,GAAG;gBAC9E,aAAa,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,iCAAiC;gBAC9E,+BAA+B,CAAC;IACpC,CAAC;IAED,OAAO;QACL,SAAS;QACT,IAAI,EAAE,IAAI,EAAE,IAAI,IAAI,SAAS;QAC7B,eAAe,EAAE,MAAM;QACvB,SAAS;QACT,WAAW;QACX,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/jobs/index.js

@@ -0,0 +1,171 @@
+/**
+ * The advisory lock namespace — the first half of the two-int lock id.
+ *
+ * 0x63644A42 is the ASCII for "cdJB", picked the same way `MIGRATION_LOCK_ID`
+ * picks "cdMG": the number is meaningless, and what matters is only that every
+ * instance computes the SAME one without coordinating.
+ */
+export const JOB_LOCK_NAMESPACE = 0x63644a42;
+/**
+ * Job name → the second half of the lock id, as a SIGNED 32-bit int.
+ *
+ * FNV-1a rather than a hash import: the requirement is that two processes
+ * agree, not that the result is hard to reverse. `| 0` at the end is what
+ * makes it signed — Postgres takes `int4`, and handing it 3 000 000 000 is an
+ * out-of-range error rather than a silent wrap.
+ */
+export function jobLockKey(name) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < name.length; i++) {
+        h ^= name.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h | 0;
+}
+/**
+ * The engine's own bookkeeping table.
+ *
+ * Created here rather than in a migration, and the precedent is `_migrations`
+ * itself: 05 §3 owns the DOMAIN schema — every table a tenant's data lives in —
+ * and the runners that operate on it keep their own state beside it. Both are
+ * `_`-prefixed, both hold no tenant data, both have no `org_id` and therefore
+ * no RLS policy to write (`rls.ts` only inspects tables that carry one).
+ *
+ * `last_run_at` is written whether the job SUCCEEDED OR FAILED. A job that
+ * throws every time would otherwise be due on every tick forever, and a
+ * failing 15-minute reaper hammering the database once a second is a worse
+ * outage than the one it started with. The error is kept beside it so the
+ * operator can see which, and how long it has been that way.
+ */
+async function ensureTable(sql) {
+    await sql `
+    CREATE TABLE IF NOT EXISTS _jobs (
+      name        text PRIMARY KEY,
+      last_run_at timestamptz NOT NULL,
+      last_ms     integer NOT NULL DEFAULT 0,
+      last_did    integer NOT NULL DEFAULT 0,
+      last_error  text
+    )
+  `;
+}
+export async function runDueJobs(sql, jobs, opts) {
+    const started = Date.now();
+    const clock = opts.now ?? (() => new Date());
+    const log = opts.log ?? (() => { });
+    const maxPasses = opts.maxPasses ?? 20;
+    const spent = () => Date.now() - started;
+    const ran = [];
+    const skipped = [];
+    const failed = [];
+    await ensureTable(sql);
+    const last = new Map((await sql `SELECT name, last_run_at FROM _jobs`).map((r) => [r.name, r.last_run_at]));
+    for (const job of jobs) {
+        if (spent() >= opts.budgetMs) {
+            skipped.push({ name: job.name, why: "budget" });
+            continue;
+        }
+        const now = clock();
+        const previous = last.get(job.name);
+        // No row at all means never run, which is due. `>=` rather than `>` so a
+        // job with everyMs 0 — "every tick" — actually runs every tick.
+        if (previous && now.getTime() - previous.getTime() < job.everyMs) {
+            skipped.push({ name: job.name, why: "not-due" });
+            continue;
+        }
+        const at = Date.now();
+        let did = 0;
+        let passes = 0;
+        let error = null;
+        let lockedOut = false;
+        try {
+            for (;;) {
+                const outcome = await runOnce(sql, job, clock(), log);
+                if (outcome === "locked") {
+                    lockedOut = true;
+                    break;
+                }
+                passes++;
+                did += outcome.did;
+                if (outcome.note)
+                    log(`jobs: ${job.name}: ${outcome.note}`);
+                if (!outcome.more)
+                    break;
+                if (passes >= maxPasses) {
+                    log(`jobs: ${job.name}: stopping at ${maxPasses} passes with work left`);
+                    break;
+                }
+                if (spent() >= opts.budgetMs) {
+                    log(`jobs: ${job.name}: out of budget with work left`);
+                    break;
+                }
+            }
+        }
+        catch (e) {
+            error = e instanceof Error ? e.message : String(e);
+        }
+        if (lockedOut) {
+            // Another instance has it. Deliberately NOT recorded as a run: that
+            // instance will write `last_run_at` when it finishes, and claiming the
+            // run here would make this one think the work was done.
+            skipped.push({ name: job.name, why: "locked" });
+            continue;
+        }
+        const ms = Date.now() - at;
+        if (error)
+            failed.push({ name: job.name, error });
+        else
+            ran.push({ name: job.name, did, ms, passes });
+        await record(sql, job.name, clock(), ms, did, error);
+    }
+    return { ran, skipped, failed, ms: spent() };
+}
+/**
+ * One pass of one job: take the lock, claim maintenance, do the work — all in
+ * ONE transaction, so all three end together however it ends.
+ *
+ * `SET LOCAL app.maintenance` is 08 §9.2's maintenance claim (D56) and without
+ * it every statement in every job matches zero rows on any deployment whose
+ * role does not bypass RLS. `LOCAL` is the half that makes it an exemption
+ * rather than a hole: it cannot outlive this transaction, so nothing that runs
+ * after it inherits cross-tenant reach.
+ */
+async function runOnce(sql, job, now, log) {
+    return sql.begin(async (tx) => {
+        const [lock] = await tx `
+      SELECT pg_try_advisory_xact_lock(${JOB_LOCK_NAMESPACE}, ${jobLockKey(job.name)}) AS ok
+    `;
+        if (!lock?.ok)
+            return "locked";
+        await tx `SET LOCAL app.maintenance = 'on'`;
+        return job.run({ sql: tx, now, log });
+    });
+}
+/** Bookkeeping, in its own transaction so a rolled-back job still records the
+ *  attempt. Every job is idempotent, so the worst case if this write is lost
+ *  to a crash is that the work is repeated — which is the direction to fail
+ *  in. */
+async function record(sql, name, at, ms, did, error) {
+    await sql `
+    INSERT INTO _jobs (name, last_run_at, last_ms, last_did, last_error)
+    VALUES (${name}, ${at}, ${ms}, ${did}, ${error})
+    ON CONFLICT (name) DO UPDATE
+      SET last_run_at = EXCLUDED.last_run_at,
+          last_ms     = EXCLUDED.last_ms,
+          last_did    = EXCLUDED.last_did,
+          last_error  = EXCLUDED.last_error
+  `;
+}
+/** One line an operator can read in a log without a dashboard. */
+export function summarise(s) {
+    const ran = s.ran.filter((r) => r.did > 0).map((r) => `${r.name}:${r.did}`);
+    const parts = [`${s.ms}ms`];
+    if (ran.length)
+        parts.push(ran.join(" "));
+    if (s.failed.length)
+        parts.push(`FAILED ${s.failed.map((f) => f.name).join(" ")}`);
+    const locked = s.skipped.filter((x) => x.why === "locked");
+    if (locked.length)
+        parts.push(`locked ${locked.map((l) => l.name).join(" ")}`);
+    return `jobs: ${parts.join(" · ")}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/jobs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"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"}

package/dist/jobs/reaper.js

@@ -0,0 +1,182 @@
+/**
+ * 05 §3.11's reaper, cut to the three jobs L1 needs (L1.2).
+ *
+ * §3.11 lists eighteen steps. The other fifteen land with L2, and the split is
+ * not arbitrary — these three are the ones whose ABSENCE is already costing
+ * something today:
+ *
+ *   · `write-mode-downgrade` (§3.11 step 12) makes the read-time downgrade in
+ *     `routes/sessions.ts` real. Until now `effectiveWriteMode()` computed the
+ *     right answer on every request and no row ever changed, so the dashboard
+ *     showed `open` on a project that had behaved as `link-required` for days.
+ *     One of those two is lying to the operator.
+ *   · `expire-rows` (steps 1, 2, 4) deletes rows that are already expired by
+ *     their own column. Nothing reads them — every consumer checks
+ *     `expires_at` — so this is purely a table that grows without bound. A
+ *     nonce table nobody sweeps is the one that eventually makes an INSERT
+ *     slow at three in the morning.
+ *   · `reap-pending-attachments` (step 5) is the one that costs actual money:
+ *     an upload that was presigned and never bound leaves a blob in the bucket
+ *     that no row will ever reference and no user will ever see.
+ *
+ * Every statement here is idempotent and bounded by a `WHERE` clause on time.
+ * That is what makes DoD 3's "two ticks do not double-run" a belt-and-braces
+ * guarantee rather than the only thing standing between us and corruption:
+ * running any of these twice does exactly what running it once does.
+ */
+/** How many rows one pass will touch. Small enough that the transaction is
+ *  short and the advisory lock is not held across a long DELETE; large enough
+ *  that a normal backlog clears in one pass. `more: true` is what makes the
+ *  size a batching decision rather than a cap on how much ever gets done. */
+const BATCH = 500;
+/**
+ * §3.11 step 12 — the first-run auto-downgrade.
+ *
+ * 05 §4.2 gives a new project 24 hours of `open` writes so that `npx snagset`
+ * reaches a first pin with no dashboard round trip. This is the other half:
+ * the clock actually running out.
+ *
+ * `write_mode_downgrade_at = NULL` in the same statement, because the column
+ * means "a downgrade is pending" and leaving a past timestamp on a project
+ * that is already `link-required` makes the dashboard's countdown render a
+ * negative number.
+ */
+export const writeModeDowngrade = {
+    name: "write-mode-downgrade",
+    everyMs: 60_000,
+    async run({ sql, now }) {
+        const rows = await sql `
+      UPDATE projects
+         SET write_mode = 'link-required',
+             write_mode_downgrade_at = NULL
+       WHERE write_mode = 'open'
+         AND write_mode_downgrade_at IS NOT NULL
+         AND write_mode_downgrade_at <= ${now}
+         AND deleted_at IS NULL
+      RETURNING id
+    `;
+        return rows.length
+            ? { did: rows.length, note: `${rows.length} project(s) downgraded to link-required` }
+            : { did: 0 };
+    },
+};
+/**
+ * §3.11 steps 1, 2 and 4 — rows whose own column says they are expired.
+ *
+ * One job rather than three because they share a shape, a cadence and a
+ * failure mode, and three jobs would mean three advisory locks and three
+ * `_jobs` rows to describe one sentence: "delete what has expired".
+ *
+ * The `stream_tickets` case (step 3) is deliberately absent — 08 §9.4 deleted
+ * SSE outright, so there is no such table to sweep and a statement against one
+ * would be dead code that reads as coverage.
+ */
+export const expireRows = {
+    name: "expire-rows",
+    everyMs: 15 * 60_000,
+    async run({ sql, now }) {
+        // Three separate statements, counted together. A single statement with
+        // UNION would need three different row shapes to line up and would tell
+        // the operator nothing about WHICH table was growing.
+        const idem = await sql `
+      DELETE FROM idempotency_keys
+       WHERE ctid IN (SELECT ctid FROM idempotency_keys WHERE expires_at < ${now} LIMIT ${BATCH})
+    `;
+        const nonces = await sql `
+      DELETE FROM identity_nonces
+       WHERE ctid IN (SELECT ctid FROM identity_nonces WHERE expires_at < ${now} LIMIT ${BATCH})
+    `;
+        const counters = await sql `
+      DELETE FROM rate_counters
+       WHERE ctid IN (SELECT ctid FROM rate_counters WHERE expires_at < ${now} LIMIT ${BATCH})
+    `;
+        const did = idem.count + nonces.count + counters.count;
+        // Any one of them filling its batch means there is more of that one left.
+        const more = idem.count === BATCH || nonces.count === BATCH || counters.count === BATCH;
+        return did
+            ? {
+                did,
+                more,
+                note: `expired ${idem.count} idempotency · ${nonces.count} nonces · ${counters.count} counters`,
+            }
+            : { did: 0, more };
+    },
+};
+/**
+ * §3.11 step 5 — presigned uploads that were never bound to a comment.
+ *
+ * The two windows are LOCK L4's, and the difference between them is not a
+ * rounding preference. An IMAGE is captured, resized and uploaded by our own
+ * code inside one composer submission, so two hours is enormous slack for a
+ * slow phone on hotel wifi. A FILE is a browser PUT straight to the bucket
+ * against a 5-minute presign, so anything older than 15 minutes cannot still
+ * be in flight — the URL it would use has already expired.
+ *
+ * `DeleteObject` is attempted unconditionally and its failure is swallowed,
+ * because both outcomes are fine and neither is worth a retry: the browser may
+ * never have PUT anything (delete on a missing key is a no-op in S3), or the
+ * bucket may be misconfigured (in which case the row still has to leave
+ * `pending`, or it is re-tried on every tick forever). What must NOT happen is
+ * the row being marked orphaned while the bytes stay — so the delete is
+ * attempted first and the row is updated after.
+ *
+ * With no bucket configured the job does nothing and says so. That is the
+ * annotation-mode deployment (08 §8.5), where no blob was ever written and
+ * there is nothing to reap.
+ */
+export function reapPendingAttachments(bucket) {
+    return {
+        name: "reap-pending-attachments",
+        everyMs: 5 * 60_000,
+        async run({ sql, now, log }) {
+            const imageCutoff = new Date(now.getTime() - 2 * 60 * 60_000);
+            const fileCutoff = new Date(now.getTime() - 15 * 60_000);
+            const rows = await sql `
+        SELECT id, project_id, storage_key, bytes, kind
+          FROM attachments
+         WHERE state = 'pending'
+           AND ((kind = 'file' AND created_at < ${fileCutoff})
+             OR (kind <> 'file' AND created_at < ${imageCutoff}))
+         ORDER BY created_at
+         LIMIT ${BATCH}
+      `;
+            if (!rows.length)
+                return { did: 0 };
+            if (!bucket) {
+                return { did: 0, note: `${rows.length} pending attachment(s) and no bucket to reap from` };
+            }
+            let reaped = 0;
+            for (const row of rows) {
+                try {
+                    await bucket.del(row.storage_key);
+                }
+                catch (e) {
+                    // Named, not silent: a bucket that refuses every delete is a bill
+                    // that grows, and the only place it shows up is here.
+                    log(`jobs: reap-pending-attachments: delete ${row.storage_key} failed: ${String(e)}`);
+                }
+                await sql `UPDATE attachments SET state = 'orphaned' WHERE id = ${row.id}`;
+                // §12.6's counter. Decremented per row rather than in one statement at
+                // the end so a mid-batch failure cannot leave the counter describing
+                // rows that were already reaped.
+                await sql `
+          UPDATE projects
+             SET storage_bytes_used = GREATEST(0, storage_bytes_used - ${Number(row.bytes)})
+           WHERE id = ${row.project_id}
+        `;
+                reaped++;
+            }
+            return {
+                did: reaped,
+                more: rows.length === BATCH,
+                note: `${reaped} orphaned upload(s) reaped`,
+            };
+        },
+    };
+}
+/** The L1 set, in the order a tick runs them: cheapest and most
+ *  user-visible first, so a budget that runs out costs the least. */
+export function l1Jobs(bucket) {
+    return [writeModeDowngrade, expireRows, reapPendingAttachments(bucket)];
+}
+//# sourceMappingURL=reaper.js.map

package/dist/jobs/reaper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reaper.js","sourceRoot":"","sources":["../../src/jobs/reaper.ts"],"names":[],"mappings":"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"}