@hyperfixation/core 0.1.0

package/dist/status-route.d.ts

@@ -0,0 +1,29 @@
+import type { Pool } from "pg";
+import type { StatusOptions, StatusReport } from "./status.js";
+/** The three routes, relative to wherever the app mounts them. */
+export type StatusRoute = "status" | "pause" | "resume";
+/** `hf_app_state.paused_by` and the audit row's actor when the write token did it. */
+export declare const STATUS_TOKEN_ACTOR = "status-token";
+export interface StatusRouteHandlers {
+    status(): Promise<StatusReport>;
+    pause(): Promise<unknown>;
+    resume(): Promise<unknown>;
+}
+export interface StatusHandlerOptions extends StatusOptions {
+    pool: Pool;
+    handlers: StatusRouteHandlers;
+}
+/**
+ * Matched on the suffix rather than on a fixed prefix: the app owns where it mounts these, and
+ * the template's `app/api/status/route.ts` is only the default.
+ */
+export declare function statusRouteOf(pathname: string): StatusRoute | undefined;
+/**
+ * `GET /api/status` under the read token; `POST /api/status/pause` and `/resume` under the
+ * write token. A write token reads too — it is strictly the more privileged of the two, and a
+ * deploy check that had to carry both would be two secrets where one will do.
+ *
+ * Every refusal answers the same way whether the token was wrong, missing or unconfigured, and
+ * the comparison itself is `timingSafeEqual` against the stored hash.
+ */
+export declare function createStatusHandler(options: StatusHandlerOptions): (request: Request) => Promise<Response>;

package/dist/status-route.js

@@ -0,0 +1,61 @@
+import { bearerToken, statusTokenMatches } from "./status-token.js";
+/** `hf_app_state.paused_by` and the audit row's actor when the write token did it. */
+export const STATUS_TOKEN_ACTOR = "status-token";
+const TOKEN_HASHES_STATEMENT = "SELECT read_token_hash, write_token_hash FROM hf_app_state WHERE id = 1";
+/**
+ * Matched on the suffix rather than on a fixed prefix: the app owns where it mounts these, and
+ * the template's `app/api/status/route.ts` is only the default.
+ */
+export function statusRouteOf(pathname) {
+    const trimmed = pathname.replace(/\/+$/, "");
+    if (trimmed.endsWith("/status"))
+        return "status";
+    if (trimmed.endsWith("/status/pause"))
+        return "pause";
+    if (trimmed.endsWith("/status/resume"))
+        return "resume";
+    return undefined;
+}
+/**
+ * `GET /api/status` under the read token; `POST /api/status/pause` and `/resume` under the
+ * write token. A write token reads too — it is strictly the more privileged of the two, and a
+ * deploy check that had to carry both would be two secrets where one will do.
+ *
+ * Every refusal answers the same way whether the token was wrong, missing or unconfigured, and
+ * the comparison itself is `timingSafeEqual` against the stored hash.
+ */
+export function createStatusHandler(options) {
+    return async (request) => {
+        const route = statusRouteOf(new URL(request.url).pathname);
+        if (route === undefined)
+            return json({ error: "not found" }, 404);
+        const method = route === "status" ? "GET" : "POST";
+        if (request.method !== method) {
+            return json({ error: `${route} is ${method}` }, 405, { allow: method });
+        }
+        if (!(await authorized(options.pool, request, route))) {
+            return json({ error: "unauthorized" }, 401, { "www-authenticate": "Bearer" });
+        }
+        if (route === "status")
+            return json(await options.handlers.status(), 200);
+        const result = route === "pause" ? await options.handlers.pause() : await options.handlers.resume();
+        return json(result, 200);
+    };
+}
+async function authorized(pool, request, route) {
+    const presented = bearerToken(request);
+    const { rows } = await pool.query(TOKEN_HASHES_STATEMENT);
+    const hashes = rows[0];
+    // Both comparisons run on a read so that a valid read token and a valid write token take the
+    // same path; neither short-circuits on the other's result.
+    const write = statusTokenMatches(presented, hashes?.write_token_hash);
+    if (route !== "status")
+        return write;
+    return statusTokenMatches(presented, hashes?.read_token_hash) || write;
+}
+function json(body, status, headers = {}) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json", "cache-control": "no-store", ...headers },
+    });
+}

