@arcforgelabs/flow 2026.10.50 → 2026.10.52

package/server/core/capture-match.js

@@ -0,0 +1,158 @@
+// The capture matcher (docs/DATA_MODEL.md, "Storage"). Flow code, not the
+// model, picks the job a form is about. It scores each job on the Jobs board
+// against the read or typed fields, in the style of the accounting link
+// suggestions: a score, a rank and the signals behind it. A person always
+// confirms the job before anything is applied.
+//
+// Points: case number 60 exact, 50 for a common misread (O for 0, l for 1),
+// practice and dentist 20, due date within 3 days 10, work or teeth found in
+// the job's lines 10.
+
+export const MATCH_POINTS = Object.freeze({ caseNumber: 60, caseMisread: 50, practice: 12, dentist: 8, date: 10, work: 10 });
+// A job at or above this, with no other job within SURE_GAP, is the one sure job.
+export const SURE_SCORE = 60;
+export const SURE_GAP = 20;
+// A job below this is not shown.
+export const SHOWN_SCORE = 20;
+const SHOWN_MAX = 5;
+const DATE_DAYS = 3;
+
+// Fields that find the job (the work is its lines). They are not proposed as
+// changes to a job that exists.
+const IDENTITY = new Set(['case_number', 'practice', 'work']);
+const MISREAD = { O: '0', Q: '0', D: '0', I: '1', L: '1', S: '5', B: '8', Z: '2', G: '6' };
+const NAME_NOISE = new Set(['dr', 'dental', 'dentist', 'dentistry', 'clinic', 'surgery', 'practice', 'centre', 'center', 'pty', 'ltd', 'the', 'and', 'of']);
+
+export const jobKey = (job) => `${job.sourceSystem}:${job.sourceJobRef}`;
+
+const plain = (value) => String(value ?? '').trim();
+const caseText = (value) => plain(value).toUpperCase().replace(/[^A-Z0-9]/g, '');
+const misread = (value) => caseText(value).replace(/[OQDILSBZG]/g, (ch) => MISREAD[ch]);
+
+function words(value) {
+  return plain(value).toLowerCase().replace(/[^a-z0-9 ]+/g, ' ').split(/\s+/)
+    .filter((word) => word.length > 1 && !NAME_NOISE.has(word));
+}
+
+// Edit distance, for close spelling of a name.
+function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i += 1) {
+    let previous = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const kept = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+      previous = kept;
+    }
+  }
+  return row[b.length];
+}
+
+const closeWord = (a, b) => a === b || (Math.min(a.length, b.length) >= 4 && distance(a, b) <= Math.floor(Math.max(a.length, b.length) / 4));
+
+// Half or more of the shorter name's words appear, by close spelling, in the other.
+export function sameName(read, known) {
+  const a = words(read);
+  const b = words(known);
+  if (!a.length || !b.length) return false;
+  const [short, long] = a.length <= b.length ? [a, b] : [b, a];
+  const found = short.filter((word) => long.some((other) => closeWord(word, other))).length;
+  return found * 2 >= short.length;
+}
+
+// A date as a lab writes it: 2026-10-31, 31/10/2026, 31/10/26 or 31/10 (day
+// first, as in Australia). A date with no year takes the year nearest `now`.
+export function readDate(value, now = new Date()) {
+  const text = plain(value);
+  let match = /^(\d{4})-(\d{1,2})-(\d{1,2})$/.exec(text);
+  if (match) return utc(+match[1], +match[2], +match[3]);
+  match = /^(\d{1,2})[/.-](\d{1,2})(?:[/.-](\d{2}|\d{4}))?$/.exec(text);
+  if (!match) return null;
+  const [, day, month, year] = match;
+  if (year) return utc(year.length === 2 ? 2000 + +year : +year, +month, +day);
+  const near = [-1, 0, 1].map((step) => utc(now.getUTCFullYear() + step, +month, +day)).filter(Boolean);
+  return near.sort((a, b) => Math.abs(a - now) - Math.abs(b - now))[0] ?? null;
+}
+
+function utc(year, month, day) {
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCMonth() === month - 1 && date.getUTCDate() === day ? date : null;
+}
+
+function teethOf(value) {
+  return plain(value).match(/\b[1-8][1-8]\b/g) ?? [];
+}
+
+function workFound(fields, job) {
+  const lines = (job.lines ?? []).map((line) => plain(line.description).toLowerCase()).join(' ');
+  if (!lines) return false;
+  const work = words(fields.work).filter((word) => word.length >= 4);
+  if (work.some((word) => lines.includes(word))) return true;
+  return teethOf(fields.teeth).some((tooth) => new RegExp(`\\b${tooth}\\b`).test(lines));
+}
+
+function score(fields, job, now) {
+  const signals = [];
+  const readCase = caseText(fields.case_number);
+  const jobCase = caseText(job.caseRef);
+  if (readCase && jobCase) {
+    if (readCase === jobCase) signals.push({ signal: 'case_number', points: MATCH_POINTS.caseNumber });
+    else if (misread(readCase) === misread(jobCase)) signals.push({ signal: 'case_number_misread', points: MATCH_POINTS.caseMisread });
+  }
+  if (sameName(fields.practice, job.clientName) || sameName(fields.practice, job.workClientName)) {
+    signals.push({ signal: 'practice', points: MATCH_POINTS.practice });
+  }
+  if (sameName(fields.dentist, job.practitioner)) signals.push({ signal: 'dentist', points: MATCH_POINTS.dentist });
+  const due = readDate(fields.due_date, now);
+  const jobDue = readDate(job.dueOn ?? job.jobDate, now);
+  if (due && jobDue && Math.abs(due - jobDue) <= DATE_DAYS * 86_400_000) signals.push({ signal: 'date', points: MATCH_POINTS.date });
+  if (workFound(fields, job)) signals.push({ signal: 'work', points: MATCH_POINTS.work });
+  return { score: signals.reduce((sum, s) => sum + s.points, 0), signals };
+}
+
+// `fields` is { key: value }. `jobs` is the Jobs board's jobs
+// (server/core/job-board.js). Answers { outcome, jobs }: outcome `sure` (one
+// job), `close` (a short pick list) or `none` (offer a new job).
+export function matchJobs(fields, jobs, { now = new Date() } = {}) {
+  const ranked = (jobs ?? [])
+    .map((job) => ({ job, ...score(fields, job, now) }))
+    .filter((entry) => entry.score >= SHOWN_SCORE)
+    .sort((a, b) => b.score - a.score || plain(a.job.sourceJobRef).localeCompare(plain(b.job.sourceJobRef)))
+    .slice(0, SHOWN_MAX);
+  const [top, next] = ranked;
+  const outcome = !top ? 'none'
+    : top.score >= SURE_SCORE && (!next || top.score - next.score >= SURE_GAP) ? 'sure' : 'close';
+  return {
+    outcome,
+    jobs: ranked.map(({ job, score: points, signals }) => ({
+      jobId: jobKey(job), caseRef: job.caseRef ?? null, clientName: job.clientName ?? null, score: points, signals,
+    })),
+  };
+}
+
+// What the job holds now for a read field, where the board shows it.
+function current(job, key) {
+  if (!job) return '';
+  if (key === 'dentist') return plain(job.practitioner);
+  if (key === 'due_date') return plain(job.dueOn);
+  return '';
+}
+
+// The proposed change from the fields and the match. One sure job: update it
+// with each field that differs. Close jobs: update, and the person picks the
+// job. No job: create one from the fields. A field the reader was not sure
+// of keeps its sure score, so the screen can mark it.
+export function proposeChange(read, match, jobs) {
+  const sure = match.outcome === 'sure' ? match.jobs[0] : null;
+  const job = sure ? (jobs ?? []).find((entry) => jobKey(entry) === sure.jobId) ?? null : null;
+  const changes = read
+    .filter((field) => plain(field.value) && (match.outcome === 'none' || !IDENTITY.has(field.key)))
+    .map((field) => ({ field: field.key, from: current(job, field.key), to: plain(field.value), sure: field.sure }))
+    .filter((change) => change.from !== change.to);
+  return {
+    action: match.outcome === 'none' ? 'create' : 'update',
+    jobId: sure?.jobId ?? null,
+    changes,
+  };
+}

