@rubytech/create-maxy-code 0.1.571 → 0.1.573

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

@@ -0,0 +1,562 @@
+/**
+ * Cypher reads. One module, so no caller writes its own query and no query
+ * forgets the `accountId` scope.
+ *
+ * Every query here is account-scoped by property, never by edge. Account scope
+ * is a property in this ontology; an ownership edge added to satisfy an
+ * adjacency rule is a second source of truth that drifts.
+ *
+ * The session-taking functions are the dispatch plugin's, moved here unchanged
+ * so the plugin and the office planner share one implementation. The functions
+ * that own their session (`readDay`, `readJobList`, `readCounts`) are the
+ * planner's, and exist so a route can read the graph while holding none of it.
+ */
+import type { Session } from "neo4j-driver";
+import { withSession } from "./session.js";
+import type {
+  DispatchCounts,
+  FieldVisit,
+  JobListFilter,
+  JobRow,
+  PlannerVisit,
+  VisitRow,
+} from "./types.js";
+
+/** Neo4j integers arrive as `{low, high}`; coerce without losing a real number. */
+function num(v: unknown): number {
+  if (typeof v === "number") return v;
+  if (v && typeof v === "object" && "low" in (v as Record<string, unknown>)) {
+    return Number((v as { low: number }).low);
+  }
+  return Number(v ?? 0);
+}
+
+function str(v: unknown): string | null {
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+
+/** Visits a worker is already committed to inside a window. */
+export interface Commitment {
+  readonly visitId: string;
+  readonly start: string;
+  readonly end: string;
+}
+
+/** What a visit currently carries, for the required-before-terminal gate. */
+export interface VisitRecordState {
+  readonly notes: number;
+  readonly media: number;
+  readonly parts: number;
+  readonly checklistDone: number;
+  readonly checklistTotal: number;
+  readonly signatures: number;
+}
+
+/** Shared job projection, so every job query returns one shape. */
+export function projectJob(g: { get(key: string): unknown }): JobRow {
+  return {
+    jobId: String(g.get("jobId")),
+    status: String(g.get("status")),
+    jobType: str(g.get("jobType")),
+    slaTargetAt: str(g.get("slaTargetAt")),
+    createdAt: str(g.get("createdAt")),
+    siteId: str(g.get("siteId")),
+    siteName: str(g.get("siteName")),
+    customerId: str(g.get("customerId")),
+  };
+}
+
+/** 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")),
+    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")),
+    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),
+  };
+}
+
+export async function readJob(
+  session: Session,
+  accountId: string,
+  jobId: string,
+): Promise<JobRow | null> {
+  const r = await session.run(
+    `MATCH (j:Job {accountId: $accountId, jobId: $jobId})
+     OPTIONAL MATCH (j)-[:AT_SITE]->(s:Site)
+     OPTIONAL MATCH (j)-[:FOR_CUSTOMER]->(c:Customer)
+     RETURN j.jobId AS jobId, j.status AS status, j.jobType AS jobType,
+            j.slaTargetAt AS slaTargetAt, j.createdAt AS createdAt,
+            s.siteId AS siteId, s.name AS siteName, c.customerId AS customerId
+     LIMIT 1`,
+    { accountId, jobId },
+  );
+  if (r.records.length === 0) return null;
+  return projectJob(r.records[0]);
+}
+
+export async function readVisit(
+  session: Session,
+  accountId: string,
+  visitId: string,
+): Promise<VisitRow | null> {
+  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)
+     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
+     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")),
+    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")),
+    arrivedObservedDistanceM: dist == null ? null : num(dist),
+  };
+}
+
+export async function readVisitRecordState(
+  session: Session,
+  accountId: string,
+  visitId: string,
+): Promise<VisitRecordState> {
+  const r = await session.run(
+    `MATCH (v:Visit {accountId: $accountId, visitId: $visitId})
+     RETURN size(coalesce(v.notes, []))         AS notes,
+            size(coalesce(v.media, []))         AS media,
+            size(coalesce(v.parts, []))         AS parts,
+            size(coalesce(v.checklistDone, [])) AS checklistDone,
+            size(coalesce(v.checklist, []))     AS checklistTotal,
+            size(coalesce(v.signatures, []))    AS signatures
+     LIMIT 1`,
+    { accountId, visitId },
+  );
+  if (r.records.length === 0) {
+    return {
+      notes: 0,
+      media: 0,
+      parts: 0,
+      checklistDone: 0,
+      checklistTotal: 0,
+      signatures: 0,
+    };
+  }
+  const g = r.records[0];
+  return {
+    notes: num(g.get("notes")),
+    media: num(g.get("media")),
+    parts: num(g.get("parts")),
+    checklistDone: num(g.get("checklistDone")),
+    checklistTotal: num(g.get("checklistTotal")),
+    signatures: num(g.get("signatures")),
+  };
+}
+
+export async function readVisitsForJob(
+  session: Session,
+  accountId: string,
+  jobId: string,
+): 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)
+     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
+     ORDER BY v.startDate ASC`,
+    { accountId, jobId },
+  );
+  return r.records.map((g) => {
+    const dist = g.get("arrivedObservedDistanceM");
+    return {
+      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")),
+      workerId: str(g.get("workerId")),
+      arrivedPressedAt: str(g.get("arrivedPressedAt")),
+      arrivedObservedAt: str(g.get("arrivedObservedAt")),
+      arrivedObservedDistanceM: dist == null ? null : num(dist),
+    };
+  });
+}
+
+/** Visits a worker is already committed to inside `[from, to)`. */
+export async function readCommitments(
+  session: Session,
+  accountId: string,
+  from: string,
+  to: string,
+): Promise<Map<string, Commitment[]>> {
+  const r = await session.run(
+    `MATCH (v:Visit {accountId: $accountId})-[:ATTENDED_BY]->(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 },
+  );
+  const out = new Map<string, Commitment[]>();
+  for (const g of r.records) {
+    const workerId = str(g.get("workerId"));
+    if (!workerId) continue;
+    const list = out.get(workerId) ?? [];
+    list.push({
+      visitId: String(g.get("visitId")),
+      start: String(g.get("start")),
+      end: String(g.get("end")),
+    });
+    out.set(workerId, list);
+  }
+  return out;
+}
+
+/**
+ * The job-list query as text plus params, extracted so its shape is testable
+ * without a database.
+ */
+export function buildJobListQuery(filter: JobListFilter): {
+  text: string;
+  params: Record<string, unknown>;
+} {
+  const clauses: string[] = ["j.accountId = $accountId"];
+  if (filter.status) clauses.push("j.status = $status");
+  if (filter.jobType) clauses.push("j.jobType = $jobType");
+  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 }",
+    );
+  }
+  // One EXISTS carrying both bounds, never two. Two independent clauses are
+  // satisfied by DIFFERENT visits — a job with one visit in January and another
+  // in December would match a March window, because January satisfies the
+  // upper bound and December the lower. The window has to hold of a single
+  // visit for the job to have been worked in that window.
+  if (filter.from || filter.to) {
+    const bounds = [
+      filter.from ? "wv.startDate >= $from" : null,
+      filter.to ? "wv.startDate < $to" : null,
+    ]
+      .filter(Boolean)
+      .join(" AND ");
+    clauses.push(`EXISTS { MATCH (j)-[:HAS_VISIT]->(wv:Visit) WHERE ${bounds} }`);
+  }
+  return {
+    text: `MATCH (j:Job)
+     WHERE ${clauses.join(" AND ")}
+     OPTIONAL MATCH (j)-[:AT_SITE]->(s:Site)
+     OPTIONAL MATCH (j)-[:FOR_CUSTOMER]->(c:Customer)
+     RETURN j.jobId AS jobId, j.status AS status, j.jobType AS jobType,
+            j.slaTargetAt AS slaTargetAt, j.createdAt AS createdAt,
+            s.siteId AS siteId, s.name AS siteName, c.customerId AS customerId
+     ORDER BY coalesce(j.slaTargetAt, j.createdAt) ASC
+     LIMIT $limit`,
+    params: {
+      status: filter.status ?? null,
+      jobType: filter.jobType ?? null,
+      workerId: filter.workerId ?? null,
+      from: filter.from ?? null,
+      to: filter.to ?? null,
+      limit: Math.min(Math.max(filter.limit ?? 50, 1), 500),
+    },
+  };
+}
+
+export async function readJobs(
+  session: Session,
+  accountId: string,
+  filter: JobListFilter,
+): Promise<JobRow[]> {
+  const { text, params } = buildJobListQuery(filter);
+  const r = await session.run(text, { accountId, ...params });
+  return r.records.map(projectJob);
+}
+
+/** Element id of an existing node on this account, or null. */
+export async function readNodeId(
+  session: Session,
+  accountId: string,
+  label: "Site" | "Customer" | "Engineer" | "Vehicle",
+  keyProp: string,
+  keyValue: string,
+): Promise<string | null> {
+  const r = await session.run(
+    `MATCH (n:${label} {accountId: $accountId}) WHERE n[$keyProp] = $keyValue
+     RETURN elementId(n) AS id LIMIT 1`,
+    { accountId, keyProp, keyValue },
+  );
+  return r.records.length === 0 ? null : String(r.records[0].get("id"));
+}
+
+/** Every visit at one site, newest first, with its job. */
+export async function readSiteHistory(
+  session: Session,
+  accountId: string,
+  siteId: string,
+  limit: number,
+): Promise<Array<VisitRow & { jobStatus: string; notes: string[]; mediaCount: number }>> {
+  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)
+     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,
+            coalesce(v.notes, []) AS notes,
+            size(coalesce(v.media, [])) AS mediaCount,
+            v.arrivedPressedAt AS arrivedPressedAt,
+            v.arrivedObservedAt AS arrivedObservedAt,
+            v.arrivedObservedDistanceM AS arrivedObservedDistanceM
+     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),
+    };
+  });
+}
+
+/** Every visit starting inside `[from, to)`. */
+export async function readVisitsInWindow(
+  session: Session,
+  accountId: string,
+  from: string,
+  to: string,
+): Promise<Array<VisitRow & { siteName: string | null }>> {
+  const r = await session.run(
+    `MATCH (v:Visit {accountId: $accountId})
+     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)
+     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
+     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),
+    };
+  });
+}
+
+/**
+ * Visit ids whose `startDate` is not Zulu-normalised.
+ *
+ * The window compare above is lexical, so an offset-bearing start is wrong by
+ * the offset: correct under GMT, an hour out under BST. `dispatch-allocate`
+ * stores the caller's `start` string verbatim while normalising `end` through
+ * `toISOString`, so this cannot be corrected on read. It can only be made
+ * visible, which is what this is for.
+ */
+export function nonZuluStarts(visits: readonly PlannerVisit[]): string[] {
+  return visits
+    .filter((v) => v.startDate !== null && !v.startDate.endsWith("Z"))
+    .map((v) => v.visitId);
+}
+
+/**
+ * Every visit starting inside `[fromUtc, toUtc)`, carrying the fields a planner
+ * card needs. The shipped window read returns `siteName` only, so a card had no
+ * customer and no job type to show.
+ */
+export async function readDay(
+  accountId: string,
+  fromUtc: string,
+  toUtc: string,
+): Promise<PlannerVisit[]> {
+  return withSession(async (session) => {
+    const r = await session.run(
+      `MATCH (v:Visit {accountId: $accountId})
+       WHERE v.startDate >= $from AND v.startDate < $to
+       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)
+       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,
+              c.customerId AS customerId, c.name AS customerName,
+              j.jobType AS jobType,
+              v.arrivedPressedAt AS arrivedPressedAt,
+              v.arrivedObservedAt AS arrivedObservedAt,
+              v.arrivedObservedDistanceM AS arrivedObservedDistanceM
+       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.
+ *
+ * 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,
+  workerId: string,
+  fromUtc: string,
+  toUtc: string,
+): Promise<FieldVisit[]> {
+  return withSession(async (session) => {
+    const r = await session.run(
+      `MATCH (v:Visit {accountId: $accountId})-[:ATTENDED_BY]->(e: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
+       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")),
+        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")),
+      };
+    });
+  });
+}
+
+/** The job list, owning its own session. */
+export async function readJobList(
+  accountId: string,
+  filter: JobListFilter,
+): Promise<JobRow[]> {
+  const { text, params } = buildJobListQuery(filter);
+  return withSession(async (session) => {
+    const r = await session.run(text, { accountId, ...params });
+    return r.records.map(projectJob);
+  });
+}
+
+/**
+ * True counts, as aggregates.
+ *
+ * `readJobList` caps at 500 rows, so the length of its result is not the number
+ * of open jobs on an account with 2,869 of them. `overdue` is computed here
+ * rather than stored, because a stored flag goes stale the moment the clock
+ * passes the target with nothing writing to the row.
+ */
+export async function readCounts(
+  accountId: string,
+  terminalJobStatuses: readonly string[],
+  nowIso: string,
+): Promise<DispatchCounts> {
+  return withSession(async (session) => {
+    const r = await session.run(
+      `MATCH (j:Job {accountId: $accountId})
+       WITH j,
+            NOT (j)-[:HAS_VISIT]->(:Visit) AS unallocated,
+            (j.slaTargetAt IS NOT NULL AND j.slaTargetAt < $nowIso
+               AND NOT j.status IN $terminalJob) AS overdue
+       RETURN count(j) AS total,
+              sum(CASE WHEN unallocated THEN 1 ELSE 0 END) AS unallocated,
+              sum(CASE WHEN overdue THEN 1 ELSE 0 END) AS overdue`,
+      { accountId, nowIso, terminalJob: terminalJobStatuses },
+    );
+    const g = r.records[0];
+    return {
+      total: num(g?.get("total")),
+      unallocated: num(g?.get("unallocated")),
+      overdue: num(g?.get("overdue")),
+    };
+  });
+}

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