package/dist/status-token.d.ts

@@ -0,0 +1,19 @@
+/** What `hf_app_state.read_token_hash` and `write_token_hash` hold. */
+export declare const STATUS_TOKEN_DIGEST = "sha256";
+/**
+ * The stored form of a status token. Hashing is not only about the database: it also makes the
+ * comparison fixed-width, which is what lets `timingSafeEqual` — which throws on a length
+ * mismatch — be used on a value an attacker chooses the length of.
+ */
+export declare function hashStatusToken(token: string): string;
+/**
+ * Constant-time against the stored hash. Every "no" that is not about the bytes — no token
+ * presented, no hash configured, a hash that is not a `sha256` digest — is answered before the
+ * comparison and is not timing-sensitive: none of them depends on the presented token.
+ *
+ * An app with no hash configured is refused rather than opened: an unset token is a
+ * misconfiguration, and the status endpoint can pause the app.
+ */
+export declare function statusTokenMatches(presented: string | null | undefined, storedHash: string | null | undefined): boolean;
+/** `Authorization: Bearer <token>`, and nothing else — a token in a query string is logged. */
+export declare function bearerToken(request: Request): string | null;

package/dist/status-token.js

@@ -0,0 +1,40 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+/** What `hf_app_state.read_token_hash` and `write_token_hash` hold. */
+export const STATUS_TOKEN_DIGEST = "sha256";
+const DIGEST_BYTES = 32;
+/**
+ * The stored form of a status token. Hashing is not only about the database: it also makes the
+ * comparison fixed-width, which is what lets `timingSafeEqual` — which throws on a length
+ * mismatch — be used on a value an attacker chooses the length of.
+ */
+export function hashStatusToken(token) {
+    return createHash(STATUS_TOKEN_DIGEST).update(token, "utf8").digest("hex");
+}
+/**
+ * Constant-time against the stored hash. Every "no" that is not about the bytes — no token
+ * presented, no hash configured, a hash that is not a `sha256` digest — is answered before the
+ * comparison and is not timing-sensitive: none of them depends on the presented token.
+ *
+ * An app with no hash configured is refused rather than opened: an unset token is a
+ * misconfiguration, and the status endpoint can pause the app.
+ */
+export function statusTokenMatches(presented, storedHash) {
+    if (presented === null || presented === undefined || presented === "")
+        return false;
+    if (storedHash === null || storedHash === undefined)
+        return false;
+    const stored = Buffer.from(storedHash, "hex");
+    // `Buffer.from` truncates at the first non-hex character rather than throwing, so a mangled
+    // hash arrives here short; nothing of digest length can be produced that way by accident.
+    if (stored.length !== DIGEST_BYTES)
+        return false;
+    return timingSafeEqual(createHash(STATUS_TOKEN_DIGEST).update(presented, "utf8").digest(), stored);
+}
+/** `Authorization: Bearer <token>`, and nothing else — a token in a query string is logged. */
+export function bearerToken(request) {
+    const header = request.headers.get("authorization");
+    if (header === null)
+        return null;
+    const match = /^Bearer (.+)$/i.exec(header.trim());
+    return match === null ? null : match[1];
+}

package/dist/status.d.ts

