@rubytech/create-realagent-code 0.1.573 → 0.1.575

package/payload/platform/lib/dispatch-read/src/read.ts

@@ -14,11 +14,13 @@
 import type { Session } from "neo4j-driver";
 import { withSession } from "./session.js";
 import type {
+  Attendance,
   DispatchCounts,
   FieldVisit,
   JobListFilter,
   JobRow,
   PlannerVisit,
+  SiteLocation,
   VisitRow,
 } from "./types.js";
 
@@ -52,6 +54,70 @@ export interface VisitRecordState {
   readonly signatures: number;
 }
 
+/**
+ * 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.
+ */
+export const ATTENDANCE_MATCH =
+  `OPTIONAL MATCH (v)-[:HAS_ATTENDANCE]->(att:Attendance)-[:BY_ENGINEER]->(e:Engineer)`;
+
+/** The collected list, named `attendances`. Pair with `ATTENDANCE_MATCH`. */
+export const 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.
+ */
+export function projectAttendances(g: { get(key: string): unknown }): {
+  attendances: Attendance[];
+  workerId: string | null;
+  arrivedPressedAt: string | null;
+  arrivedObservedAt: string | null;
+  arrivedObservedDistanceM: number | null;
+} {
+  const raw = (g.get("attendances") as Array<Record<string, unknown>> | null) ?? [];
+  const attendances: Attendance[] = 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. */
 export function projectJob(g: { get(key: string): unknown }): JobRow {
   return {
@@ -68,7 +134,6 @@ export function projectJob(g: { get(key: string): unknown }): JobRow {
 
 /** Shared visit projection, so the day read and its tests cannot drift apart. */
 export function projectVisit(g: { get(key: string): unknown }): PlannerVisit {
-  const dist = g.get("arrivedObservedDistanceM");
   return {
     visitId: String(g.get("visitId")),
     jobId: str(g.get("jobId")),
@@ -76,14 +141,11 @@ export function projectVisit(g: { get(key: string): unknown }): PlannerVisit {
     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),
   };
 }
 
@@ -114,19 +176,16 @@ export async function readVisit(
   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)
+     ${ATTENDANCE_MATCH}
+     WITH v, j, ${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")),
@@ -134,10 +193,7 @@ export async function readVisit(
     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),
   };
 }
 
@@ -185,27 +241,69 @@ export async function readVisitsForJob(
 ): Promise<VisitRow[]> {
   const r = await session.run(
     `MATCH (j:Job {accountId: $accountId, jobId: $jobId})-[:HAS_VISIT]->(v:Visit)
-     OPTIONAL MATCH (v)-[:ATTENDED_BY]->(e:Engineer)
+     ${ATTENDANCE_MATCH}
+     WITH v, ${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.
+ */
+export async function readOpenVisitsForWorker(
+  session: Session,
+  accountId: string,
+  workerId: string,
+  terminalStatuses: readonly string[],
+): Promise<VisitRow[]> {
+  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)
+     ${ATTENDANCE_MATCH}
+     WITH v, j, mine, ${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),
     };
   });
@@ -219,7 +317,9 @@ export async function readCommitments(
   to: string,
 ): Promise<Map<string, Commitment[]>> {
   const r = await session.run(
-    `MATCH (v:Visit {accountId: $accountId})-[:ATTENDED_BY]->(e:Engineer)
+    // 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`,
@@ -240,6 +340,72 @@ export async function readCommitments(
   return out;
 }
 
+/** Where a worker was last, for the travel estimate at allocation. */
+export interface PreviousVisit {
+  readonly visitId: string;
+  /** Null when the visit's job was never linked to a site. */
+  readonly siteId: string | null;
+}
+
+/**
+ * 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.
+ */
+export async function readPreviousVisits(
+  session: Session,
+  accountId: string,
+  before: string,
+  dayStart: string,
+): Promise<Map<string, PreviousVisit>> {
+  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<string, PreviousVisit>();
+  const latest = new Map<string, string>();
+  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.
@@ -254,7 +420,7 @@ export function buildJobListQuery(filter: JobListFilter): {
   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 }",
+      "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
@@ -306,7 +472,7 @@ export async function readJobs(
 export async function readNodeId(
   session: Session,
   accountId: string,
-  label: "Site" | "Customer" | "Engineer" | "Vehicle",
+  label: "Site" | "Customer" | "Engineer" | "Vehicle" | "Job",
   keyProp: string,
   keyValue: string,
 ): Promise<string | null> {
@@ -318,6 +484,128 @@ export async function readNodeId(
   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.
+ */
+export async function readSiteLocation(
+  session: Session,
+  accountId: string,
+  siteId: string,
+): Promise<SiteLocation | null> {
+  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),
+  };
+}
+
+
+/**
+ * One intake draft. Every optional property is returned explicitly as null
+ * rather than omitted, so a caller can tell "the draft does not carry this"
+ * from "the read did not ask for it".
+ */
+export interface DraftRow {
+  draftId: string;
+  receivedAt: string;
+  source: string;
+  sourceRef: string;
+  jobType: string | null;
+  siteId: string | null;
+  customerId: string | null;
+  description: string | null;
+  verdict: string | null;
+  decidedAt: string | null;
+  decidedBy: string | null;
+  reason: string | null;
+  jobId: string | null;
+}
+
+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: { get(key: string): unknown }): DraftRow {
+  const s = (k: string): string | null => {
+    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. */
+export async function readDraft(
+  session: Session,
+  accountId: string,
+  draftId: string,
+): Promise<DraftRow | null> {
+  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.
+ */
+export async function readDrafts(
+  session: Session,
+  accountId: string,
+  verdict: string | null,
+  limit: number,
+): Promise<DraftRow[]> {
+  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. */
 export async function readSiteHistory(
   session: Session,
@@ -328,39 +616,31 @@ export async function readSiteHistory(
   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)
+     ${ATTENDANCE_MATCH}
+     WITH j, v, ${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") as string[]) ?? [],
-      // 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") as string[]) ?? [],
+    // 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)`. */
@@ -375,32 +655,24 @@ export async function readVisitsInWindow(
      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)
+     ${ATTENDANCE_MATCH}
+     WITH v, j, s, ${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),
+  }));
 }
 
 /**
@@ -435,15 +707,13 @@ export async function readDay(
        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)
+       ${ATTENDANCE_MATCH}
+       WITH v, j, s, c, ${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 },
     );
@@ -452,17 +722,131 @@ export async function readDay(
 }
 
 /**
- * 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: string) =>
+  `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
+       ${ATTENDANCE_MATCH}
+       WITH v${carry}, j, s, c, pa, ct, ${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).
+ */
+export function projectFieldVisit(
+  g: { get(key: string): unknown },
+  own?: Attendance,
+): FieldVisit {
+  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.
  */
 export async function readWorkerDay(
   accountId: string,
@@ -472,49 +856,68 @@ export async function readWorkerDay(
 ): Promise<FieldVisit[]> {
   return withSession(async (session) => {
     const r = await session.run(
-      `MATCH (v:Visit {accountId: $accountId})-[:ATTENDED_BY]->(e:Engineer {accountId: $accountId, engineerId: $workerId})
+      // 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.
+ */
+export async function readFieldVisit(
+  session: Session,
+  accountId: string,
+  visitId: string,
+): Promise<FieldVisit | null> {
+  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. */
 export async function readJobList(
   accountId: string,