@rubytech/create-maxy-code 0.1.571 → 0.1.573

package/payload/platform/lib/dispatch-write/dist/lifecycle.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Dispatch writes, shared by the MCP tools and the field job sheet.
+ *
+ * The sibling of `dispatch-read`, and for the same reason: the field Mini App's
+ * route must be assertable as holding no graph access while still writing to
+ * the graph. Two consumption shapes, matching that package — session-taking
+ * functions for the plugin, which owns its driver, and session-owning wrappers
+ * for the UI route, which must not.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkTransition = checkTransition;
+exports.isTerminal = isTerminal;
+exports.initialStatus = initialStatus;
+exports.firstMissingRequiredField = firstMissingRequiredField;
+exports.formatTransitionRefused = formatTransitionRefused;
+const index_js_1 = require("../../dispatch-read/dist/index.js");
+function checkTransition(kind, from, to, cfg) {
+    const edges = kind === "job" ? cfg.statuses.jobTransitions : cfg.statuses.visitTransitions;
+    const legal = edges.some(([f, t]) => f === from && t === to);
+    return legal ? { legal: true } : { legal: false, reason: "not-in-config" };
+}
+/** Is this a declared terminal status of the given kind? */
+function isTerminal(kind, status, cfg) {
+    const list = kind === "job" ? cfg.statuses.job : cfg.statuses.visit;
+    return list.some((s) => s.name === status && s.terminal);
+}
+/** The status a newly created job or visit starts in: the first declared. */
+function initialStatus(kind, cfg) {
+    const list = kind === "job" ? cfg.statuses.job : cfg.statuses.visit;
+    return list[0].name;
+}
+function fieldSatisfied(field, state) {
+    switch (field) {
+        case "notes":
+            return state.notes > 0;
+        case "media":
+            return state.media > 0;
+        case "parts":
+            return state.parts > 0;
+        case "signature":
+            return state.signatures > 0;
+        case "checklist":
+            // Every item, not merely one: a half-done checklist is the case this
+            // guard exists for.
+            return state.checklistTotal > 0 && state.checklistDone >= state.checklistTotal;
+        default:
+            // Unreachable while RECORDABLE_FIELDS and this switch agree. Answering
+            // false rather than throwing keeps an unknown field a REFUSAL to close
+            // the visit, which is the safe direction: a throw here would abort the
+            // status change with a stack trace instead of a named missing field.
+            return false;
+    }
+}
+/**
+ * The first `records.requiredBeforeTerminal` field this visit does not carry,
+ * or null when it carries them all. Returns the FIRST rather than all of them
+ * so the refusal names one concrete thing to go and do.
+ */
+function firstMissingRequiredField(toStatus, cfg, state) {
+    const required = cfg.records.requiredBeforeTerminal[toStatus];
+    if (!required)
+        return null;
+    for (const field of required) {
+        if (!index_js_1.RECORDABLE_FIELDS.includes(field))
+            continue;
+        if (!fieldSatisfied(field, state)) {
+            return field;
+        }
+    }
+    return null;
+}
+function formatTransitionRefused(p) {
+    return (`[dispatch] op=transition-refused jobId=${p.jobId} visitId=${p.visitId ?? "none"} ` +
+        `from=${p.from} to=${p.to} reason=${p.reason}`);
+}
+//# sourceMappingURL=lifecycle.js.map

package/payload/platform/lib/dispatch-write/dist/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AA0BH,0CAUC;AAGD,gCAOC;AAGD,sCAGC;AAwCD,8DAcC;AAED,0DAWC;AArGD,gEAAsE;AAQtE,SAAgB,eAAe,CAC7B,IAAoB,EACpB,IAAY,EACZ,EAAU,EACV,GAAmB;IAEnB,MAAM,KAAK,GACT,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IAC/E,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAC7D,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;AAC7E,CAAC;AAED,4DAA4D;AAC5D,SAAgB,UAAU,CACxB,IAAoB,EACpB,MAAc,EACd,GAAmB;IAEnB,MAAM,IAAI,GAAG,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC;IACpE,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC;AAC3D,CAAC;AAED,6EAA6E;AAC7E,SAAgB,aAAa,CAAC,IAAoB,EAAE,GAAmB;IACrE,MAAM,IAAI,GAAG,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC;IACpE,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACtB,CAAC;AAYD,SAAS,cAAc,CAAC,KAAsB,EAAE,KAAuB;IACrE,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,OAAO;YACV,OAAO,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC;QACzB,KAAK,OAAO;YACV,OAAO,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC;QACzB,KAAK,OAAO;YACV,OAAO,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC;QACzB,KAAK,WAAW;YACd,OAAO,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC;QAC9B,KAAK,WAAW;YACd,qEAAqE;YACrE,oBAAoB;YACpB,OAAO,KAAK,CAAC,cAAc,GAAG,CAAC,IAAI,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,cAAc,CAAC;QACjF;YACE,uEAAuE;YACvE,uEAAuE;YACvE,uEAAuE;YACvE,qEAAqE;YACrE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAgB,yBAAyB,CACvC,QAAgB,EAChB,GAAmB,EACnB,KAAuB;IAEvB,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IAC9D,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC7B,IAAI,CAAC,4BAAiB,CAAC,QAAQ,CAAC,KAAwB,CAAC;YAAE,SAAS;QACpE,IAAI,CAAC,cAAc,CAAC,KAAwB,EAAE,KAAK,CAAC,EAAE,CAAC;YACrD,OAAO,KAAwB,CAAC;QAClC,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAgB,uBAAuB,CAAC,CAMvC;IACC,OAAO,CACL,0CAA0C,CAAC,CAAC,KAAK,YAAY,CAAC,CAAC,OAAO,IAAI,MAAM,GAAG;QACnF,QAAQ,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,MAAM,EAAE,CAC/C,CAAC;AACJ,CAAC"}