@@ -0,0 +1,45 @@
+import type { RunStatus } from "@hyperfixation/db";
+import type { Pool } from "pg";
+/** This package's own version, which `/api/status` reports as the core the app runs. */
+export declare const CORE_VERSION: string;
+export interface QueueStatus {
+    name: string;
+    /** `null` when the queue is registered with no global limit. */
+    globalConcurrency: number | null;
+    enqueued: number;
+    running: number;
+}
+export interface PeriodStatus {
+    period: string;
+    budgetUsd: string;
+    spentUsd: string;
+    /** `SUM(cost_usd)` of the period's `ok` rows, for the drift below. */
+    ledgerUsd: string;
+    driftUsd: string;
+}
+export interface StatusReport {
+    /** `degraded` when there are anomalies or any period's spend disagrees with its ledger. */
+    health: "ok" | "degraded";
+    app: string;
+    applicationVersion: string | null;
+    coreVersion: string;
+    paused: boolean;
+    pausedBy: string | null;
+    runs: Record<RunStatus, number>;
+    queues: QueueStatus[];
+    approvals: Record<string, number>;
+    llmCalls: Record<string, number>;
+    actions: Record<string, number>;
+    budget: {
+        current: PeriodStatus | null;
+        previous: PeriodStatus | null;
+    };
+    anomalies: number;
+    at: string;
+}
+export interface StatusOptions {
+    app: string;
+    applicationVersion: string | null;
+}
+/** What `GET /api/status` answers with, and what `hf doctor` reads. */
+export declare function appStatus(pool: Pool, options: StatusOptions): Promise<StatusReport>;

package/dist/status.js

