@rubytech/create-realagent-code 0.1.574 → 0.1.575

package/dist/index.js

@@ -3419,6 +3419,20 @@ function setupAccount() {
             env: { ...neo4jEnv, PLATFORM_ROOT: join(INSTALL_DIR, "platform") },
         });
     }
+    // Task 2513 — converge :Visit.startDate and :Visit.endDate onto canonical
+    // UTC. The planner window compares startDate to Z-suffixed bounds LEXICALLY,
+    // so a row storing a +01:00 offset lands in the wrong day under BST. Runs
+    // after the seed for the same reasons the two convergences above do, and is
+    // scoped to this install's accounts so a co-resident brand sharing one Neo4j
+    // is untouched. Idempotent: a converged install rewrites nothing and prints
+    // op=start-migration rewritten=0.
+    const convergeVisitInstants = join(INSTALL_DIR, "platform/plugins/dispatch/mcp/dist/scripts/converge-visit-instants.js");
+    if (existsSync(convergeVisitInstants)) {
+        shell("node", [convergeVisitInstants], {
+            cwd: INSTALL_DIR,
+            env: { ...neo4jEnv, PLATFORM_ROOT: join(INSTALL_DIR, "platform") },
+        });
+    }
     // Task 2460 — clear the brand-wide agent root this step used to write.
     // Every bundled specialist now reaches a session through the per-account
     // registry that `syncAccountAgentRegistry` mirrors at spawn from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent-code",
-  "version": "0.1.574",
+  "version": "0.1.575",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent-code": "./dist/index.js"

package/payload/platform/lib/canonical-instant/dist/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The single definition of a canonical stored instant.
+ *
+ * Extracted from `plugins/scheduling/mcp/src/lib/time-format.ts` by Task 2513,
+ * unchanged, so the dispatch writer, the dispatch migration and the two
+ * scheduling writers cannot disagree about what canonical means. Task 2213
+ * stated the invariant as "One function, three callers, no drift possible"; a
+ * second copy in the dispatch tree would have broken it.
+ *
+ * Pure. No database, no driver, no plugin import.
+ */
+/**
+ * Validates an IANA timezone string. Throws with a clear message if invalid.
+ */
+export declare function validateTimezone(tz: string): void;
+/**
+ * The exact 24-character shape `toISOString()` produces, as a regex source.
+ *
+ * Exported as a string rather than a `RegExp` because it is also passed to
+ * Cypher as a `=~` parameter. One source, so the standing audit's predicate and
+ * this module's predicate cannot drift; passing it as a parameter also removes
+ * the backslash-escaping ambiguity of an inlined Cypher literal.
+ */
+export declare const CANONICAL_INSTANT_PATTERN = "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z";
+/**
+ * Task 2213, generalised by Task 2513 — the single definition of a canonical
+ * stored instant.
+ *
+ * Stored instants are compared as STRINGS, lexically, in Cypher: the scheduling
+ * dispatcher on `e.startDate <= $now`, and the dispatch planner on
+ * `v.startDate >= $from AND v.startDate < $to`. An offset suffix is never
+ * parsed, so a `+01:00` value sorts by its wall-clock digits — 60 minutes out
+ * under BST, and correct under GMT, which is why the defect self-heals every
+ * October and returns every March.
+ *
+ * The output is therefore always the exact 24-character shape `toISOString()`
+ * produces. The fixed width is the point: lexical order equals instant order
+ * only when every stored value shares one shape. That is also why this is not
+ * done in Cypher — `toString(datetime(...))` omits `.000` at a zero-millisecond
+ * instant, and `"…00.000Z"` sorts BEFORE `"…00Z"`.
+ *
+ * A zoneless wall clock is read in `zone`, never in the server's zone: a
+ * server-local reading makes the stored instant depend on which machine wrote
+ * it, which is the same fault class one layer down. With no usable zone this
+ * throws rather than guessing.
+ *
+ * DST is resolved the way `Temporal`'s `disambiguation: 'compatible'` resolves
+ * it. Take the offsets in force a day either side, giving two candidate
+ * instants; keep those that render back to exactly the input wall clock. If any
+ * survive, take the earliest (the earlier occurrence of an ambiguous autumn
+ * time). If none survive, the wall clock is inside a spring-forward gap and does
+ * not exist, so take the later candidate, which shifts it past the gap.
+ */
+export declare function normaliseInstant(raw: string, zone: string | null): string;
+/** True when `value` is already in the canonical form above. */
+export declare function isCanonicalInstant(value: string): boolean;
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/canonical-instant/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAYjD;AA6CD;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,wDAAwD,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CA8BzE;AAED,gEAAgE;AAChE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEzD"}