package/payload/platform/lib/dispatch-write/dist/write.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The two visit writes, shared by the MCP tools and the field job sheet.
+ *
+ * Moved out of `platform/plugins/dispatch/mcp/src/tools/` unchanged except for
+ * the return shape. The plugin's tool files are now adapters that map the
+ * outcome below onto `ToolResult`.
+ */
+import type { Session } from "neo4j-driver";
+import type { DispatchConfig } from "../../dispatch-read/dist/index.js";
+import { type VisitRecordState } from "./lifecycle.js";
+/**
+ * A domain answer, not an MCP one.
+ *
+ * The plugin maps this onto `ToolResult`; the field route maps it onto an HTTP
+ * status and a JSON body. Returning the MCP shape from a shared library would
+ * have made the route parse a JSON string out of a text block to learn whether
+ * a write succeeded.
+ *
+ * `reason` is a stable machine token and `message` is the operator-facing text.
+ * They are separate because the route branches on the first and renders the
+ * second, and a route that branched on prose would break the day somebody
+ * improved the wording.
+ */
+export type WriteOutcome<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+    readonly message: string;
+};
+/**
+ * Record what happened on the visit: a note, a photo, a part, a ticked
+ * checklist item, a signature, an arrival.
+ *
+ * Each arrival property is written with its **own** SET clause and only when
+ * that call supplies it. That is the load-bearing detail of the whole tool. A
+ * pressed arrival is what somebody said; an observed one is what was measured.
+ * If a single write set both, recording one would blank the other, and the
+ * disagreement between them — which is the finding worth having — would be
+ * destroyed by the act of recording it.
+ *
+ * An observation with no press is stored and flagged, not dropped: a worker who
+ * never pressed arrive is precisely the case the geofence exists to cover.
+ */
+export interface VisitRecordParams {
+    session: Session;
+    accountId: string;
+    cfg: DispatchConfig;
+    emit: (line: string) => void;
+    visitId: string;
+    note?: string;
+    mediaRef?: string;
+    partId?: string;
+    checklistItem?: string;
+    signature?: string;
+    arrivedPressedAt?: string;
+    arrivedObservedAt?: string;
+    arrivedObservedDistanceM?: number;
+}
+export interface VisitRecordResult {
+    visitId: string;
+    jobId: string | null;
+    recorded: VisitRecordState;
+    arrivedPressedAt: string | null;
+    arrivedObservedAt: string | null;
+    arrivedObservedDistanceM: number | null;
+    vocabulary: DispatchConfig["vocabulary"];
+}
+export declare function visitRecord(p: VisitRecordParams): Promise<WriteOutcome<VisitRecordResult>>;
+/**
+ * Move a visit between statuses, and close the job when the last one lands.
+ *
+ * Two refusals, both loud, both naming what was attempted:
+ *
+ *   - the transition is not in the account's edge list → `not-in-config`
+ *   - the visit does not carry a field the target status requires →
+ *     `missing-required-field:<f>`
+ *
+ * Neither is swallowed. A status that quietly failed to change is
+ * indistinguishable from one nobody tried to change, and that is the whole
+ * failure mode this tool exists inside of.
+ *
+ * `op=job-close` carries `recordLagS`: the gap between the work ending and the
+ * record being written. On the reference account one worker closed Monday's
+ * jobs on Tuesday morning, so every finish time was when a button was pressed.
+ * The number is the only way to see that happening again.
+ */
+export type StatusSource = "press" | "geofence" | "office";
+export interface VisitStatusSetParams {
+    session: Session;
+    accountId: string;
+    cfg: DispatchConfig;
+    emit: (line: string) => void;
+    now: () => number;
+    by: string;
+    visitId: string;
+    to: string;
+    source: StatusSource;
+}
+export interface VisitStatusResult {
+    visitId: string;
+    jobId: string | null;
+    from: string;
+    to: string;
+    at: string;
+    source: StatusSource;
+    jobClosed: string | null;
+    vocabulary: DispatchConfig["vocabulary"];
+}
+export declare function visitStatusSet(p: VisitStatusSetParams): Promise<WriteOutcome<VisitStatusResult>>;
+//# sourceMappingURL=write.d.ts.map