@@ -0,0 +1,99 @@
+import { createRequire } from "node:module";
+/** This package's own version, which `/api/status` reports as the core the app runs. */
+export const CORE_VERSION = createRequire(import.meta.url)("../package.json").version;
+/**
+ * Every read here is a plain `SELECT` and none of them locks anything — in particular not a
+ * budget row, which is the one thing the lock order forbids any of these paths to take.
+ */
+const STATE_STATEMENT = "SELECT paused, paused_by, budget_usd::text AS budget_usd FROM hf_app_state WHERE id = 1";
+const PERIODS_STATEMENT = "SELECT to_char(date_trunc('month', now() AT TIME ZONE 'UTC'), 'YYYY-MM') AS current_period, " +
+    "to_char(date_trunc('month', now() AT TIME ZONE 'UTC') - interval '1 month', 'YYYY-MM') " +
+    "AS previous_period";
+const RUN_COUNTS_STATEMENT = "SELECT status, count(*)::int AS n FROM hf_run GROUP BY status";
+const APPROVAL_COUNTS_STATEMENT = "SELECT status, count(*)::int AS n FROM hf_approval GROUP BY status";
+const LEDGER_COUNTS_STATEMENT = "SELECT status, count(*)::int AS n FROM hf_llm_call GROUP BY status";
+const ACTION_COUNTS_STATEMENT = "SELECT status, count(*)::int AS n FROM hf_action_log GROUP BY status";
+/**
+ * Queue depth from the workflow rows rather than from any counter: `ENQUEUED` is waiting and
+ * `PENDING` is dispatched, and a queue whose concurrency is zero shows the backlog a pause is
+ * holding back. Joined against `dbos.queues` so a queue with nothing on it still appears.
+ */
+const QUEUES_STATEMENT = "SELECT q.name, COALESCE(q.concurrency, -1)::int AS global_concurrency, " +
+    "COALESCE(SUM((w.status = 'ENQUEUED')::int), 0)::int AS enqueued, " +
+    "COALESCE(SUM((w.status = 'PENDING')::int), 0)::int AS running " +
+    "FROM dbos.queues q LEFT JOIN dbos.workflow_status w ON w.queue_name = q.name " +
+    "AND w.status IN ('ENQUEUED', 'PENDING') GROUP BY q.name, q.concurrency ORDER BY q.name";
+/**
+ * Per-period spend against budget, with the exact drift `reconcile()` reports and never
+ * corrects: a call is billed to the period stamped on its own row, so this comparison is not
+ * an estimate.
+ */
+const BUDGET_STATEMENT = "SELECT b.period, b.budget_usd::text AS budget_usd, b.spent_usd::text AS spent_usd, " +
+    "COALESCE((SELECT SUM(l.cost_usd) FROM hf_llm_call l " +
+    "WHERE l.period = b.period AND l.status = 'ok'), 0)::text AS ledger_usd " +
+    "FROM hf_budget_period b WHERE b.period = ANY($1::text[])";
+/**
+ * `reconcile()`'s step (1) invariant violation, counted live rather than accumulated: a
+ * `running` run with no `dbos.workflow_status` row at all cannot happen, because every path
+ * that writes `current_workflow_id` enqueues in the same transaction.
+ */
+const ANOMALIES_STATEMENT = "SELECT count(*)::int AS n FROM hf_run r " +
+    "LEFT JOIN dbos.workflow_status w ON w.workflow_uuid = r.current_workflow_id " +
+    "WHERE r.status = 'running' AND w.workflow_uuid IS NULL";
+const RUN_STATUSES = ["running", "waiting", "paused", "done", "failed"];
+/** What `GET /api/status` answers with, and what `hf doctor` reads. */
+export async function appStatus(pool, options) {
+    const [state, periods, runs, approvals, llmCalls, actions, queues, anomalies] = await Promise.all([
+        pool.query(STATE_STATEMENT),
+        pool.query(PERIODS_STATEMENT),
+        counts(pool, RUN_COUNTS_STATEMENT),
+        counts(pool, APPROVAL_COUNTS_STATEMENT),
+        counts(pool, LEDGER_COUNTS_STATEMENT),
+        counts(pool, ACTION_COUNTS_STATEMENT),
+        pool.query(QUEUES_STATEMENT),
+        pool.query(ANOMALIES_STATEMENT),
+    ]);
+    const { current_period: current, previous_period: previous } = periods.rows[0];
+    const budget = await pool.query(BUDGET_STATEMENT, [[current, previous]]);
+    const periodStatus = (period) => {
+        const row = budget.rows.find((candidate) => candidate.period === period);
+        if (row === undefined)
+            return null;
+        return {
+            period: row.period,
+            budgetUsd: row.budget_usd,
+            spentUsd: row.spent_usd,
+            ledgerUsd: row.ledger_usd,
+            driftUsd: (Number(row.spent_usd) - Number(row.ledger_usd)).toFixed(6),
+        };
+    };
+    const budgetStatus = { current: periodStatus(current), previous: periodStatus(previous) };
+    const drifting = [budgetStatus.current, budgetStatus.previous].some((period) => period !== null && Number(period.driftUsd) !== 0);
+    const anomalyCount = anomalies.rows[0].n;
+    return {
+        health: anomalyCount === 0 && !drifting ? "ok" : "degraded",
+        app: options.app,
+        applicationVersion: options.applicationVersion,
+        coreVersion: CORE_VERSION,
+        paused: state.rows[0]?.paused ?? false,
+        pausedBy: state.rows[0]?.paused_by ?? null,
+        runs: Object.fromEntries(RUN_STATUSES.map((status) => [status, runs[status] ?? 0])),
+        queues: queues.rows.map((row) => ({
+            name: row.name,
+            // `-1` is the COALESCE above standing in for a NULL `concurrency`, which is "no limit".
+            globalConcurrency: row.global_concurrency < 0 ? null : row.global_concurrency,
+            enqueued: row.enqueued,
+            running: row.running,
+        })),
+        approvals,
+        llmCalls,
+        actions,
+        budget: budgetStatus,
+        anomalies: anomalyCount,
+        at: new Date().toISOString(),
+    };
+}
+async function counts(pool, statement) {
+    const { rows } = await pool.query(statement);
+    return Object.fromEntries(rows.map((row) => [row.status, row.n]));
+}

package/dist/step-client.d.ts

@@ -0,0 +1,8 @@
+import type { StepDatabase } from "@hyperfixation/db";
+import type { ClientBase } from "pg";
+/**
+ * The open, fenced client behind a `ctx.tx` handle. `StepDatabase`'s type omits `$client`, so
+ * the cast is how the step-side helpers issue the positional-parameter SQL the rest of this
+ * package is written in — `loader.ts` reaches for it the same way.
+ */
+export declare function stepClient(db: StepDatabase): ClientBase;

package/dist/step-client.js