package/payload/platform/lib/canonical-instant/dist/index.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * The single definition of a canonical stored instant.
+ *
+ * Extracted from `plugins/scheduling/mcp/src/lib/time-format.ts` by Task 2513,
+ * unchanged, so the dispatch writer, the dispatch migration and the two
+ * scheduling writers cannot disagree about what canonical means. Task 2213
+ * stated the invariant as "One function, three callers, no drift possible"; a
+ * second copy in the dispatch tree would have broken it.
+ *
+ * Pure. No database, no driver, no plugin import.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANONICAL_INSTANT_PATTERN = void 0;
+exports.validateTimezone = validateTimezone;
+exports.normaliseInstant = normaliseInstant;
+exports.isCanonicalInstant = isCanonicalInstant;
+/**
+ * Validates an IANA timezone string. Throws with a clear message if invalid.
+ */
+function validateTimezone(tz) {
+    if (!tz || tz.trim().length === 0) {
+        throw new Error("Timezone is required but was empty");
+    }
+    try {
+        // Intl.DateTimeFormat throws RangeError for invalid IANA timezone identifiers
+        new Intl.DateTimeFormat("en-GB", { timeZone: tz });
+    }
+    catch {
+        throw new Error(`Invalid timezone: "${tz}" — expected IANA format like "Europe/London" or "America/New_York"`);
+    }
+}
+/** Ends with `Z` or a numeric UTC offset, e.g. `+01:00`, `-0500`. */
+const HAS_ZONE = /(?:Z|[+-]\d{2}:?\d{2})$/;
+/** The zone's wall-clock parts at a given instant. */
+function partsAt(ms, zone) {
+    const dtf = new Intl.DateTimeFormat("en-GB", {
+        timeZone: zone,
+        hour12: false,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+    });
+    return Object.fromEntries(dtf.formatToParts(new Date(ms)).map((p) => [p.type, p.value]));
+}
+/**
+ * Milliseconds the zone is ahead of UTC at `ms`.
+ *
+ * Subtracted against the SECOND-truncated instant, never `ms` itself.
+ * `Intl.DateTimeFormat` resolves only to seconds, so differencing its
+ * reconstruction against a millisecond-bearing instant folds the fractional part
+ * into the offset: at `09:00:00.500` the offset came back as 3_599_500 rather
+ * than 3_600_000, and the caller's `naive - offset` then landed a full second
+ * out. A real zone offset is always a whole number of minutes, so truncating is
+ * lossless here and keeps the caller's sub-second precision intact.
+ */
+function offsetMsAt(ms, zone) {
+    const p = partsAt(ms, zone);
+    // `hour` renders as "24" for midnight in en-GB; % 24 folds it back to 0.
+    const wallUtc = Date.UTC(+p.year, +p.month - 1, +p.day, +p.hour % 24, +p.minute, +p.second);
+    return wallUtc - Math.floor(ms / 1000) * 1000;
+}
+/** The zone's wall clock at `ms`, in the same shape as a zoneless input. */
+function wallAt(ms, zone) {
+    const p = partsAt(ms, zone);
+    const hh = String(+p.hour % 24).padStart(2, "0");
+    return `${p.year}-${p.month}-${p.day}T${hh}:${p.minute}:${p.second}`;
+}
+/**
+ * The exact 24-character shape `toISOString()` produces, as a regex source.
+ *
+ * Exported as a string rather than a `RegExp` because it is also passed to
+ * Cypher as a `=~` parameter. One source, so the standing audit's predicate and
+ * this module's predicate cannot drift; passing it as a parameter also removes
+ * the backslash-escaping ambiguity of an inlined Cypher literal.
+ */
+exports.CANONICAL_INSTANT_PATTERN = "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z";
+/**
+ * Task 2213, generalised by Task 2513 — the single definition of a canonical
+ * stored instant.
+ *
+ * Stored instants are compared as STRINGS, lexically, in Cypher: the scheduling
+ * dispatcher on `e.startDate <= $now`, and the dispatch planner on
+ * `v.startDate >= $from AND v.startDate < $to`. An offset suffix is never
+ * parsed, so a `+01:00` value sorts by its wall-clock digits — 60 minutes out
+ * under BST, and correct under GMT, which is why the defect self-heals every
+ * October and returns every March.
+ *
+ * The output is therefore always the exact 24-character shape `toISOString()`
+ * produces. The fixed width is the point: lexical order equals instant order
+ * only when every stored value shares one shape. That is also why this is not
+ * done in Cypher — `toString(datetime(...))` omits `.000` at a zero-millisecond
+ * instant, and `"…00.000Z"` sorts BEFORE `"…00Z"`.
+ *
+ * A zoneless wall clock is read in `zone`, never in the server's zone: a
+ * server-local reading makes the stored instant depend on which machine wrote
+ * it, which is the same fault class one layer down. With no usable zone this
+ * throws rather than guessing.
+ *
+ * DST is resolved the way `Temporal`'s `disambiguation: 'compatible'` resolves
+ * it. Take the offsets in force a day either side, giving two candidate
+ * instants; keep those that render back to exactly the input wall clock. If any
+ * survive, take the earliest (the earlier occurrence of an ambiguous autumn
+ * time). If none survive, the wall clock is inside a spring-forward gap and does
+ * not exist, so take the later candidate, which shifts it past the gap.
+ */
+function normaliseInstant(raw, zone) {
+    const trimmed = raw.trim();
+    if (HAS_ZONE.test(trimmed)) {
+        const ms = Date.parse(trimmed);
+        if (Number.isNaN(ms)) {
+            throw new Error(`Unparseable instant: "${raw}" — expected an ISO 8601 date-time`);
+        }
+        return new Date(ms).toISOString();
+    }
+    if (!zone) {
+        throw new Error(`Instant "${raw}" carries no timezone offset and no timezone is available to read it in — ` +
+            `pass an IANA timezone, or write the offset into the value`);
+    }
+    validateTimezone(zone);
+    const naive = Date.parse(`${trimmed}Z`);
+    if (Number.isNaN(naive)) {
+        throw new Error(`Unparseable instant: "${raw}" — expected an ISO 8601 date-time`);
+    }
+    const DAY_MS = 86_400_000;
+    const before = naive - offsetMsAt(naive - DAY_MS, zone);
+    const after = naive - offsetMsAt(naive + DAY_MS, zone);
+    const valid = [before, after].filter((ms) => wallAt(ms, zone) === trimmed);
+    const chosen = valid.length > 0 ? Math.min(...valid) : Math.max(before, after);
+    return new Date(chosen).toISOString();
+}
+/** True when `value` is already in the canonical form above. */
+function isCanonicalInstant(value) {
+    return new RegExp(`^${exports.CANONICAL_INSTANT_PATTERN}$`).test(value);
+}
+//# sourceMappingURL=index.js.map

