@astralarium/repo-postgres 0.1.0 → 0.2.0

package/README.md

@@ -8,3 +8,32 @@ Roles:
 - `app_service`: app service.
 
 Roles are cluster-wide: one app per cluster.
+
+```sql
+SELECT slug.slug('Room 52'); -- room-52
+```
+
+```ts
+// app modules: `taskclaimJobs` (requires `taskclaim`, `cron`) deletes expired claims hourly
+postgresDatabase({ modules: [appModule, slug, taskclaimJobs], name: "app-db" });
+```
+
+```ts
+// producer: one message per key per window
+await enqueueClaimed(
+  sql,
+  env.REFRESH,
+  `project:${id}`,
+  { id },
+  { windowSeconds: 300 },
+);
+
+// consumer
+await consumeClaimed(sql, batch, {
+  parse: parseRefreshTask,
+  run: refreshProject,
+  maxRetries: 3, // the consumer's max_retries
+  retryAfterMs: (e) =>
+    e instanceof RetryAfterError ? e.retryAfterMs : undefined,
+});
+```

package/dist/src/queue.d.ts

@@ -0,0 +1,86 @@
+import { type Sql, type TransactionSql } from "./sql.ts";
+/** A Cloudflare Queues producer binding, as `enqueueClaimed` sends. */
+export interface Queue<Body> {
+    send(body: Body): Promise<unknown>;
+}
+/** A Cloudflare Queues message, as `consumeClaimed` settles it. */
+export interface QueueMessage<Body> {
+    readonly body: Body;
+    /** Deliveries so far, this one included: 1 on the first. */
+    readonly attempts: number;
+    ack(): void;
+    retry(options?: {
+        delaySeconds?: number;
+    }): void;
+}
+/** A Cloudflare Queues consumer batch. */
+export interface MessageBatch<Body> {
+    /** Queue name. */
+    readonly queue: string;
+    readonly messages: readonly QueueMessage<Body>[];
+}
+/** A claimed task's queue message body. */
+export interface ClaimedTask<Task> {
+    /** Claim key (`claimTask`). */
+    key: string;
+    /** Claim token (`claimTask`). */
+    claim: string;
+    /** Claim window (`claimTask`); a held retry's claim ends one window past
+     *  its due time. */
+    windowSeconds: number;
+    task: Task;
+}
+/** Claims `key` for `windowSeconds`: a fresh token, or undefined while an
+ *  unexpired claim holds it. */
+export declare function claimTask(sql: Sql | TransactionSql, key: string, { windowSeconds }: {
+    windowSeconds: number;
+}): Promise<string | undefined>;
+/** Holds `key`'s claim by `token` through a retry due in `delaySeconds`,
+ *  then `windowSeconds` more, reclaiming a freed key; a later claim
+ *  stays. */
+export declare function holdTask(sql: Sql | TransactionSql, key: string, token: string, { delaySeconds, windowSeconds, }: {
+    delaySeconds: number;
+    windowSeconds: number;
+}): Promise<void>;
+/** Frees `key`'s claim by `token`; a later claim stays. */
+export declare function releaseTask(sql: Sql | TransactionSql, key: string, token: string): Promise<void>;
+/** Sends `task` to `queue` under a fresh claim of `key` (`claimTask`);
+ *  resolves to the claim token, undefined while a claim holds the key.
+ *  A failed send releases the claim and throws the send's error; a failed
+ *  release logs, its claim held for the window. Takes a client outside any
+ *  transaction: the claim commits before the send. */
+export declare function enqueueClaimed<Task>(sql: Sql, queue: Queue<ClaimedTask<Task>>, key: string, task: Task, options: {
+    windowSeconds: number;
+}): Promise<string | undefined>;
+/** How `consumeClaimed` runs a batch's tasks. */
+export interface ConsumeClaimedOptions<Task> {
+    /** The task a message carries; undefined or a throw for one it cannot
+     *  run. */
+    parse: (task: unknown) => Task | undefined;
+    /** Runs one task; a throw fails the attempt. Idempotent: a task can run
+     *  more than once. */
+    run: (task: Task) => Promise<void>;
+    /** The consumer's `max_retries`: retries after the first delivery, an
+     *  integer from 0. */
+    maxRetries: number;
+    /** Milliseconds a `run` throw asks to wait (e.g. `Retry-After`): a finite
+     *  number from 0, or undefined for none. Another value or a throw counts
+     *  as none. */
+    retryAfterMs?: (exception: unknown) => number | undefined;
+}
+/**
+ * Queue consumer of claimed tasks, messages in order. A run acks, keeping
+ * its claim until the window ends: a trigger inside the window coalesces.
+ * A failure retries after 30 s, doubling each attempt, or a longer
+ * `retryAfterMs`, up to 12 hours, holding the claim through the retry
+ * (`holdTask`). The last failure logs, releases the claim and acks; so does
+ * a task `parse` rejects or throws on. A body lacking a claim logs and acks.
+ * A failed claim write logs and the delivery settles as decided: a failed
+ * hold retries, a failed release acks, the key claimed for the window. The
+ * batch continues. Delivery is at-least-once (a queue redelivery reruns a
+ * task): `run` must be idempotent. Takes a client
+ * outside any transaction: each claim write commits before its message
+ * settles. Rejects with a `RangeError` for a `maxRetries` other than an
+ * integer from 0.
+ */
+export declare function consumeClaimed<Task>(sql: Sql, batch: MessageBatch<unknown>, options: ConsumeClaimedOptions<Task>): Promise<void>;

