@agent-native/core 0.85.7 → 0.86.1

package/corpus/templates/design/shared/pen-path.ts

@@ -287,6 +287,302 @@ function cubicBezierValue(
   );
 }
 
+/**
+ * Compact, lossless, attribute-safe encoding of a full structured `PenPath`
+ * (every node's anchor point, handleIn, handleOut, and the path's `closed`
+ * flag) — for stashing on a committed screen element (e.g.
+ * `data-an-pen-nodes="..."`) so the flattened `<path d="...">` baked by
+ * `serializePenPath` can later be re-hydrated into an editable vector path
+ * for vector edit mode.
+ *
+ * Format: `JSON.stringify([closedFlag, ...nodeTuples])` where each node
+ * tuple is `[px, py, hix, hiy, hox, hoy]` and a missing handle is encoded as
+ * `null` for both of its coordinates. This is plain JSON (no raw `"`, `<`,
+ * `>`, or `&`), so it round-trips safely through `Element.setAttribute` /
+ * `getAttribute` without any additional escaping, and stays compact because
+ * every node is a flat numeric array rather than an object with repeated
+ * key names.
+ */
+export function serializePenNodes(path: PenPath): string {
+  const tuples: PenNodeTuple[] = path.nodes.map((node) => [
+    node.point.x,
+    node.point.y,
+    node.handleIn ? node.handleIn.x : null,
+    node.handleIn ? node.handleIn.y : null,
+    node.handleOut ? node.handleOut.x : null,
+    node.handleOut ? node.handleOut.y : null,
+  ]);
+  return JSON.stringify([path.closed ? 1 : 0, ...tuples]);
+}
+
+/**
+ * Inverse of `serializePenNodes`. Returns `null` (never throws) for any
+ * malformed, truncated, or otherwise unrecognized input, so callers can
+ * safely attempt to parse arbitrary/untrusted attribute strings read back
+ * off the DOM.
+ */
+export function parsePenNodes(serialized: string): PenPath | null {
+  if (typeof serialized !== "string" || serialized.length === 0) return null;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(serialized);
+  } catch {
+    return null;
+  }
+
+  if (!Array.isArray(parsed) || parsed.length === 0) return null;
+  const [closedFlag, ...tuples] = parsed;
+  if (closedFlag !== 0 && closedFlag !== 1) return null;
+
+  const nodes: PenNode[] = [];
+  for (const tuple of tuples) {
+    const node = parsePenNodeTuple(tuple);
+    if (!node) return null;
+    nodes.push(node);
+  }
+
+  return { nodes, closed: closedFlag === 1 };
+}
+
+function parsePenNodeTuple(tuple: unknown): PenNode | null {
+  if (!Array.isArray(tuple) || tuple.length !== 6) return null;
+  const [px, py, hix, hiy, hox, hoy] = tuple;
+  if (!isFiniteNumber(px) || !isFiniteNumber(py)) return null;
+  if (!isNullOrFiniteNumber(hix) || !isNullOrFiniteNumber(hiy)) return null;
+  if (!isNullOrFiniteNumber(hox) || !isNullOrFiniteNumber(hoy)) return null;
+  // A handle's two coordinates must agree on presence — one present and the
+  // other null is not a representable PenPoint.
+  if ((hix === null) !== (hiy === null)) return null;
+  if ((hox === null) !== (hoy === null)) return null;
+
+  return {
+    point: { x: px, y: py },
+    handleIn: hix === null || hiy === null ? undefined : { x: hix, y: hiy },
+    handleOut: hox === null || hoy === null ? undefined : { x: hox, y: hoy },
+  };
+}
+
+type PenNodeTuple = [
+  number,
+  number,
+  number | null,
+  number | null,
+  number | null,
+  number | null,
+];
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function isNullOrFiniteNumber(value: unknown): value is number | null {
+  return value === null || isFiniteNumber(value);
+}
+
+/**
+ * Nearest pen anchor to `point` within `radiusInCanvasPx`, or `null` if none
+ * qualifies. Ties (equal distance) resolve to the earlier node index, same
+ * as a stable nearest-match scan.
+ */
+export function hitTestPenAnchor(
+  path: PenPath,
+  point: PenPoint,
+  radiusInCanvasPx: number,
+): { nodeIndex: number } | null {
+  let bestIndex = -1;
+  let bestDistance = Infinity;
+
+  path.nodes.forEach((node, index) => {
+    const distance = Math.hypot(node.point.x - point.x, node.point.y - point.y);
+    if (distance <= radiusInCanvasPx && distance < bestDistance) {
+      bestDistance = distance;
+      bestIndex = index;
+    }
+  });
+
+  return bestIndex === -1 ? null : { nodeIndex: bestIndex };
+}
+
+/**
+ * Nearest pen control-handle endpoint (a node's `handleIn` or `handleOut`)
+ * to `point` within `radiusInCanvasPx`, or `null` if none qualifies. Nodes
+ * without a given handle are skipped for that handle.
+ */
+export function hitTestPenHandle(
+  path: PenPath,
+  point: PenPoint,
+  radiusInCanvasPx: number,
+): { nodeIndex: number; which: "in" | "out" } | null {
+  let bestIndex = -1;
+  let bestWhich: "in" | "out" = "in";
+  let bestDistance = Infinity;
+
+  path.nodes.forEach((node, index) => {
+    (["in", "out"] as const).forEach((which) => {
+      const handle = which === "in" ? node.handleIn : node.handleOut;
+      if (!handle) return;
+      const distance = Math.hypot(handle.x - point.x, handle.y - point.y);
+      if (distance <= radiusInCanvasPx && distance < bestDistance) {
+        bestDistance = distance;
+        bestIndex = index;
+        bestWhich = which;
+      }
+    });
+  });
+
+  return bestIndex === -1 ? null : { nodeIndex: bestIndex, which: bestWhich };
+}
+
+/**
+ * Returns a new path with the anchor at `nodeIndex` moved to `newPoint`.
+ * By default its `handleIn`/`handleOut` translate along with it (Figma:
+ * dragging an anchor keeps both handles' offsets from the anchor fixed).
+ * Pass `{ moveHandlesWithAnchor: false }` to move only the anchor point and
+ * leave both handles at their existing absolute positions. Never mutates
+ * `path`.
+ */
+export function movePenAnchor(
+  path: PenPath,
+  nodeIndex: number,
+  newPoint: PenPoint,
+  options?: { moveHandlesWithAnchor?: boolean },
+): PenPath {
+  if (!isValidNodeIndex(path, nodeIndex)) return clonePenPath(path);
+
+  const moveHandles = options?.moveHandlesWithAnchor ?? true;
+  const node = path.nodes[nodeIndex];
+  const dx = newPoint.x - node.point.x;
+  const dy = newPoint.y - node.point.y;
+
+  const nextNode: PenNode = {
+    point: { ...newPoint },
+    handleIn: node.handleIn
+      ? moveHandles
+        ? { x: node.handleIn.x + dx, y: node.handleIn.y + dy }
+        : { ...node.handleIn }
+      : undefined,
+    handleOut: node.handleOut
+      ? moveHandles
+        ? { x: node.handleOut.x + dx, y: node.handleOut.y + dy }
+        : { ...node.handleOut }
+      : undefined,
+  };
+
+  return replaceNode(path, nodeIndex, nextNode);
+}
+
+/**
+ * Returns a new path with the `which` control handle of the node at
+ * `nodeIndex` moved to `newHandlePoint`. For a smooth node (one whose
+ * *opposite* handle already exists), the opposite handle mirrors the drag
+ * by default — the anchor stays the midpoint between both handles, so the
+ * tangent stays continuous (Figma default). Pass `{ breakSymmetry: true }`
+ * to move only the dragged handle, leaving the opposite handle where it
+ * was; this turns the anchor into a cusp going forward. A node with no
+ * opposite handle (a cusp already, or a plain corner gaining its first
+ * handle) never gains one as a side effect of this call — only the
+ * requested handle is created/moved. Never mutates `path`.
+ */
+export function movePenHandle(
+  path: PenPath,
+  nodeIndex: number,
+  which: "in" | "out",
+  newHandlePoint: PenPoint,
+  options?: { breakSymmetry?: boolean },
+): PenPath {
+  if (!isValidNodeIndex(path, nodeIndex)) return clonePenPath(path);
+
+  const node = path.nodes[nodeIndex];
+  const oppositeKey = which === "in" ? "handleOut" : "handleIn";
+  const draggedKey = which === "in" ? "handleIn" : "handleOut";
+  const hasOpposite = !!node[oppositeKey];
+
+  const nextNode: PenNode = { ...clonePenNode(node) };
+  nextNode[draggedKey] = { ...newHandlePoint };
+
+  if (hasOpposite && !options?.breakSymmetry) {
+    nextNode[oppositeKey] = mirrorPoint(node.point, newHandlePoint);
+  }
+
+  return replaceNode(path, nodeIndex, nextNode);
+}
+
+/**
+ * Returns a new path with the node at `nodeIndex` converted to `type`.
+ * Converting to `"corner"` drops both handles (a corner anchor has none).
+ * Converting to `"smooth"` synthesizes symmetric handles from the
+ * neighboring anchors when the node doesn't already have at least one
+ * handle — reusing the same mirrored-handle shape `createSmoothNode`
+ * produces — so the anchor gets a continuous tangent through its
+ * neighbors. A node that already has a handleIn or handleOut is left as-is
+ * aside from ensuring both sides are populated and mirrored, since it's
+ * already effectively smooth. Never mutates `path`.
+ */
+export function setPenNodeType(
+  path: PenPath,
+  nodeIndex: number,
+  type: "corner" | "smooth",
+): PenPath {
+  if (!isValidNodeIndex(path, nodeIndex)) return clonePenPath(path);
+
+  const node = path.nodes[nodeIndex];
+
+  if (type === "corner") {
+    return replaceNode(path, nodeIndex, { point: { ...node.point } });
+  }
+
+  if (node.handleIn || node.handleOut) {
+    // Already has at least one handle: treat as smooth already, but make
+    // sure both sides are present and mirrored around the anchor so the
+    // tangent is continuous on both sides.
+    const source = node.handleOut ?? node.handleIn!;
+    const handleOut = node.handleOut ?? mirrorPoint(node.point, source);
+    const handleIn = node.handleIn ?? mirrorPoint(node.point, handleOut);
+    return replaceNode(path, nodeIndex, {
+      point: { ...node.point },
+      handleIn: { ...handleIn },
+      handleOut: { ...handleOut },
+    });
+  }
+
+  // Plain corner with no handles yet: synthesize a symmetric handle pair
+  // from the neighboring anchors so the new tangent follows the path's
+  // local direction, matching what a freshly-dragged smooth anchor looks
+  // like via createSmoothNode.
+  const neighbor =
+    path.nodes[nodeIndex + 1] ??
+    path.nodes[nodeIndex - 1] ??
+    (path.closed ? path.nodes[0] : undefined);
+  const direction = neighbor
+    ? { x: neighbor.point.x - node.point.x, y: neighbor.point.y - node.point.y }
+    : { x: 1, y: 0 };
+  // Scale the synthesized handle to a small fraction of the distance to the
+  // neighbor (rather than reaching all the way to it), matching the usual
+  // proportions of a Figma smooth-anchor handle.
+  const HANDLE_FRACTION = 1 / 3;
+  const handleOut = {
+    x: node.point.x + direction.x * HANDLE_FRACTION,
+    y: node.point.y + direction.y * HANDLE_FRACTION,
+  };
+
+  return replaceNode(path, nodeIndex, createSmoothNode(node.point, handleOut));
+}
+
+function isValidNodeIndex(path: PenPath, nodeIndex: number): boolean {
+  return (
+    Number.isInteger(nodeIndex) &&
+    nodeIndex >= 0 &&
+    nodeIndex < path.nodes.length
+  );
+}
+
+function replaceNode(path: PenPath, nodeIndex: number, node: PenNode): PenPath {
+  const nodes = path.nodes.map(clonePenNode);
+  nodes[nodeIndex] = clonePenNode(node);
+  return { nodes, closed: path.closed };
+}
+
 export function serializePenPath(path: PenPath): string {
   const [first, ...rest] = path.nodes;
   if (!first) return "";

package/corpus/templates/dispatch/package.json

@@ -27,8 +27,8 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@react-router/dev": "^8.0.1",
-    "@react-router/fs-routes": "^8.0.1",
+    "@react-router/dev": "^8.1.0",
+    "@react-router/fs-routes": "^8.1.0",
     "@tailwindcss/typography": "^0.5.20",
     "@tailwindcss/vite": "catalog:",
     "@types/node": "^24.2.1",
@@ -38,7 +38,7 @@
     "oxfmt": "catalog:",
     "react": "catalog:",
     "react-dom": "catalog:",
-    "react-router": "^8.0.1",
+    "react-router": "^8.1.0",
     "tailwindcss": "catalog:",
     "tsx": "^4.20.3",
     "typescript": "^6.0.3",

package/corpus/templates/forms/.agents/skills/real-time-sync/SKILL.md

@@ -58,6 +58,21 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
 - Don't create manual polling loops — `useDbSync()` handles SSE plus fallback polling
 - Don't create your own fetch-based polling alongside `useDbSync` — use the `onEvent` callback for custom handling
+- Don't open your own `EventSource` to `/_agent-native/events`. A tab must hold exactly ONE SSE connection no matter how many features listen — extra streams eat the browser's per-origin connection budget and can starve ordinary data fetches (worst on HTTP/1.1 dev servers). Subscribe to the shared transport instead:
+
+  ```ts
+  import { subscribeSyncEvents } from "@agent-native/core/client";
+
+  const unsubscribe = subscribeSyncEvents({
+    onEvents: (events) => {
+      // filter by event.source and handle push-style updates
+    },
+    // Optional: relax your own fallback cadence while push is healthy.
+    onSseStateChange: (connected) => {},
+  });
+  ```
+
+  `useDbSync` and every `subscribeSyncEvents` subscriber share one `EventSource` and one fallback poll loop per tab — this is how collaborative documents receive doc updates and cursor/awareness events.
 
 ## Which sources to depend on
 

package/corpus/templates/forms/.agents/skills/storing-data/SKILL.md

@@ -25,6 +25,14 @@ Agent-native apps use Drizzle ORM over the configured SQL backend. Local develop
 
 For app code, use Drizzle's schema/query DSL by default. Raw SQL is an escape hatch for additive migrations, health checks, or one-off maintenance, not the normal way to build features.
 
+### Naming migrations
+
+When you add an entry to a `runMigrations([...])` list (`@agent-native/core/db`), always give it a unique `name:` slug (e.g. `name: "analytics-alert-rules-table"`) alongside its `version`. Never renumber or reuse version numbers on existing entries.
+
+Why: version numbers alone are not a safe identity. Two branches that each independently extend the same migration list can ship different DDL under the same version numbers — whichever branch deploys first "claims" those version numbers in the bookkeeping table, and the other branch's DDL is silently treated as already applied even though it never ran. This exact collision took down analytics: parallel branches both extended their migration list through v75-v83 with different DDL, so `analytics_alert_rules`, `analytics_alert_incidents`, and `session_recordings.network_error_count` never made it to production despite the bookkeeping table showing every version as applied. A `name:` slug is tracked independently of version numbers, so it applies exactly once per database regardless of what any other branch already recorded.
+
+Existing unnamed migrations don't need to be renamed retroactively (the two gating strategies coexist), but any new entry should always carry a name.
+
 ### Core SQL Stores (auto-created, available in all templates)
 
 | Store               | Purpose                                              | Access                                     |

package/corpus/templates/forms/package.json

@@ -64,8 +64,8 @@
     "@radix-ui/react-switch": "^1.2.5",
     "@radix-ui/react-tabs": "^1.1.12",
     "@radix-ui/react-tooltip": "^1.2.7",
-    "@react-router/dev": "^8.0.1",
-    "@react-router/fs-routes": "^8.0.1",
+    "@react-router/dev": "^8.1.0",
+    "@react-router/fs-routes": "^8.1.0",
     "@swc/core": "^1.13.3",
     "@tailwindcss/typography": "^0.5.16",
     "@tailwindcss/vite": "catalog:",
@@ -83,7 +83,7 @@
     "oxfmt": "catalog:",
     "react": "catalog:",
     "react-dom": "catalog:",
-    "react-router": "^8.0.1",
+    "react-router": "^8.1.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.5.0",
     "tailwindcss": "catalog:",

package/corpus/templates/forms/server/plugins/db.ts

@@ -1,6 +1,34 @@
-import { runMigrations } from "@agent-native/core/db";
+import {
+  ensureAdditiveColumns,
+  getDbExec,
+  runMigrations,
+} from "@agent-native/core/db";
 
-export default runMigrations(
+import * as schema from "../db/schema.js";
+
+/**
+ * Every Drizzle table exported from schema.ts. Filters out type-only and
+ * helper exports the same way db.spec.ts's `isDrizzleTable` regression guard
+ * does: a real table carries a Symbol-keyed drizzle metadata bag, plain
+ * exports don't.
+ */
+function isDrizzleTable(value: unknown): value is object {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    Object.getOwnPropertySymbols(value).some((s) =>
+      s.toString().includes("drizzle"),
+    )
+  );
+}
+
+const schemaTables = Object.values(schema).filter(isDrizzleTable);
+
+// Convention: every new migration below MUST set a unique `name:` slug (see
+// packages/core/src/db/migrations.ts for the full rationale). Version numbers
+// alone are not a safe identity across parallel branches that each extend
+// this list independently against the shared `forms_migrations` table.
+const runFormsMigrations = runMigrations(
   [
     {
       version: 1,
@@ -125,3 +153,35 @@ CREATE INDEX IF NOT EXISTS form_shares_resource_idx ON form_shares (resource_id,
   ],
   { table: "forms_migrations" },
 );
+
+/**
+ * The migration list above is the authoritative source for tables, indexes,
+ * and data transforms. `ensureAdditiveColumns` runs after it as a
+ * belt-and-braces safety net for the case where a column gets added to
+ * schema.ts without a matching hand-written ALTER migration, which would
+ * silently 500 every query touching a pre-existing production table. It only
+ * ever adds missing columns — never drops, renames, or retypes anything — and
+ * any failure here is logged and swallowed so it can never fail boot.
+ */
+export default async (nitroApp: any): Promise<void> => {
+  await runFormsMigrations(nitroApp);
+  try {
+    const summary = await ensureAdditiveColumns({
+      db: getDbExec(),
+      tables: schemaTables,
+    });
+    if (summary.errors.length > 0) {
+      console.warn(
+        "[db] ensureAdditiveColumns completed with errors:",
+        summary.errors,
+      );
+    }
+  } catch (err) {
+    // Never fail boot over the safety net itself — the authoritative
+    // migrations above already ran.
+    console.warn(
+      "[db] ensureAdditiveColumns failed (non-fatal):",
+      err instanceof Error ? err.message : err,
+    );
+  }
+};

package/corpus/templates/macros/package.json

@@ -57,8 +57,8 @@
     "@radix-ui/react-toggle": "^1.1.9",
     "@radix-ui/react-toggle-group": "^1.1.10",
     "@radix-ui/react-tooltip": "^1.2.7",
-    "@react-router/dev": "^8.0.1",
-    "@react-router/fs-routes": "^8.0.1",
+    "@react-router/dev": "^8.1.0",
+    "@react-router/fs-routes": "^8.1.0",
     "@swc/core": "^1.13.3",
     "@tailwindcss/typography": "^0.5.16",
     "@tailwindcss/vite": "catalog:",
@@ -81,7 +81,7 @@
     "react": "catalog:",
     "react-dom": "catalog:",
     "react-hook-form": "^7.71.2",
-    "react-router": "^8.0.1",
+    "react-router": "^8.1.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.5.0",
     "tailwindcss": "catalog:",

package/corpus/templates/macros/server/plugins/db.ts

@@ -1,4 +1,11 @@
-import { runMigrations, isPostgres } from "@agent-native/core/db";
+import {
+  ensureAdditiveColumns,
+  getDbExec,
+  runMigrations,
+  isPostgres,
+} from "@agent-native/core/db";
+
+import * as schema from "../db/schema.js";
 
 function pk(): string {
   return isPostgres() ? "SERIAL PRIMARY KEY" : "INTEGER PRIMARY KEY";
@@ -8,7 +15,29 @@ function realType(): string {
   return isPostgres() ? "DOUBLE PRECISION" : "REAL";
 }
 
-export default runMigrations(
+/**
+ * Every Drizzle table exported from schema.ts. Filters out type-only and
+ * helper exports the same way db.spec.ts's `isDrizzleTable` regression guard
+ * does: a real table carries a Symbol-keyed drizzle metadata bag, plain
+ * exports don't.
+ */
+function isDrizzleTable(value: unknown): value is object {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    Object.getOwnPropertySymbols(value).some((s) =>
+      s.toString().includes("drizzle"),
+    )
+  );
+}
+
+const schemaTables = Object.values(schema).filter(isDrizzleTable);
+
+// Convention: every new migration below MUST set a unique `name:` slug (see
+// packages/core/src/db/migrations.ts for the full rationale). Version numbers
+// alone are not a safe identity across parallel branches that each extend
+// this list independently.
+const runMacrosMigrations = runMigrations(
   [
     {
       version: 1,
@@ -106,3 +135,35 @@ export default runMigrations(
   ],
   { table: "macros_migrations" },
 );
+
+/**
+ * The migration list above is the authoritative source for tables, indexes,
+ * and data transforms. `ensureAdditiveColumns` runs after it as a
+ * belt-and-braces safety net for the failure mode where a column is added to
+ * schema.ts without a matching hand-written ALTER migration, which silently
+ * 500s every query touching a pre-existing production table. It only ever
+ * adds missing columns — never drops, renames, or retypes anything — and any
+ * failure here is logged and swallowed so it can never fail boot.
+ */
+export default async (nitroApp: any): Promise<void> => {
+  await runMacrosMigrations(nitroApp);
+  try {
+    const summary = await ensureAdditiveColumns({
+      db: getDbExec(),
+      tables: schemaTables,
+    });
+    if (summary.errors.length > 0) {
+      console.warn(
+        "[db] ensureAdditiveColumns completed with errors:",
+        summary.errors,
+      );
+    }
+  } catch (err) {
+    // Never fail boot over the safety net itself — the authoritative
+    // migrations above already ran.
+    console.warn(
+      "[db] ensureAdditiveColumns failed (non-fatal):",
+      err instanceof Error ? err.message : err,
+    );
+  }
+};

package/corpus/templates/mail/.agents/skills/real-time-sync/SKILL.md

@@ -58,6 +58,21 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
 - Don't create manual polling loops — `useDbSync()` handles SSE plus fallback polling
 - Don't create your own fetch-based polling alongside `useDbSync` — use the `onEvent` callback for custom handling
+- Don't open your own `EventSource` to `/_agent-native/events`. A tab must hold exactly ONE SSE connection no matter how many features listen — extra streams eat the browser's per-origin connection budget and can starve ordinary data fetches (worst on HTTP/1.1 dev servers). Subscribe to the shared transport instead:
+
+  ```ts
+  import { subscribeSyncEvents } from "@agent-native/core/client";
+
+  const unsubscribe = subscribeSyncEvents({
+    onEvents: (events) => {
+      // filter by event.source and handle push-style updates
+    },
+    // Optional: relax your own fallback cadence while push is healthy.
+    onSseStateChange: (connected) => {},
+  });
+  ```
+
+  `useDbSync` and every `subscribeSyncEvents` subscriber share one `EventSource` and one fallback poll loop per tab — this is how collaborative documents receive doc updates and cursor/awareness events.
 
 ## Which sources to depend on
 

package/corpus/templates/mail/.agents/skills/storing-data/SKILL.md

@@ -25,6 +25,14 @@ Agent-native apps use Drizzle ORM over the configured SQL backend. Local develop
 
 For app code, use Drizzle's schema/query DSL by default. Raw SQL is an escape hatch for additive migrations, health checks, or one-off maintenance, not the normal way to build features.
 
+### Naming migrations
+
+When you add an entry to a `runMigrations([...])` list (`@agent-native/core/db`), always give it a unique `name:` slug (e.g. `name: "analytics-alert-rules-table"`) alongside its `version`. Never renumber or reuse version numbers on existing entries.
+
+Why: version numbers alone are not a safe identity. Two branches that each independently extend the same migration list can ship different DDL under the same version numbers — whichever branch deploys first "claims" those version numbers in the bookkeeping table, and the other branch's DDL is silently treated as already applied even though it never ran. This exact collision took down analytics: parallel branches both extended their migration list through v75-v83 with different DDL, so `analytics_alert_rules`, `analytics_alert_incidents`, and `session_recordings.network_error_count` never made it to production despite the bookkeeping table showing every version as applied. A `name:` slug is tracked independently of version numbers, so it applies exactly once per database regardless of what any other branch already recorded.
+
+Existing unnamed migrations don't need to be renamed retroactively (the two gating strategies coexist), but any new entry should always carry a name.
+
 ### Core SQL Stores (auto-created, available in all templates)
 
 | Store               | Purpose                                              | Access                                     |