@@ -0,0 +1,50 @@
+import { existsSync, readFileSync } from "node:fs";
+import neo4j, { type Driver, type Session } from "neo4j-driver";
+
+/**
+ * This package owns its Neo4j session.
+ *
+ * That is the point of the package. Callers ask for a day or a count and never
+ * hold a URI, a password or a session, so the office planner's route can be
+ * asserted to contain no graph access at all while still reading the graph.
+ */
+
+let driver: Driver | null = null;
+
+function password(): string {
+  if (process.env.NEO4J_PASSWORD) return process.env.NEO4J_PASSWORD;
+  const file = process.env.NEO4J_PASSWORD_FILE;
+  if (file && existsSync(file)) return readFileSync(file, "utf-8").trim();
+  throw new Error(
+    "[dispatch-read] Neo4j password not found in NEO4J_PASSWORD or NEO4J_PASSWORD_FILE",
+  );
+}
+
+function getDriver(): Driver {
+  if (driver) return driver;
+  // Never defaulted. Brands are isolated and each runs its own Neo4j port, so a
+  // localhost fallback would silently read another brand's graph.
+  const uri = process.env.NEO4J_URI;
+  if (!uri) {
+    throw new Error(
+      "[dispatch-read] NEO4J_URI unset — refusing to default to bolt://localhost:7687",
+    );
+  }
+  driver = neo4j.driver(uri, neo4j.auth.basic(process.env.NEO4J_USER ?? "neo4j", password()));
+  return driver;
+}
+
+/** Acquire, run, always close. */
+export async function withSession<T>(fn: (session: Session) => Promise<T>): Promise<T> {
+  const session = getDriver().session();
+  try {
+    return await fn(session);
+  } finally {
+    await session.close();
+  }
+}
+
+/** Test seam: inject a driver so read tests never open a socket. */
+export function __setDriverForTests(d: Driver | null): void {
+  driver = d;
+}