package/payload/platform/lib/dispatch-write/dist/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../src/write.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAMxE,OAAO,EAKL,KAAK,gBAAgB,EACtB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IACtB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACxC;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAU9E;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,cAAc,CAAC;IACpB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wBAAwB,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,UAAU,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;CAC1C;AAED,wBAAsB,WAAW,CAC/B,CAAC,EAAE,iBAAiB,GACnB,OAAO,CAAC,YAAY,CAAC,iBAAiB,CAAC,CAAC,CA4G1C;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE3D,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,cAAc,CAAC;IACpB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,YAAY,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;CAC1C;AAED,wBAAsB,cAAc,CAClC,CAAC,EAAE,oBAAoB,GACtB,OAAO,CAAC,YAAY,CAAC,iBAAiB,CAAC,CAAC,CA4I1C"}

package/payload/platform/lib/dispatch-write/dist/write.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.visitRecord = visitRecord;
+exports.visitStatusSet = visitStatusSet;
+const index_js_1 = require("../../dispatch-read/dist/index.js");
+const lifecycle_js_1 = require("./lifecycle.js");
+function refuse(reason, message) {
+    return { ok: false, reason, message };
+}
+async function visitRecord(p) {
+    const visit = await (0, index_js_1.readVisit)(p.session, p.accountId, p.visitId);
+    if (!visit) {
+        return refuse("not-found", `No ${p.cfg.vocabulary.visit} "${p.visitId}" on this account.`);
+    }
+    const sets = [];
+    const params = {
+        accountId: p.accountId,
+        visitId: p.visitId,
+    };
+    if (p.note !== undefined) {
+        sets.push("v.notes = coalesce(v.notes, []) + $note");
+        params.note = p.note;
+    }
+    if (p.mediaRef !== undefined) {
+        sets.push("v.media = coalesce(v.media, []) + $mediaRef");
+        params.mediaRef = p.mediaRef;
+    }
+    if (p.partId !== undefined) {
+        sets.push("v.parts = coalesce(v.parts, []) + $partId");
+        params.partId = p.partId;
+    }
+    if (p.checklistItem !== undefined) {
+        // Not validated against the job type's template. A worker who ticks
+        // something the template does not list has still done it, and refusing the
+        // record would lose the only account of it.
+        sets.push("v.checklistDone = CASE WHEN $checklistItem IN coalesce(v.checklistDone, []) " +
+            "THEN v.checklistDone ELSE coalesce(v.checklistDone, []) + $checklistItem END");
+        params.checklistItem = p.checklistItem;
+    }
+    if (p.signature !== undefined) {
+        sets.push("v.signatures = coalesce(v.signatures, []) + $signature");
+        params.signature = p.signature;
+    }
+    // Three separate SET clauses, never one object assignment. Each fires only
+    // when this call supplied that value, so neither arrival can clear the other.
+    if (p.arrivedPressedAt !== undefined) {
+        sets.push("v.arrivedPressedAt = $arrivedPressedAt");
+        params.arrivedPressedAt = p.arrivedPressedAt;
+    }
+    if (p.arrivedObservedAt !== undefined) {
+        sets.push("v.arrivedObservedAt = $arrivedObservedAt");
+        params.arrivedObservedAt = p.arrivedObservedAt;
+    }
+    if (p.arrivedObservedDistanceM !== undefined) {
+        sets.push("v.arrivedObservedDistanceM = $arrivedObservedDistanceM");
+        params.arrivedObservedDistanceM = p.arrivedObservedDistanceM;
+    }
+    if (sets.length === 0) {
+        return refuse("nothing-to-record", `Nothing to record. Supply at least one of: note, mediaRef, partId, checklistItem, signature, arrivedPressedAt, arrivedObservedAt.`);
+    }
+    await p.session.run(`MATCH (v:Visit {accountId: $accountId, visitId: $visitId}) SET ${sets.join(", ")}`, params);
+    const state = await (0, index_js_1.readVisitRecordState)(p.session, p.accountId, p.visitId);
+    p.emit(`[dispatch] op=visit-record visitId=${p.visitId} notes=${state.notes} ` +
+        `media=${state.media} parts=${state.parts} ` +
+        `checklist=${state.checklistDone}/${state.checklistTotal} ` +
+        `signatures=${state.signatures}`);
+    if (p.arrivedObservedAt !== undefined) {
+        // The press this observation is being compared against is whichever one the
+        // visit already carried, or the one this same call supplied.
+        const pressedAt = p.arrivedPressedAt ?? visit.arrivedPressedAt;
+        const deltaS = pressedAt === null || pressedAt === undefined
+            ? null
+            : Math.round((Date.parse(p.arrivedObservedAt) - Date.parse(pressedAt)) / 1000);
+        p.emit(`[dispatch] op=arrival-observed visitId=${p.visitId} ` +
+            `distanceM=${p.arrivedObservedDistanceM ?? "none"} ` +
+            `observedAt=${p.arrivedObservedAt} pressedAt=${pressedAt ?? "none"} ` +
+            `deltaS=${deltaS ?? "none"}`);
+    }
+    const after = await (0, index_js_1.readVisit)(p.session, p.accountId, p.visitId);
+    return {
+        ok: true,
+        value: {
+            visitId: p.visitId,
+            jobId: visit.jobId,
+            recorded: state,
+            arrivedPressedAt: after?.arrivedPressedAt ?? null,
+            arrivedObservedAt: after?.arrivedObservedAt ?? null,
+            arrivedObservedDistanceM: after?.arrivedObservedDistanceM ?? null,
+            vocabulary: p.cfg.vocabulary,
+        },
+    };
+}
+async function visitStatusSet(p) {
+    const visit = await (0, index_js_1.readVisit)(p.session, p.accountId, p.visitId);
+    if (!visit) {
+        return refuse("not-found", `No ${p.cfg.vocabulary.visit} "${p.visitId}" on this account.`);
+    }
+    const declared = p.cfg.statuses.visit.some((s) => s.name === p.to);
+    if (!declared) {
+        p.emit((0, lifecycle_js_1.formatTransitionRefused)({
+            jobId: visit.jobId ?? "none",
+            visitId: p.visitId,
+            from: visit.status,
+            to: p.to,
+            reason: "not-in-config",
+        }));
+        return refuse("not-in-config", `"${p.to}" is not a ${p.cfg.vocabulary.visit} status on this account. Declared: ${p.cfg.statuses.visit.map((s) => s.name).join(", ")}.`);
+    }
+    const check = (0, lifecycle_js_1.checkTransition)("visit", visit.status, p.to, p.cfg);
+    if (!check.legal) {
+        p.emit((0, lifecycle_js_1.formatTransitionRefused)({
+            jobId: visit.jobId ?? "none",
+            visitId: p.visitId,
+            from: visit.status,
+            to: p.to,
+            reason: check.reason,
+        }));
+        const legalNext = p.cfg.statuses.visitTransitions
+            .filter(([from]) => from === visit.status)
+            .map(([, to]) => to);
+        return refuse(check.reason, `This account allows no move from "${visit.status}" to "${p.to}". From "${visit.status}" it allows: ${legalNext.join(", ") || "nothing"}.`);
+    }
+    const state = await (0, index_js_1.readVisitRecordState)(p.session, p.accountId, p.visitId);
+    const missing = (0, lifecycle_js_1.firstMissingRequiredField)(p.to, p.cfg, state);
+    if (missing) {
+        p.emit((0, lifecycle_js_1.formatTransitionRefused)({
+            jobId: visit.jobId ?? "none",
+            visitId: p.visitId,
+            from: visit.status,
+            to: p.to,
+            reason: `missing-required-field:${missing}`,
+        }));
+        return refuse(`missing-required-field:${missing}`, `This account requires ${missing} on a ${p.cfg.vocabulary.visit} before it reaches "${p.to}". Record it with dispatch-visit-record first.`);
+    }
+    const at = new Date(p.now()).toISOString();
+    const terminal = (0, lifecycle_js_1.isTerminal)("visit", p.to, p.cfg);
+    // `closedAt` only. `endDate` is the PLANNED end, written at allocation from
+    // the job type's duration, and it is the closest thing this ontology has to
+    // when the worker left. Overwriting it with the close instant would destroy
+    // the plan and make the two identical, so every lag computed from it would
+    // be zero — which is exactly the number this task exists to stop reporting.
+    await p.session.run(`MATCH (v:Visit {accountId: $accountId, visitId: $visitId})
+     SET v.status = $status` + (terminal ? `, v.closedAt = $at` : ``), { accountId: p.accountId, visitId: p.visitId, status: p.to, at });
+    p.emit(`[dispatch] op=visit-status jobId=${visit.jobId ?? "none"} visitId=${p.visitId} ` +
+        `from=${visit.status} to=${p.to} by=${p.by} at=${at} source=${p.source}`);
+    let jobClosed = null;
+    if (terminal && visit.jobId) {
+        const siblings = await (0, index_js_1.readVisitsForJob)(p.session, p.accountId, visit.jobId);
+        const allTerminal = siblings.every((v) => v.visitId === p.visitId || (0, lifecycle_js_1.isTerminal)("visit", v.status, p.cfg));
+        if (allTerminal) {
+            const terminalJobStatus = p.cfg.statuses.job.find((s) => s.terminal)?.name;
+            if (terminalJobStatus) {
+                await p.session.run(`MATCH (j:Job {accountId: $accountId, jobId: $jobId}) SET j.status = $status, j.closedAt = $at`, {
+                    accountId: p.accountId,
+                    jobId: visit.jobId,
+                    status: terminalJobStatus,
+                    at,
+                });
+                jobClosed = terminalJobStatus;
+            }
+            // Measured from when the worker was due to LEAVE, not from when they
+            // arrived. Nothing in this ontology records leaving site, so the planned
+            // `endDate` is the proxy — and it is the right one, because measuring
+            // from arrival adds the whole job duration to every lag and would report
+            // a two-hour job closed on the doorstep as two hours late.
+            //
+            // The ladder falls back to an arrival and then to the start only when a
+            // visit carries no planned end, which allocation always writes. Falling
+            // back to `at` would make every lag zero and hide what this counts.
+            const dueToLeaveAt = visit.endDate ??
+                visit.arrivedPressedAt ??
+                visit.arrivedObservedAt ??
+                visit.startDate;
+            const recordLagS = dueToLeaveAt === null
+                ? 0
+                : Math.max(0, Math.round((Date.parse(at) - Date.parse(dueToLeaveAt)) / 1000));
+            p.emit(`[dispatch] op=job-close jobId=${visit.jobId} visits=${siblings.length} ` +
+                `terminal=${p.to} recordLagS=${recordLagS}`);
+        }
+    }
+    return {
+        ok: true,
+        value: {
+            visitId: p.visitId,
+            jobId: visit.jobId,
+            from: visit.status,
+            to: p.to,
+            at,
+            source: p.source,
+            jobClosed,
+            vocabulary: p.cfg.vocabulary,
+        },
+    };
+}
+//# sourceMappingURL=write.js.map