package/dist/src/queue.js

@@ -0,0 +1,201 @@
+/**
+ * Claimed tasks on Cloudflare Queues: a task key queues once per claim
+ * window, its claim (`taskclaim.claim`) held through retries. Needs the
+ * `taskclaim` schema module; `taskclaimJobs` deletes expired claims.
+ *
+ * `enqueueClaimed` and `consumeClaimed` take a client outside any
+ * transaction. `Sql` rejects a `begin` transaction's client; a reserved
+ * connection inside a manual `BEGIN` type-checks, so the requirement rests
+ * on the caller.
+ */
+import { log } from "@astralarium/repo-telemetry";
+import { msInterval } from "./sql.js";
+/** Claims `key` for `windowSeconds`: a fresh token, or undefined while an
+ *  unexpired claim holds it. */
+export async function claimTask(sql, key, { windowSeconds }) {
+    const [claimed] = await sql `
+    INSERT INTO taskclaim.claim AS c (key, expires_at, token)
+    VALUES (
+      ${key},
+      CURRENT_TIMESTAMP + ${msInterval(sql, windowSeconds * 1000)},
+      gen_random_uuid()
+    )
+    ON CONFLICT (key) DO UPDATE SET
+      expires_at = EXCLUDED.expires_at,
+      token = EXCLUDED.token
+    WHERE c.expires_at < CURRENT_TIMESTAMP
+    RETURNING token
+  `;
+    return claimed?.token;
+}
+/** Holds `key`'s claim by `token` through a retry due in `delaySeconds`,
+ *  then `windowSeconds` more, reclaiming a freed key; a later claim
+ *  stays. */
+export async function holdTask(sql, key, token, { delaySeconds, windowSeconds, }) {
+    const held = msInterval(sql, (delaySeconds + windowSeconds) * 1000);
+    await sql `
+    INSERT INTO taskclaim.claim AS c (key, expires_at, token)
+    VALUES (${key}, CURRENT_TIMESTAMP + ${held}, ${token})
+    ON CONFLICT (key) DO UPDATE SET
+      expires_at = EXCLUDED.expires_at
+    WHERE c.token = EXCLUDED.token
+  `;
+}
+/** Frees `key`'s claim by `token`; a later claim stays. */
+export async function releaseTask(sql, key, token) {
+    await sql `
+    DELETE FROM taskclaim.claim
+    WHERE key = ${key} AND token = ${token}
+  `;
+}
+/** Sends `task` to `queue` under a fresh claim of `key` (`claimTask`);
+ *  resolves to the claim token, undefined while a claim holds the key.
+ *  A failed send releases the claim and throws the send's error; a failed
+ *  release logs, its claim held for the window. Takes a client outside any
+ *  transaction: the claim commits before the send. */
+export async function enqueueClaimed(sql, queue, key, task, options) {
+    const claim = await claimTask(sql, key, options);
+    if (!claim)
+        return undefined;
+    try {
+        await queue.send({
+            key,
+            claim,
+            windowSeconds: options.windowSeconds,
+            task,
+        });
+    }
+    catch (sendException) {
+        try {
+            await releaseTask(sql, key, claim);
+        }
+        catch (exception) {
+            log.error("queue.claim_release_failed", "task {key} send failed, then its claim release; key claimed for the window", { key, exception });
+        }
+        throw sendException;
+    }
+    return claim;
+}
+/** Longest delay of a queue retry: Cloudflare Queues' 12 hours. */
+const MAX_RETRY_DELAY_SECONDS = 43_200;
+/** Seconds before the retry of a task's `attempts`th failed delivery: 30,
+ *  doubling each attempt, or a longer `retryAfterMs`; at most
+ *  `MAX_RETRY_DELAY_SECONDS`. A non-finite or negative `retryAfterMs`
+ *  counts as none. */
+function retryDelaySeconds(attempts, retryAfterMs) {
+    const backoff = 30 * 2 ** (attempts - 1);
+    const retryAfter = retryAfterMs !== undefined &&
+        Number.isFinite(retryAfterMs) &&
+        retryAfterMs >= 0
+        ? Math.ceil(retryAfterMs / 1000)
+        : 0;
+    return Math.min(Math.max(backoff, retryAfter), MAX_RETRY_DELAY_SECONDS);
+}
+/** Milliseconds `retryAfterMs` asks to wait after `exception`; undefined
+ *  for none or a throw. */
+function requestedWaitMs(retryAfterMs, exception) {
+    try {
+        return retryAfterMs?.(exception);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A claim token: a uuid, as `taskclaim.claim.token` stores it. */
+const CLAIM_TOKEN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** `body` as a claimed task envelope; undefined for another shape. */
+function envelopeOf(body) {
+    if (typeof body !== "object" || body === null)
+        return undefined;
+    const { key, claim, windowSeconds, task } = body;
+    return typeof key === "string" &&
+        typeof claim === "string" &&
+        CLAIM_TOKEN.test(claim) &&
+        typeof windowSeconds === "number" &&
+        Number.isFinite(windowSeconds) &&
+        windowSeconds >= 0
+        ? { key, claim, windowSeconds, task }
+        : undefined;
+}
+/**
+ * Queue consumer of claimed tasks, messages in order. A run acks, keeping
+ * its claim until the window ends: a trigger inside the window coalesces.
+ * A failure retries after 30 s, doubling each attempt, or a longer
+ * `retryAfterMs`, up to 12 hours, holding the claim through the retry
+ * (`holdTask`). The last failure logs, releases the claim and acks; so does
+ * a task `parse` rejects or throws on. A body lacking a claim logs and acks.
+ * A failed claim write logs and the delivery settles as decided: a failed
+ * hold retries, a failed release acks, the key claimed for the window. The
+ * batch continues. Delivery is at-least-once (a queue redelivery reruns a
+ * task): `run` must be idempotent. Takes a client
+ * outside any transaction: each claim write commits before its message
+ * settles. Rejects with a `RangeError` for a `maxRetries` other than an
+ * integer from 0.
+ */
+export async function consumeClaimed(sql, batch, options) {
+    const { maxRetries } = options;
+    if (!(Number.isInteger(maxRetries) && maxRetries >= 0))
+        throw new RangeError(`maxRetries must be an integer from 0: ${maxRetries}`);
+    const { queue } = batch;
+    for (const message of batch.messages) {
+        const envelope = envelopeOf(message.body);
+        if (!envelope) {
+            log.warn("queue.message_malformed", "{queue} message lacks a task claim; acked", { queue });
+            message.ack();
+            continue;
+        }
+        const { key, claim, windowSeconds } = envelope;
+        const settlement = await attempt(queue, envelope, message, options);
+        try {
+            if (!settlement.ack) {
+                await holdTask(sql, key, claim, {
+                    delaySeconds: settlement.delaySeconds,
+                    windowSeconds,
+                });
+            }
+            else if (settlement.release) {
+                await releaseTask(sql, key, claim);
+            }
+        }
+        catch (exception) {
+            if (settlement.ack)
+                log.error("queue.claim_release_failed", "{queue} task {key} claim release failed; acked, key claimed for the window", { queue, key, exception });
+            else
+                log.error("queue.claim_hold_failed", "{queue} task {key} claim hold failed; retrying", { queue, key, exception });
+        }
+        if (settlement.ack)
+            message.ack();
+        else
+            message.retry({ delaySeconds: settlement.delaySeconds });
+    }
+}
+/** Parses and runs `envelope`'s task, logging an unparseable or finally
+ *  failed one; resolves to the delivery's settlement. */
+async function attempt(queue, { key, task: body }, { attempts }, { parse, run, maxRetries, retryAfterMs }) {
+    let task;
+    try {
+        task = parse(body);
+    }
+    catch (exception) {
+        log.warn("queue.task_unparseable", "{queue} task {key} unparseable; releasing its claim and acking", { queue, key, exception });
+        return { ack: true, release: true };
+    }
+    if (task === undefined) {
+        log.warn("queue.task_unparseable", "{queue} task {key} unparseable; releasing its claim and acking", { queue, key });
+        return { ack: true, release: true };
+    }
+    try {
+        await run(task);
+        return { ack: true, release: false };
+    }
+    catch (exception) {
+        if (attempts <= maxRetries) {
+            return {
+                ack: false,
+                delaySeconds: retryDelaySeconds(attempts, requestedWaitMs(retryAfterMs, exception)),
+            };
+        }
+        log.error("queue.task_failed", "{queue} task {key} failed after {attempts, plural, one {# attempt} other {# attempts}}", { queue, key, attempts, exception });
+        return { ack: true, release: true };
+    }
+}

package/dist/src/schema/index.d.ts

@@ -1,3 +1,3 @@
 /** Schema modules: each package's slice of the app database. */
 export { defineSchemaModule, type SchemaModule, type SchemaModuleDeclaration, } from "./module.ts";
-export { appSchema, cron, partman, trgm } from "./modules.ts";
+export { appSchema, cron, partman, slug, taskclaim, taskclaimJobs, trgm, } from "./modules.ts";

package/dist/src/schema/index.js

@@ -1,3 +1,3 @@
 /** Schema modules: each package's slice of the app database. */
 export { defineSchemaModule, } from "./module.js";
-export { appSchema, cron, partman, trgm } from "./modules.js";
+export { appSchema, cron, partman, slug, taskclaim, taskclaimJobs, trgm, } from "./modules.js";

package/dist/src/schema/modules.d.ts

@@ -3,6 +3,13 @@ export declare const appSchema: import("./module.ts").SchemaModule;
 /** pg_partman in schema `partman`, granted to `app_admin`; `reset.sql`
  *  clears its config for the dropped schemas. */
 export declare const partman: import("./module.ts").SchemaModule;
+/** Schema `slug`: `slug.slug(name)`, a name's URL slug (NFC, lowercase
+ *  alphanumerics, spaces as `-`), immutable. */
+export declare const slug: import("./module.ts").SchemaModule;
+/** Schema `taskclaim`: table `taskclaim.claim`, one claim per task key,
+ *  for `@astralarium/repo-postgres/queue`, and `taskclaim.delete_expired()`;
+ *  a snapshot's scrub empties it. */
+export declare const taskclaim: import("./module.ts").SchemaModule;
 /** pg_trgm, for trigram (name) search. */
 export declare const trgm: import("./module.ts").SchemaModule;
 /**
@@ -13,3 +20,5 @@ export declare const trgm: import("./module.ts").SchemaModule;
  * needs it idle.
  */
 export declare const cron: import("./module.ts").SchemaModule;
+/** pg_cron job `taskclaim-ttl`: `taskclaim.delete_expired()` hourly. */
+export declare const taskclaimJobs: import("./module.ts").SchemaModule;

package/dist/src/schema/modules.js

@@ -20,6 +20,22 @@ export const partman = defineSchemaModule({
     extensions: ["partman"],
     beforeReset: "before-reset.sql",
 });
+/** Schema `slug`: `slug.slug(name)`, a name's URL slug (NFC, lowercase
+ *  alphanumerics, spaces as `-`), immutable. */
+export const slug = defineSchemaModule({
+    name: "slug",
+    root: resolve(SQL_DIR, "slug"),
+    files: ["schema.sql"],
+});
+/** Schema `taskclaim`: table `taskclaim.claim`, one claim per task key,
+ *  for `@astralarium/repo-postgres/queue`, and `taskclaim.delete_expired()`;
+ *  a snapshot's scrub empties it. */
+export const taskclaim = defineSchemaModule({
+    name: "taskclaim",
+    root: resolve(SQL_DIR, "taskclaim"),
+    files: ["schema.sql"],
+    scrub: "scrub.sql",
+});
 /** pg_trgm, for trigram (name) search. */
 export const trgm = defineSchemaModule({
     name: "trgm",
@@ -46,3 +62,10 @@ export const cron = defineSchemaModule({
         "cron.use_background_workers=on",
     ],
 });
+/** pg_cron job `taskclaim-ttl`: `taskclaim.delete_expired()` hourly. */
+export const taskclaimJobs = defineSchemaModule({
+    name: "taskclaim-jobs",
+    root: resolve(SQL_DIR, "taskclaim/jobs"),
+    files: ["schema.sql"],
+    requires: [cron, taskclaim],
+});

package/dist/testkit/index.d.ts

@@ -1,6 +1,7 @@
-/** Test support: transactions that roll back, and Vitest hooks for
- *  Postgres.js under workerd. */
+/** Test support: transactions that roll back, advisory locks, and Vitest
+ *  hooks for Postgres.js under workerd. */
 import type { Sql, TransactionSql } from "../src/sql.ts";
+export { type AdvisoryLock, backendPid, type HeldTransaction, holdTransaction, lockHolders, lockWaiters, } from "./locks.ts";
 /** Runs `fn` in a transaction that always rolls back; resolves to its result. */
 export declare function rolledBack<T>(sql: Sql, fn: (tx: TransactionSql) => Promise<T>): Promise<T>;
 /** Vitest `onUnhandledError` dropping only Postgres.js's close/read race

package/dist/testkit/index.js

@@ -1,3 +1,4 @@
+export { backendPid, holdTransaction, lockHolders, lockWaiters, } from "./locks.js";
 /** Thrown out of `rolledBack`'s transaction to roll it back. */
 class Rollback extends Error {
     result;

package/dist/testkit/locks.d.ts

@@ -0,0 +1,27 @@
+/** Observing and holding Postgres advisory locks. */
+import type { Fragment, Sql, TransactionSql } from "../src/sql.ts";
+/** SQL of an advisory lock's bigint key, as its lock call computes it
+ *  (e.g. `hashtextextended(name, 0)`). */
+export type AdvisoryLock = (sql: Sql | TransactionSql) => Fragment;
+/** A transaction `holdTransaction` keeps open. */
+export interface HeldTransaction {
+    /** Backend pid of the holding session. */
+    holder: number;
+    /** Lets the transaction end. */
+    release: () => void;
+    /** The transaction's end. */
+    done: Promise<unknown>;
+}
+/** Backend pid of `sql`'s session. */
+export declare function backendPid(sql: Sql | TransactionSql): Promise<number>;
+/** Backend pids of the sessions waiting on `lock` behind session `holder`
+ *  (a backend pid). */
+export declare function lockWaiters(sql: Sql, lock: AdvisoryLock, holder: number): Promise<number[]>;
+/** Backend pids of the sessions holding `lock`, in either mode. */
+export declare function lockHolders(sql: Sql, lock: AdvisoryLock): Promise<number[]>;
+/**
+ * A transaction holding its locks until `release`. `transaction` opens it
+ * and calls `hold` once it takes them; resolves once `hold` runs, and
+ * rejects when the transaction ends first.
+ */
+export declare function holdTransaction(transaction: (hold: (sql: TransactionSql) => Promise<void>) => Promise<unknown>): Promise<HeldTransaction>;

package/dist/testkit/locks.js

@@ -0,0 +1,57 @@
+/** Backend pid of `sql`'s session. */
+export async function backendPid(sql) {
+    const [row] = await sql `SELECT pg_backend_pid() AS pid`;
+    if (!row)
+        throw new Error("no backend pid");
+    return row.pid;
+}
+/** `pg_locks` condition: the row is of `lock`. */
+function isLock(sql, lock) {
+    const key = lock(sql);
+    return sql `
+    locktype = 'advisory'
+    AND classid = ((${key} >> 32) & 4294967295)::oid
+    AND objid = (${key} & 4294967295)::oid
+    AND objsubid = 1
+  `;
+}
+/** Backend pids of the sessions waiting on `lock` behind session `holder`
+ *  (a backend pid). */
+export async function lockWaiters(sql, lock, holder) {
+    const rows = await sql `
+    SELECT pid FROM pg_locks
+    WHERE ${isLock(sql, lock)}
+      AND NOT granted
+      AND ${holder}::integer = ANY(pg_blocking_pids(pid))
+  `;
+    return rows.map((x) => x.pid);
+}
+/** Backend pids of the sessions holding `lock`, in either mode. */
+export async function lockHolders(sql, lock) {
+    const rows = await sql `
+    SELECT pid FROM pg_locks
+    WHERE ${isLock(sql, lock)}
+      AND granted
+  `;
+    return rows.map((x) => x.pid);
+}
+/**
+ * A transaction holding its locks until `release`. `transaction` opens it
+ * and calls `hold` once it takes them; resolves once `hold` runs, and
+ * rejects when the transaction ends first.
+ */
+export async function holdTransaction(transaction) {
+    let release = () => undefined;
+    const released = new Promise((resolve) => (release = resolve));
+    let taken = (_) => undefined;
+    const holding = new Promise((resolve) => (taken = resolve));
+    const done = transaction(async (sql) => {
+        taken(await backendPid(sql));
+        await released;
+    });
+    const holder = await Promise.race([
+        holding,
+        done.then(() => Promise.reject(new Error("transaction ended before holding"))),
+    ]);
+    return { holder, release, done };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astralarium/repo-postgres",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "MIT",
   "homepage": "https://github.com/astralarium/repo/tree/main/packages/repo-postgres#readme",
   "repository": {
@@ -21,6 +21,7 @@
   },
   "exports": {
     "./provision": "./dist/src/provision/index.js",
+    "./queue": "./dist/src/queue.js",
     "./schema": "./dist/src/schema/index.js",
     "./sql": "./dist/src/sql.js",
     "./testkit": "./dist/testkit/index.js",
@@ -32,19 +33,19 @@
   "dependencies": {
     "postgres": "^3.4.9",
     "zod": "^4.6.7",
-    "@astralarium/repo-telemetry": "^0.1.0",
     "@astralarium/repo-package-files": "^0.1.0",
-    "@astralarium/repo-dev": "^0.1.0",
-    "@astralarium/repo-deploy-info": "^0.1.0"
+    "@astralarium/repo-deploy-info": "^0.1.1",
+    "@astralarium/repo-dev": "^0.1.1",
+    "@astralarium/repo-telemetry": "^0.2.0"
   },
   "devDependencies": {
     "@types/node": "^24.2.0",
     "eslint": "^10.2.1",
     "typescript": "^6.0.3",
     "vitest": "^5.0.3",
-    "@astralarium/repo-config-eslint": "^0.1.0",
-    "@astralarium/repo-config-typescript": "^0.1.0",
-    "@astralarium/repo-config-vitest": "^0.1.0"
+    "@astralarium/repo-config-vitest": "^0.2.0",
+    "@astralarium/repo-config-eslint": "^0.3.0",
+    "@astralarium/repo-config-typescript": "^0.1.0"
   },
   "peerDependencies": {
     "vitest": "^5.0.3"

package/sql/slug/schema.sql

@@ -0,0 +1,25 @@
+-- `slug.slug(name)`: the URL slug of a name: lowercase letters and digits,
+-- spaces as `-`, other characters dropped. `O'Brien` → `obrien`;
+-- `Room 52` → `room-52`. Names normalize to NFC first: decomposed and
+-- composed spellings slug alike. Case and letter classes follow Unicode
+-- (`pg_c_utf8`), whatever the database's or argument's collation.
+SET ROLE app_admin;
+
+CREATE SCHEMA slug AUTHORIZATION app_admin;
+
+GRANT USAGE ON SCHEMA slug TO app_service;
+
+CREATE FUNCTION slug.slug(name text) RETURNS text
+LANGUAGE SQL IMMUTABLE PARALLEL SAFE
+RETURN replace(
+  regexp_replace(
+    lower(normalize(name, NFC) COLLATE pg_c_utf8),
+    '[^[:alnum:] ]',
+    '',
+    'g'
+  ),
+  ' ',
+  '-'
+);
+
+SET ROLE NONE;

package/sql/taskclaim/jobs/schema.sql

@@ -0,0 +1,19 @@
+-- taskclaim's pg_cron job: hourly `taskclaim.delete_expired()`. Skipped
+-- where pg_cron is not loaded.
+DO $$
+BEGIN
+  IF current_setting('cron.database_name', true) IS NULL THEN
+    RAISE NOTICE 'pg_cron is not loaded; skipping taskclaim jobs';
+    RETURN;
+  END IF;
+
+  PERFORM cron.schedule(
+    'taskclaim-ttl',
+    '15 * * * *',
+    $job$
+      SET statement_timeout = '30s';
+      SELECT taskclaim.delete_expired();
+    $job$
+  );
+END;
+$$;

package/sql/taskclaim/schema.sql

@@ -0,0 +1,41 @@
+-- Task claims in schema `taskclaim`: one row per task key, de-duplicating
+-- queued tasks (`@astralarium/repo-postgres/queue`), and expired-claim
+-- cleanup.
+SET ROLE app_admin;
+
+CREATE SCHEMA taskclaim AUTHORIZATION app_admin;
+
+GRANT USAGE ON SCHEMA taskclaim TO app_service;
+
+CREATE TABLE taskclaim.claim
+(
+  key        text PRIMARY KEY,
+  -- End of the claim; past it, a claim of the key replaces the row.
+  expires_at timestamptz NOT NULL,
+  -- Token of the claiming task, carried in its queue message.
+  token      uuid NOT NULL
+);
+CREATE INDEX claim_expires_at_idx ON taskclaim.claim (expires_at);
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON taskclaim.claim TO app_service;
+
+-- Deletes expired claims; their count. Reserved for the owner;
+-- `taskclaimJobs` schedules it.
+CREATE FUNCTION taskclaim.delete_expired()
+RETURNS bigint
+LANGUAGE plpgsql
+SET search_path = pg_catalog
+AS $$
+DECLARE
+  deleted bigint;
+BEGIN
+  DELETE FROM taskclaim.claim WHERE expires_at < CURRENT_TIMESTAMP;
+  GET DIAGNOSTICS deleted = ROW_COUNT;
+  RETURN deleted;
+END;
+$$;
+
+COMMENT ON FUNCTION taskclaim.delete_expired() IS 'Deletes expired claims.';
+REVOKE ALL ON FUNCTION taskclaim.delete_expired() FROM PUBLIC;
+
+SET ROLE NONE;

package/sql/taskclaim/scrub.sql

@@ -0,0 +1,3 @@
+-- Snapshot scrub: claims name tasks queued in the source environment; their
+-- messages stay behind there. taskclaim's `scrub`.
+TRUNCATE taskclaim.claim;