@rubytech/create-realagent-code 0.1.574 → 0.1.576

package/dist/__tests__/preserve-house-cloudflare.test.js

@@ -6,10 +6,10 @@
 // Runs under `node --test dist/__tests__/*`.
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync, statSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { backupHouseCloudflare, restoreHouseCloudflare, migrateHouseCredentialFromAccount, } from "../preserve-house-cloudflare.js";
+import { backupHouseCloudflare, restoreHouseCloudflare, } from "../preserve-house-cloudflare.js";
 function makeDirs() {
     const root = mkdtempSync(join(tmpdir(), "house-1664-"));
     const installDir = join(root, "install");
@@ -66,73 +66,3 @@ function acctSecrets(installDir, id, contents) {
     writeFileSync(p, contents);
     return p;
 }
-test("relocates a per-account master into the house file, mode 600, account untouched", () => {
-    const { root, installDir } = makeDirs();
-    try {
-        const acct = acctSecrets(installDir, "acc-1", "CLOUDFLARE_API_TOKEN=cfat_minter\nCLOUDFLARE_ACCOUNT_ID=deadbeef\nCF_PAGES_D1_TOKEN=stale\n");
-        const before = readFileSync(acct, "utf-8");
-        const r = migrateHouseCredentialFromAccount(installDir);
-        assert.equal(r.result, "relocated");
-        assert.equal(r.source, "acc-1");
-        const house = join(installDir, "platform/config", "cloudflare-house.env");
-        assert.equal(readFileSync(house, "utf-8"), "CLOUDFLARE_API_TOKEN=cfat_minter\nCLOUDFLARE_ACCOUNT_ID=deadbeef\n", "only the two master keys are relocated, no stale scoped token");
-        assert.equal(statSync(house).mode & 0o777, 0o600, "house file is mode 600");
-        assert.equal(readFileSync(acct, "utf-8"), before, "account file untouched");
-    }
-    finally {
-        rmSync(root, { recursive: true, force: true });
-    }
-});
-test("no-op when the house file already exists (never overwrites)", () => {
-    const { root, installDir, configDir } = makeDirs();
-    try {
-        const house = join(configDir, "cloudflare-house.env");
-        writeFileSync(house, "CLOUDFLARE_API_TOKEN=existing\nCLOUDFLARE_ACCOUNT_ID=xyz\n");
-        acctSecrets(installDir, "acc-1", "CLOUDFLARE_API_TOKEN=other\nCLOUDFLARE_ACCOUNT_ID=zzz\n");
-        const r = migrateHouseCredentialFromAccount(installDir);
-        assert.equal(r.result, "noop");
-        assert.equal(readFileSync(house, "utf-8"), "CLOUDFLARE_API_TOKEN=existing\nCLOUDFLARE_ACCOUNT_ID=xyz\n", "existing house file is untouched");
-    }
-    finally {
-        rmSync(root, { recursive: true, force: true });
-    }
-});
-test("absent when no account carries a master (no house file, no error)", () => {
-    const { root, installDir } = makeDirs();
-    try {
-        acctSecrets(installDir, "acc-1", "CF_PAGES_D1_TOKEN=scoped_only\n");
-        const r = migrateHouseCredentialFromAccount(installDir);
-        assert.equal(r.result, "absent");
-        assert.ok(!existsSync(join(installDir, "platform/config", "cloudflare-house.env")));
-    }
-    finally {
-        rmSync(root, { recursive: true, force: true });
-    }
-});
-test("deterministic pick — lexicographically-first account id wins", () => {
-    const { root, installDir } = makeDirs();
-    try {
-        acctSecrets(installDir, "bbb", "CLOUDFLARE_API_TOKEN=tok_b\nCLOUDFLARE_ACCOUNT_ID=idb\n");
-        acctSecrets(installDir, "aaa", "CLOUDFLARE_API_TOKEN=tok_a\nCLOUDFLARE_ACCOUNT_ID=ida\n");
-        const r = migrateHouseCredentialFromAccount(installDir);
-        assert.equal(r.source, "aaa");
-        assert.match(readFileSync(join(installDir, "platform/config", "cloudflare-house.env"), "utf-8"), /tok_a/);
-    }
-    finally {
-        rmSync(root, { recursive: true, force: true });
-    }
-});
-test("full upgrade path: pre-1631 relocates, second run is a no-op", () => {
-    const { root, installDir, persistentDir } = makeDirs();
-    try {
-        // Pre-1631 upgrade: no house file survives the wipe/restore (nothing saved).
-        simulateUpgrade(installDir, persistentDir);
-        assert.ok(!existsSync(join(installDir, "platform/config", "cloudflare-house.env")));
-        acctSecrets(installDir, "acc-1", "CLOUDFLARE_API_TOKEN=cfat_minter\nCLOUDFLARE_ACCOUNT_ID=deadbeef\n");
-        assert.equal(migrateHouseCredentialFromAccount(installDir).result, "relocated");
-        assert.equal(migrateHouseCredentialFromAccount(installDir).result, "noop", "second run is idempotent");
-    }
-    finally {
-        rmSync(root, { recursive: true, force: true });
-    }
-});

package/dist/index.js

@@ -10,9 +10,8 @@ import { buildBrandCronBlock, mergeBrandCronBlock } from "./cron-registration.js
 import { validateTierFlag, validateEntitlementBase64, applyTierToAccountConfig, entitlementPath } from "./tier-flag.js";
 import { parseOsRelease, isUbuntuLike as isUbuntuLikePure, parseAptCacheCandidate, decideAptResolution, } from "./apt-resolve.js";
 import { findPeerBrandOnDefaultNeo4jPort } from "./peer-brand-detect.js";
-import { removeClientAdminsKey } from "./converge-client-admins.js";
 import { seedPublicInstructionFiles } from "./public-instruction-seed.js";
-import { backupHouseCloudflare, restoreHouseCloudflare, migrateHouseCredentialFromAccount, } from "./preserve-house-cloudflare.js";
+import { backupHouseCloudflare, restoreHouseCloudflare, } from "./preserve-house-cloudflare.js";
 import { resolveNeo4jPidfileScrub } from "./neo4j-pidfile-scrub.js";
 import { runInitLogging } from "./init-logging.js";
 import { requireSupportedPlatform, detectPlatform } from "./platform-detect.js";
@@ -2650,15 +2649,6 @@ function deployPayload() {
     if (restoreHouseCloudflare(INSTALL_DIR, persistentDir)) {
         console.log("  Restored Cloudflare house credential (cloudflare-house.env preserved).");
     }
-    // Task 1671 — a pre-1631 install crossing the 0.1.449 boundary has no house
-    // credential yet, but its per-account secrets still carry the account-wide
-    // master (a minter, Task 1670). Relocate it into the house file so the broker
-    // and calendar find it where the 1631 readers expect it, with zero manual
-    // step. Idempotent: no-op once the house file exists (fresh install → absent).
-    {
-        const mig = migrateHouseCredentialFromAccount(INSTALL_DIR);
-        console.log(`  [install] op=house-cred-migrate result=${mig.result}${mig.source ? ` source=${mig.source}` : ""}`);
-    }
     // users.json is read directly from persistentDir by both
     // platform/ui/app/lib/paths.ts (USERS_FILE = MAXY_DIR/users.json) and the
     // admin MCP plugin (USERS_FILE = CONFIG_DIR/users.json). No copy into the
@@ -2690,13 +2680,6 @@ function deployPayload() {
     // installer is its own npm package and doesn't bundle the platform lib.
     // Mirrors checkAdminAuthInvariant() in platform/lib/admins-write/src/index.ts;
     // future divergence between the two should be caught by the test suite.
-    // Task 1623 — converge existing client account.json to drop the vestigial
-    // admins[] key before the invariant check reads them. House untouched.
-    for (const r of removeClientAdminsKey(join(INSTALL_DIR, "data", "accounts"))) {
-        if (r.action === "removed" || r.action === "unreadable" || r.action === "write-failed") {
-            console.log(`  [converge-1623] account=${r.accountId.slice(0, 8)} admins=${r.action}`);
-        }
-    }
     runInstallInvariantCheck(persistentUsersFile, join(INSTALL_DIR, "data", "accounts"));
     // The version marker is NOT written here. It is stamped at the very end of a
     // fully-successful install (after plugin registration and every throwing
@@ -3392,33 +3375,13 @@ function setupAccount() {
         logFile(`  [neo4j] passing NEO4J_URI=${neo4jUri} to seed`);
         shell("bash", [seedScript], { cwd: INSTALL_DIR, env: neo4jEnv });
     }
-    // Task 2213 — converge :Event.startDate onto canonical UTC. The dispatcher
-    // compares startDate to new Date().toISOString() LEXICALLY, so a row storing
-    // a +01:00 offset fires 60 minutes late under BST. Runs after the seed so the
-    // schema exists, with the same Neo4j env, and needs PLATFORM_ROOT to scope
-    // itself to this install's accounts on a shared Neo4j. Idempotent: a converged
-    // install rewrites nothing and prints op=done rewritten=0.
-    const convergeStartDate = join(INSTALL_DIR, "platform/plugins/scheduling/mcp/dist/scripts/converge-startdate-utc.js");
-    if (existsSync(convergeStartDate)) {
-        shell("node", [convergeStartDate], {
-            cwd: INSTALL_DIR,
-            env: { ...neo4jEnv, PLATFORM_ROOT: join(INSTALL_DIR, "platform") },
-        });
-    }
-    // Task 2361 — collapse the two routine description properties onto
-    // `:Event.description`, preferring whichever value the operator or the agent
-    // wrote. Runs after the seed for the same reasons the convergence above does:
-    // the schema exists by then, and the same Neo4j env is already built. Scoped to
-    // this install's accounts via PLATFORM_ROOT, so a co-resident brand sharing one
-    // Neo4j is untouched. Idempotent: a converged install matches nothing and
-    // prints converged=0.
-    const convergeRoutineDescription = join(INSTALL_DIR, "platform/plugins/scheduling/mcp/dist/scripts/converge-routine-description.js");
-    if (existsSync(convergeRoutineDescription)) {
-        shell("node", [convergeRoutineDescription], {
-            cwd: INSTALL_DIR,
-            env: { ...neo4jEnv, PLATFORM_ROOT: join(INSTALL_DIR, "platform") },
-        });
-    }
+    // Install-time data migrations were removed on 2026-08-08 by operator
+    // decision. Three convergences ran here (Tasks 2213, 2361, 2513). Every
+    // device in the fleet is past the state each one existed to repair, so on
+    // every install they scanned and rewrote nothing while adding a Neo4j
+    // round-trip and a way to fail: 2513's script leaked its driver and hung
+    // the installer after printing scanned=0. A future migration belongs in a
+    // one-shot the operator runs deliberately, not on the upgrade path.
     // 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/dist/preserve-house-cloudflare.js

@@ -6,8 +6,8 @@
 // calendar reconcile/publish scripts) fails with "house credential not found"
 // until an operator re-mints the token by hand. The persistent copy lives in
 // the brand's persistent config dir so even a full reinstall restores it.
-import { existsSync, cpSync, chmodSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { existsSync, cpSync, chmodSync } from "node:fs";
+import { join } from "node:path";
 const HOUSE_CRED_FILE = "cloudflare-house.env";
 /**
  * Copy the live house credential (if any) into the persistent store before the
@@ -35,50 +35,3 @@ export function restoreHouseCloudflare(installDir, persistentDir) {
     chmodSync(dest, 0o600);
     return true;
 }
-/**
- * Task 1671 — on upgrade, if no house credential exists yet, relocate an
- * existing per-account master (CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID)
- * into the house file (mode 600). This lets a pre-1631 install cross the 0.1.449
- * boundary with zero manual step: the broker/calendar (Task 1670) then mint
- * their scoped tokens from the relocated minter where the 1631 readers expect it.
- *
- * Fail-safe and idempotent:
- * - never overwrites an existing house file (returns "noop");
- * - never guesses a token (both master keys required);
- * - deterministic: scans accounts sorted by id, takes the first with a master;
- * - relocates only the two master keys, so no per-account scoped token leaks
- *   house-side.
- *
- * The relocated file is preserved on subsequent upgrades by backupHouseCloudflare
- * (Task 1664), which runs before the wipe on the next install.
- */
-export function migrateHouseCredentialFromAccount(installDir) {
-    const house = join(installDir, "platform/config", HOUSE_CRED_FILE);
-    if (existsSync(house))
-        return { result: "noop" };
-    const accountsDir = join(installDir, "data/accounts");
-    if (!existsSync(accountsDir))
-        return { result: "absent" };
-    for (const id of readdirSync(accountsDir).sort()) {
-        const secrets = join(accountsDir, id, "secrets", "cloudflare.env");
-        if (!existsSync(secrets))
-            continue;
-        const env = {};
-        for (const line of readFileSync(secrets, "utf8").split("\n")) {
-            const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
-            if (m)
-                env[m[1]] = m[2].trim();
-        }
-        const apiToken = env.CLOUDFLARE_API_TOKEN;
-        const accountId = env.CLOUDFLARE_ACCOUNT_ID;
-        if (!apiToken || !accountId)
-            continue;
-        mkdirSync(dirname(house), { recursive: true });
-        writeFileSync(house, `CLOUDFLARE_API_TOKEN=${apiToken}\nCLOUDFLARE_ACCOUNT_ID=${accountId}\n`, {
-            mode: 0o600,
-        });
-        chmodSync(house, 0o600);
-        return { result: "relocated", source: id };
-    }
-    return { result: "absent" };
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent-code",
-  "version": "0.1.574",
+  "version": "0.1.576",
   "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);
+    }
+  });
+});