package/server/core/captures.js

@@ -0,0 +1,501 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { and, desc, eq, gt, isNotNull, isNull, lt, or, sql } from 'drizzle-orm';
+import { CAPTURE_DECISIONS, captures } from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+import { matchJobs, proposeChange, readDate } from './capture-match.js';
+import { listFields, setJobFieldValue } from './custom-fields.js';
+
+// Shown when the module is off or the keys are missing. Type it still works.
+const READER_OFF = 'reader turned off';
+
+// A capture is one photo of a handwritten lab form (docs/DATA_MODEL.md,
+// "Storage"). This does not change a job. The reader, when it is on, fills
+// `read` in the background (server/core/reader.js). When it is off, or the
+// keys are missing, the capture is `problem` ("reader turned off") and a
+// person can type the proposal. A ready capture is matched to a job on the
+// Jobs board (server/core/capture-match.js), and the match proposes the
+// change. Apply or Discard records that decision and deletes the photo. A capture nobody decides is deleted after 7 days,
+// photo included.
+//
+// Nothing here writes the photo, the typed fields or a patient name to a log.
+// Callers log a capture id and an error code only.
+
+export const MAX_PHOTO_BYTES = 12 * 1024 * 1024;
+export const CAPTURE_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+export const EMPTY_PROPOSAL = Object.freeze({ action: null, jobId: null, changes: [] });
+
+const PHOTO_TYPES = new Set(['image/jpeg', 'image/png', 'image/webp', 'image/heic', 'image/heif']);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ACTIONS = new Set(['update', 'create', 'note']);
+// A job on the Jobs board: its work system and its id there (capture-match.js jobKey).
+const JOB_ID = /^[a-z][a-z0-9_-]{0,39}:[^\u0000-\u001f]{1,200}$/;
+const FIELD_MAX = 60;
+const VALUE_MAX = 2000;
+const CHANGES_MAX = 40;
+
+const invalid = (message) => new FlowError('invalid', message);
+
+export function readPhoto(bytes, contentType) {
+  // A request body can arrive as a string or a list. A photo is a buffer.
+  // The type check comes before any read of the bytes.
+  if (typeof bytes === 'string' || Array.isArray(bytes) || !Buffer.isBuffer(bytes)) throw invalid('photo is required');
+  const type = String(contentType ?? '').split(';')[0].trim().toLowerCase();
+  const fileType = type === 'image/jpg' ? 'image/jpeg' : type;
+  if (!PHOTO_TYPES.has(fileType)) throw new FlowError('unsupported_media', 'photo must be a jpeg, png, webp or heic');
+  if (bytes.length === 0) throw invalid('photo is required');
+  if (bytes.length > MAX_PHOTO_BYTES) throw new FlowError('photo_too_large', 'photo is too large');
+  if (!looksLikePhoto(fileType, bytes)) throw new FlowError('not_a_photo', 'photo could not be read');
+  return { fileType, fileSize: bytes.length, fileSha256: createHash('sha256').update(bytes).digest('hex') };
+}
+
+function looksLikePhoto(type, bytes) {
+  if (type === 'image/jpeg') return bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff;
+  if (type === 'image/png') return bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));
+  if (type === 'image/webp') return bytes.length >= 12 && bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP';
+  if (bytes.length < 12 || bytes.toString('ascii', 4, 8) !== 'ftyp') return false;
+  const brand = bytes.toString('ascii', 8, 12);
+  return ['heic', 'heix', 'hevc', 'hevx', 'heim', 'heis', 'heif', 'mif1', 'msf1'].includes(brand);
+}
+
+export function readIdempotencyKey(raw) {
+  const key = String(raw ?? '').trim();
+  if (!key || key.length > 200 || /[\u0000-\u001f\u007f]/.test(key)) throw invalid('idempotency key is required');
+  return key;
+}
+
+export function readSource(raw) {
+  const source = String(raw ?? 'api').trim().toLowerCase() || 'api';
+  if (!['phone', 'desk', 'api'].includes(source)) throw invalid('source must be phone, desk or api');
+  return source;
+}
+
+function readText(value, max) {
+  if (typeof value !== 'string') throw invalid('a change must be text');
+  const trimmed = value.trim();
+  if (trimmed.length > max) throw invalid('a change is too long');
+  return trimmed;
+}
+
+// What a person typed. The values are stored on the capture and returned to
+// that person. They are not written to a log.
+export function readProposal(input) {
+  if (input == null) return { ...EMPTY_PROPOSAL, changes: [] };
+  const action = input.action ?? null;
+  if (action !== null && !ACTIONS.has(action)) throw invalid('action must be update, create or note');
+  const jobId = input.jobId ?? null;
+  if (jobId !== null && !JOB_ID.test(String(jobId))) throw invalid('jobId must be a job id');
+  if (!Array.isArray(input.changes)) throw invalid('changes must be a list');
+  if (input.changes.length > CHANGES_MAX) throw invalid('too many changes');
+  const changes = input.changes.map((change) => ({
+    field: readText(change?.field, FIELD_MAX),
+    from: readText(change?.from ?? '', VALUE_MAX),
+    to: readText(change?.to ?? '', VALUE_MAX),
+    ...(Number.isFinite(change?.sure) ? { sure: Math.min(1, Math.max(0, change.sure)) } : {}),
+  }));
+  if (changes.some((change) => !change.field)) throw invalid('a change needs a field');
+  if (changes.length > 0 && !action) throw invalid('action is required');
+  return { action, jobId, changes };
+}
+
+export function captureView(row, link = null) {
+  return {
+    id: row.id,
+    organisationId: row.organisationId,
+    state: row.state,
+    source: row.source,
+    fileType: row.fileType,
+    fileSize: row.fileSize,
+    fileSha256: row.fileSha256,
+    proposal: row.proposal ?? { ...EMPTY_PROPOSAL, changes: [] },
+    read: row.read ?? null,
+    match: row.match ?? null,
+    problem: row.problem,
+    decision: row.decision,
+    decidedAt: row.decidedAt,
+    photoDeletedAt: row.photoDeletedAt,
+    createdAt: row.createdAt,
+    link,
+  };
+}
+
+function linkFor(storage, row, baseUrl) {
+  if (!row || row.photoDeletedAt) return null;
+  return storage.signedLink({ key: row.fileKey, baseUrl });
+}
+
+async function byId(db, organisationId, id) {
+  if (!UUID.test(String(id ?? ''))) throw notFound('capture');
+  const [row] = await db.select().from(captures).where(and(
+    eq(captures.organisationId, organisationId),
+    eq(captures.id, id),
+  ));
+  if (!row) throw notFound('capture');
+  return row;
+}
+
+async function byIdempotency(db, organisationId, idempotencyKey) {
+  const [row] = await db.select().from(captures).where(and(
+    eq(captures.organisationId, organisationId),
+    eq(captures.idempotencyKey, idempotencyKey),
+  ));
+  return row ?? null;
+}
+
+// The first body stored for an idempotency key wins. A repeat upload, even
+// with different bytes, returns that capture and stores nothing else. If the
+// process stops after the bytes are stored and before the row is inserted,
+// the object is orphaned: its key is a random id and it is not a capture.
+export async function uploadCapture(db, storage, organisationId, {
+  bytes, contentType, idempotencyKey, source = 'api', personId, baseUrl, reader = null,
+}) {
+  const photo = readPhoto(bytes, contentType);
+  const key = readIdempotencyKey(idempotencyKey);
+  const from = readSource(source);
+  const existing = await byIdempotency(db, organisationId, key);
+  if (existing) {
+    // The read is queued after the row is inserted. A repeat of the same
+    // key starts it if that queue step did not finish. It does not read a
+    // capture that already has a result.
+    if (existing.state === 'reading' && reader?.on) {
+      const settled = await reader.schedule(existing);
+      return { capture: settled ?? existing, created: false, link: linkFor(storage, settled ?? existing, baseUrl) };
+    }
+    return { capture: existing, created: false, link: linkFor(storage, existing, baseUrl) };
+  }
+
+  const id = randomUUID();
+  const fileKey = `captures/${String(organisationId).toLowerCase()}/${id}`;
+  try {
+    await storage.put({ key: fileKey, body: bytes, contentType: photo.fileType });
+  } catch (error) {
+    if (error instanceof FlowError) throw error;
+    throw new FlowError('storage_unavailable', 'the photo could not be stored');
+  }
+  try {
+    const reading = Boolean(reader?.on);
+    const [row] = await db.insert(captures).values({
+      id,
+      organisationId,
+      state: reading ? 'reading' : 'problem',
+      source: from,
+      fileKey,
+      fileType: photo.fileType,
+      fileSize: photo.fileSize,
+      fileSha256: photo.fileSha256,
+      idempotencyKey: key,
+      proposal: { ...EMPTY_PROPOSAL, changes: [] },
+      problem: reading ? null : READER_OFF,
+      createdBy: personId ?? null,
+    }).onConflictDoNothing({ target: [captures.organisationId, captures.idempotencyKey] }).returning();
+    if (row) {
+      // With background jobs off, schedule reads before it returns, so the
+      // response is the finished capture. With jobs on, the row stays `reading`.
+      const settled = reading ? await reader.schedule(row) : row;
+      return { capture: settled ?? row, created: true, link: linkFor(storage, settled ?? row, baseUrl) };
+    }
+  } catch (error) {
+    await storage.delete(fileKey).catch(() => {});
+    if (error instanceof FlowError) throw error;
+    throw new FlowError('storage_unavailable', 'the photo could not be stored');
+  }
+  // Another request stored this key first. Drop the bytes we just wrote.
+  // Their key is this attempt's id, not the winner's.
+  await storage.delete(fileKey).catch(() => {});
+  const winner = await byIdempotency(db, organisationId, key);
+  if (!winner) throw new FlowError('conflict', 'this upload was already stored');
+  return { capture: winner, created: false, link: linkFor(storage, winner, baseUrl) };
+}
+
+export async function readCapture(db, storage, organisationId, id, baseUrl) {
+  const row = await byId(db, organisationId, id);
+  return { capture: row, link: linkFor(storage, row, baseUrl) };
+}
+
+export async function typeProposal(db, storage, organisationId, id, input, { baseUrl } = {}) {
+  const proposal = readProposal(input);
+  await byId(db, organisationId, id);
+  const [row] = await db.update(captures).set({
+    state: 'ready',
+    problem: null,
+    proposal,
+    updatedAt: sql`now()`,
+  }).where(and(
+    eq(captures.organisationId, organisationId),
+    eq(captures.id, id),
+    sql`${captures.state} in ('ready', 'problem')`,
+  )).returning();
+  if (!row) throw new FlowError('conflict', 'this capture is not ready');
+  return { capture: row, link: linkFor(storage, row, baseUrl) };
+}
+
+// What a person typed instead of a read: { key: value }, keys as the reader's.
+function readTypedFields(input) {
+  if (input == null || typeof input !== 'object' || Array.isArray(input)) throw invalid('fields must be an object');
+  const entries = Object.entries(input);
+  if (entries.length > CHANGES_MAX) throw invalid('too many fields');
+  return entries.map(([key, value]) => ({ key: readText(key, FIELD_MAX), value: readText(value ?? '', VALUE_MAX), seen: '', sure: 1 }));
+}
+
+const isEmpty = (proposal) => !proposal?.action && !(proposal?.changes?.length);
+
+// Scores the Jobs board against the read (or typed) fields, stores the match
+// and, when nobody has typed a change yet, the proposed change. Typed fields
+// always replace the proposal: the person asked for a new match. `jobs` is
+// the board's jobs (server/core/job-board.js boardJobs).
+export async function matchCapture(db, storage, organisationId, id, { jobs, fields = null, baseUrl, now } = {}) {
+  const current = await byId(db, organisationId, id);
+  if (current.state !== 'ready' && !(fields && current.state === 'problem')) throw new FlowError('conflict', 'this capture is not ready');
+  const read = fields ? readTypedFields(fields) : (current.read?.fields ?? []);
+  const values = Object.fromEntries(read.map((field) => [field.key, field.value]));
+  const match = matchJobs(values, jobs, { now });
+  const replace = Boolean(fields) || isEmpty(current.proposal);
+  const [row] = await db.update(captures).set({
+    state: 'ready',
+    problem: null,
+    match,
+    ...(replace ? { proposal: proposeChange(read, match, jobs) } : {}),
+    updatedAt: sql`now()`,
+  }).where(and(
+    eq(captures.organisationId, organisationId),
+    eq(captures.id, id),
+    eq(captures.state, current.state),
+  )).returning();
+  if (!row) throw new FlowError('conflict', 'this capture changed; open it again');
+  return { capture: row, link: linkFor(storage, row, baseUrl) };
+}
+
+// The capture tray: every capture still open, and the ones decided in the
+// last day, newest first. No signed link: the result sheet asks for one.
+export async function listCaptures(db, organisationId, { now = new Date(), limit = 100 } = {}) {
+  const since = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+  return db.select().from(captures).where(and(
+    eq(captures.organisationId, organisationId),
+    or(isNull(captures.decision), gt(captures.decidedAt, since)),
+  )).orderBy(desc(captures.createdAt)).limit(limit);
+}
+
+// A custom field's value from the text on the form. Undefined: Flow cannot
+// set this field from text (a person field), so it is left as it is.
+function fieldValue(field, text) {
+  const bad = () => invalid(`${field.name}: "${text}" does not fit this field`);
+  switch (field.type) {
+    case 'number': {
+      const number = Number(text.replace(/,/g, ''));
+      if (!Number.isFinite(number)) throw bad();
+      return number;
+    }
+    case 'date': {
+      const date = readDate(text);
+      if (!date) throw bad();
+      return date.toISOString().slice(0, 10);
+    }
+    case 'dropdown': {
+      const option = field.options.find((o) => !o.archived && o.name.toLowerCase() === text.toLowerCase());
+      if (!option) throw bad();
+      return option.id;
+    }
+    case 'checkbox':
+      if (/^(yes|y|true|x|✓|1)$/i.test(text)) return true;
+      if (/^(no|n|false|0)$/i.test(text)) return false;
+      throw bad();
+    case 'person':
+      return undefined;
+    default:
+      return text;
+  }
+}
+
+// Apply writes what Flow owns: the job's custom fields, each with its own
+// event (who, when, from and to). A field the work system owns (due date,
+// shade) stays there; the result sheet links to the job in that system.
+// Every value is checked before the first write, so a bad one writes none.
+async function applyToJob(db, organisationId, proposal, personId) {
+  if (proposal?.action !== 'update' || !proposal.jobId) return;
+  const at = proposal.jobId.indexOf(':');
+  const job = { sourceSystem: proposal.jobId.slice(0, at), sourceJobRef: proposal.jobId.slice(at + 1) };
+  const fields = new Map((await listFields(db, organisationId)).map((field) => [`custom_${field.id}`, field]));
+  const writes = proposal.changes
+    .filter((change) => fields.has(change.field))
+    .map((change) => ({ field: fields.get(change.field), value: fieldValue(fields.get(change.field), change.to) }))
+    .filter((write) => write.value !== undefined);
+  for (const { field, value } of writes) {
+    await setJobFieldValue(db, organisationId, { ...job, fieldId: field.id, value }, { personId });
+  }
+}
+
+async function deletePhoto(db, storage, row) {
+  if (row.photoDeletedAt) return row;
+  try {
+    await storage.delete(row.fileKey);
+  } catch (error) {
+    const failure = error instanceof FlowError ? error : new FlowError('storage_unavailable', 'the photo could not be deleted');
+    failure.captureId = row.id;
+    if (!failure.code) failure.code = 'storage_unavailable';
+    throw failure;
+  }
+  const [next] = await db.update(captures).set({
+    photoDeletedAt: sql`now()`,
+    updatedAt: sql`now()`,
+  }).where(and(
+    eq(captures.organisationId, row.organisationId),
+    eq(captures.id, row.id),
+    isNull(captures.photoDeletedAt),
+  )).returning();
+  return next ?? row;
+}
+
+// Records the person's decision and deletes the photo. Apply first writes
+// the job's custom fields (applyToJob). The same decision again writes the
+// same values, which changes nothing, and deletes the photo if that was
+// still waiting.
+export async function decideCapture(db, storage, organisationId, id, decision, { personId, baseUrl } = {}) {
+  if (!CAPTURE_DECISIONS.includes(decision)) throw invalid('decision must be applied or discarded');
+  const current = await byId(db, organisationId, id);
+  if (current.state === 'done') {
+    if (current.decision !== decision) throw new FlowError('conflict', 'this capture already has a decision');
+    const row = await deletePhoto(db, storage, current);
+    return { capture: row, link: null };
+  }
+  if (current.state !== 'ready') throw new FlowError('conflict', 'this capture is not ready');
+  if (decision === 'applied') await applyToJob(db, organisationId, current.proposal, personId ?? null);
+  const [row] = await db.update(captures).set({
+    state: 'done',
+    decision,
+    decidedBy: personId ?? null,
+    decidedAt: sql`now()`,
+    updatedAt: sql`now()`,
+  }).where(and(
+    eq(captures.organisationId, organisationId),
+    eq(captures.id, id),
+    eq(captures.state, 'ready'),
+  )).returning();
+  if (!row) {
+    const again = await byId(db, organisationId, id);
+    if (again.state === 'done' && again.decision === decision) {
+      return { capture: await deletePhoto(db, storage, again), link: null };
+    }
+    throw new FlowError('conflict', again.state === 'done' ? 'this capture already has a decision' : 'this capture is not ready');
+  }
+  const deleted = await deletePhoto(db, storage, row);
+  return { capture: deleted, link: null };
+}
+
+// Serves a signed Flow link. The checksum is checked before any byte is
+// returned. An S3 link is not served here; S3 honours that URL itself.
+export async function readCapturePhoto(db, storage, token) {
+  const opened = storage.openLink(String(token ?? ''));
+  if (!opened.ok) {
+    const error = new FlowError(opened.code, opened.code === 'link_expired' ? 'this link has expired' : 'this link is not valid');
+    throw error;
+  }
+  const [row] = await db.select().from(captures).where(eq(captures.fileKey, opened.key));
+  if (!row || row.photoDeletedAt) throw notFound('photo');
+  let stored;
+  try {
+    stored = await storage.get(row.fileKey);
+  } catch (error) {
+    const failure = error instanceof FlowError ? error : new FlowError('storage_unavailable', 'the file store could not be reached');
+    failure.captureId = row.id;
+    throw failure;
+  }
+  if (!stored) throw notFound('photo');
+  const sha = createHash('sha256').update(stored.body).digest('hex');
+  if (sha !== row.fileSha256) {
+    const error = new FlowError('hash_mismatch', 'the photo did not match its record');
+    error.captureId = row.id;
+    throw error;
+  }
+  return { body: stored.body, contentType: row.fileType, captureId: row.id };
+}
+
+// Deletes photos that are still here after a decision, and deletes captures
+// that nobody decided and that are older than the retention window. A delete
+// that fails leaves the row, so the next pass tries again. Two passes at once
+// are safe: deleting a missing object and deleting a row that is already gone
+// both do nothing.
+export async function sweepCaptures(db, storage, { now = new Date(), retentionMs = CAPTURE_RETENTION_MS, limit = 100 } = {}) {
+  const cutoff = new Date(now.getTime() - retentionMs);
+  const open = { id: captures.id, organisationId: captures.organisationId, fileKey: captures.fileKey };
+  const stale = await db.select(open).from(captures).where(and(
+    isNull(captures.decision),
+    isNull(captures.photoDeletedAt),
+    lt(captures.createdAt, cutoff),
+  )).limit(limit);
+  const failed = [];
+  let removed = 0;
+  for (const row of stale) {
+    try {
+      await storage.delete(row.fileKey);
+      await db.delete(captures).where(and(
+        eq(captures.organisationId, row.organisationId),
+        eq(captures.id, row.id),
+        isNull(captures.decision),
+      ));
+      removed += 1;
+    } catch {
+      failed.push(row.id);
+    }
+  }
+  const stuck = await db.select(open).from(captures).where(and(
+    isNotNull(captures.decision),
+    isNull(captures.photoDeletedAt),
+  )).limit(limit);
+  let photos = 0;
+  for (const row of stuck) {
+    try {
+      await storage.delete(row.fileKey);
+      await db.update(captures).set({ photoDeletedAt: sql`now()`, updatedAt: sql`now()` }).where(and(
+        eq(captures.organisationId, row.organisationId),
+        eq(captures.id, row.id),
+        isNull(captures.photoDeletedAt),
+      ));
+      photos += 1;
+    } catch {
+      failed.push(row.id);
+    }
+  }
+  return { removed, photos, failed };
+}
+
+export function createCaptureRetentionWorker({
+  db, storage, log = console, retentionMs = CAPTURE_RETENTION_MS, everyMs = 60 * 60 * 1000, firstDelayMs = 60_000,
+  timers = globalThis,
+}) {
+  let timer = null;
+  let stopped = true;
+  let running = null;
+
+  async function tick() {
+    try {
+      const result = await sweepCaptures(db, storage, { retentionMs });
+      for (const id of result.failed) log.error?.(`[captures] ${id} storage_unavailable`);
+    } catch {
+      log.error?.('[captures] - sweep_failed');
+    }
+  }
+
+  function schedule(delay) {
+    if (stopped) return;
+    timer = timers.setTimeout(async () => {
+      timer = null;
+      running = tick();
+      await running;
+      running = null;
+      schedule(everyMs);
+    }, delay);
+    timer?.unref?.();
+  }
+
+  return {
+    start() {
+      stopped = false;
+      schedule(firstDelayMs);
+    },
+    async stop() {
+      stopped = true;
+      if (timer) timers.clearTimeout(timer);
+      timer = null;
+      await running;
+    },
+  };
+}