src/jobs-edit.ts

Functions

Imports

It imports src/agents.ts, src/env.ts, src/job-body-check.ts, src/job-fact-check.ts, src/jobs-claim.ts, src/jobs-mirror.ts, src/jobs-schema.ts, src/jobs-transition.ts. Imported by src/controls-plan.ts, src/jobs-park.ts, src/jobs-transition.ts, src/jobs.ts.

Source

1import type { Env } from "./env";
2import type { Agent } from "./agents";
3import { OPEN_JOB_STATUSES, outsideJobNamespace, type JobRow } from "./jobs-schema";
4import { signedJobBody } from "./jobs-claim";
5import { jobTextRefusal } from "./job-body-check";
6import { factCheckBody } from "./job-fact-check";
7import { jobAudit, mirrorStatements } from "./jobs-mirror";
8import { callerIsSeat, guardedTransition, readJob, refuse, type JobResult } from "./jobs-transition";
9
10// Edit: the seat correcting a job that nobody is working (job_4ef99d687805, Dustin
11// 2026-10-07). Before it, a posted job could not be changed, because its body is
12// signed, so every correction was a supersede and a repost.
13//
14// Only the seat (callerIsSeat: the admin or a can_merge caller), never a driver: a
15// driver that could rewrite a job's body could hand itself a different prompt under a
16// signature this Worker made. Only while the job is queued or blocked. A claimed job is
17// being worked to the body it was handed, and a finished one is history.
18//
19// A new body goes through signedJobBody, the path post uses, so it is refused for what
20// post refuses and signed as post signs it, and claim and resume verify it as they
21// verify a posted body. The version the edit replaces is copied to job_versions
22// (migrations/0033) in the same guarded batch as the UPDATE, the mirror and the audit
23// row, so a version is never lost and never kept for an edit that did not commit.
24
25const EDITABLE_STATUSES: readonly JobRow["status"][] = ["queued", "blocked"];
26
27/** One earlier version of a job, as an edit replaced it. */
28export interface JobVersion {
29  edited_by: string;
30  edited_at: string;
31  title: string;
32  // As it was stored: the signed text, frontmatter and all.
33  body: string;
34  priority: number;
35  gate_required: number;
36}
37
38const JOB_VERSIONS_MAX = 100;
39
40/** A job's earlier versions, newest first: what list returns for one named id to a
41 *  caller holding write. */
42export async function jobVersions(db: D1Database, jobId: string): Promise<JobVersion[]> {
43  const { results } = await db
44    .prepare(
45      `SELECT edited_by, edited_at, title, body, priority, gate_required FROM job_versions
46       WHERE job_id = ?1 ORDER BY id DESC LIMIT ?2`
47    )
48    .bind(jobId, JOB_VERSIONS_MAX)
49    .all<JobVersion>();
50  return results ?? [];
51}
52
53/** The other open job holding a (namespace, title), if any. */
54export async function openTitleHolder(db: D1Database, namespace: string, title: string, id: string): Promise<{ id: string; status: string } | null> {
55  const placeholders = OPEN_JOB_STATUSES.map((_, i) => `?${i + 4}`).join(", ");
56  return db
57    .prepare(`SELECT id, status FROM jobs WHERE namespace = ?1 AND title = ?2 AND id != ?3 AND status IN (${placeholders}) LIMIT 1`)
58    .bind(namespace, title, id, ...OPEN_JOB_STATUSES)
59    .first<{ id: string; status: string }>();
60}
61
62function collision(namespace: string, title: string, holder: { id: string; status: string } | null): JobResult {
63  const named = holder ? `: ${holder.id} is ${holder.status}` : "";
64  return refuse("edit", `${namespace} already has another open job titled '${title}'${named}. One open job per (namespace, title), so the edit was refused and nothing was written.`);
65}
66
67export async function editJob(
68  env: Env,
69  agent: Agent,
70  now: Date,
71  id: string,
72  args: { title?: string; body?: string; priority?: number; gate_required?: boolean }
73): Promise<JobResult> {
74  if (!callerIsSeat(agent)) {
75    return refuse(
76      "edit",
77      `${agent.actor} cannot edit a job. Changing a posted job is the seat's act, and this caller holds neither the admin identity nor can_merge.`
78    );
79  }
80  if (args.title === undefined && args.body === undefined && args.priority === undefined && args.gate_required === undefined) {
81    return refuse("edit", "edit needs at least one of title, body, priority and gate_required.");
82  }
83  const title = args.title?.trim();
84  if (args.title !== undefined && !title) {
85    return refuse("edit", "a job needs a title: it is how the queue refuses a duplicate while one is still open.");
86  }
87  // After the seat check, so a driver is told it may not edit before it is told its body is
88  // unfilled (src/job-body-check.ts).
89  const unfilled = jobTextRefusal(args.title, args.body);
90  if (unfilled) return refuse("edit", unfilled);
91  let signed: string | undefined;
92  if (args.body !== undefined) {
93    const checked = await signedJobBody(env, args.body);
94    if (!checked.ok) return refuse("edit", checked.problem);
95    signed = checked.signed;
96  }
97
98  const current = await readJob(env.DB, id);
99  if (!current) return refuse("edit", `no job ${id}.`);
100  // The job's own namespace: the tool's check saw only the namespace argument, which an
101  // id-based call may omit.
102  const outside = outsideJobNamespace(agent, current.namespace);
103  if (outside) return refuse("edit", `${agent.actor} cannot edit ${id} ('${current.title}'): ${outside}`);
104  if (!EDITABLE_STATUSES.includes(current.status)) {
105    return refuse(
106      "edit",
107      `${id} is ${current.status}${current.claimed_by && current.status === "claimed" ? ` (held by ${current.claimed_by})` : ""}. Edit changes a queued or blocked job; ${current.status === "claimed" ? "a claimed job is being worked to the body it was handed, so block or release it first" : "a finished job is not rewritten"}.`
108    );
109  }
110
111  // A new body's merged, tagged and published claims, read against GitHub and npm in the
112  // job's own namespace (src/job-fact-check.ts). A claim read as false refuses the edit; one
113  // that could not be read is a warning.
114  const facts = args.body === undefined ? { refusal: null, warnings: [] } : await factCheckBody(env, current.namespace, args.body);
115  if (facts.refusal) return refuse("edit", facts.refusal);
116
117  const edited: JobRow = {
118    ...current,
119    title: title ?? current.title,
120    body: signed ?? current.body,
121    priority: args.priority ?? current.priority,
122    gate_required: args.gate_required === undefined ? current.gate_required : args.gate_required ? 1 : 0,
123    updated_at: now.toISOString(),
124  };
125  if (edited.title !== current.title) {
126    const holder = await openTitleHolder(env.DB, current.namespace, edited.title, id);
127    if (holder) return collision(current.namespace, edited.title, holder);
128  }
129  const changed = (["title", "body", "priority", "gate_required"] as const).filter((field) => edited[field] !== current[field]);
130  // The same body signs to the same text, so an edit that restates the job is caught here
131  // rather than kept as a version identical to the row.
132  if (changed.length === 0) return refuse("edit", `${id} already reads that way. Nothing was written.`);
133
134  let won: boolean;
135  try {
136    won = await guardedTransition(env, current, [
137      env.DB.prepare(
138        `INSERT INTO job_versions (job_id, namespace, edited_by, edited_at, title, body, priority, gate_required)
139         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)`
140      ).bind(id, current.namespace, agent.actor, now.toISOString(), current.title, current.body, current.priority, current.gate_required),
141      // ?7 is the status read above, so the row is changed only in the state it was edited in.
142      env.DB.prepare(
143        `UPDATE jobs SET title = ?2, body = ?3, priority = ?4, gate_required = ?5, updated_at = ?6
144         WHERE id = ?1 AND status = ?7 RETURNING id`
145      ).bind(id, edited.title, edited.body, edited.priority, edited.gate_required, edited.updated_at, current.status),
146      ...(await mirrorStatements(env, edited, "job-edited", agent.actor)),
147      jobAudit(env.DB, agent.actor, "job-edited", edited, {
148        changed,
149        previous: { title: current.title, priority: current.priority, gate_required: current.gate_required },
150        status: current.status,
151      }),
152    ]);
153  } catch (err) {
154    // The partial unique index over (namespace, title) for open jobs: another job took
155    // the title between the check above and this write.
156    const message = err instanceof Error ? err.message : String(err);
157    if (/UNIQUE/i.test(message)) return collision(current.namespace, edited.title, await openTitleHolder(env.DB, current.namespace, edited.title, id).catch(() => null));
158    throw err;
159  }
160  if (!won) {
161    const moved = await readJob(env.DB, id);
162    return refuse(
163      "edit",
164      `${id} changed between reading it and editing it: it is now ${moved?.status ?? "gone"}${moved?.claimed_by ? `, held by ${moved.claimed_by}` : ""}. Nothing was written.`
165    );
166  }
167  return {
168    ok: true,
169    action: "edit",
170    job: edited,
171    versions: await jobVersions(env.DB, id),
172    ...(facts.warnings.length > 0 ? { warnings: facts.warnings } : {}),
173  };
174}