@rubytech/create-sitedesk-code 0.1.522 → 0.1.523

package/payload/platform/lib/graph-write/src/index.ts

@@ -218,14 +218,44 @@ export interface WriteNodeWithEdgesParams {
    * a failed embed must never abort an otherwise-valid write.
    */
   embed?: (text: string) => Promise<number[]>;
+  /**
+   * Optional natural-key merge. When present and non-empty the node write
+   * becomes a MERGE on `accountId` plus the named properties, and every
+   * relationship in the same call becomes a MERGE — a re-import of the same
+   * row then matches the existing node and its existing edges instead of
+   * creating a second copy. Absent (the default), both paths CREATE exactly
+   * as before. `accountId` is always part of the key and is never named here.
+   * Task 2132.
+   */
+  mergeOn?: string[];
 }
 
 export interface WriteNodeResult {
   nodeId: string;
   labels: string[];
+  /**
+   * Edges created on a plain write. Under `mergeOn` this counts edges
+   * *resolved* — created plus already-present — because a re-import
+   * legitimately creates none. Both readings satisfy the same invariant the
+   * writer checks: one edge per requested relationship, or the write rolls back.
+   */
   edgesCreated: number;
 }
 
+/**
+ * Properties a `mergeOn` write sets on creation only, so a re-import
+ * preserves the original provenance and creation time rather than restamping
+ * them with the second run's values. Mirrors the ON CREATE blocks in
+ * memory-archive-write.ts and the installer's LocalBusiness bootstrap.
+ */
+const MERGE_CREATE_ONLY_PROPS = new Set([
+  "createdAt",
+  "createdByAgent",
+  "createdBySession",
+  "createdByTool",
+  "createdBySource",
+]);
+
 /** Stamp flattened provenance into node properties. */
 export function stampCreatedBy(
   props: Record<string, unknown>,
@@ -316,6 +346,34 @@ export async function writeNodeWithEdges(
     );
   }
 
+  // Natural-key merge (Task 2132). Validated here so a malformed key throws
+  // before any query runs — a key naming a property the caller did not write
+  // would silently MERGE on `null` and collapse unrelated rows onto one node.
+  const mergeKeys = params.mergeOn;
+  if (mergeKeys !== undefined) {
+    if (mergeKeys.length === 0) {
+      throw new Error(
+        "mergeOn must name at least one property (accountId is always included and must not be named)."
+      );
+    }
+    for (const k of mergeKeys) {
+      if (!(k in props)) {
+        throw new Error(
+          `mergeOn property "${k}" is not present in props — the natural key must be written with the node.`
+        );
+      }
+      // `k in props` is true for an explicit undefined, and Neo4j would then
+      // MERGE on null and collapse every keyless row onto one node — the exact
+      // failure this validation exists to prevent.
+      const v = (props as Record<string, unknown>)[k];
+      if (v === undefined || v === null || v === "") {
+        throw new Error(
+          `mergeOn property "${k}" is empty — a natural key must carry a value, or the merge collapses unrelated rows onto one node.`
+        );
+      }
+    }
+  }
+
   // Embed safety net. When the node carries a vector-indexed label, lacks an
   // embedding, and an embedder is injected, compute a bounded props embedding
   // so no indexed node enters the graph invisible to vector search. A failed
