@rubytech/create-sitedesk-code 0.1.521 → 0.1.523

package/payload/platform/lib/routine-templates/src/__tests__/seed.test.ts

@@ -0,0 +1,298 @@
+/**
+ * Task 2130 — the seed's own behaviour, plus the structural guards on the
+ * Cypher it issues.
+ *
+ * The Cypher's runtime semantics belong to Neo4j and are proven on a real
+ * install (the task's laptop verification). What IS testable here, and what a
+ * future edit would otherwise break silently, is the SHAPE of the statement:
+ * which properties `ON CREATE` writes and — the load-bearing one — which
+ * properties `ON MATCH` is allowed to touch. A re-seed that writes
+ * `eventStatus` on match would re-suspend every routine the operator had
+ * enabled, on every upgrade, and nothing would report it.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  MERGE_CYPHER,
+  ROUTINE_ROSTER,
+  ROUTINE_TEMPLATE_VERSION,
+  VERIFY_CYPHER,
+  resolveOwnerTimezone,
+  seedRoutineRoster,
+  type RoutineMergeAction,
+  type SeedSessionLike,
+} from "../index.js";
+
+interface FakeCall {
+  query: string;
+  params: Record<string, unknown>;
+}
+
+/** A session that answers the two statements the seed issues, in order:
+ *  the timezone read, the MERGE, then the verify read. */
+function fakeSession(opts: {
+  timezone?: { timezone: string; timezoneSource: string } | null;
+  merges: Array<{ key: string; eventId: string; action: RoutineMergeAction }>;
+  verify: { actual: number; suspended: number; nextRunNull: number };
+}): { session: SeedSessionLike; calls: FakeCall[] } {
+  const calls: FakeCall[] = [];
+  const rec = (obj: Record<string, unknown>) => ({ get: (k: string) => obj[k] });
+  const session: SeedSessionLike = {
+    async run(query: string, params: Record<string, unknown> = {}) {
+      calls.push({ query, params });
+      if (query.includes("UserProfile")) {
+        return { records: opts.timezone ? [rec({ timezone: opts.timezone.timezone })] : [] };
+      }
+      if (query.includes("MERGE (e:Event")) {
+        return { records: opts.merges.map((m) => rec({ ...m })) };
+      }
+      return { records: [rec(opts.verify)] };
+    },
+  };
+  return { session, calls };
+}
+
+const allUnchanged = ROUTINE_ROSTER.map((r) => ({
+  key: r.key,
+  eventId: `id-${r.key}`,
+  action: "unchanged" as RoutineMergeAction,
+}));
+
+const allCreated = ROUTINE_ROSTER.map((r) => ({
+  key: r.key,
+  eventId: `id-${r.key}`,
+  action: "create" as RoutineMergeAction,
+}));
+
+const cleanVerify = { actual: 10, suspended: 10, nextRunNull: 10 };
+
+describe("MERGE statement shape", () => {
+  /** The property names assigned inside a `ON CREATE SET` / `ON MATCH SET`
+   *  block, up to the next clause keyword. */
+  function propertiesSetIn(clause: "ON CREATE SET" | "ON MATCH SET"): string[] {
+    const start = MERGE_CYPHER.indexOf(clause);
+    expect(start, `${clause} must be present`).toBeGreaterThan(-1);
+    const after = MERGE_CYPHER.slice(start + clause.length);
+    const end = after.search(/\n\s*(ON MATCH SET|RETURN|WITH)\b/);
+    const body = end === -1 ? after : after.slice(0, end);
+    return [...body.matchAll(/\be\.([a-zA-Z]+)\s*=/g)].map((m) => m[1]);
+  }
+
+  it("ON CREATE writes the full suspended shape", () => {
+    const props = new Set(propertiesSetIn("ON CREATE SET"));
+    for (const required of [
+      "eventId",
+      "name",
+      "agentPrompt",
+      "recurrence",
+      "routineTemplateVersion",
+      "eventStatus",
+      "nextRun",
+      "agentChannel",
+      "agentDestination",
+      "actionPlugin",
+      "sourcePlugin",
+      "timezone",
+    ]) {
+      expect(props, `ON CREATE must set ${required}`).toContain(required);
+    }
+  });
+
+  it("ON CREATE seeds suspended, with no nextRun, channel, destination or action", () => {
+    const start = MERGE_CYPHER.indexOf("ON CREATE SET");
+    const body = MERGE_CYPHER.slice(start, MERGE_CYPHER.indexOf("ON MATCH SET"));
+    expect(body).toContain("e.eventStatus = 'suspended'");
+    expect(body).toContain("e.nextRun = null");
+    expect(body).toContain("e.agentChannel = null");
+    expect(body).toContain("e.agentDestination = null");
+    expect(body).toContain("e.actionPlugin = null");
+  });
+
+  it("ON CREATE leaves sourcePlugin null so the lifecycle sweep never cancels an enabled routine", () => {
+    // check-due-events.ts cancels any 'scheduled' Event whose sourcePlugin is
+    // absent from enabledPlugins. A roster routine spans many plugins, so any
+    // value here would cancel it the moment an operator enabled it.
+    const start = MERGE_CYPHER.indexOf("ON CREATE SET");
+    const body = MERGE_CYPHER.slice(start, MERGE_CYPHER.indexOf("ON MATCH SET"));
+    expect(body).toContain("e.sourcePlugin = null");
+  });
+
+  it("ON MATCH touches ONLY the prompt, name, version and updatedAt", () => {
+    expect(new Set(propertiesSetIn("ON MATCH SET"))).toEqual(
+      new Set(["agentPrompt", "name", "routineTemplateVersion", "updatedAt"]),
+    );
+  });
+
+  it("ON MATCH never writes anything the operator controls", () => {
+    const start = MERGE_CYPHER.indexOf("ON MATCH SET");
+    const body = MERGE_CYPHER.slice(start, MERGE_CYPHER.indexOf("RETURN"));
+    for (const operatorOwned of ["eventStatus", "agentChannel", "agentDestination", "recurrence", "timezone"]) {
+      expect(body, `ON MATCH must not write ${operatorOwned}`).not.toContain(`e.${operatorOwned} =`);
+    }
+  });
+
+  it("refreshes only a behind-version row with no operator edit", () => {
+    expect(MERGE_CYPHER).toContain("(existed AND NOT edited AND priorVersion < $version) AS refreshing");
+  });
+
+  it("reads the operator-edit guard from a property both edit paths actually write", () => {
+    // The guard is only as real as its producer. Shipping the reader without a
+    // writer would leave `edited` false for every row, so the first version
+    // bump would silently overwrite every customised prompt while the code
+    // comment promised the opposite. Both paths that let an operator change a
+    // routine's prompt stamp it: the scheduling plugin's schedule-update tool,
+    // and the Routines page PATCH route.
+    expect(MERGE_CYPHER).toContain("pre.operatorEdited IS NOT NULL AS edited");
+    const writers = [
+      resolve(process.cwd(), "../../plugins/scheduling/mcp/src/tools/schedule-update.ts"),
+      resolve(process.cwd(), "../../ui/server/routes/admin/routines.ts"),
+    ];
+    for (const writer of writers) {
+      expect(readFileSync(writer, "utf-8"), `${writer} must stamp operatorEdited`).toMatch(
+        /e\.operatorEdited = \$/,
+      );
+    }
+  });
+
+  it("MERGEs on the account plus the template key", () => {
+    expect(MERGE_CYPHER).toContain("MERGE (e:Event {accountId: $accountId, routineTemplate: row.key})");
+  });
+
+  it("verify reads the roster back out of the graph rather than counting writes", () => {
+    expect(VERIFY_CYPHER).toContain("MATCH (e:Event {accountId: $accountId})");
+    expect(VERIFY_CYPHER).toContain("e.routineTemplate IS NOT NULL");
+    expect(VERIFY_CYPHER).toContain("count(e) AS actual");
+  });
+});
+
+describe("resolveOwnerTimezone", () => {
+  it("accepts an owner-set zone", async () => {
+    const { session } = fakeSession({
+      timezone: { timezone: "Europe/Lisbon", timezoneSource: "owner-set" },
+      merges: allUnchanged,
+      verify: cleanVerify,
+    });
+    expect(await resolveOwnerTimezone(session, "acct-1")).toEqual({
+      timezone: "Europe/Lisbon",
+      source: "owner-profile",
+    });
+  });
+
+  it("reports absent rather than defaulting to the box's zone", async () => {
+    const { session } = fakeSession({ timezone: null, merges: allUnchanged, verify: cleanVerify });
+    expect(await resolveOwnerTimezone(session, "acct-1")).toEqual({ timezone: null, source: "absent" });
+  });
+
+  it("only reads a profile marked owner-set", async () => {
+    const { session, calls } = fakeSession({ timezone: null, merges: allUnchanged, verify: cleanVerify });
+    await resolveOwnerTimezone(session, "acct-1");
+    expect(calls[0].query).toContain("up.timezoneSource = 'owner-set'");
+  });
+});
+
+describe("seedRoutineRoster", () => {
+  const seed = async (over: Partial<Parameters<typeof seedRoutineRoster>[0]> = {}, fake = {
+    timezone: { timezone: "Europe/Lisbon", timezoneSource: "owner-set" },
+    merges: allUnchanged,
+    verify: cleanVerify,
+  }) => {
+    const lines: string[] = [];
+    const { session, calls } = fakeSession(fake);
+    let tick = 0;
+    const report = await seedRoutineRoster({
+      session,
+      accountId: "abcd1234-0000-0000-0000-000000000000",
+      now: "2026-07-29T00:00:00.000Z",
+      log: (l) => lines.push(l),
+      clock: () => (tick++ === 0 ? 1000 : 1042),
+      ...over,
+    });
+    return { report, lines, calls };
+  };
+
+  it("passes every roster row to the MERGE", async () => {
+    const { calls } = await seed();
+    const mergeCall = calls.find((c) => c.query.includes("MERGE (e:Event"))!;
+    expect((mergeCall.params.rows as unknown[]).length).toBe(ROUTINE_ROSTER.length);
+    expect(mergeCall.params.version).toBe(ROUTINE_TEMPLATE_VERSION);
+    expect(mergeCall.params.timezone).toBe("Europe/Lisbon");
+  });
+
+  it("passes a null timezone through rather than substituting one", async () => {
+    const { calls } = await seed({}, { timezone: null, merges: allUnchanged, verify: cleanVerify });
+    const mergeCall = calls.find((c) => c.query.includes("MERGE (e:Event"))!;
+    expect(mergeCall.params.timezone).toBeNull();
+  });
+
+  it("emits the full lifecycle on a run that changes nothing", async () => {
+    const { lines } = await seed();
+    expect(lines.filter((l) => l.includes("op=begin"))).toHaveLength(1);
+    expect(lines.filter((l) => l.includes("op=tz-resolved"))).toHaveLength(1);
+    expect(lines.filter((l) => l.includes("op=merge"))).toHaveLength(ROUTINE_ROSTER.length);
+    expect(lines.filter((l) => l.includes("op=verify"))).toHaveLength(1);
+    expect(lines.filter((l) => l.includes("op=end"))).toHaveLength(1);
+  });
+
+  it("carries the account correlation key on every line", async () => {
+    const { lines } = await seed();
+    expect(lines.every((l) => l.includes("acct=abcd1234"))).toBe(true);
+  });
+
+  it("reports the verify counts measured back out of the graph", async () => {
+    // One row short of the roster: the drift the verify pass exists to report.
+    // Derived from ROUTINE_ROSTER rather than typed, so adding a routine does
+    // not silently turn this into an assertion about a stale count.
+    const expected = ROUTINE_ROSTER.length;
+    const short = expected - 1;
+    const { report, lines } = await seed({}, {
+      timezone: { timezone: "Europe/Lisbon", timezoneSource: "owner-set" },
+      merges: allUnchanged,
+      verify: { actual: short, suspended: short, nextRunNull: short },
+    });
+    expect(report.verify).toEqual({ expected, actual: short, suspended: short, nextRunNull: short });
+    expect(lines).toContainEqual(
+      `[routine-seed] op=verify acct=abcd1234 expected=${expected} actual=${short} suspended=${short} nextRunNull=${short}`,
+    );
+  });
+
+  it("logs tz-resolved as null when no owner-set profile exists", async () => {
+    const { lines } = await seed({}, { timezone: null, merges: allUnchanged, verify: cleanVerify });
+    expect(lines).toContainEqual("[routine-seed] op=tz-resolved acct=abcd1234 tz=null source=absent");
+  });
+
+  it("counts each merge action separately", async () => {
+    const mixed = [
+      { key: "start-of-day", eventId: "e1", action: "create" as RoutineMergeAction },
+      { key: "inbound-check", eventId: "e2", action: "refresh-version" as RoutineMergeAction },
+      { key: "end-of-day", eventId: "e3", action: "skip-operator-edited" as RoutineMergeAction },
+      { key: "weekly-digest", eventId: "e4", action: "unchanged" as RoutineMergeAction },
+    ];
+    const { report } = await seed({}, {
+      timezone: null,
+      merges: mixed,
+      verify: { actual: 4, suspended: 3, nextRunNull: 3 },
+    });
+    expect(report.created).toBe(1);
+    expect(report.refreshed).toBe(1);
+    expect(report.skippedOperatorEdited).toBe(1);
+    expect(report.unchanged).toBe(1);
+  });
+
+  it("names the action and eventId on every merge line, so a clobber is greppable", async () => {
+    const { lines } = await seed({}, {
+      timezone: null,
+      merges: allCreated,
+      verify: cleanVerify,
+    });
+    expect(lines).toContainEqual(
+      "[routine-seed] op=merge acct=abcd1234 key=start-of-day action=create eventId=id-start-of-day",
+    );
+  });
+
+  it("reports elapsed time on op=end", async () => {
+    const { report, lines } = await seed();
+    expect(report.ranMs).toBe(42);
+    expect(lines.find((l) => l.includes("op=end"))).toContain("ranMs=42");
+  });
+});

