@rubytech/create-realagent-code 0.1.574 → 0.1.575

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

@@ -1,20 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ATTENDANCE_COLLECT = exports.ATTENDANCE_MATCH = void 0;
+exports.projectAttendances = projectAttendances;
 exports.projectJob = projectJob;
 exports.projectVisit = projectVisit;
 exports.readJob = readJob;
 exports.readVisit = readVisit;
 exports.readVisitRecordState = readVisitRecordState;
 exports.readVisitsForJob = readVisitsForJob;
+exports.readOpenVisitsForWorker = readOpenVisitsForWorker;
 exports.readCommitments = readCommitments;
+exports.readPreviousVisits = readPreviousVisits;
 exports.buildJobListQuery = buildJobListQuery;
 exports.readJobs = readJobs;
 exports.readNodeId = readNodeId;
+exports.readSiteLocation = readSiteLocation;
+exports.readDraft = readDraft;
+exports.readDrafts = readDrafts;
 exports.readSiteHistory = readSiteHistory;
 exports.readVisitsInWindow = readVisitsInWindow;
 exports.nonZuluStarts = nonZuluStarts;
 exports.readDay = readDay;
+exports.projectFieldVisit = projectFieldVisit;
 exports.readWorkerDay = readWorkerDay;
+exports.readFieldVisit = readFieldVisit;
 exports.readJobList = readJobList;
 exports.readCounts = readCounts;
 const session_js_1 = require("./session.js");