@@ -410,10 +468,39 @@ export async function writeNodeWithEdges(
 
     let nodeRes;
     try {
-      nodeRes = await tx.run(
-        `CREATE (n:${labelStr} $props) RETURN elementId(n) AS nodeId, labels(n) AS nodeLabels`,
-        { props: nodeProps }
-      );
+      if (mergeKeys) {
+        // Natural-key MERGE. Creation-only properties sit under ON CREATE so a
+        // re-import preserves the original provenance and createdAt, matching
+        // PERSON_AND_CONNECTED_EDGE_CYPHER in memory-archive-write.ts and the
+        // installer's LocalBusiness bootstrap. Everything else refreshes.
+        const keyProps = ["accountId", ...mergeKeys];
+        const keyPattern = keyProps.map((k) => `${k}: $key_${k}`).join(", ");
+        const keyParams: Record<string, unknown> = {};
+        for (const k of keyProps) {
+          keyParams[`key_${k}`] = (nodeProps as Record<string, unknown>)[k];
+        }
+        const createProps: Record<string, unknown> = {};
+        const updateProps: Record<string, unknown> = {};
+        for (const [k, v] of Object.entries(nodeProps as Record<string, unknown>)) {
+          if (keyProps.includes(k)) continue;
+          (MERGE_CREATE_ONLY_PROPS.has(k) ? createProps : updateProps)[k] = v;
+        }
+        nodeRes = await tx.run(
+          `MERGE (n:${labelStr} {${keyPattern}}) ON CREATE SET n += $createProps SET n += $updateProps RETURN elementId(n) AS nodeId, labels(n) AS nodeLabels`,
+          { ...keyParams, createProps, updateProps }
+        );
+        const outcome = nodeRes.summary?.counters.updates().nodesCreated
+          ? "created"
+          : "matched";
+        process.stderr.write(
+          `[graph-write] op=merge label=${labelCsv} key=${keyProps.join(",")} outcome=${outcome}\n`
+        );
+      } else {
+        nodeRes = await tx.run(
+          `CREATE (n:${labelStr} $props) RETURN elementId(n) AS nodeId, labels(n) AS nodeLabels`,
+          { props: nodeProps }
+        );
+      }
     } catch (err) {
       // surface UserProfile uniqueness violations as a structured
       // reject line. Neo4j's ConstraintValidationFailed message names the
@@ -448,12 +535,32 @@ export async function writeNodeWithEdges(
     let edgesCreated = 0;
     for (const rel of relationships) {
       const type = rel.type.replace(/`/g, "");
-      const q =
-        rel.direction === "outgoing"
-          ? `MATCH (a), (b) WHERE elementId(a) = $from AND elementId(b) = $to CREATE (a)-[:\`${type}\`]->(b)`
-          : `MATCH (a), (b) WHERE elementId(a) = $from AND elementId(b) = $to CREATE (b)-[:\`${type}\`]->(a)`;
-      const r = await tx.run(q, { from: nodeId, to: rel.targetNodeId });
-      const created = r.summary.counters.updates().relationshipsCreated;
+      let created: number;
+      if (mergeKeys) {
+        // Under a natural-key merge the edges MERGE too: a node that matched
+        // must not accumulate a second copy of each relationship. A repeat
+        // legitimately creates zero relationships, so the unresolved-target
+        // guard below switches from the create counter to the returned row
+        // count — 0 rows means the MATCH failed to resolve an endpoint, the
+        // condition the guard was written for.
+        const dir =
+          rel.direction === "outgoing"
+            ? `(a)-[r:\`${type}\`]->(b)`
+            : `(b)-[r:\`${type}\`]->(a)`;
+        const r = await tx.run(
+          `MATCH (a), (b) WHERE elementId(a) = $from AND elementId(b) = $to MERGE ${dir} RETURN count(r) AS n`,
+          { from: nodeId, to: rel.targetNodeId }
+        );
+        created =
+          r.records.length === 0 ? 0 : Number(r.records[0].get("n") ?? 0);
+      } else {
+        const q =
+          rel.direction === "outgoing"
+            ? `MATCH (a), (b) WHERE elementId(a) = $from AND elementId(b) = $to CREATE (a)-[:\`${type}\`]->(b)`
+            : `MATCH (a), (b) WHERE elementId(a) = $from AND elementId(b) = $to CREATE (b)-[:\`${type}\`]->(a)`;
+        const r = await tx.run(q, { from: nodeId, to: rel.targetNodeId });
+        created = r.summary.counters.updates().relationshipsCreated;
+      }
       if (created === 0) {
         process.stderr.write(
           `[graph-write] reject reason=unresolved-target-on-create labels=${labelCsv} agent=${agentLabel} relType=${rel.type} targetId=${rel.targetNodeId}\n`

package/payload/platform/lib/routine-templates/dist/index.d.ts

@@ -0,0 +1,151 @@
+/**
+ * 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 { 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;
+}
+/** First eight characters of the accountId — the correlation key every
+ *  `[routine-seed]` and `[schedule-audit]` line carries. */
+export declare function acctTag(accountId: string): string;
+/**
+ * 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 declare function resolveOwnerTimezone(session: SeedSessionLike, accountId: string): Promise<{
+    timezone: string | null;
+    source: "owner-profile" | "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 declare const MERGE_CYPHER = "\nUNWIND $rows AS row\nOPTIONAL MATCH (pre:Event {accountId: $accountId, routineTemplate: row.key})\nWITH row,\n     pre IS NOT NULL AS existed,\n     coalesce(pre.routineTemplateVersion, 0) AS priorVersion,\n     pre.operatorEdited IS NOT NULL AS edited\nWITH row, existed, priorVersion, edited,\n     (existed AND NOT edited AND priorVersion < $version) AS refreshing\nMERGE (e:Event {accountId: $accountId, routineTemplate: row.key})\n  ON CREATE SET e.eventId = randomUUID(),\n                e.name = row.name,\n                e.agentPrompt = row.prompt,\n                e.recurrence = row.recurrence,\n                e.routineTemplateVersion = $version,\n                e.eventStatus = 'suspended',\n                e.nextRun = null,\n                e.agentChannel = null,\n                e.agentDestination = null,\n                e.actionPlugin = null,\n                e.actionTool = null,\n                e.actionArgs = null,\n                e.sourcePlugin = null,\n                e.timezone = $timezone,\n                e.createdBySource = 'installer',\n                e.createdByAgent = 'system',\n                e.createdByTool = 'routine-roster-seed',\n                e.createdAt = $now,\n                e.updatedAt = $now\n  ON MATCH SET e.agentPrompt = CASE WHEN refreshing THEN row.prompt ELSE e.agentPrompt END,\n               e.name = CASE WHEN refreshing THEN row.name ELSE e.name END,\n               e.routineTemplateVersion = CASE WHEN refreshing THEN $version ELSE e.routineTemplateVersion END,\n               e.updatedAt = CASE WHEN refreshing THEN $now ELSE e.updatedAt END\nRETURN row.key AS key,\n       e.eventId AS eventId,\n       CASE WHEN NOT existed THEN 'create'\n            WHEN priorVersion >= $version THEN 'unchanged'\n            WHEN edited THEN 'skip-operator-edited'\n            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 declare const VERIFY_CYPHER = "\nMATCH (e:Event {accountId: $accountId})\nWHERE e.routineTemplate IS NOT NULL\nRETURN count(e) AS actual,\n       sum(CASE WHEN e.eventStatus = 'suspended' THEN 1 ELSE 0 END) AS suspended,\n       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 declare function seedRoutineRoster(args: SeedRoutineRosterArgs): Promise<RoutineSeedReport>;
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/routine-templates/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAA4C,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAE7F,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC5F,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;2EAG2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,KAAK,CAAC;YAAE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC,CAAC;CAClH;AAED;;;;;;;4EAO4E;AAC5E,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,iBAAiB,GAAG,sBAAsB,GAAG,WAAW,CAAC;AAErG,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AAED;;;;;;0EAM0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,eAAe,GAAG,QAAQ,CAAC;IAC3C,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;CACf;AAYD;4DAC4D;AAC5D,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,eAAe,GAAG,QAAQ,CAAA;CAAE,CAAC,CAa1E;AAED;;;;;;;;;;;;kEAYkE;AAClE,eAAO,MAAM,YAAY,01DAsCwB,CAAC;AAElD;+DAC+D;AAC/D,eAAO,MAAM,aAAa,4QAK+C,CAAC;AAE1E,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,MAAM,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACpC,+DAA+D;IAC/D,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B;sEACkE;IAClE,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAyE/F"}

package/payload/platform/lib/routine-templates/dist/index.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERIFY_CYPHER = exports.MERGE_CYPHER = exports.ROUTINE_TEMPLATE_VERSION = exports.ROUTINE_ROSTER_KEYS = exports.ROUTINE_ROSTER = void 0;
+exports.acctTag = acctTag;
+exports.resolveOwnerTimezone = resolveOwnerTimezone;
+exports.seedRoutineRoster = seedRoutineRoster;
+/**
+ * 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.
+ */
+const roster_js_1 = require("./roster.js");
+var roster_js_2 = require("./roster.js");
+Object.defineProperty(exports, "ROUTINE_ROSTER", { enumerable: true, get: function () { return roster_js_2.ROUTINE_ROSTER; } });
+Object.defineProperty(exports, "ROUTINE_ROSTER_KEYS", { enumerable: true, get: function () { return roster_js_2.ROUTINE_ROSTER_KEYS; } });
+Object.defineProperty(exports, "ROUTINE_TEMPLATE_VERSION", { enumerable: true, get: function () { return roster_js_2.ROUTINE_TEMPLATE_VERSION; } });
+/** 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) {
+    if (typeof raw === "number")
+        return raw;
+    if (raw && typeof raw.toNumber === "function") {
+        return raw.toNumber();
+    }
+    return Number(raw ?? 0);
+}
+/** First eight characters of the accountId — the correlation key every
+ *  `[routine-seed]` and `[schedule-audit]` line carries. */
+function acctTag(accountId) {
+    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.
+ */
+async function resolveOwnerTimezone(session, accountId) {
+    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. */
+exports.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. */
+exports.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`;
+/**
+ * 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.
+ */
+async function seedRoutineRoster(args) {
+    const { session, accountId, version = roster_js_1.ROUTINE_TEMPLATE_VERSION, now = new Date().toISOString(), roster = roster_js_1.ROUTINE_ROSTER, log = (line) => 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(exports.MERGE_CYPHER, {
+        accountId,
+        version,
+        timezone,
+        now,
+        rows: roster.map((r) => ({ key: r.key, name: r.name, prompt: r.prompt, recurrence: r.recurrence })),
+    });
+    const merges = mergeRes.records.map((rec) => ({
+        key: String(rec.get("key")),
+        eventId: String(rec.get("eventId")),
+        action: String(rec.get("action")),
+    }));
+    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(exports.VERIFY_CYPHER, { accountId });
+    const verifyRec = verifyRes.records[0];
+    const verify = {
+        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,
+    };
+}
+//# sourceMappingURL=index.js.map

package/payload/platform/lib/routine-templates/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/routine-templates/dist/roster.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Task 2130 — the shipped routine roster.
+ *
+ * A fresh install used to ship zero routines, so the only working examples
+ * lived in one customer's graph and every operator wrote the prompts from
+ * scratch. These eleven are the catalogue that ships with the platform instead.
+ *
+ * Two properties make a routine shippable, and both are load-bearing:
+ *
+ *   1. It resolves its own surfaces at run time. Every prompt opens on
+ *      `capabilities-here`, which reports the account's live install set, and
+ *      ends the turn without replying when the surface it needs is absent. That
+ *      is what makes the same eleven rows correct on an estate agency, a web studio
+ *      and a field-service install rather than a template someone must edit.
+ *
+ *   2. It names nobody. No prompt carries a person's name, an email address, a
+ *      phone number, a hostname or a database name. `scripts/check-routine-
+ *      templates-generic.sh` is the standing control for that; a review pass is
+ *      not, because the failure is silent and the routine still works.
+ *
+ * The `recurrence` on each row is a PROPOSAL, not a schedule. Seeded rows carry
+ * `eventStatus:'suspended'` and `nextRun:NULL`, so nothing here fires until an
+ * operator enables it and supplies the cron and zone they actually want (see
+ * `.docs/routine-roster.md` for why the enable path takes all four arguments).
+ *
+ * Every tool name cited in a prompt exists in
+ * `platform/services/claude-session-manager/src/canonical-tool-names.generated.ts`.
+ * The roster test asserts that, so a renamed tool breaks the build rather than
+ * shipping a prompt that reaches for a tool no install serves.
+ */
+/** Bumped whenever any prompt in the roster changes. The seed refreshes a
+ *  routine's prompt only when the stored `routineTemplateVersion` is BELOW this
+ *  and no operator has edited the row, so an unbumped edit ships to new installs
+ *  and never reaches existing ones — bump it in the same commit as the edit. */
+export declare const ROUTINE_TEMPLATE_VERSION = 1;
+export interface RoutineTemplate {
+    /** Stable identity. Half of the MERGE key `(accountId, routineTemplate)`, so
+     *  it is never renamed: a renamed key seeds a duplicate row and orphans the
+     *  original, which the operator then has to delete by hand. */
+    readonly key: string;
+    /** The title shown on `/routines`. */
+    readonly name: string;
+    /** The proposed cron. Written ON CREATE only, never refreshed, so an operator
+     *  who retimes a routine keeps their expression across upgrades. */
+    readonly recurrence: string;
+    /** The injected turn. Refreshed on a version bump when the row is unedited. */
+    readonly prompt: string;
+}
+/** The eleven. Order is the display order on `/routines` before the operator
+ *  retimes anything: the daily rhythm first, then the reconciles, then the
+ *  weekly, then the standing check. */
+export declare const ROUTINE_ROSTER: readonly RoutineTemplate[];
+/** Every roster key, in roster order. The scheduling heartbeat's `op=roster`
+ *  drift check reconciles this expected set against what is actually in the
+ *  graph, so it is exported rather than re-derived there. */
+export declare const ROUTINE_ROSTER_KEYS: readonly string[];
+//# sourceMappingURL=roster.d.ts.map

package/payload/platform/lib/routine-templates/dist/roster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roster.d.ts","sourceRoot":"","sources":["../src/roster.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;gFAGgF;AAChF,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,MAAM,WAAW,eAAe;IAC9B;;mEAE+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;wEACoE;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAwID;;uCAEuC;AACvC,eAAO,MAAM,cAAc,EAAE,SAAS,eAAe,EAYpD,CAAC;AAEF;;6DAE6D;AAC7D,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAAqC,CAAC"}