package/payload/platform/lib/canonical-instant/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/payload/platform/lib/canonical-instant/src/__tests__/normalise-instant.test.ts

@@ -0,0 +1,158 @@
+// Task 2213. The due predicate compares startDate lexically against
+// new Date().toISOString(), so every stored value must share that exact shape.
+import { describe, it, expect } from "vitest";
+import { CANONICAL_INSTANT_PATTERN, normaliseInstant, isCanonicalInstant } from "../index.js";
+
+describe("normaliseInstant — offset-bearing input", () => {
+  it("converts a BST offset to the equivalent UTC instant", () => {
+    expect(normaliseInstant("2026-07-30T11:45:00+01:00", "Europe/London")).toBe(
+      "2026-07-30T10:45:00.000Z"
+    );
+  });
+  it("leaves an already-canonical value byte-identical", () => {
+    expect(normaliseInstant("2026-06-28T05:00:00.000Z", "UTC")).toBe("2026-06-28T05:00:00.000Z");
+  });
+  it("adds the missing .000 to a Z value that lacks it", () => {
+    expect(normaliseInstant("2026-07-28T10:00:00Z", "UTC")).toBe("2026-07-28T10:00:00.000Z");
+  });
+  it("handles the milliseconds-plus-offset shape", () => {
+    expect(normaliseInstant("2026-08-02T19:00:00.000+01:00", "Europe/London")).toBe(
+      "2026-08-02T18:00:00.000Z"
+    );
+  });
+  it("ignores the zone argument entirely when the value carries one", () => {
+    expect(normaliseInstant("2026-07-30T11:45:00+01:00", "America/New_York")).toBe(
+      "2026-07-30T10:45:00.000Z"
+    );
+  });
+});
+
+describe("normaliseInstant — zoneless wall clock", () => {
+  it("reads a summer wall clock in the given zone", () => {
+    expect(normaliseInstant("2026-07-20T09:00:00", "Europe/London")).toBe(
+      "2026-07-20T08:00:00.000Z"
+    );
+  });
+  it("reads a winter wall clock in the given zone", () => {
+    expect(normaliseInstant("2026-01-15T09:00:00", "Europe/London")).toBe(
+      "2026-01-15T09:00:00.000Z"
+    );
+  });
+  it("reads a non-UK zone", () => {
+    expect(normaliseInstant("2026-07-20T09:00:00", "America/New_York")).toBe(
+      "2026-07-20T13:00:00.000Z"
+    );
+  });
+  it("shifts a spring-forward gap wall clock past the gap", () => {
+    // 01:30 on 29 Mar 2026 does not exist in Europe/London; 01:00 GMT -> 02:00 BST.
+    expect(normaliseInstant("2026-03-29T01:30:00", "Europe/London")).toBe(
+      "2026-03-29T01:30:00.000Z"
+    );
+  });
+  it("takes the earlier occurrence of an ambiguous autumn wall clock", () => {
+    // 01:30 on 25 Oct 2026 happens twice; the earlier one is BST at 00:30Z.
+    expect(normaliseInstant("2026-10-25T01:30:00", "Europe/London")).toBe(
+      "2026-10-25T00:30:00.000Z"
+    );
+  });
+  it("takes the earlier occurrence of an ambiguous US wall clock", () => {
+    expect(normaliseInstant("2026-11-01T01:30:00", "America/New_York")).toBe(
+      "2026-11-01T05:30:00.000Z"
+    );
+  });
+});
+
+describe("normaliseInstant — partial and sub-second precision", () => {
+  it("keeps the fractional second on a zoneless value", () => {
+    // Intl resolves only to seconds. Differencing its reconstruction against a
+    // millisecond-bearing instant used to fold the fraction into the offset and
+    // land a full second out (09:00:00.5 BST came back as 08:00:01.000Z).
+    expect(normaliseInstant("2026-07-20T09:00:00.5", "Europe/London")).toBe(
+      "2026-07-20T08:00:00.500Z"
+    );
+    expect(normaliseInstant("2026-01-15T09:00:00.123", "Europe/London")).toBe(
+      "2026-01-15T09:00:00.123Z"
+    );
+  });
+
+  it("reads a minute-precision value in the zone", () => {
+    expect(normaliseInstant("2026-07-20T09:00", "Europe/London")).toBe(
+      "2026-07-20T08:00:00.000Z"
+    );
+  });
+
+  it("reads a date-only value as midnight in the zone", () => {
+    // Midnight on 20 July in London is 23:00Z on the 19th.
+    expect(normaliseInstant("2026-07-20", "Europe/London")).toBe("2026-07-19T23:00:00.000Z");
+    expect(normaliseInstant("2026-01-15", "Europe/London")).toBe("2026-01-15T00:00:00.000Z");
+  });
+
+  it("accepts an offset written without a colon", () => {
+    expect(normaliseInstant("2026-07-20T09:00:00+0100", "Europe/London")).toBe(
+      "2026-07-20T08:00:00.000Z"
+    );
+  });
+});
+
+describe("normaliseInstant — refusals", () => {
+  it("throws on a zoneless value with a null zone, naming the value", () => {
+    expect(() => normaliseInstant("2026-07-20T09:00:00", null)).toThrow(/2026-07-20T09:00:00/);
+  });
+  it("throws on a zoneless value with an invalid zone", () => {
+    expect(() => normaliseInstant("2026-07-20T09:00:00", "Not/AZone")).toThrow(/Not\/AZone/);
+  });
+  it("throws on an unparseable value, naming it", () => {
+    expect(() => normaliseInstant("next tuesday", "Europe/London")).toThrow(/next tuesday/);
+  });
+});
+
+describe("normaliseInstant — server timezone independence", () => {
+  it("gives the same answer whatever the process TZ is", () => {
+    // A server-local reading (new Date("2026-07-20T09:00:00")) would differ here.
+    const before = process.env.TZ;
+    try {
+      process.env.TZ = "Asia/Tokyo";
+      expect(normaliseInstant("2026-07-20T09:00:00", "Europe/London")).toBe(
+        "2026-07-20T08:00:00.000Z"
+      );
+      process.env.TZ = "America/Los_Angeles";
+      expect(normaliseInstant("2026-07-20T09:00:00", "Europe/London")).toBe(
+        "2026-07-20T08:00:00.000Z"
+      );
+    } finally {
+      process.env.TZ = before;
+    }
+  });
+});
+
+describe("isCanonicalInstant", () => {
+  it("accepts only the full 24-character shape", () => {
+    expect(isCanonicalInstant("2026-07-30T10:45:00.000Z")).toBe(true);
+    // Right instant, wrong shape: "…00.000Z" sorts BEFORE "…00Z", so a mixed
+    // corpus breaks the ordering the whole fix restores.
+    expect(isCanonicalInstant("2026-07-30T10:45:00Z")).toBe(false);
+    expect(isCanonicalInstant("2026-07-30T11:45:00+01:00")).toBe(false);
+    expect(isCanonicalInstant("2026-07-20T09:00:00")).toBe(false);
+  });
+});
+
+describe("CANONICAL_INSTANT_PATTERN", () => {
+  // The pattern is also handed to Cypher as a `=~` parameter. 2213's review
+  // found its audit regex was never executed by any test, the session being
+  // mocked. This executes the exact exported string.
+  const re = new RegExp(`^${CANONICAL_INSTANT_PATTERN}$`);
+
+  it("accepts exactly what isCanonicalInstant accepts", () => {
+    for (const v of ["2026-08-07T09:00:00.000Z", "2026-01-15T23:59:59.999Z"]) {
+      expect(re.test(v)).toBe(true);
+      expect(isCanonicalInstant(v)).toBe(true);
+    }
+  });
+
+  it("rejects the three non-canonical forms", () => {
+    for (const v of ["2026-08-07T09:00:00+01:00", "2026-08-07T09:00:00Z", "2026-08-07T09:00:00"]) {
+      expect(re.test(v)).toBe(false);
+      expect(isCanonicalInstant(v)).toBe(false);
+    }
+  });
+});