package/payload/platform/lib/dispatch-write/dist/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../src/write.ts"],"names":[],"mappings":";;AAuFA,kCA8GC;AAiDD,wCA8IC;AA3XD,gEAI2C;AAC3C,iDAMwB;AAmBxB,SAAS,MAAM,CAAC,MAAc,EAAE,OAAe;IAC7C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AACxC,CAAC;AA8CM,KAAK,UAAU,WAAW,CAC/B,CAAoB;IAEpB,MAAM,KAAK,GAAG,MAAM,IAAA,oBAAS,EAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IACjE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,MAAM,CACX,WAAW,EACX,MAAM,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,KAAK,CAAC,CAAC,OAAO,oBAAoB,CAC/D,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,MAAM,MAAM,GAA4B;QACtC,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,OAAO,EAAE,CAAC,CAAC,OAAO;KACnB,CAAC;IAEF,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC;QACrD,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;IACvB,CAAC;IACD,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC7B,IAAI,CAAC,IAAI,CAAC,6CAA6C,CAAC,CAAC;QACzD,MAAM,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;IAC/B,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAC;QACvD,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,CAAC;IACD,IAAI,CAAC,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QAClC,oEAAoE;QACpE,2EAA2E;QAC3E,4CAA4C;QAC5C,IAAI,CAAC,IAAI,CACP,8EAA8E;YAC5E,8EAA8E,CACjF,CAAC;QACF,MAAM,CAAC,aAAa,GAAG,CAAC,CAAC,aAAa,CAAC;IACzC,CAAC;IACD,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,CAAC,IAAI,CAAC,wDAAwD,CAAC,CAAC;QACpE,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC;IACjC,CAAC;IAED,2EAA2E;IAC3E,8EAA8E;IAC9E,IAAI,CAAC,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACrC,IAAI,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC;QACpD,MAAM,CAAC,gBAAgB,GAAG,CAAC,CAAC,gBAAgB,CAAC;IAC/C,CAAC;IACD,IAAI,CAAC,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QACtC,IAAI,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC;QACtD,MAAM,CAAC,iBAAiB,GAAG,CAAC,CAAC,iBAAiB,CAAC;IACjD,CAAC;IACD,IAAI,CAAC,CAAC,wBAAwB,KAAK,SAAS,EAAE,CAAC;QAC7C,IAAI,CAAC,IAAI,CAAC,wDAAwD,CAAC,CAAC;QACpE,MAAM,CAAC,wBAAwB,GAAG,CAAC,CAAC,wBAAwB,CAAC;IAC/D,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,MAAM,CACX,mBAAmB,EACnB,mIAAmI,CACpI,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,CACjB,kEAAkE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EACnF,MAAM,CACP,CAAC;IAEF,MAAM,KAAK,GAAG,MAAM,IAAA,+BAAoB,EAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IAC5E,CAAC,CAAC,IAAI,CACJ,sCAAsC,CAAC,CAAC,OAAO,UAAU,KAAK,CAAC,KAAK,GAAG;QACrE,SAAS,KAAK,CAAC,KAAK,UAAU,KAAK,CAAC,KAAK,GAAG;QAC5C,aAAa,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,cAAc,GAAG;QAC3D,cAAc,KAAK,CAAC,UAAU,EAAE,CACnC,CAAC;IAEF,IAAI,CAAC,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QACtC,4EAA4E;QAC5E,6DAA6D;QAC7D,MAAM,SAAS,GAAG,CAAC,CAAC,gBAAgB,IAAI,KAAK,CAAC,gBAAgB,CAAC;QAC/D,MAAM,MAAM,GACV,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,SAAS;YAC3C,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,IAAI,CAAC,KAAK,CACR,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CACjE,CAAC;QACR,CAAC,CAAC,IAAI,CACJ,0CAA0C,CAAC,CAAC,OAAO,GAAG;YACpD,aAAa,CAAC,CAAC,wBAAwB,IAAI,MAAM,GAAG;YACpD,cAAc,CAAC,CAAC,iBAAiB,cAAc,SAAS,IAAI,MAAM,GAAG;YACrE,UAAU,MAAM,IAAI,MAAM,EAAE,CAC/B,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,IAAA,oBAAS,EAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IACjE,OAAO;QACL,EAAE,EAAE,IAAI;QACR,KAAK,EAAE;YACL,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,QAAQ,EAAE,KAAK;YACf,gBAAgB,EAAE,KAAK,EAAE,gBAAgB,IAAI,IAAI;YACjD,iBAAiB,EAAE,KAAK,EAAE,iBAAiB,IAAI,IAAI;YACnD,wBAAwB,EAAE,KAAK,EAAE,wBAAwB,IAAI,IAAI;YACjE,UAAU,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU;SAC7B;KACF,CAAC;AACJ,CAAC;AAiDM,KAAK,UAAU,cAAc,CAClC,CAAuB;IAEvB,MAAM,KAAK,GAAG,MAAM,IAAA,oBAAS,EAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IACjE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,MAAM,CACX,WAAW,EACX,MAAM,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,KAAK,CAAC,CAAC,OAAO,oBAAoB,CAC/D,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;IACnE,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,CAAC,CAAC,IAAI,CACJ,IAAA,sCAAuB,EAAC;YACtB,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,MAAM;YAC5B,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,IAAI,EAAE,KAAK,CAAC,MAAM;YAClB,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,MAAM,EAAE,eAAe;SACxB,CAAC,CACH,CAAC;QACF,OAAO,MAAM,CACX,eAAe,EACf,IAAI,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,sCAAsC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACxI,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,IAAA,8BAAe,EAAC,OAAO,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IAClE,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC,CAAC,IAAI,CACJ,IAAA,sCAAuB,EAAC;YACtB,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,MAAM;YAC5B,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,IAAI,EAAE,KAAK,CAAC,MAAM;YAClB,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,MAAM,EAAE,KAAK,CAAC,MAAM;SACrB,CAAC,CACH,CAAC;QACF,MAAM,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,gBAAgB;aAC9C,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,KAAK,KAAK,CAAC,MAAM,CAAC;aACzC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;QACvB,OAAO,MAAM,CACX,KAAK,CAAC,MAAM,EACZ,qCAAqC,KAAK,CAAC,MAAM,SAAS,CAAC,CAAC,EAAE,YAAY,KAAK,CAAC,MAAM,gBAAgB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,GAAG,CAC3I,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,IAAA,+BAAoB,EAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAG,IAAA,wCAAyB,EAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC9D,IAAI,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC,IAAI,CACJ,IAAA,sCAAuB,EAAC;YACtB,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,MAAM;YAC5B,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,IAAI,EAAE,KAAK,CAAC,MAAM;YAClB,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,MAAM,EAAE,0BAA0B,OAAO,EAAE;SAC5C,CAAC,CACH,CAAC;QACF,OAAO,MAAM,CACX,0BAA0B,OAAO,EAAE,EACnC,yBAAyB,OAAO,SAAS,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,uBAAuB,CAAC,CAAC,EAAE,gDAAgD,CAC3I,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAG,IAAA,yBAAU,EAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IAClD,4EAA4E;IAC5E,4EAA4E;IAC5E,4EAA4E;IAC5E,2EAA2E;IAC3E,4EAA4E;IAC5E,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,CACjB;4BACwB,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC,EACjE,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CACjE,CAAC;IAEF,CAAC,CAAC,IAAI,CACJ,oCAAoC,KAAK,CAAC,KAAK,IAAI,MAAM,YAAY,CAAC,CAAC,OAAO,GAAG;QAC/E,QAAQ,KAAK,CAAC,MAAM,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,MAAM,EAAE,CAC3E,CAAC;IAEF,IAAI,SAAS,GAAkB,IAAI,CAAC;IACpC,IAAI,QAAQ,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,MAAM,IAAA,2BAAgB,EAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAC7E,MAAM,WAAW,GAAG,QAAQ,CAAC,KAAK,CAChC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,IAAI,IAAA,yBAAU,EAAC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CACvE,CAAC;QACF,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,iBAAiB,GAAG,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC;YAC3E,IAAI,iBAAiB,EAAE,CAAC;gBACtB,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,CACjB,+FAA+F,EAC/F;oBACE,SAAS,EAAE,CAAC,CAAC,SAAS;oBACtB,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,MAAM,EAAE,iBAAiB;oBACzB,EAAE;iBACH,CACF,CAAC;gBACF,SAAS,GAAG,iBAAiB,CAAC;YAChC,CAAC;YACD,qEAAqE;YACrE,yEAAyE;YACzE,sEAAsE;YACtE,yEAAyE;YACzE,2DAA2D;YAC3D,EAAE;YACF,wEAAwE;YACxE,wEAAwE;YACxE,oEAAoE;YACpE,MAAM,YAAY,GAChB,KAAK,CAAC,OAAO;gBACb,KAAK,CAAC,gBAAgB;gBACtB,KAAK,CAAC,iBAAiB;gBACvB,KAAK,CAAC,SAAS,CAAC;YAClB,MAAM,UAAU,GACd,YAAY,KAAK,IAAI;gBACnB,CAAC,CAAC,CAAC;gBACH,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;YAClF,CAAC,CAAC,IAAI,CACJ,iCAAiC,KAAK,CAAC,KAAK,WAAW,QAAQ,CAAC,MAAM,GAAG;gBACvE,YAAY,CAAC,CAAC,EAAE,eAAe,UAAU,EAAE,CAC9C,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,EAAE,EAAE,IAAI;QACR,KAAK,EAAE;YACL,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,IAAI,EAAE,KAAK,CAAC,MAAM;YAClB,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,EAAE;YACF,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,SAAS;YACT,UAAU,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU;SAC7B;KACF,CAAC;AACJ,CAAC"}