@@ -0,0 +1,8 @@
+/**
+ * The open, fenced client behind a `ctx.tx` handle. `StepDatabase`'s type omits `$client`, so
+ * the cast is how the step-side helpers issue the positional-parameter SQL the rest of this
+ * package is written in — `loader.ts` reaches for it the same way.
+ */
+export function stepClient(db) {
+    return db.$client;
+}

package/dist/tasks.d.ts

@@ -0,0 +1,96 @@
+import { type RecordTable } from "@hyperfixation/db";
+import type { StepContext } from "@hyperfixation/workflows";
+import type { ClientBase, Pool } from "pg";
+import type { Registry } from "./registry.js";
+export declare const TASK_CREATE_MANUAL_OPERATION = "tasks.createManual";
+export declare const TASK_COMPLETE_OPERATION = "tasks.complete";
+export declare const TASK_CANCEL_OPERATION = "tasks.cancel";
+export declare const TASK_LIST_OPERATION = "tasks.list";
+/** The columns `taskRowOf` maps, shared with the workspace's own `hf_task` reads. */
+export declare const TASK_COLUMNS = "id, record_type, record_id, title, due_at, owner_id, done_at, cancelled_at, origin, created_at";
+export interface TaskTarget {
+    recordType?: string;
+    recordId?: string | number;
+}
+export interface TaskCreateOptions extends TaskTarget {
+    title: string;
+    dueAt?: Date;
+    ownerId?: string;
+    /** Distinguishes two tasks one step opens; defaults to the step's key. */
+    key?: string;
+}
+export interface TaskCreateManualOptions extends TaskTarget {
+    title: string;
+    dueAt?: Date;
+    ownerId?: string;
+    userId?: string;
+}
+export interface TaskCreated {
+    id: number;
+    /** False when a replay found the task its own `origin_ref` had already opened. */
+    created: boolean;
+}
+export interface TaskCloseOptions {
+    id: number;
+    userId?: string;
+}
+export interface TaskClosed {
+    id: number;
+    /** False when the task was already done or cancelled; nothing was written. */
+    changed: boolean;
+}
+export interface TaskListOptions {
+    recordType?: string;
+    recordId?: string | number;
+    ownerId?: string;
+    /** True for tasks neither done nor cancelled, false for the rest, omitted for both. */
+    open?: boolean;
+}
+export interface TaskRow {
+    id: number;
+    recordType: string | null;
+    recordId: string | null;
+    title: string;
+    dueAt: Date | null;
+    ownerId: string | null;
+    doneAt: Date | null;
+    cancelledAt: Date | null;
+    origin: string;
+    createdAt: Date;
+}
+export interface TaskQueryRow {
+    id: string;
+    record_type: string | null;
+    record_id: string | null;
+    title: string;
+    due_at: Date | null;
+    owner_id: string | null;
+    done_at: Date | null;
+    cancelled_at: Date | null;
+    origin: string;
+    created_at: Date;
+}
+/**
+ * The colon keeps a flow task's `origin_ref` disjoint from `actions.perform`'s, which is the bare
+ * `hf_action_log` id on the same partial unique index.
+ */
+export declare function flowOriginRef(runId: string, key: string): string;
+/**
+ * A task a flow opens, inside `ctx.tx`. Keyed by `(run_id, step key)` through `origin_ref`, so
+ * attempt 2 re-running the step finds its own task rather than opening a second one.
+ *
+ * The record type is checked against the registry here rather than at the next boot: a task
+ * carrying a `record_type` no app registers is what E002 refuses.
+ */
+export declare function createTask(ctx: StepContext, records: Registry<RecordTable>, options: TaskCreateOptions): Promise<TaskCreated>;
+/** A task a human opens from the workspace: no run, no `origin_ref`, so no replay to survive. */
+export declare function createManualTask(pool: Pool, records: Registry<RecordTable>, options: TaskCreateManualOptions): Promise<TaskCreated>;
+export declare function completeTask(pool: Pool, options: TaskCloseOptions): Promise<TaskClosed>;
+export declare function cancelTask(pool: Pool, options: TaskCloseOptions): Promise<TaskClosed>;
+export declare function listTasks(pool: Pool, options?: TaskListOptions): Promise<TaskRow[]>;
+export declare function taskRowOf(row: TaskQueryRow): TaskRow;
+/**
+ * Every open task on a record, cancelled in one statement. Called from inside
+ * `records.archive()`'s transaction, which already holds the record's own row.
+ */
+export declare function cancelOpenTasksForRecord(queryable: Pool | ClientBase, recordType: string, recordId: string): Promise<number[]>;