@@ -30,6 +39,58 @@ function num(v) {
 function str(v) {
     return typeof v === "string" && v.length > 0 ? v : null;
 }
+/**
+ * The attendance sub-pattern, as one string every visit query interpolates
+ * (Task 2512).
+ *
+ * It COLLECTS rather than returning a row per attender, and that is the whole
+ * point: `OPTIONAL MATCH (v)-[:ATTENDED_BY]->(e:Engineer)` returned one record
+ * per edge, so a two-worker visit arrived as two rows carrying one set of times
+ * and rendered as two separate visits. `collect` drops nulls, so an unallocated
+ * visit yields `[]` and never a list holding one empty map.
+ *
+ * Interpolated rather than repeated by hand because nine queries need it, and a
+ * hand-copied ninth is the one that keeps the old shape.
+ */
+exports.ATTENDANCE_MATCH = `OPTIONAL MATCH (v)-[:HAS_ATTENDANCE]->(att:Attendance)-[:BY_ENGINEER]->(e:Engineer)`;
+/** The collected list, named `attendances`. Pair with `ATTENDANCE_MATCH`. */
+exports.ATTENDANCE_COLLECT = `collect(CASE WHEN att IS NULL THEN NULL ELSE {
+     workerId: e.engineerId,
+     arrivedPressedAt: att.arrivedPressedAt,
+     arrivedObservedAt: att.arrivedObservedAt,
+     arrivedObservedDistanceM: att.arrivedObservedDistanceM
+   } END) AS attendances`;
+/**
+ * Project the collected list, and derive the sole-attendee scalars from it.
+ *
+ * The scalars are populated only at exactly one attendance. At two they are
+ * null, because "which single worker?" has no answer and returning either one
+ * is a silent cross-assignment — the same failure `portal-visits-push.ts`
+ * refuses by binding on a property rather than matching a name.
+ */
+function projectAttendances(g) {
+    const raw = g.get("attendances") ?? [];
+    const attendances = raw
+        .filter((a) => a && typeof a.workerId === "string" && a.workerId.length > 0)
+        .map((a) => ({
+        workerId: String(a.workerId),
+        arrivedPressedAt: str(a.arrivedPressedAt),
+        arrivedObservedAt: str(a.arrivedObservedAt),
+        arrivedObservedDistanceM: a.arrivedObservedDistanceM == null ? null : num(a.arrivedObservedDistanceM),
+    }))
+        // Sorted here rather than in Cypher: `collect` has no ORDER BY of its own,
+        // and two reads of one visit returning different orders would make a
+        // rendered card's worker order arbitrary.
+        .sort((x, y) => (x.workerId < y.workerId ? -1 : x.workerId > y.workerId ? 1 : 0));
+    const sole = attendances.length === 1 ? attendances[0] : null;
+    return {
+        attendances,
+        workerId: sole?.workerId ?? null,
+        arrivedPressedAt: sole?.arrivedPressedAt ?? null,
+        arrivedObservedAt: sole?.arrivedObservedAt ?? null,
+        arrivedObservedDistanceM: sole?.arrivedObservedDistanceM ?? null,
+    };
+}
 /** Shared job projection, so every job query returns one shape. */
 function projectJob(g) {
     return {
@@ -45,7 +106,6 @@ function projectJob(g) {
 }
 /** Shared visit projection, so the day read and its tests cannot drift apart. */
 function projectVisit(g) {
-    const dist = g.get("arrivedObservedDistanceM");
     return {
         visitId: String(g.get("visitId")),
         jobId: str(g.get("jobId")),
@@ -53,14 +113,11 @@ function projectVisit(g) {
         startDate: str(g.get("startDate")),
         endDate: str(g.get("endDate")),
         purpose: str(g.get("purpose")),
-        workerId: str(g.get("workerId")),
         siteName: str(g.get("siteName")),
         customerId: str(g.get("customerId")),
         customerName: str(g.get("customerName")),
         jobType: str(g.get("jobType")),
-        arrivedPressedAt: str(g.get("arrivedPressedAt")),
-        arrivedObservedAt: str(g.get("arrivedObservedAt")),
-        arrivedObservedDistanceM: dist == null ? null : num(dist),
+        ...projectAttendances(g),
     };
 }
 async function readJob(session, accountId, jobId) {
@@ -78,18 +135,15 @@ async function readJob(session, accountId, jobId) {
 async function readVisit(session, accountId, visitId) {
     const r = await session.run(`MATCH (v:Visit {accountId: $accountId, visitId: $visitId})
      OPTIONAL MATCH (j:Job)-[:HAS_VISIT]->(v)
-     OPTIONAL MATCH (v)-[:ATTENDED_BY]->(e:Engineer)
+     ${exports.ATTENDANCE_MATCH}
+     WITH v, j, ${exports.ATTENDANCE_COLLECT}
      RETURN v.visitId AS visitId, j.jobId AS jobId, v.status AS status,
             v.startDate AS startDate, v.endDate AS endDate, v.purpose AS purpose,
-            e.engineerId AS workerId,
-            v.arrivedPressedAt AS arrivedPressedAt,
-            v.arrivedObservedAt AS arrivedObservedAt,
-            v.arrivedObservedDistanceM AS arrivedObservedDistanceM
+            attendances
      LIMIT 1`, { accountId, visitId });
     if (r.records.length === 0)
         return null;
     const g = r.records[0];
-    const dist = g.get("arrivedObservedDistanceM");
     return {
         visitId: String(g.get("visitId")),
         jobId: str(g.get("jobId")),
@@ -97,10 +151,7 @@ async function readVisit(session, accountId, visitId) {
         startDate: str(g.get("startDate")),
         endDate: str(g.get("endDate")),
         purpose: str(g.get("purpose")),
-        workerId: str(g.get("workerId")),
-        arrivedPressedAt: str(g.get("arrivedPressedAt")),
-        arrivedObservedAt: str(g.get("arrivedObservedAt")),
-        arrivedObservedDistanceM: dist == null ? null : num(dist),
+        ...projectAttendances(g),
     };
 }
 async function readVisitRecordState(session, accountId, visitId) {
@@ -134,32 +185,69 @@ async function readVisitRecordState(session, accountId, visitId) {
 }
 async function readVisitsForJob(session, accountId, jobId) {
     const r = await session.run(`MATCH (j:Job {accountId: $accountId, jobId: $jobId})-[:HAS_VISIT]->(v:Visit)
-     OPTIONAL MATCH (v)-[:ATTENDED_BY]->(e:Engineer)
+     ${exports.ATTENDANCE_MATCH}
+     WITH v, ${exports.ATTENDANCE_COLLECT}
      RETURN v.visitId AS visitId, v.status AS status, v.startDate AS startDate,
-            v.endDate AS endDate, v.purpose AS purpose, e.engineerId AS workerId,
-            v.arrivedPressedAt AS arrivedPressedAt,
-            v.arrivedObservedAt AS arrivedObservedAt,
-            v.arrivedObservedDistanceM AS arrivedObservedDistanceM
+            v.endDate AS endDate, v.purpose AS purpose, attendances
      ORDER BY v.startDate ASC`, { accountId, jobId });
+    return r.records.map((g) => ({
+        visitId: String(g.get("visitId")),
+        jobId,
+        status: String(g.get("status")),
+        startDate: str(g.get("startDate")),
+        endDate: str(g.get("endDate")),
+        purpose: str(g.get("purpose")),
+        ...projectAttendances(g),
+    }));
+}
+/**
+ * A worker's visits that are not finished, newest first (Task 2510).
+ *
+ * Deliberately not scoped to today. A visit that overran yesterday is still
+ * open, and a day window would silently drop the photo of the job most likely to
+ * need one.
+ */
+async function readOpenVisitsForWorker(session, accountId, workerId, terminalStatuses) {
+    const r = await session.run(
+    // Anchored on the caller's own attendance, then the whole visit's collected
+    // beside it — the shape `readWorkerDay` uses, for the same reason: the
+    // sole-attendee rule returns null on a visit they share, and this list is
+    // what a worker's photo or voice note gets attached to.
+    `MATCH (v:Visit {accountId: $accountId})-[:HAS_ATTENDANCE]->(mine:Attendance)-[:BY_ENGINEER]->(:Engineer {engineerId: $workerId})
+     WHERE NOT v.status IN $terminal
+     OPTIONAL MATCH (j:Job)-[:HAS_VISIT]->(v)
+     ${exports.ATTENDANCE_MATCH}
+     WITH v, j, mine, ${exports.ATTENDANCE_COLLECT}
+     RETURN v.visitId AS visitId, j.jobId AS jobId, v.status AS status,
+            v.startDate AS startDate, v.endDate AS endDate, v.purpose AS purpose,
+            attendances,
+            mine.arrivedPressedAt AS ownArrivedPressedAt,
+            mine.arrivedObservedAt AS ownArrivedObservedAt,
+            mine.arrivedObservedDistanceM AS ownArrivedObservedDistanceM
+     ORDER BY v.startDate DESC`, { accountId, workerId, terminal: [...terminalStatuses] });
     return r.records.map((g) => {
-        const dist = g.get("arrivedObservedDistanceM");
+        const dist = g.get("ownArrivedObservedDistanceM");
         return {
             visitId: String(g.get("visitId")),
-            jobId,
+            jobId: str(g.get("jobId")),
             status: String(g.get("status")),
             startDate: str(g.get("startDate")),
             endDate: str(g.get("endDate")),
             purpose: str(g.get("purpose")),
-            workerId: str(g.get("workerId")),
-            arrivedPressedAt: str(g.get("arrivedPressedAt")),
-            arrivedObservedAt: str(g.get("arrivedObservedAt")),
+            attendances: projectAttendances(g).attendances,
+            workerId,
+            arrivedPressedAt: str(g.get("ownArrivedPressedAt")),
+            arrivedObservedAt: str(g.get("ownArrivedObservedAt")),
             arrivedObservedDistanceM: dist == null ? null : num(dist),
         };
     });
 }
 /** Visits a worker is already committed to inside `[from, to)`. */
 async function readCommitments(session, accountId, from, to) {
-    const r = await session.run(`MATCH (v:Visit {accountId: $accountId})-[:ATTENDED_BY]->(e:Engineer)
+    const r = await session.run(
+    // One row per ATTENDANCE is correct here and nowhere else: a commitment
+    // belongs to a worker, so a two-worker visit legitimately commits both.
+    `MATCH (v:Visit {accountId: $accountId})-[:HAS_ATTENDANCE]->(:Attendance)-[:BY_ENGINEER]->(e:Engineer)
      WHERE v.startDate < $to AND coalesce(v.endDate, v.startDate) > $from
      RETURN e.engineerId AS workerId, v.visitId AS visitId,
             v.startDate AS start, coalesce(v.endDate, v.startDate) AS end`, { accountId, from, to });
@@ -178,6 +266,60 @@ async function readCommitments(session, accountId, from, to) {
     }
     return out;
 }
+/**
+ * Each worker's latest visit ending at or before `before`, no earlier than
+ * `dayStart`.
+ *
+ * `readCommitments` cannot answer this: it reads only inside the requested
+ * window, and the origin of a journey is by definition outside it.
+ *
+ * **Both bounds, always.** Without the upper one, a worker's current job
+ * becomes the origin and the estimate measures a journey that has not happened
+ * yet. Without the lower one, yesterday's last job becomes this morning's
+ * origin and the office is shown a drive nobody will make. `dayStart` is the
+ * caller's, computed in the account's timezone, because "that day" is not a
+ * UTC fact.
+ *
+ * The collapse to one visit per worker is done here rather than in the Cypher.
+ * A `head(collect(...))` would be invisible to every test that does not hold a
+ * real database, and picking the wrong origin visit is the failure that
+ * produces a confident number for the wrong journey.
+ */
+async function readPreviousVisits(session, accountId, before, dayStart) {
+    const r = await session.run(
+    // One row per ATTENDANCE, as `readCommitments` above: a two-worker visit is
+    // where BOTH of them were, so each is legitimately coming from it. Task 2512
+    // retired `ATTENDED_BY`; this query was written against it and would have
+    // matched nothing, reporting every worker as having no previous visit.
+    `MATCH (v:Visit {accountId: $accountId})-[:HAS_ATTENDANCE]->(:Attendance)-[:BY_ENGINEER]->(e:Engineer)
+     WHERE coalesce(v.endDate, v.startDate) <= $before
+       AND coalesce(v.endDate, v.startDate) >= $dayStart
+     OPTIONAL MATCH (j:Job {accountId: $accountId})-[:HAS_VISIT]->(v)
+     OPTIONAL MATCH (j)-[:AT_SITE]->(s:Site {accountId: $accountId})
+     RETURN e.engineerId AS workerId, v.visitId AS visitId,
+            coalesce(v.endDate, v.startDate) AS endDate, s.siteId AS siteId`, { accountId, before, dayStart });
+    const out = new Map();
+    const latest = new Map();
+    for (const g of r.records) {
+        const workerId = str(g.get("workerId"));
+        if (!workerId)
+            continue;
+        const endDate = str(g.get("endDate"));
+        if (endDate === null)
+            continue;
+        const held = latest.get(workerId);
+        // Strictly later, so two visits ending on the same instant keep the first
+        // the query returned rather than flipping between runs.
+        if (held !== undefined && held >= endDate)
+            continue;
+        latest.set(workerId, endDate);
+        out.set(workerId, {
+            visitId: String(g.get("visitId")),
+            siteId: str(g.get("siteId")),
+        });
+    }
+    return out;
+}
 /**
  * The job-list query as text plus params, extracted so its shape is testable
  * without a database.
@@ -191,7 +333,7 @@ function buildJobListQuery(filter) {
     if (filter.unallocatedOnly)
         clauses.push("NOT (j)-[:HAS_VISIT]->(:Visit)");
     if (filter.workerId) {
-        clauses.push("EXISTS { MATCH (j)-[:HAS_VISIT]->(:Visit)-[:ATTENDED_BY]->(w:Engineer) WHERE w.engineerId = $workerId }");
+        clauses.push("EXISTS { MATCH (j)-[:HAS_VISIT]->(:Visit)-[:HAS_ATTENDANCE]->(:Attendance)-[:BY_ENGINEER]->(w:Engineer) WHERE w.engineerId = $workerId }");
     }
     // One EXISTS carrying both bounds, never two. Two independent clauses are
     // satisfied by DIFFERENT visits — a job with one visit in January and another
@@ -238,41 +380,107 @@ async function readNodeId(session, accountId, label, keyProp, keyValue) {
      RETURN elementId(n) AS id LIMIT 1`, { accountId, keyProp, keyValue });
     return r.records.length === 0 ? null : String(r.records[0].get("id"));
 }
+/**
+ * A site's position and radius, or null when the account holds no such site
+ * (Task 2510).
+ *
+ * A site that exists but carries no coordinates returns nulls rather than null:
+ * "this site is not on the account" and "this site has never been placed" are
+ * different problems, and the geofence names each of them separately.
+ */
+async function readSiteLocation(session, accountId, siteId) {
+    const r = await session.run(`MATCH (s:Site {accountId: $accountId, siteId: $siteId})
+     RETURN s.siteId AS siteId, s.latitude AS latitude, s.longitude AS longitude,
+            s.geofenceRadiusM AS geofenceRadiusM
+     LIMIT 1`, { accountId, siteId });
+    if (r.records.length === 0)
+        return null;
+    const g = r.records[0];
+    const lat = g.get("latitude");
+    const lon = g.get("longitude");
+    const rad = g.get("geofenceRadiusM");
+    return {
+        siteId: String(g.get("siteId")),
+        latitude: lat == null ? null : num(lat),
+        longitude: lon == null ? null : num(lon),
+        geofenceRadiusM: rad == null ? null : num(rad),
+    };
+}
+const DRAFT_RETURN = `d.draftId AS draftId, d.receivedAt AS receivedAt, d.source AS source,
+            d.sourceRef AS sourceRef, d.jobType AS jobType, d.siteId AS siteId,
+            d.customerId AS customerId, d.description AS description,
+            d.verdict AS verdict, d.decidedAt AS decidedAt, d.decidedBy AS decidedBy,
+            d.reason AS reason, d.jobId AS jobId`;
+function projectDraft(rec) {
+    const s = (k) => {
+        const v = rec.get(k);
+        return typeof v === "string" && v.length > 0 ? v : null;
+    };
+    return {
+        draftId: s("draftId") ?? "",
+        receivedAt: s("receivedAt") ?? "",
+        source: s("source") ?? "",
+        sourceRef: s("sourceRef") ?? "",
+        jobType: s("jobType"),
+        siteId: s("siteId"),
+        customerId: s("customerId"),
+        description: s("description"),
+        verdict: s("verdict"),
+        decidedAt: s("decidedAt"),
+        decidedBy: s("decidedBy"),
+        reason: s("reason"),
+        jobId: s("jobId"),
+    };
+}
+/** One draft by its id, or null. */
+async function readDraft(session, accountId, draftId) {
+    const r = await session.run(`MATCH (d:IntakeDraft {accountId: $accountId, draftId: $draftId})
+     RETURN ${DRAFT_RETURN}`, { accountId, draftId });
+    return r.records.length === 0 ? null : projectDraft(r.records[0]);
+}
+/**
+ * The queue, oldest first. A null `verdict` argument means undecided only,
+ * which is what the queue is; a named verdict returns those already decided,
+ * because a rejection whose reason nobody can read is not a record of anything.
+ *
+ * Undecided is the ABSENCE of the property, never a written value, so the
+ * predicate is `IS NULL` rather than an equality against a sentinel.
+ */
+async function readDrafts(session, accountId, verdict, limit) {
+    const r = await session.run(`MATCH (d:IntakeDraft {accountId: $accountId})
+     WHERE ($verdict IS NULL AND d.verdict IS NULL) OR d.verdict = $verdict
+     RETURN ${DRAFT_RETURN}
+     ORDER BY d.receivedAt ASC
+     LIMIT $limit`, { accountId, verdict, limit: Math.min(Math.max(limit, 1), 200) });
+    return r.records.map(projectDraft);
+}
 /** Every visit at one site, newest first, with its job. */
 async function readSiteHistory(session, accountId, siteId, limit) {
     const r = await session.run(`MATCH (j:Job {accountId: $accountId})-[:AT_SITE]->(:Site {accountId: $accountId, siteId: $siteId})
      MATCH (j)-[:HAS_VISIT]->(v:Visit)
-     OPTIONAL MATCH (v)-[:ATTENDED_BY]->(e:Engineer)
+     ${exports.ATTENDANCE_MATCH}
+     WITH j, v, ${exports.ATTENDANCE_COLLECT}
      RETURN j.jobId AS jobId, j.status AS jobStatus, v.visitId AS visitId,
             v.status AS status, v.startDate AS startDate, v.endDate AS endDate,
-            v.purpose AS purpose, e.engineerId AS workerId,
+            v.purpose AS purpose, attendances,
             coalesce(v.notes, []) AS notes,
-            size(coalesce(v.media, [])) AS mediaCount,
-            v.arrivedPressedAt AS arrivedPressedAt,
-            v.arrivedObservedAt AS arrivedObservedAt,
-            v.arrivedObservedDistanceM AS arrivedObservedDistanceM
+            size(coalesce(v.media, [])) AS mediaCount
      ORDER BY v.startDate DESC
      LIMIT $limit`, { accountId, siteId, limit: Math.min(Math.max(limit, 1), 200) });
-    return r.records.map((g) => {
-        const dist = g.get("arrivedObservedDistanceM");
-        return {
-            visitId: String(g.get("visitId")),
-            jobId: String(g.get("jobId")),
-            jobStatus: String(g.get("jobStatus")),
-            status: String(g.get("status")),
-            startDate: str(g.get("startDate")),
-            endDate: str(g.get("endDate")),
-            purpose: str(g.get("purpose")),
-            workerId: str(g.get("workerId")),
-            notes: g.get("notes") ?? [],
-            // A count, not the references. A worker at a door needs to know whether
-            // photographs exist before deciding to load them on a bad signal.
-            mediaCount: num(g.get("mediaCount") ?? 0),
-            arrivedPressedAt: str(g.get("arrivedPressedAt")),
-            arrivedObservedAt: str(g.get("arrivedObservedAt")),
-            arrivedObservedDistanceM: dist == null ? null : num(dist),
-        };
-    });
+    return r.records.map((g) => ({
+        visitId: String(g.get("visitId")),
+        jobId: String(g.get("jobId")),
+        jobStatus: String(g.get("jobStatus")),
+        status: String(g.get("status")),
+        startDate: str(g.get("startDate")),
+        endDate: str(g.get("endDate")),
+        purpose: str(g.get("purpose")),
+        notes: g.get("notes") ?? [],
+        // A count, not the references. A worker at a door needs to know whether
+        // photographs exist before deciding to load them on a bad signal.
+        mediaCount: num(g.get("mediaCount") ?? 0),
+        ...projectAttendances(g),
+    }));
 }
 /** Every visit starting inside `[from, to)`. */
 async function readVisitsInWindow(session, accountId, from, to) {
@@ -280,30 +488,22 @@ async function readVisitsInWindow(session, accountId, from, to) {
      WHERE v.startDate >= $from AND v.startDate < $to
      OPTIONAL MATCH (j:Job)-[:HAS_VISIT]->(v)
      OPTIONAL MATCH (j)-[:AT_SITE]->(s:Site)
-     OPTIONAL MATCH (v)-[:ATTENDED_BY]->(e:Engineer)
+     ${exports.ATTENDANCE_MATCH}
+     WITH v, j, s, ${exports.ATTENDANCE_COLLECT}
      RETURN v.visitId AS visitId, j.jobId AS jobId, v.status AS status,
             v.startDate AS startDate, v.endDate AS endDate, v.purpose AS purpose,
-            e.engineerId AS workerId, s.name AS siteName,
-            v.arrivedPressedAt AS arrivedPressedAt,
-            v.arrivedObservedAt AS arrivedObservedAt,
-            v.arrivedObservedDistanceM AS arrivedObservedDistanceM
+            attendances, s.name AS siteName
      ORDER BY v.startDate ASC`, { accountId, from, to });
-    return r.records.map((g) => {
-        const dist = g.get("arrivedObservedDistanceM");
-        return {
-            visitId: String(g.get("visitId")),
-            jobId: str(g.get("jobId")),
-            status: String(g.get("status")),
-            startDate: str(g.get("startDate")),
-            endDate: str(g.get("endDate")),
-            purpose: str(g.get("purpose")),
-            workerId: str(g.get("workerId")),
-            siteName: str(g.get("siteName")),
-            arrivedPressedAt: str(g.get("arrivedPressedAt")),
-            arrivedObservedAt: str(g.get("arrivedObservedAt")),
-            arrivedObservedDistanceM: dist == null ? null : num(dist),
-        };
-    });
+    return r.records.map((g) => ({
+        visitId: String(g.get("visitId")),
+        jobId: str(g.get("jobId")),
+        status: String(g.get("status")),
+        startDate: str(g.get("startDate")),
+        endDate: str(g.get("endDate")),
+        purpose: str(g.get("purpose")),
+        siteName: str(g.get("siteName")),
+        ...projectAttendances(g),
+    }));
 }
 /**
  * Visit ids whose `startDate` is not Zulu-normalised.
@@ -331,74 +531,193 @@ async function readDay(accountId, fromUtc, toUtc) {
        OPTIONAL MATCH (j:Job)-[:HAS_VISIT]->(v)
        OPTIONAL MATCH (j)-[:AT_SITE]->(s:Site)
        OPTIONAL MATCH (j)-[:FOR_CUSTOMER]->(c:Customer)
-       OPTIONAL MATCH (v)-[:ATTENDED_BY]->(e:Engineer)
+       ${exports.ATTENDANCE_MATCH}
+       WITH v, j, s, c, ${exports.ATTENDANCE_COLLECT}
        RETURN v.visitId AS visitId, j.jobId AS jobId, v.status AS status,
               v.startDate AS startDate, v.endDate AS endDate, v.purpose AS purpose,
-              e.engineerId AS workerId, s.name AS siteName,
+              attendances, s.name AS siteName,
               c.customerId AS customerId, c.name AS customerName,
-              j.jobType AS jobType,
-              v.arrivedPressedAt AS arrivedPressedAt,
-              v.arrivedObservedAt AS arrivedObservedAt,
-              v.arrivedObservedDistanceM AS arrivedObservedDistanceM
+              j.jobType AS jobType
        ORDER BY v.startDate ASC`, { accountId, from: fromUtc, to: toUtc });
         return r.records.map(projectVisit);
     });
 }
 /**
- * One worker's visits in a window, with the contact detail a doorstep needs.
+ * The columns a field card needs beyond a plain visit row, as one clause.
+ *
+ * Written once because two reads return this shape — the day list and the
+ * single-visit sheet read — and a card that differed between the two would be
+ * a worker seeing a telephone on one screen and not the other.
+ *
+ * It returns `attendances` and NO arrival columns, because the two reads
+ * legitimately differ on whose arrival a card shows: `readWorkerDay` shows the
+ * caller their own, and `readFieldVisit`, which names no worker, falls back to
+ * the sole-attendee rule. Each adds its own arrival clause; the columns they
+ * share stay here.
+ */
+const FIELD_RETURN = `v.visitId AS visitId, j.jobId AS jobId, v.status AS status,
+       v.startDate AS startDate, v.endDate AS endDate, v.purpose AS purpose,
+       attendances,
+       s.siteId AS siteId, s.name AS siteName,
+       c.name AS customerName,
+       ct.name AS contactName, ct.telephone AS contactTelephone,
+       pa IS NOT NULL AS addressed,
+       pa.streetAddress AS streetAddress, pa.addressLocality AS addressLocality,
+       pa.postalCode AS postalCode`;
+/**
+ * The optional neighbourhood a visit hangs in.
+ *
+ * Every hop is optional: a visit allocated before its job was linked must stay
+ * in the day rather than drop out of it.
+ *
+ * **The `WITH` is what stops a visit appearing twice.** An `OPTIONAL MATCH`
+ * that finds two nodes returns two rows, so a site holding two `AT_ADDRESS`
+ * edges — or a customer holding two contacts — would put the same visit on the
+ * worker's list once per match, each copy showing a different address. That
+ * state is reachable: `memory-write`'s edge check is warn-only, so nothing
+ * blocks a second edge being written directly.
+ *
+ * Which of two the collapse keeps is arbitrary, and it is not this query's job
+ * to choose. `dispatch-site-upsert` is what guarantees a site has one address:
+ * it clears the previous edge before writing the next.
+ *
+ * **Two aggregating `WITH`s, not one.** The attendance collect is a second
+ * multiplication on the same rows, and folding both into one `WITH` would make
+ * each address appear once per attendance and each attendance once per address.
+ * Collapsing them in turn keeps every grouping key a plain node.
+ *
+ * `carry` is the extra binding a caller needs kept alive across both — `, mine`
+ * for the worker day, empty for the sheet. Anything not named in a `WITH` is
+ * dropped, so a caller that binds a variable before this clause and reads it
+ * after must pass it here.
+ */
+const fieldOptionalMatches = (carry) => `OPTIONAL MATCH (j:Job {accountId: $accountId})-[:HAS_VISIT]->(v)
+       OPTIONAL MATCH (j)-[:AT_SITE]->(s:Site {accountId: $accountId})
+       OPTIONAL MATCH (j)-[:FOR_CUSTOMER]->(c:Customer {accountId: $accountId})
+       OPTIONAL MATCH (s)-[:AT_ADDRESS]->(pa0:PostalAddress)
+       OPTIONAL MATCH (ct0:Contact {accountId: $accountId})-[:CONTACT_FOR]->(c)
+       WITH v${carry}, j, s, c,
+            head(collect(DISTINCT pa0)) AS pa,
+            head(collect(DISTINCT ct0)) AS ct
+       ${exports.ATTENDANCE_MATCH}
+       WITH v${carry}, j, s, c, pa, ct, ${exports.ATTENDANCE_COLLECT}`;
+/**
+ * One field card from one record.
+ *
+ * `address` is set when the `AT_ADDRESS` edge resolved and omitted when it did
+ * not. The **edge** decides the key, read off its own `addressed` column rather
+ * than inferred from the three property columns: a PostalAddress missing its
+ * locality is still somewhere a worker can drive to, and inferring absence from
+ * empty properties would report the site unaddressed while the census, which
+ * counts the edge, called it addressed.
+ *
+ * `own` is the caller's own attendance, passed by `readWorkerDay` and omitted by
+ * the sheet read. With it, the four worker fields are that worker's; without it
+ * they fall back to the sole-attendee rule and go null on a shared visit. The
+ * distinction is load-bearing: a sheet that showed no arrival to the worker who
+ * pressed it would read as a lost press (Task 2512).
+ */
+function projectFieldVisit(g, own) {
+    const addressed = g.get("addressed") === true;
+    const att = projectAttendances(g);
+    const worker = own ?? {
+        workerId: att.workerId,
+        arrivedPressedAt: att.arrivedPressedAt,
+        arrivedObservedAt: att.arrivedObservedAt,
+        arrivedObservedDistanceM: att.arrivedObservedDistanceM,
+    };
+    return {
+        visitId: String(g.get("visitId")),
+        jobId: str(g.get("jobId")),
+        status: String(g.get("status")),
+        startDate: str(g.get("startDate")),
+        endDate: str(g.get("endDate")),
+        purpose: str(g.get("purpose")),
+        attendances: att.attendances,
+        workerId: worker.workerId,
+        arrivedPressedAt: worker.arrivedPressedAt,
+        arrivedObservedAt: worker.arrivedObservedAt,
+        arrivedObservedDistanceM: worker.arrivedObservedDistanceM,
+        siteId: str(g.get("siteId")),
+        siteName: str(g.get("siteName")),
+        customerName: str(g.get("customerName")),
+        contactName: str(g.get("contactName")),
+        contactTelephone: str(g.get("contactTelephone")),
+        ...(addressed
+            ? {
+                address: {
+                    streetAddress: str(g.get("streetAddress")),
+                    addressLocality: str(g.get("addressLocality")),
+                    postalCode: str(g.get("postalCode")),
+                },
+            }
+            : {}),
+    };
+}
+/**
+ * One worker's visits in a window, with the contact detail and the street a
+ * doorstep needs.
  *
  * A separate function rather than a widening of `readDay`, because the planner
  * draws a week of cards for the whole roster and needs a customer's telephone
  * on none of them.
- *
- * **No address and no postcode.** `schema-dispatch.md` declares neither on
- * `:Site`, and the only `PostalAddress` edge in the whole ontology is
- * logistics' `(:Stop)-[:AT_ADDRESS]->(:PostalAddress)`. Returning them as
- * always-null columns would read to a worker as "this site has no address"
- * rather than "we do not store one". Task 2514 adds the edge.
  */
 async function readWorkerDay(accountId, workerId, fromUtc, toUtc) {
     return (0, session_js_1.withSession)(async (session) => {
-        const r = await session.run(`MATCH (v:Visit {accountId: $accountId})-[:ATTENDED_BY]->(e:Engineer {accountId: $accountId, engineerId: $workerId})
+        const r = await session.run(
+        // Anchored on the CALLER'S OWN attendance (`mine`), then the whole
+        // visit's attendances collected beside it. The worker's arrival times are
+        // read off `mine` rather than through the sole-attendee rule: on a visit
+        // they share with somebody, that rule returns null, and a field sheet
+        // showing no arrival to the worker who pressed it reads as a lost press.
+        `MATCH (v:Visit {accountId: $accountId})-[:HAS_ATTENDANCE]->(mine:Attendance)-[:BY_ENGINEER]->(:Engineer {accountId: $accountId, engineerId: $workerId})
        WHERE v.startDate >= $from AND v.startDate < $to
-       OPTIONAL MATCH (j:Job {accountId: $accountId})-[:HAS_VISIT]->(v)
-       OPTIONAL MATCH (j)-[:AT_SITE]->(s:Site {accountId: $accountId})
-       OPTIONAL MATCH (j)-[:FOR_CUSTOMER]->(c:Customer {accountId: $accountId})
-       OPTIONAL MATCH (ct:Contact {accountId: $accountId})-[:CONTACT_FOR]->(c)
-       RETURN v.visitId AS visitId, j.jobId AS jobId, v.status AS status,
-              v.startDate AS startDate, v.endDate AS endDate, v.purpose AS purpose,
-              e.engineerId AS workerId,
-              v.arrivedPressedAt AS arrivedPressedAt,
-              v.arrivedObservedAt AS arrivedObservedAt,
-              v.arrivedObservedDistanceM AS arrivedObservedDistanceM,
-              s.siteId AS siteId, s.name AS siteName,
-              c.name AS customerName,
-              ct.name AS contactName, ct.telephone AS contactTelephone
+       ${fieldOptionalMatches(", mine")}
+       RETURN ${FIELD_RETURN},
+              mine.arrivedPressedAt AS ownArrivedPressedAt,
+              mine.arrivedObservedAt AS ownArrivedObservedAt,
+              mine.arrivedObservedDistanceM AS ownArrivedObservedDistanceM
        ORDER BY v.startDate ASC`, { accountId, workerId, from: fromUtc, to: toUtc });
         // Sorted in the query, not on the client: an empty result and an unsorted
         // one must not be able to look alike.
         return r.records.map((g) => {
-            const dist = g.get("arrivedObservedDistanceM");
-            return {
-                visitId: String(g.get("visitId")),
-                jobId: str(g.get("jobId")),
-                status: String(g.get("status")),
-                startDate: str(g.get("startDate")),
-                endDate: str(g.get("endDate")),
-                purpose: str(g.get("purpose")),
-                workerId: str(g.get("workerId")),
-                arrivedPressedAt: str(g.get("arrivedPressedAt")),
-                arrivedObservedAt: str(g.get("arrivedObservedAt")),
+            const dist = g.get("ownArrivedObservedDistanceM");
+            return projectFieldVisit(g, {
+                workerId,
+                arrivedPressedAt: str(g.get("ownArrivedPressedAt")),
+                arrivedObservedAt: str(g.get("ownArrivedObservedAt")),
                 arrivedObservedDistanceM: dist == null ? null : num(dist),
-                siteId: str(g.get("siteId")),
-                siteName: str(g.get("siteName")),
-                customerName: str(g.get("customerName")),
-                contactName: str(g.get("contactName")),
-                contactTelephone: str(g.get("contactTelephone")),
-            };
+            });
         });
     });
 }
+/**
+ * One visit as a field card, for the job sheet.
+ *
+ * The sheet used to serve a plain `VisitRow`, which carries no site name, no
+ * customer and no contact, so every sheet rendered "Site not named" with no
+ * telephone on it. This is the same projection the day list uses, so the two
+ * screens cannot disagree.
+ *
+ * It takes a session because the sheet route already holds one, and it applies
+ * no worker filter: the route does its own ownership check, and a read that
+ * also filtered would turn another worker's visit into a 404 where the route
+ * means to return a 403.
+ */
+async function readFieldVisit(session, accountId, visitId) {
+    const r = await session.run(
+    // No `mine` to anchor on, because the sheet applies no worker filter, so the
+    // four worker fields fall to the sole-attendee rule and go null on a shared
+    // visit. `attendances` carries everyone either way, which is what the sheet
+    // renders (Task 2512).
+    `MATCH (v:Visit {accountId: $accountId, visitId: $visitId})
+     ${fieldOptionalMatches("")}
+     RETURN ${FIELD_RETURN}
+     LIMIT 1`, { accountId, visitId });
+    if (r.records.length === 0)
+        return null;
+    return projectFieldVisit(r.records[0]);
+}
 /** The job list, owning its own session. */
 async function readJobList(accountId, filter) {
     const { text, params } = buildJobListQuery(filter);