package/payload/platform/lib/canonical-instant/src/index.ts

@@ -0,0 +1,147 @@
+/**
+ * The single definition of a canonical stored instant.
+ *
+ * Extracted from `plugins/scheduling/mcp/src/lib/time-format.ts` by Task 2513,
+ * unchanged, so the dispatch writer, the dispatch migration and the two
+ * scheduling writers cannot disagree about what canonical means. Task 2213
+ * stated the invariant as "One function, three callers, no drift possible"; a
+ * second copy in the dispatch tree would have broken it.
+ *
+ * Pure. No database, no driver, no plugin import.
+ */
+
+/**
+ * Validates an IANA timezone string. Throws with a clear message if invalid.
+ */
+export function validateTimezone(tz: string): void {
+  if (!tz || tz.trim().length === 0) {
+    throw new Error("Timezone is required but was empty");
+  }
+  try {
+    // Intl.DateTimeFormat throws RangeError for invalid IANA timezone identifiers
+    new Intl.DateTimeFormat("en-GB", { timeZone: tz });
+  } catch {
+    throw new Error(
+      `Invalid timezone: "${tz}" — expected IANA format like "Europe/London" or "America/New_York"`,
+    );
+  }
+}
+
+/** Ends with `Z` or a numeric UTC offset, e.g. `+01:00`, `-0500`. */
+const HAS_ZONE = /(?:Z|[+-]\d{2}:?\d{2})$/;
+
+/** The zone's wall-clock parts at a given instant. */
+function partsAt(ms: number, zone: string): Record<string, string> {
+  const dtf = new Intl.DateTimeFormat("en-GB", {
+    timeZone: zone,
+    hour12: false,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  });
+  return Object.fromEntries(dtf.formatToParts(new Date(ms)).map((p) => [p.type, p.value]));
+}
+
+/**
+ * Milliseconds the zone is ahead of UTC at `ms`.
+ *
+ * Subtracted against the SECOND-truncated instant, never `ms` itself.
+ * `Intl.DateTimeFormat` resolves only to seconds, so differencing its
+ * reconstruction against a millisecond-bearing instant folds the fractional part
+ * into the offset: at `09:00:00.500` the offset came back as 3_599_500 rather
+ * than 3_600_000, and the caller's `naive - offset` then landed a full second
+ * out. A real zone offset is always a whole number of minutes, so truncating is
+ * lossless here and keeps the caller's sub-second precision intact.
+ */
+function offsetMsAt(ms: number, zone: string): number {
+  const p = partsAt(ms, zone);
+  // `hour` renders as "24" for midnight in en-GB; % 24 folds it back to 0.
+  const wallUtc = Date.UTC(+p.year, +p.month - 1, +p.day, +p.hour % 24, +p.minute, +p.second);
+  return wallUtc - Math.floor(ms / 1000) * 1000;
+}
+
+/** The zone's wall clock at `ms`, in the same shape as a zoneless input. */
+function wallAt(ms: number, zone: string): string {
+  const p = partsAt(ms, zone);
+  const hh = String(+p.hour % 24).padStart(2, "0");
+  return `${p.year}-${p.month}-${p.day}T${hh}:${p.minute}:${p.second}`;
+}
+
+/**
+ * The exact 24-character shape `toISOString()` produces, as a regex source.
+ *
+ * Exported as a string rather than a `RegExp` because it is also passed to
+ * Cypher as a `=~` parameter. One source, so the standing audit's predicate and
+ * this module's predicate cannot drift; passing it as a parameter also removes
+ * the backslash-escaping ambiguity of an inlined Cypher literal.
+ */
+export const CANONICAL_INSTANT_PATTERN = "\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z";
+
+/**
+ * Task 2213, generalised by Task 2513 — the single definition of a canonical
+ * stored instant.
+ *
+ * Stored instants are compared as STRINGS, lexically, in Cypher: the scheduling
+ * dispatcher on `e.startDate <= $now`, and the dispatch planner on
+ * `v.startDate >= $from AND v.startDate < $to`. An offset suffix is never
+ * parsed, so a `+01:00` value sorts by its wall-clock digits — 60 minutes out
+ * under BST, and correct under GMT, which is why the defect self-heals every
+ * October and returns every March.
+ *
+ * The output is therefore always the exact 24-character shape `toISOString()`
+ * produces. The fixed width is the point: lexical order equals instant order
+ * only when every stored value shares one shape. That is also why this is not
+ * done in Cypher — `toString(datetime(...))` omits `.000` at a zero-millisecond
+ * instant, and `"…00.000Z"` sorts BEFORE `"…00Z"`.
+ *
+ * A zoneless wall clock is read in `zone`, never in the server's zone: a
+ * server-local reading makes the stored instant depend on which machine wrote
+ * it, which is the same fault class one layer down. With no usable zone this
+ * throws rather than guessing.
+ *
+ * DST is resolved the way `Temporal`'s `disambiguation: 'compatible'` resolves
+ * it. Take the offsets in force a day either side, giving two candidate
+ * instants; keep those that render back to exactly the input wall clock. If any
+ * survive, take the earliest (the earlier occurrence of an ambiguous autumn
+ * time). If none survive, the wall clock is inside a spring-forward gap and does
+ * not exist, so take the later candidate, which shifts it past the gap.
+ */
+export function normaliseInstant(raw: string, zone: string | null): string {
+  const trimmed = raw.trim();
+
+  if (HAS_ZONE.test(trimmed)) {
+    const ms = Date.parse(trimmed);
+    if (Number.isNaN(ms)) {
+      throw new Error(`Unparseable instant: "${raw}" — expected an ISO 8601 date-time`);
+    }
+    return new Date(ms).toISOString();
+  }
+
+  if (!zone) {
+    throw new Error(
+      `Instant "${raw}" carries no timezone offset and no timezone is available to read it in — ` +
+        `pass an IANA timezone, or write the offset into the value`,
+    );
+  }
+  validateTimezone(zone);
+
+  const naive = Date.parse(`${trimmed}Z`);
+  if (Number.isNaN(naive)) {
+    throw new Error(`Unparseable instant: "${raw}" — expected an ISO 8601 date-time`);
+  }
+
+  const DAY_MS = 86_400_000;
+  const before = naive - offsetMsAt(naive - DAY_MS, zone);
+  const after = naive - offsetMsAt(naive + DAY_MS, zone);
+  const valid = [before, after].filter((ms) => wallAt(ms, zone) === trimmed);
+  const chosen = valid.length > 0 ? Math.min(...valid) : Math.max(before, after);
+  return new Date(chosen).toISOString();
+}
+
+/** True when `value` is already in the canonical form above. */
+export function isCanonicalInstant(value: string): boolean {
+  return new RegExp(`^${CANONICAL_INSTANT_PATTERN}$`).test(value);
+}