package/payload/platform/lib/dispatch-write/src/__tests__/lifecycle.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import {
+  checkTransition,
+  firstMissingRequiredField,
+  initialStatus,
+  isTerminal,
+} from "../index.js";
+import type { DispatchConfig } from "../../../dispatch-read/src/types.js";
+
+const cfg = {
+  statuses: {
+    job: [{ name: "New", terminal: false }, { name: "Closed", terminal: true }],
+    visit: [{ name: "Allocated", terminal: false }, { name: "Complete", terminal: true }],
+    jobTransitions: [["New", "Closed"]],
+    visitTransitions: [["Allocated", "Complete"]],
+  },
+  records: { checklists: {}, requiredBeforeTerminal: { Complete: ["signature"] } },
+  vocabulary: { job: "job", visit: "visit", worker: "engineer" },
+} as unknown as DispatchConfig;
+
+const empty = {
+  notes: 0, media: 0, parts: 0, checklistDone: 0, checklistTotal: 0, signatures: 0,
+};
+
+describe("dispatch-write lifecycle", () => {
+  it("allows a transition the config declares", () => {
+    expect(checkTransition("visit", "Allocated", "Complete", cfg)).toEqual({ legal: true });
+  });
+
+  it("refuses one it does not, naming the reason", () => {
+    expect(checkTransition("visit", "Complete", "Allocated", cfg)).toEqual({
+      legal: false,
+      reason: "not-in-config",
+    });
+  });
+
+  it("reads terminality from the config, not from a status name", () => {
+    expect(isTerminal("visit", "Complete", cfg)).toBe(true);
+    expect(isTerminal("visit", "Allocated", cfg)).toBe(false);
+  });
+
+  it("takes the initial status from the first declared, whatever it is called", () => {
+    expect(initialStatus("visit", cfg)).toBe("Allocated");
+    expect(initialStatus("job", cfg)).toBe("New");
+  });
+
+  it("names the first missing required field", () => {
+    expect(firstMissingRequiredField("Complete", cfg, empty)).toBe("signature");
+  });
+
+  it("returns null when the target requires nothing", () => {
+    expect(firstMissingRequiredField("Allocated", cfg, empty)).toBeNull();
+  });
+
+  it("treats a half-done checklist as missing, not as satisfied", () => {
+    const needsChecklist = {
+      ...cfg,
+      records: { checklists: {}, requiredBeforeTerminal: { Complete: ["checklist"] } },
+    } as unknown as DispatchConfig;
+    expect(
+      firstMissingRequiredField("Complete", needsChecklist, { ...empty, checklistDone: 1, checklistTotal: 2 }),
+    ).toBe("checklist");
+    expect(
+      firstMissingRequiredField("Complete", needsChecklist, { ...empty, checklistDone: 2, checklistTotal: 2 }),
+    ).toBeNull();
+  });
+});