package/payload/platform/lib/routine-templates/src/index.ts

@@ -0,0 +1,299 @@
+/**
+ * Task 2130 — the routine-roster seed.
+ *
+ * One module, two callers: `platform/scripts/seed-neo4j.sh` reaches it through
+ * `dist/seed-cli.js` on every install and upgrade (which is what covers the
+ * existing fleet), and the admin plugin's `account_create` imports it directly
+ * for a new client sub-account. Sharing the MERGE rather than writing it twice
+ * is the point: two copies drift, and the drift would only ever be noticed as
+ * "the sub-accounts have different routines from the house".
+ *
+ * The seed is inert by construction. Every row lands `eventStatus:'suspended'`
+ * with `nextRun` NULL, and all four selecting queries in `check-due-events.ts`
+ * admit only `'scheduled'`: the one-time dispatch (`:686-690`, `WHERE
+ * e.eventStatus = 'scheduled' AND e.recurrence IS NULL`), the recurring
+ * dispatch (`:739-744`), the lifecycle activate/heal probe (`:491`) and the
+ * lifecycle deactivation sweep (`:550-551`). NULL `nextRun` is the second,
+ * independent guard: the recurring query also requires `e.nextRun IS NOT NULL`
+ * (`:742`). Neither guard depends on the other holding.
+ *
+ * `nextRun` is left NULL rather than computed, and that is not tidiness. The
+ * recurring loop advances from the STORED value, not from now
+ * (`check-due-events.ts:778`, `currentDate: new Date(currentNextRun)`), so a
+ * row seeded with a computed `nextRun` and enabled a month later advances one
+ * occurrence per tick and dispatches on every one of them. A quarter-hourly
+ * routine would replay roughly 2,880 turns. The only safe value is no value,
+ * until an operator supplies a recurrence through `schedule-update`, which
+ * recomputes from now.
+ *
+ * Each line number above is paired with the construct it points at. Bare
+ * numbers drift on the next edit to that file and then send a reader somewhere
+ * unrelated, which is worse than no citation.
+ */
+import { ROUTINE_ROSTER, ROUTINE_TEMPLATE_VERSION, type RoutineTemplate } from "./roster.js";
+
+export { ROUTINE_ROSTER, ROUTINE_ROSTER_KEYS, ROUTINE_TEMPLATE_VERSION } from "./roster.js";
+export type { RoutineTemplate } from "./roster.js";
+
+/** The minimal Neo4j session surface the seed needs. Both the admin plugin's
+ *  `getSession()` and a driver session from `seed-cli` satisfy it; the tests
+ *  pass an in-memory fake. Deliberately not `neo4j-driver`'s `Session` type, so
+ *  this module stays importable by a consumer that has no driver types. */
+export interface SeedSessionLike {
+  run(query: string, params?: Record<string, unknown>): Promise<{ records: Array<{ get(key: string): unknown }> }>;
+}
+
+/** What the seed did to one routine.
+ *  - `create` — the row did not exist. On an already-seeded account this is the
+ *    clobber signature: something deleted the row, or the MERGE key changed.
+ *  - `refresh-version` — the stored template version was behind and no operator
+ *    had edited the row, so the prompt and name were refreshed.
+ *  - `skip-operator-edited` — a refresh was due and was withheld because the row
+ *    carries `operatorEdited`. The operator's prompt wins, permanently.
+ *  - `unchanged` — the row is already at this version. The steady state. */
+export type RoutineMergeAction = "create" | "refresh-version" | "skip-operator-edited" | "unchanged";
+
+export interface RoutineMergeRow {
+  key: string;
+  eventId: string;
+  action: RoutineMergeAction;
+}
+
+/** The post-condition, measured back out of the graph rather than counted from
+ *  the statements issued. A seed that ran and wrote nothing must not be able to
+ *  report success, which is exactly what counting its own writes would do.
+ *
+ *  `expected === actual` is the health signal. `suspended` and `nextRunNull`
+ *  equal `actual` on a fresh seed and legitimately fall below it once an
+ *  operator enables a routine — they are measurements, not assertions. */
+export interface RoutineVerifyCounts {
+  expected: number;
+  actual: number;
+  suspended: number;
+  nextRunNull: number;
+}
+
+export interface RoutineSeedReport {
+  accountId: string;
+  version: number;
+  timezone: string | null;
+  timezoneSource: "owner-profile" | "absent";
+  merges: RoutineMergeRow[];
+  created: number;
+  refreshed: number;
+  skippedOperatorEdited: number;
+  unchanged: number;
+  verify: RoutineVerifyCounts;
+  ranMs: number;
+}
+
+/** Neo4j returns integers as its own `Integer` type over bolt and as plain
+ *  numbers through a test fake. Normalise both without importing the driver. */
+function toInt(raw: unknown): number {
+  if (typeof raw === "number") return raw;
+  if (raw && typeof (raw as { toNumber?: () => number }).toNumber === "function") {
+    return (raw as { toNumber: () => number }).toNumber();
+  }
+  return Number(raw ?? 0);
+}
+
+/** First eight characters of the accountId — the correlation key every
+ *  `[routine-seed]` and `[schedule-audit]` line carries. */
+export function acctTag(accountId: string): string {
+  return accountId.slice(0, 8);
+}
+
+/**
+ * The owner's IANA timezone, read from the owner `:UserProfile` and accepted
+ * only when it is owner-set.
+ *
+ * A profile whose `timezoneSource` is anything else was backfilled from the
+ * box's own zone, and seeding that onto a routine would give the operator a
+ * routine that fires at the server's hour while looking entirely healthy. NULL
+ * is the honest value in that case, and the heartbeat's `op=null-timezone`
+ * count is what surfaces it — on occasion one, rather than at the first
+ * mis-timed fire.
+ */
+export async function resolveOwnerTimezone(
+  session: SeedSessionLike,
+  accountId: string,
+): Promise<{ timezone: string | null; source: "owner-profile" | "absent" }> {
+  const res = await session.run(
+    `MATCH (up:UserProfile {accountId: $accountId})
+     WHERE up.timezoneSource = 'owner-set' AND up.timezone IS NOT NULL AND trim(up.timezone) <> ''
+     RETURN up.timezone AS timezone
+     LIMIT 1`,
+    { accountId },
+  );
+  const raw = res.records[0]?.get("timezone");
+  if (typeof raw === "string" && raw.trim() !== "") {
+    return { timezone: raw.trim(), source: "owner-profile" };
+  }
+  return { timezone: null, source: "absent" };
+}
+
+/** The MERGE. One statement over the whole roster.
+ *
+ *  The pre-state is captured by an OPTIONAL MATCH before the MERGE, because the
+ *  MERGE itself cannot report which branch it took. Without it the seed could
+ *  only log what it intended; `action=create` on an already-seeded account
+ *  would be indistinguishable from `action=unchanged`, and the clobber it
+ *  signals would be invisible.
+ *
+ *  ON MATCH writes nothing an operator controls: not `eventStatus`, not
+ *  `agentChannel`, not `agentDestination`, not `recurrence`, not `timezone`. A
+ *  re-seed on upgrade must not re-suspend an enabled routine, unbind a bound
+ *  destination, or reset a retimed cron. Only the prompt, the name and the
+ *  version move, and only when the row is behind and unedited. */
+export const MERGE_CYPHER = `
+UNWIND $rows AS row
+OPTIONAL MATCH (pre:Event {accountId: $accountId, routineTemplate: row.key})
+WITH row,
+     pre IS NOT NULL AS existed,
+     coalesce(pre.routineTemplateVersion, 0) AS priorVersion,
+     pre.operatorEdited IS NOT NULL AS edited
+WITH row, existed, priorVersion, edited,
+     (existed AND NOT edited AND priorVersion < $version) AS refreshing
+MERGE (e:Event {accountId: $accountId, routineTemplate: row.key})
+  ON CREATE SET e.eventId = randomUUID(),
+                e.name = row.name,
+                e.agentPrompt = row.prompt,
+                e.recurrence = row.recurrence,
+                e.routineTemplateVersion = $version,
+                e.eventStatus = 'suspended',
+                e.nextRun = null,
+                e.agentChannel = null,
+                e.agentDestination = null,
+                e.actionPlugin = null,
+                e.actionTool = null,
+                e.actionArgs = null,
+                e.sourcePlugin = null,
+                e.timezone = $timezone,
+                e.createdBySource = 'installer',
+                e.createdByAgent = 'system',
+                e.createdByTool = 'routine-roster-seed',
+                e.createdAt = $now,
+                e.updatedAt = $now
+  ON MATCH SET e.agentPrompt = CASE WHEN refreshing THEN row.prompt ELSE e.agentPrompt END,
+               e.name = CASE WHEN refreshing THEN row.name ELSE e.name END,
+               e.routineTemplateVersion = CASE WHEN refreshing THEN $version ELSE e.routineTemplateVersion END,
+               e.updatedAt = CASE WHEN refreshing THEN $now ELSE e.updatedAt END
+RETURN row.key AS key,
+       e.eventId AS eventId,
+       CASE WHEN NOT existed THEN 'create'
+            WHEN priorVersion >= $version THEN 'unchanged'
+            WHEN edited THEN 'skip-operator-edited'
+            ELSE 'refresh-version' END AS action`;
+
+/** The post-condition read. Counts every roster row the account actually holds,
+ *  independently of what the MERGE above believes it wrote. */
+export const VERIFY_CYPHER = `
+MATCH (e:Event {accountId: $accountId})
+WHERE e.routineTemplate IS NOT NULL
+RETURN count(e) AS actual,
+       sum(CASE WHEN e.eventStatus = 'suspended' THEN 1 ELSE 0 END) AS suspended,
+       sum(CASE WHEN e.nextRun IS NULL THEN 1 ELSE 0 END) AS nextRunNull`;
+
+export interface SeedRoutineRosterArgs {
+  session: SeedSessionLike;
+  accountId: string;
+  /** Defaults to `ROUTINE_TEMPLATE_VERSION`. Injected by the tests. */
+  version?: number;
+  /** ISO timestamp stamped on created rows. Injected by the tests. */
+  now?: string;
+  /** Defaults to `ROUTINE_ROSTER`. Injected by the tests. */
+  roster?: readonly RoutineTemplate[];
+  /** Where the `[routine-seed]` lines go. Defaults to stderr. */
+  log?: (line: string) => void;
+  /** Elapsed milliseconds for `op=end`. Injected by the tests so the line is
+   *  assertable; `Date.now()` either side of the work otherwise. */
+  clock?: () => number;
+}
+
+/**
+ * Seed (or re-seed) the roster for one account and report what happened.
+ *
+ * Emits the full `[routine-seed]` lifecycle on every run, including a run that
+ * changes nothing: `op=begin`, `op=tz-resolved`, one `op=merge` per routine,
+ * `op=verify`, `op=end`. A no-op run that logged nothing would be
+ * indistinguishable from a seed that never ran, and "never ran" is the failure
+ * this logging exists to make visible.
+ *
+ * Throws on a Neo4j failure. Both callers catch: the installer path exits
+ * non-zero, and `account_create` reports a created-but-routine-less account
+ * with the recovery action rather than a generic create failure.
+ */
+export async function seedRoutineRoster(args: SeedRoutineRosterArgs): Promise<RoutineSeedReport> {
+  const {
+    session,
+    accountId,
+    version = ROUTINE_TEMPLATE_VERSION,
+    now = new Date().toISOString(),
+    roster = ROUTINE_ROSTER,
+    log = (line: string) => process.stderr.write(`${line}\n`),
+    clock = () => Date.now(),
+  } = args;
+
+  const acct = acctTag(accountId);
+  const startedAt = clock();
+  log(`[routine-seed] op=begin acct=${acct} roster=${roster.length} version=${version}`);
+
+  const { timezone, source } = await resolveOwnerTimezone(session, accountId);
+  log(`[routine-seed] op=tz-resolved acct=${acct} tz=${timezone ?? "null"} source=${source}`);
+
+  const mergeRes = await session.run(MERGE_CYPHER, {
+    accountId,
+    version,
+    timezone,
+    now,
+    rows: roster.map((r) => ({ key: r.key, name: r.name, prompt: r.prompt, recurrence: r.recurrence })),
+  });
+
+  const merges: RoutineMergeRow[] = mergeRes.records.map((rec) => ({
+    key: String(rec.get("key")),
+    eventId: String(rec.get("eventId")),
+    action: String(rec.get("action")) as RoutineMergeAction,
+  }));
+
+  for (const m of merges) {
+    log(`[routine-seed] op=merge acct=${acct} key=${m.key} action=${m.action} eventId=${m.eventId}`);
+  }
+
+  const verifyRes = await session.run(VERIFY_CYPHER, { accountId });
+  const verifyRec = verifyRes.records[0];
+  const verify: RoutineVerifyCounts = {
+    expected: roster.length,
+    actual: toInt(verifyRec?.get("actual")),
+    suspended: toInt(verifyRec?.get("suspended")),
+    nextRunNull: toInt(verifyRec?.get("nextRunNull")),
+  };
+  log(
+    `[routine-seed] op=verify acct=${acct} expected=${verify.expected} actual=${verify.actual} ` +
+      `suspended=${verify.suspended} nextRunNull=${verify.nextRunNull}`,
+  );
+
+  const created = merges.filter((m) => m.action === "create").length;
+  const refreshed = merges.filter((m) => m.action === "refresh-version").length;
+  const skippedOperatorEdited = merges.filter((m) => m.action === "skip-operator-edited").length;
+  const unchanged = merges.filter((m) => m.action === "unchanged").length;
+  const ranMs = clock() - startedAt;
+
+  log(
+    `[routine-seed] op=end acct=${acct} ranMs=${ranMs} created=${created} ` +
+      `skipped=${skippedOperatorEdited} refreshed=${refreshed} unchanged=${unchanged}`,
+  );
+
+  return {
+    accountId,
+    version,
+    timezone,
+    timezoneSource: source,
+    merges,
+    created,
+    refreshed,
+    skippedOperatorEdited,
+    unchanged,
+    verify,
+    ranMs,
+  };
+}