package/payload/platform/lib/canonical-instant/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
+}

package/payload/platform/lib/canonical-instant/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    globals: false,
+    include: ["src/__tests__/**/*.test.ts"],
+  },
+});

package/payload/platform/lib/dispatch-read/dist/geo.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Distance to a site, and whether that counts as being there.
+ *
+ * The verdict names why it could not fire rather than returning a bare false.
+ * "This site has no coordinates", "this account configured no radius" and "the
+ * worker is four kilometres away" are three different problems with three
+ * different fixes, and a single boolean sends an operator to the wrong one.
+ */
+import type { DispatchConfig, SiteLocation } from "./types.js";
+/** Great-circle distance in metres, rounded. */
+export declare function distanceM(a: {
+    latitude: number;
+    longitude: number;
+}, b: {
+    latitude: number;
+    longitude: number;
+}): number;
+export interface GeofenceVerdict {
+    siteHasCoords: boolean;
+    /** The site's own radius, else the account default, else null. */
+    radiusM: number | null;
+    /** Null when there is nothing to measure against. */
+    distanceM: number | null;
+    inside: boolean;
+}
+export declare function geofenceVerdict(p: {
+    site: SiteLocation | null;
+    cfg: DispatchConfig;
+    at: {
+        latitude: number;
+        longitude: number;
+    };
+}): GeofenceVerdict;
+//# sourceMappingURL=geo.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"geo.d.ts","sourceRoot":"","sources":["../src/geo.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAM/D,gDAAgD;AAChD,wBAAgB,SAAS,CACvB,CAAC,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAC1C,CAAC,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACzC,MAAM,CAQR;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,OAAO,CAAC;IACvB,kEAAkE;IAClE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,qDAAqD;IACrD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE;IACjC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IAC1B,GAAG,EAAE,cAAc,CAAC;IACpB,EAAE,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C,GAAG,eAAe,CAclB"}

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

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.distanceM = distanceM;
+exports.geofenceVerdict = geofenceVerdict;
+const EARTH_RADIUS_M = 6_371_000;
+const toRad = (deg) => (deg * Math.PI) / 180;
+/** Great-circle distance in metres, rounded. */
+function distanceM(a, b) {
+    const dLat = toRad(b.latitude - a.latitude);
+    const dLon = toRad(b.longitude - a.longitude);
+    const lat1 = toRad(a.latitude);
+    const lat2 = toRad(b.latitude);
+    const h = Math.sin(dLat / 2) ** 2 + Math.sin(dLon / 2) ** 2 * Math.cos(lat1) * Math.cos(lat2);
+    return Math.round(2 * EARTH_RADIUS_M * Math.asin(Math.sqrt(h)));
+}
+function geofenceVerdict(p) {
+    const siteHasCoords = p.site !== null && p.site.latitude !== null && p.site.longitude !== null;
+    const radiusM = p.site?.geofenceRadiusM ?? p.cfg.vehicles?.defaultGeofenceRadiusM ?? null;
+    if (!siteHasCoords) {
+        return { siteHasCoords: false, radiusM, distanceM: null, inside: false };
+    }
+    const d = distanceM({ latitude: p.site.latitude, longitude: p.site.longitude }, p.at);
+    // A distance with no radius to compare it against cannot say whether anybody
+    // arrived. Reported, never assumed.
+    return { siteHasCoords: true, radiusM, distanceM: d, inside: radiusM !== null && d <= radiusM };
+}
+//# sourceMappingURL=geo.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"geo.js","sourceRoot":"","sources":["../src/geo.ts"],"names":[],"mappings":";;AAeA,8BAWC;AAWD,0CAkBC;AA7CD,MAAM,cAAc,GAAG,SAAS,CAAC;AAEjC,MAAM,KAAK,GAAG,CAAC,GAAW,EAAU,EAAE,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC;AAE7D,gDAAgD;AAChD,SAAgB,SAAS,CACvB,CAA0C,EAC1C,CAA0C;IAE1C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC/B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC/B,MAAM,CAAC,GACL,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACtF,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAWD,SAAgB,eAAe,CAAC,CAI/B;IACC,MAAM,aAAa,GACjB,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,KAAK,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC;IAC3E,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,EAAE,eAAe,IAAI,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,sBAAsB,IAAI,IAAI,CAAC;IAC1F,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC3E,CAAC;IACD,MAAM,CAAC,GAAG,SAAS,CACjB,EAAE,QAAQ,EAAE,CAAC,CAAC,IAAK,CAAC,QAAkB,EAAE,SAAS,EAAE,CAAC,CAAC,IAAK,CAAC,SAAmB,EAAE,EAChF,CAAC,CAAC,EAAE,CACL,CAAC;IACF,6EAA6E;IAC7E,oCAAoC;IACpC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,IAAI,CAAC,IAAI,OAAO,EAAE,CAAC;AAClG,CAAC"}