package/payload/platform/lib/dispatch-write/src/__tests__/write.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it, vi } from "vitest";
+import { visitRecord, visitStatusSet } from "../write.js";
+import type { DispatchConfig } from "../../../dispatch-read/src/types.js";
+
+const cfg = {
+  statuses: {
+    job: [{ name: "New", terminal: false }, { name: "Closed", terminal: true }],
+    visit: [{ name: "Allocated", terminal: false }, { name: "Complete", terminal: true }],
+    jobTransitions: [["New", "Closed"]],
+    visitTransitions: [["Allocated", "Complete"]],
+  },
+  records: { checklists: {}, requiredBeforeTerminal: { Complete: ["signature"] } },
+  vocabulary: { job: "job", visit: "visit", worker: "engineer" },
+} as unknown as DispatchConfig;
+
+const VISIT = {
+  visitId: "v1",
+  jobId: "j1",
+  status: "Allocated",
+  startDate: null,
+  endDate: null,
+  purpose: null,
+  workerId: "w1",
+  arrivedPressedAt: null,
+  arrivedObservedAt: null,
+  arrivedObservedDistanceM: null,
+};
+
+const STATE = {
+  notes: 0, media: 0, parts: 0, checklistDone: 0, checklistTotal: 0, signatures: 0,
+};
+
+/**
+ * A fake session whose `run` answers per query shape, so these tests exercise
+ * the real control flow without opening a socket. Reads are matched on the
+ * clause the production query actually uses.
+ */
+function fakeSession(over: { visit?: unknown | null; state?: unknown; siblings?: unknown[] } = {}) {
+  const visit = over.visit === undefined ? VISIT : over.visit;
+  const state = over.state ?? STATE;
+  const writes: Array<{ query: string; params: unknown }> = [];
+  const session = {
+    run: vi.fn(async (query: string, params: unknown) => {
+      const row = (obj: Record<string, unknown>) => ({
+        records: [{ get: (k: string) => obj[k] }],
+      });
+      if (/RETURN[\s\S]*checklistDone/i.test(query)) return row(state as Record<string, unknown>);
+      if (/MATCH \(v:Visit[\s\S]*RETURN/i.test(query)) {
+        return visit === null ? { records: [] } : row(visit as Record<string, unknown>);
+      }
+      if (/HAS_VISIT/i.test(query)) {
+        return { records: (over.siblings ?? []).map((s) => ({ get: (k: string) => (s as Record<string, unknown>)[k] })) };
+      }
+      writes.push({ query, params });
+      return { records: [] };
+    }),
+  };
+  return { session: session as never, writes };
+}
+
+describe("visitStatusSet returns a domain outcome", () => {
+  it("refuses a completion missing a required field and names it", async () => {
+    const { session } = fakeSession();
+    const emitted: string[] = [];
+    const out = await visitStatusSet({
+      session, accountId: "a1", cfg, emit: (l) => emitted.push(l),
+      now: () => 0, by: "w1", visitId: "v1", to: "Complete", source: "press",
+    });
+    expect(out.ok).toBe(false);
+    if (out.ok) throw new Error("expected a refusal");
+    expect(out.reason).toBe("missing-required-field:signature");
+    expect(out.message).toContain("signature");
+    expect(emitted.join("\n")).toContain("op=transition-refused");
+  });
+
+  it("refuses a transition the config does not declare, naming both ends", async () => {
+    const { session } = fakeSession({ visit: { ...VISIT, status: "Complete" } });
+    const emitted: string[] = [];
+    const out = await visitStatusSet({
+      session, accountId: "a1", cfg, emit: (l) => emitted.push(l),
+      now: () => 0, by: "w1", visitId: "v1", to: "Allocated", source: "press",
+    });
+    expect(out.ok).toBe(false);
+    if (out.ok) throw new Error("expected a refusal");
+    expect(out.reason).toBe("not-in-config");
+    expect(emitted.join("\n")).toContain("from=Complete to=Allocated");
+  });
+
+  it("refuses a status the account never declared at all", async () => {
+    const { session } = fakeSession();
+    const out = await visitStatusSet({
+      session, accountId: "a1", cfg, emit: () => {},
+      now: () => 0, by: "w1", visitId: "v1", to: "Invoiced", source: "press",
+    });
+    expect(out.ok).toBe(false);
+    if (out.ok) throw new Error("expected a refusal");
+    expect(out.reason).toBe("not-in-config");
+    expect(out.message).toContain("Allocated, Complete");
+  });
+
+  it("refuses a visit that is not on the account", async () => {
+    const { session } = fakeSession({ visit: null });
+    const out = await visitStatusSet({
+      session, accountId: "a1", cfg, emit: () => {},
+      now: () => 0, by: "w1", visitId: "nope", to: "Complete", source: "press",
+    });
+    expect(out.ok).toBe(false);
+    if (out.ok) throw new Error("expected a refusal");
+    expect(out.reason).toBe("not-found");
+  });
+
+  it("succeeds and returns the domain value when the gate is satisfied", async () => {
+    const { session } = fakeSession({ state: { ...STATE, signatures: 1 } });
+    const out = await visitStatusSet({
+      session, accountId: "a1", cfg, emit: () => {},
+      now: () => 1_754_000_000_000, by: "w1", visitId: "v1", to: "Complete", source: "press",
+    });
+    expect(out.ok).toBe(true);
+    if (!out.ok) throw new Error(out.reason);
+    expect(out.value).toMatchObject({ visitId: "v1", from: "Allocated", to: "Complete", source: "press" });
+    // `at` comes from the injected clock, never from Date.now(), so this is
+    // exactly the epoch passed in above.
+    expect(out.value.at).toBe(new Date(1_754_000_000_000).toISOString());
+  });
+});
+
+describe("visitRecord returns a domain outcome", () => {
+  it("refuses a call that supplies nothing to record", async () => {
+    const { session } = fakeSession();
+    const out = await visitRecord({ session, accountId: "a1", cfg, emit: () => {}, visitId: "v1" });
+    expect(out.ok).toBe(false);
+    if (out.ok) throw new Error("expected a refusal");
+    expect(out.reason).toBe("nothing-to-record");
+  });
+
+  it("writes each supplied field with its own SET clause", async () => {
+    const { session, writes } = fakeSession();
+    const out = await visitRecord({
+      session, accountId: "a1", cfg, emit: () => {},
+      visitId: "v1", note: "Valve replaced", signature: "sig-data",
+    });
+    expect(out.ok).toBe(true);
+    // Both clauses in one statement, each guarded by its own parameter, is what
+    // stops one recorded field blanking another.
+    expect(writes[0].query).toContain("v.notes = coalesce(v.notes, []) + $note");
+    expect(writes[0].query).toContain("v.signatures = coalesce(v.signatures, []) + $signature");
+  });
+
+  it("never writes an arrival the call did not supply", async () => {
+    const { session, writes } = fakeSession();
+    await visitRecord({ session, accountId: "a1", cfg, emit: () => {}, visitId: "v1", arrivedObservedAt: "2026-08-07T09:00:00.000Z" });
+    // A pressed arrival is what somebody said and an observed one is what was
+    // measured; a write that set both would destroy the disagreement between
+    // them, which is the finding worth having.
+    expect(writes[0].query).toContain("v.arrivedObservedAt = $arrivedObservedAt");
+    expect(writes[0].query).not.toContain("v.arrivedPressedAt");
+  });
+});