package/dist/tasks.js

@@ -0,0 +1,151 @@
+import { assertNotInWorkflow, controlPlaneTx } from "@hyperfixation/db";
+import { insertActivity } from "./activity.js";
+import { stepClient } from "./step-client.js";
+export const TASK_CREATE_MANUAL_OPERATION = "tasks.createManual";
+export const TASK_COMPLETE_OPERATION = "tasks.complete";
+export const TASK_CANCEL_OPERATION = "tasks.cancel";
+export const TASK_LIST_OPERATION = "tasks.list";
+const INSERT_TASK_STATEMENT = "INSERT INTO hf_task (record_type, record_id, title, due_at, owner_id, origin, origin_ref) " +
+    "VALUES ($1, $2, $3, $4, $5, $6, $7) " +
+    "ON CONFLICT (origin, origin_ref) WHERE origin_ref IS NOT NULL DO NOTHING RETURNING id";
+const EXISTING_TASK_STATEMENT = "SELECT id FROM hf_task WHERE origin = $1 AND origin_ref = $2 ORDER BY id LIMIT 1";
+/** Only an open task closes; a second call changes nothing and writes no activity row. */
+const CLOSE_TASK_STATEMENT = (column) => `UPDATE hf_task SET ${column} = now() WHERE id = $1 AND done_at IS NULL AND cancelled_at IS NULL ` +
+    "RETURNING record_type, record_id";
+const CANCEL_OPEN_TASKS_STATEMENT = "UPDATE hf_task SET cancelled_at = now() WHERE record_type = $1 AND record_id = $2 " +
+    "AND done_at IS NULL AND cancelled_at IS NULL RETURNING id";
+/** The columns `taskRowOf` maps, shared with the workspace's own `hf_task` reads. */
+export const TASK_COLUMNS = "id, record_type, record_id, title, due_at, owner_id, done_at, cancelled_at, origin, created_at";
+// One statement for every filter combination: a null parameter is "no filter", which keeps the
+// shape of the query — and so its plan — the same however the workspace calls it.
+const LIST_TASKS_STATEMENT = `SELECT ${TASK_COLUMNS} FROM hf_task WHERE ($1::text IS NULL OR record_type = $1) ` +
+    "AND ($2::text IS NULL OR record_id = $2) AND ($3::text IS NULL OR owner_id = $3) " +
+    "AND ($4::boolean IS NULL OR (done_at IS NULL AND cancelled_at IS NULL) = $4) ORDER BY id";
+/**
+ * The colon keeps a flow task's `origin_ref` disjoint from `actions.perform`'s, which is the bare
+ * `hf_action_log` id on the same partial unique index.
+ */
+export function flowOriginRef(runId, key) {
+    return `${runId}:${key}`;
+}
+/**
+ * A task a flow opens, inside `ctx.tx`. Keyed by `(run_id, step key)` through `origin_ref`, so
+ * attempt 2 re-running the step finds its own task rather than opening a second one.
+ *
+ * The record type is checked against the registry here rather than at the next boot: a task
+ * carrying a `record_type` no app registers is what E002 refuses.
+ */
+export async function createTask(ctx, records, options) {
+    const target = requireTarget(records, options);
+    const key = options.key ?? ctx.key;
+    const originRef = flowOriginRef(ctx.runId, key);
+    return ctx.tx(async (db) => {
+        const client = stepClient(db);
+        const task = await insertTask(client, options, "flow", originRef);
+        // Written whether or not the insert conflicted: its own key is what makes it once-only.
+        await insertActivity(client, {
+            ...target,
+            kind: "task.created",
+            runId: ctx.runId,
+            key: `${key}:task.created`,
+            meta: { taskId: task.id, origin: "flow", originRef, title: options.title },
+        });
+        return task;
+    });
+}
+/** A task a human opens from the workspace: no run, no `origin_ref`, so no replay to survive. */
+export async function createManualTask(pool, records, options) {
+    const target = requireTarget(records, options);
+    return controlPlaneTx(pool, { operation: TASK_CREATE_MANUAL_OPERATION }, async (work) => {
+        const task = await insertTask(work, options, "manual", null);
+        await insertActivity(work, {
+            ...target,
+            kind: "task.created",
+            actorId: options.userId ?? null,
+            meta: { taskId: task.id, origin: "manual", title: options.title },
+        });
+        return task;
+    });
+}
+export function completeTask(pool, options) {
+    return closeTask(pool, options, TASK_COMPLETE_OPERATION, "done_at", "task.completed");
+}
+export function cancelTask(pool, options) {
+    return closeTask(pool, options, TASK_CANCEL_OPERATION, "cancelled_at", "task.cancelled");
+}
+export async function listTasks(pool, options = {}) {
+    assertNotInWorkflow(TASK_LIST_OPERATION);
+    const { rows } = await pool.query(LIST_TASKS_STATEMENT, [
+        options.recordType ?? null,
+        options.recordId === undefined ? null : String(options.recordId),
+        options.ownerId ?? null,
+        options.open ?? null,
+    ]);
+    return rows.map(taskRowOf);
+}
+export function taskRowOf(row) {
+    return {
+        id: Number(row.id),
+        recordType: row.record_type,
+        recordId: row.record_id,
+        title: row.title,
+        dueAt: row.due_at,
+        ownerId: row.owner_id,
+        doneAt: row.done_at,
+        cancelledAt: row.cancelled_at,
+        origin: row.origin,
+        createdAt: row.created_at,
+    };
+}
+/**
+ * Every open task on a record, cancelled in one statement. Called from inside
+ * `records.archive()`'s transaction, which already holds the record's own row.
+ */
+export async function cancelOpenTasksForRecord(queryable, recordType, recordId) {
+    const { rows } = await queryable.query(CANCEL_OPEN_TASKS_STATEMENT, [
+        recordType,
+        recordId,
+    ]);
+    return rows.map((row) => Number(row.id));
+}
+async function closeTask(pool, options, operation, column, kind) {
+    return controlPlaneTx(pool, { operation }, async (work) => {
+        const closed = await work.query(CLOSE_TASK_STATEMENT(column), [options.id]);
+        const row = closed.rows[0];
+        if (row === undefined)
+            return { id: options.id, changed: false };
+        await insertActivity(work, {
+            recordType: row.record_type,
+            recordId: row.record_id,
+            kind,
+            actorId: options.userId ?? null,
+            meta: { taskId: options.id },
+        });
+        return { id: options.id, changed: true };
+    });
+}
+async function insertTask(queryable, options, origin, originRef) {
+    const inserted = await queryable.query(INSERT_TASK_STATEMENT, [
+        options.recordType ?? null,
+        options.recordId === undefined ? null : String(options.recordId),
+        options.title,
+        options.dueAt ?? null,
+        options.ownerId ?? null,
+        origin,
+        originRef,
+    ]);
+    if (inserted.rows[0] !== undefined)
+        return { id: Number(inserted.rows[0].id), created: true };
+    const found = await queryable.query(EXISTING_TASK_STATEMENT, [origin, originRef]);
+    return { id: Number(found.rows[0].id), created: false };
+}
+/** A task may carry no record; one that names a type must name a registered one. */
+function requireTarget(records, options) {
+    if (options.recordType === undefined)
+        return {};
+    records.require(options.recordType);
+    return {
+        recordType: options.recordType,
+        ...(options.recordId === undefined ? {} : { recordId: String(options.recordId) }),
+    };
+}