package/payload/platform/lib/dispatch-read/dist/index.d.ts

@@ -12,11 +12,15 @@
  */
 export { RECORDABLE_FIELDS, loadDispatchConfig, terminalJobStatuses, terminalVisitStatuses, workerForTelegramUser, } from "./config.js";
 export type { RecordableField } from "./config.js";
+export { CALLBACK_DATA_MAX_BYTES, buildVisitKeyboard, dispatchCallbackData, parseDispatchCallback, } from "./keyboard.js";
+export type { DispatchButton, VisitKeyboard } from "./keyboard.js";
 export { withSession } from "./session.js";
 export { resolveAccountZone } from "./zone.js";
 export { MAX_RANGE_DAYS, addDaysYmd, currentWeekYmd, daysBetween, minutesIntoDay, ymdInZone, zonedDayStartUtc, zonedRangeBounds, } from "./window.js";
-export { buildJobListQuery, projectJob, projectVisit, readCommitments, readJob, readJobs, readNodeId, readSiteHistory, readVisit, readVisitRecordState, readVisitsForJob, readVisitsInWindow, } from "./read.js";
+export { buildJobListQuery, projectFieldVisit, projectJob, projectVisit, readCommitments, readDraft, readDrafts, readFieldVisit, readJob, readJobs, readNodeId, readOpenVisitsForWorker, readPreviousVisits, readSiteHistory, readSiteLocation, readVisit, readVisitRecordState, readVisitsForJob, readVisitsInWindow, } from "./read.js";
+export { distanceM, geofenceVerdict } from "./geo.js";
+export type { GeofenceVerdict } from "./geo.js";
 export { nonZuluStarts, readCounts, readDay, readJobList, readWorkerDay } from "./read.js";
-export type { Commitment, VisitRecordState } from "./read.js";
+export type { Commitment, DraftRow, PreviousVisit, VisitRecordState } from "./read.js";
 export type * from "./types.js";
 //# sourceMappingURL=index.d.ts.map