app/lab/runs.server.ts

Functions

Imports

It imports app/db/inventory.ts, app/db/runs.ts, app/lab/forms.mjs, app/lab/inventory.server.ts, app/lab/titles.mjs. Imported by app/routes/workspace.runs.run.tsx, app/routes/workspace.runs.tsx.

Source

1/**
2 * /lab/runs: run records with the lots they used (docs/KNOWLEDGE-BASE.md step 7, finding P2), so a bad lot traces to
3 * every run that used it.
4 *
5 * Append-only (Dustin, 2026-10-11): a saved run is never edited. A correction is a new run naming the one it replaces,
6 * recorded by the run's own author or by someone who reads all runs, and a run is replaced at most once. The tables'
7 * triggers refuse any UPDATE or DELETE whatever the code does.
8 *
9 * A new run's lot changes are writes to kb_lots, each with its kb_audit row in the same batch: the amount it used comes
10 * off the lot (in the lot's own unit), a lot first used today is marked opened, and a lot the run emptied is marked
11 * empty. A correction records the lots it used for the trace and changes no lot: a lot's amount is put right on its own
12 * page, which audits that too.
13 */
14
15import { can, type Actor } from "@dustinedwards/site-runtime/members";
16
17import { getLot, listLots, lotChange, type LotRow } from "~/db/inventory";
18import { getRun, listRunnableProcedures, listRuns, runIdByUid, runInsert, runLots, type RunRow } from "~/db/runs";
19
20import { amountOf, amountText, field, idOf, isDate, today } from "./forms.mjs";
21import { itemNames, withItem } from "./inventory.server";
22import { PERMISSION } from "./titles.mjs";
23
24export type RunResult = { ok: boolean; text: string; runId?: number };
25
26/** How many lot rows the record form offers: enough for a protocol's reagents, and the form works with no script. */
27const LOT_ROWS = 6;
28const OUTCOMES = ["completed", "failed", "abandoned"] as const;
29const NOTE_MAX = 4000;
30
31function refused(text: string): RunResult {
32  return { ok: false, text };
33}
34
35/** Whether `actor` may see `run`: their own, or every run with `read_all_runs`. */
36function canSeeRun(actor: Actor, run: Pick<RunRow, "actor">): boolean {
37  return run.actor === actor.email || can(actor, PERMISSION.readAllRuns);
38}
39
40/** The lots as a form offers them: item, lot number and what is left. */
41function lotLabels(names: Map<string, string>, lots: LotRow[]) {
42  return lots.map((l) => {
43    const item = withItem(l, names).item;
44    return { value: String(l.id), label: `${item}, lot ${l.lot_number}${l.amount !== null ? ` (${amountText(l.amount, l.unit)} left)` : ""}` };
45  });
46}
47
48export async function runsPage(env: Env, actor: Actor) {
49  const all = can(actor, PERMISSION.readAllRuns);
50  const [runs, procedures, lots, names] = await Promise.all([listRuns(env, all ? null : actor.email), listRunnableProcedures(env), listLots(env), itemNames(env)]);
51  const titles = new Map(procedures.map((p) => [p.slug, p.title]));
52  return {
53    runs: runs.map((r) => ({ ...r, title: titles.get(r.procedure_slug) ?? r.procedure_slug })),
54    procedures,
55    lots: lotLabels(
56      names,
57      lots.filter((l) => l.status === "in_stock"),
58    ),
59    all,
60    canRecord: can(actor, PERMISSION.recordRun),
61    lotRows: LOT_ROWS,
62  };
63}
64
65/** One run, its lots and its line of corrections, or null when it does not exist or is not the actor's to see. */
66export async function runPage(env: Env, actor: Actor, id: number) {
67  const run = await getRun(env, id);
68  if (!run || !canSeeRun(actor, run)) return null;
69  const [used, procedures, names, lots] = await Promise.all([runLots(env, id), listRunnableProcedures(env), itemNames(env), listLots(env)]);
70  const title = procedures.find((p) => p.slug === run.procedure_slug)?.title ?? run.procedure_slug;
71  return {
72    run: { ...run, title },
73    lots: used.map((l) => ({ ...l, item: names.get(`${l.item_kind}:${l.item_id}`) ?? l.item_id })),
74    // The run's own protocol stays a choice even if it is no longer published, so it can still be corrected.
75    procedures: procedures.some((p) => p.slug === run.procedure_slug) ? procedures : [{ slug: run.procedure_slug, title, version: run.procedure_version }, ...procedures],
76    allLots: lotLabels(names, lots),
77    canCorrect: run.replaced_by === null && can(actor, PERMISSION.recordRun) && canSeeRun(actor, run),
78    lotRows: LOT_ROWS,
79  };
80}
81
82type LotUse = { lot: LotRow; amount_used: number | null; emptied: boolean };
83
84/** The lots a post names, each checked: it exists, is named once, and (for a new run) is in stock with enough left. */
85async function lotUses(env: Env, form: FormData, correction: boolean): Promise<{ ok: true; uses: LotUse[] } | { ok: false; reason: string }> {
86  const uses: LotUse[] = [];
87  for (let i = 0; i < LOT_ROWS; i += 1) {
88    const text = field(form, `lot-${i}`);
89    if (!text) continue;
90    const id = idOf(text);
91    const lot = id ? await getLot(env, id) : null;
92    if (!lot) return { ok: false, reason: "One of those lots does not exist." };
93    if (uses.some((u) => u.lot.id === lot.id)) return { ok: false, reason: `Lot ${lot.lot_number} is named twice.` };
94    const amount = amountOf(field(form, `amount-${i}`));
95    if (!amount.ok) return amount;
96    const emptied = field(form, `emptied-${i}`) === "yes";
97    if (!correction) {
98      if (lot.status !== "in_stock") return { ok: false, reason: `Lot ${lot.lot_number} is ${lot.status.replace("_", " ")}, so a new run cannot use it.` };
99      if (amount.value !== null && lot.amount !== null && amount.value > lot.amount) {
100        return { ok: false, reason: `Lot ${lot.lot_number} has only ${amountText(lot.amount, lot.unit)} left.` };
101      }
102    }
103    uses.push({ lot, amount_used: amount.value, emptied });
104  }
105  return { ok: true, uses };
106}
107
108/**
109 * Records a run as `actor`, or, with `replacesId`, a correction of that run. A correction comes only from the run's own
110 * page (the id is in its address), never from a form field. Nothing is saved unless every check passes.
111 */
112export async function recordRun(
113  env: Env,
114  actor: Actor,
115  form: FormData,
116  nowMs: number,
117  { replacesId = null, uid = crypto.randomUUID() }: { replacesId?: number | null; uid?: string } = {},
118): Promise<RunResult> {
119  if (!can(actor, PERMISSION.recordRun)) return refused("You cannot record runs.");
120
121  let replaces: RunRow | null = null;
122  if (replacesId !== null) {
123    replaces = await getRun(env, replacesId);
124    if (!replaces || !canSeeRun(actor, replaces)) return refused("That run does not exist.");
125    if (replaces.replaced_by !== null) return refused(`Run ${replaces.id} is already corrected by run ${replaces.replaced_by}: correct that one.`);
126  }
127
128  // A correction that keeps the run's protocol keeps the version it followed then, published or not.
129  const slug = field(form, "procedure");
130  const procedure =
131    replaces && slug === replaces.procedure_slug
132      ? { slug, title: slug, version: replaces.procedure_version }
133      : (await listRunnableProcedures(env)).find((p) => p.slug === slug);
134  if (!procedure) return refused("Choose the protocol the run followed.");
135  const runOn = field(form, "run_on") || today(nowMs);
136  if (!isDate(runOn)) return refused(`Not a date (YYYY-MM-DD): ${runOn}.`);
137  if (runOn > today(nowMs)) return refused("A run is recorded on or after the day it happened.");
138  const outcome = field(form, "outcome") || "completed";
139  if (!(OUTCOMES as readonly string[]).includes(outcome)) return refused(`Unknown outcome: ${outcome}.`);
140  const note = field(form, "note");
141  if (note.length > NOTE_MAX) return refused(`The note is longer than ${NOTE_MAX} characters.`);
142
143  const checked = await lotUses(env, form, replaces !== null);
144  if (!checked.ok) return refused(checked.reason);
145  const uses = checked.uses;
146  if (!replaces && uses.some((u) => u.amount_used !== null || u.emptied || u.lot.opened === null) && !can(actor, PERMISSION.useLot)) {
147    return refused("You cannot change lots, so the run cannot take from them.");
148  }
149
150  const statements = runInsert(
151    env,
152    { uid, procedure_slug: procedure.slug, procedure_version: procedure.version, actor: actor.email, run_on: runOn, outcome: outcome as RunRow["outcome"], note: note || null, replaces_run_id: replaces?.id ?? null },
153    uses.map((u) => ({ lot_id: u.lot.id, amount_used: u.amount_used, unit: u.lot.unit, emptied: u.emptied })),
154  );
155  if (!replaces) {
156    for (const u of uses) {
157      const takes = u.amount_used !== null && u.lot.amount !== null;
158      // The lot was in stock when it was read. If it left stock since, this sets an impossible amount, which fails
159      // kb_lots_amount_check and aborts the whole batch: no run is saved against an emptied or discarded lot.
160      statements.push(env.DB.prepare("UPDATE kb_lots SET amount = -1 WHERE id = ? AND status <> 'in_stock'").bind(u.lot.id));
161      if (!takes && !u.emptied && u.lot.opened !== null) continue;
162      statements.push(
163        ...lotChange(
164          env,
165          actor.email,
166          u.lot.id,
167          env.DB.prepare(
168            "UPDATE kb_lots SET amount = CASE WHEN ?1 IS NULL OR amount IS NULL THEN amount ELSE amount - ?1 END, opened = coalesce(opened, ?2), status = CASE WHEN ?3 = 1 THEN 'empty' ELSE status END, updated_at = unixepoch() WHERE id = ?4",
169          ).bind(u.amount_used, runOn, u.emptied ? 1 : 0, u.lot.id),
170        ),
171      );
172    }
173  }
174
175  try {
176    await env.DB.batch(statements);
177  } catch (error) {
178    const message = error instanceof Error ? error.message : String(error);
179    if (/kb_lots_amount_check/.test(message)) return refused("A lot ran short or left stock while the run was saved; nothing was recorded. Check the lots and try again.");
180    if (/UNIQUE constraint failed: kb_runs.replaces_run_id/.test(message)) return refused("That run was corrected a moment ago: correct the newer run.");
181    throw error;
182  }
183  const runId = (await runIdByUid(env, uid)) ?? undefined;
184  const lots = uses.length === 1 ? "1 lot" : `${uses.length} lots`;
185  return {
186    ok: true,
187    runId,
188    text: replaces ? `Recorded run ${runId}, correcting run ${replaces.id}, with ${lots}.` : `Recorded run ${runId} of ${procedure.title}, with ${lots}.`,
189  };
190}