src/jobs-park.ts

Functions

Imports

It imports src/agents.ts, src/env.ts, src/jobs-edit.ts, src/jobs-mirror.ts, src/jobs-schema.ts, src/jobs-transition.ts. Imported by src/controls-perform.ts, src/jobs.ts.

Source

1import type { Env } from "./env";
2import type { Agent } from "./agents";
3import { outsideJobNamespace, type JobRow } from "./jobs-schema";
4import { openTitleHolder } from "./jobs-edit";
5import { jobAudit, mirrorStatements } from "./jobs-mirror";
6import { callerIsSeat, guardedTransition, readJob, refuse, type JobResult } from "./jobs-transition";
7
8// Park: a job that is wanted but not now (job_4ef99d687805, Dustin 2026-10-07), for
9// example one kept on his request until a decision comes back. A parked job is never
10// claimed (claim reads only queued rows), never planned (the overnight plan reads only
11// queued rows), and still listed and searchable: it keeps its row and its mirror.
12//
13// The seat's act, like edit: the admin or a can_merge caller, never a driver. A driver
14// that could park a job could take work out of the queue's order. Only a queued job is
15// parked. A claimed job is being worked, and a blocked one has somebody waiting on it:
16// resume or supersede those. The one-line reason ("comes back when ...") is kept in
17// result_summary, the column a blocked job already uses for why it is not moving, so
18// there is no migration, and it is cleared when the job comes back.
19//
20// Parked is not an open status (src/jobs-schema.ts): it holds no title slot, so the
21// partial unique index is unchanged and the feed, namespace delete and the watcher read
22// a parked job as they read a finished one. The price is that the same title can be
23// posted while a job is parked, so unpark refuses, naming the job, when it would put a
24// second open job under one title.
25
26const REASON_MAX = 300;
27
28/** A reason is one line: it is shown in a list, not read as a document. */
29function oneLine(reason: string | undefined): string | null {
30  const text = (reason ?? "").trim();
31  if (!text || text.length > REASON_MAX || /[\r\n]/.test(text)) return null;
32  return text;
33}
34
35export async function parkJob(env: Env, agent: Agent, now: Date, id: string, reason: string | undefined): Promise<JobResult> {
36  if (!callerIsSeat(agent)) {
37    return refuse("park", `${agent.actor} cannot park a job. Parking is the seat's act, and this caller holds neither the admin identity nor can_merge.`);
38  }
39  const why = oneLine(reason);
40  if (!why) {
41    return refuse("park", `park needs a reason in one line, at most ${REASON_MAX} characters, saying when the job comes back ("comes back when ...").`);
42  }
43  const current = await readJob(env.DB, id);
44  if (!current) return refuse("park", `no job ${id}.`);
45  const outside = outsideJobNamespace(agent, current.namespace);
46  if (outside) return refuse("park", `${agent.actor} cannot park ${id} ('${current.title}'): ${outside}`);
47  if (current.status !== "queued") {
48    return refuse(
49      "park",
50      `${id} is ${current.status}${current.claimed_by && current.status === "claimed" ? ` (held by ${current.claimed_by})` : ""}. Park changes a queued job; a claimed or blocked one has somebody on it, so resume or supersede that instead.`
51    );
52  }
53
54  const parked: JobRow = { ...current, status: "parked", result_summary: why, updated_at: now.toISOString() };
55  const won = await guardedTransition(env, current, [
56    env.DB.prepare(`UPDATE jobs SET status = 'parked', result_summary = ?2, updated_at = ?3 WHERE id = ?1 AND status = 'queued' RETURNING id`).bind(
57      id,
58      why,
59      parked.updated_at
60    ),
61    ...(await mirrorStatements(env, parked, "job-parked", agent.actor)),
62    jobAudit(env.DB, agent.actor, "job-parked", parked, { reason: why, priority: current.priority }),
63  ]);
64  if (!won) {
65    const moved = await readJob(env.DB, id);
66    return refuse("park", `${id} changed between reading it and parking it: it is now ${moved?.status ?? "gone"}. Nothing was written.`);
67  }
68  return { ok: true, action: "park", job: parked };
69}
70
71export async function unparkJob(env: Env, agent: Agent, now: Date, id: string): Promise<JobResult> {
72  if (!callerIsSeat(agent)) {
73    return refuse("unpark", `${agent.actor} cannot unpark a job. Unparking is the seat's act, and this caller holds neither the admin identity nor can_merge.`);
74  }
75  const current = await readJob(env.DB, id);
76  if (!current) return refuse("unpark", `no job ${id}.`);
77  const outside = outsideJobNamespace(agent, current.namespace);
78  if (outside) return refuse("unpark", `${agent.actor} cannot unpark ${id} ('${current.title}'): ${outside}`);
79  if (current.status !== "parked") return refuse("unpark", `${id} is ${current.status}, not parked.`);
80
81  const holder = await openTitleHolder(env.DB, current.namespace, current.title, id);
82  if (holder) {
83    return refuse(
84      "unpark",
85      `${current.namespace} already has another open job titled '${current.title}': ${holder.id} is ${holder.status}. One open job per (namespace, title), so ${id} stays parked and nothing was written.`
86    );
87  }
88
89  const queued: JobRow = { ...current, status: "queued", result_summary: null, updated_at: now.toISOString() };
90  let won: boolean;
91  try {
92    won = await guardedTransition(env, current, [
93      env.DB.prepare(`UPDATE jobs SET status = 'queued', result_summary = NULL, updated_at = ?2 WHERE id = ?1 AND status = 'parked' RETURNING id`).bind(
94        id,
95        queued.updated_at
96      ),
97      ...(await mirrorStatements(env, queued, "job-unparked", agent.actor)),
98      jobAudit(env.DB, agent.actor, "job-unparked", queued, { was: current.result_summary }),
99    ]);
100  } catch (err) {
101    // The partial unique index: another job took the title between the check and the write.
102    const message = err instanceof Error ? err.message : String(err);
103    if (/UNIQUE/i.test(message)) {
104      const taken = await openTitleHolder(env.DB, current.namespace, current.title, id).catch(() => null);
105      return refuse("unpark", `${current.namespace} took the title '${current.title}'${taken ? ` (${taken.id} is ${taken.status})` : ""} while this was being read. ${id} stays parked and nothing was written.`);
106    }
107    throw err;
108  }
109  if (!won) {
110    const moved = await readJob(env.DB, id);
111    return refuse("unpark", `${id} changed between reading it and unparking it: it is now ${moved?.status ?? "gone"}. Nothing was written.`);
112  }
113  return { ok: true, action: "unpark", job: queued };
114}