@checkstack/notification-backend 1.4.2 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # @checkstack/notification-backend
 
+## 1.5.0
+
+### Minor Changes
+
+- 9dcc848: Plugin-owned AI tools: every domain plugin contributes its own AI tools (chat assistant + automation AI action), and `ai-backend` is platform-only.
+
+  Every plugin-specific AI tool is owned by the plugin whose domain it acts on, registered via that plugin's own `aiToolExtensionPoint` / `aiToolProjectionExtensionPoint` from its init - the same path an external plugin author uses. `ai-backend` no longer imports or depends on any capability plugin's `*-common`; the dependency direction is strictly plugin -> ai-platform. Pure helpers (`computeFieldDiff`, capability-summary, `ScriptContextKind`) live in `@checkstack/ai-common`.
+
+  Tools shipped:
+
+  - Health checks and automations: full CRUD - `healthcheck.propose` / `automation.propose` and `*.update` (`mutate`, deep-validated) and `*.delete` (`destructive`, always confirm-gated). `healthcheck.propose`'s dry-run calls the new deep `validateConfiguration` so propose-time validation matches apply-time. Assertions are validated against the collector's result schema and the canonical operator vocabulary. Capability-catalog tools (`ai.listCapabilities`, `ai.getCapabilitySchema`), script context tools (`ai.getScriptContext`, `ai.testScript`), and notify-subscriber tools (`healthcheck.notifySystemSubscribers` / `...GroupSubscribers`).
+  - Catalog: `catalog.createSystem` / `updateSystem` / `createGroup` / `updateGroup` (`mutate`), `catalog.deleteSystem` / `deleteGroup` (`destructive`), membership tools (`mutate`), plus `catalog.listSystems` / `listGroups` read projections.
+  - Incident: `incident.create` / `update` / `addUpdate` / `resolve` / `addLink` (`mutate`), `incident.delete` / `removeLink` (`destructive`), and `incident.get` / `incident.list` read projections.
+  - Maintenance: `maintenance.create` / `update` / `addUpdate` / `close` / `addLink` (`mutate`), `maintenance.delete` / `removeLink` (`destructive`), and `maintenance.list` / `get` read projections.
+  - Read projections for SLO (`slo.listObjectives`), dependency (`dependency.list`), incident (`incident.list`), healthcheck (`healthcheck.status`), and anomaly (`anomaly.explain`), each gated by the source procedure's own access rule and routed as the principal.
+  - Documentation grounding: `ai.searchDocs` / `ai.getDoc` over a build-time bundled docs index (BM25-ish ranking), so the assistant grounds how-to answers in Checkstack's own docs offline.
+  - URL introspection: `ai.probeUrl`, an SSRF-guarded read tool the assistant uses to inspect a real endpoint before drafting a health check. Update tools compute a before -> after field diff rendered on the confirm card (approve mode) or an "Applied" card (auto mode), so a change is never silent.
+
+  `ai_analyze` automation action (automation-backend, with an editor connection picker + audited tool calls): runs a bounded AI agent on the run context as the automation's `runAs` service account, so it can never exceed that identity's permissions; destructive tools are never offered; mutating tools auto-apply through the service account's client. Produces an `automation.analysis` artifact downstream actions can branch on. The agent loop is exposed as a headless `aiAgentRunnerRef` service so automation-backend can drive it without depending on ai-backend.
+
+  `notification.notifyForSubscription` is now callable by user / application principals holding `notification.send` (previously service-only). Every tool routes through the user-scoped client, so handler-side authorization is enforced exactly as a direct UI/RPC action; the resolver gate plus the propose/apply re-check at propose AND apply are the additional authority. A systemic authz regression test asserts every registered tool falls into exactly one safe authorization category.
+
+  A new `ai_transport` enum value `automation` records the AI action's tool calls in the `ai_tool_calls` audit log. No new durable state beyond that; each tool is a thin, deterministic wrapper over an existing RPC, so every pod behaves identically.
+
+  This is a beta minor.
+
+- 9dcc848: Harden config-versioning so stored configs always migrate-then-validate and broken migration chains fail fast at boot.
+
+  - `@checkstack/backend-api` `Versioned<T>` gains `parseAssumingV1` (migrate-from-v1 then validate leniently, runtime path), `parseStrictAssumingV1` (migrate then validate strictly, editor path), and `validateMigrationChainFromV1()`. A standalone pure helper `assertMigrationChainFromV1({ version, migrations })` is the single shared implementation behind the constructor guard and `validateMigrationChainFromV1`.
+  - `Versioned` now validates its own v1 -> `version` chain in the constructor, which runs at module import / plugin registration. A new `no-restricted-syntax` ESLint rule bans calling `parse` / `safeParse` / `parseAsync` / `strict` directly on a `Versioned`'s `.schema` member.
+  - Auth strategy migration chains are validated at the `betterAuthExtensionPoint.addStrategy` chokepoint (`@checkstack/auth-backend`).
+  - Automation action AND trigger configs migrate-then-validate (lenient at dispatch, strict in the editor validator, recursing into `choose`/`parallel`/`repeat`/`sequence` blocks). The `run_script` / `run_shell` action configs bump to `version: 2` dropping the removed `sandbox` key, fixing the editor's `Unrecognized key: sandbox` error.
+  - Anomaly read path now validates: `getAnomalyConfig` / `getAnomalyAssignmentConfig` run stored records through `Versioned.parseRecord`; `PartialAnomalySettingsSchema` moved to `@checkstack/anomaly-common`. Notification ConfigService reads thread the migrations argument, and per-strategy `userConfig` is migrate-then-validated before `send()`.
+  - gitops-apply migrate-then-validates authored health-check config; integration connection validation routes through `safeValidate`. The latent HTTP health-check `result` schema (at `version: 3` with no migrations) now ships a pass-through v1 -> v2 -> v3 chain.
+
+  BREAKING CHANGES (fail-fast at boot, intended):
+
+  - Any `Versioned` config with `version > 1` and an incomplete or non-contiguous migration chain now throws at construction (boot) instead of failing lazily on first read. This covers every `Versioned` instance repo-wide, including future plugin types. Out-of-tree plugins shipping such a config must add the missing migration step(s); all in-repo strategies already have complete chains.
+  - An auth strategy declaring `configVersion > 1` without a complete chain throws at registration.
+  - A trigger's per-automation config is now a versioned `config: Versioned<TConfig>` instead of a bare `configSchema?`. Plugins registering triggers with `configSchema:` must wrap it: `config: new Versioned({ version: 1, schema })`. The underlying schema stays reachable via `config.schema`; triggers without per-automation config are unaffected.
+
+  State and scale: all affected reads resolve from shared Postgres / in-process registries, so every pod sees the same migrated answer. No new framework-owned current-state store.
+
+  This is a beta minor.
+
+- 9dcc848: Align workspace dependency versions and migrate React Router to v7.
+
+  BREAKING CHANGES (React Router v7): All frontend packages now depend on `react-router-dom@^7.16.0`. Previously the workspace declared four divergent ranges (`^6.20.0`, `^6.22.0`, `^7.1.1`, `^7.14.2`), which resolved both `react-router@6` and `react-router@7` into a single bundle. Everything is now unified on v7. The public imports the app uses (`BrowserRouter`, `Routes`, `Route`, `Link`, `NavLink`, `MemoryRouter`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`) are unchanged between v6 and v7, so no source rewrites were required - but any out-of-tree plugin still on react-router v6 should upgrade to v7 (see the React Router v6 -> v7 upgrade guide) to share the host's single router instance via the import map.
+
+  Other unified ranges (no API change): `react` -> `^18.3.1`, the `@orpc/*` family (`contract`, `server`, `client`, `tanstack-query`, `openapi`, `zod`) -> `^1.14.4`, and `better-auth` -> `^1.6.13`.
+
+  Removed the pre-rename `@orpc/react-query` leftover from `@checkstack/frontend-api`; its `createRouterUtils` / `RouterUtils` / `ProcedureUtils` now come from `@orpc/tanstack-query` (the package already in use).
+
+  Stale in-range runtime deps pulled up to current published versions: `hono` `^4.12.23`, `@tanstack/react-query` (+devtools) `^5.100.14`, `date-fns` `^4.4.0`, `jose` `^6.2.3`, `tar` `^7.5.16`, `semver` `^7.8.1`, `@xyflow/react` `^12.11.0`.
+
+### Patch Changes
+
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+  - @checkstack/auth-backend@0.5.0
+  - @checkstack/auth-common@0.8.0
+  - @checkstack/backend-api@0.21.0
+  - @checkstack/automation-backend@0.5.0
+  - @checkstack/notification-common@1.3.0
+  - @checkstack/common@0.13.0
+  - @checkstack/cache-api@0.3.9
+  - @checkstack/queue-api@0.3.9
+  - @checkstack/signal-common@0.2.6
+  - @checkstack/cache-utils@0.2.14
+
 ## 1.4.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/notification-backend",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -16,24 +16,24 @@
   },
   "dependencies": {
     "@checkstack/notification-common": "1.2.1",
-    "@checkstack/backend-api": "0.18.0",
-    "@checkstack/automation-backend": "0.2.0",
-    "@checkstack/cache-api": "0.3.6",
-    "@checkstack/cache-utils": "0.2.11",
+    "@checkstack/backend-api": "0.20.0",
+    "@checkstack/automation-backend": "0.4.0",
+    "@checkstack/cache-api": "0.3.8",
+    "@checkstack/cache-utils": "0.2.13",
     "@checkstack/signal-common": "0.2.5",
-    "@checkstack/queue-api": "0.3.6",
-    "@checkstack/auth-backend": "0.4.31",
+    "@checkstack/queue-api": "0.3.8",
+    "@checkstack/auth-backend": "0.4.33",
     "@checkstack/auth-common": "0.7.2",
     "drizzle-orm": "^0.45.0",
     "zod": "^4.2.1",
     "@checkstack/common": "0.12.0",
-    "@orpc/server": "^1.13.2"
+    "@orpc/server": "^1.14.4"
   },
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.5",
     "@checkstack/scripts": "0.3.4",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/test-utils-backend": "0.1.31",
+    "@checkstack/test-utils-backend": "0.1.33",
     "@types/node": "^20.0.0",
     "drizzle-kit": "^0.31.10",
     "typescript": "^5.0.0"

package/src/automations.test.ts

@@ -15,7 +15,7 @@ import type { Logger, RpcClient } from "@checkstack/backend-api";
 import { createMockLogger } from "@checkstack/test-utils-backend";
 
 import {
-  createNotificationActions,
+  notificationSendAction,
   notificationDeliveredTrigger,
   notificationFailedTrigger,
   notificationSendArtifactType,
@@ -32,6 +32,7 @@ const ctxBase = {
   getService: async <T,>(): Promise<T> => {
     throw new Error("not used");
   },
+  rpcClient: { forPlugin: () => ({}) } as unknown as RpcClient,
 };
 
 // ─── Triggers ──────────────────────────────────────────────────────────
@@ -126,10 +127,11 @@ describe("notification.send", () => {
         ],
       },
     });
-    const [send] = createNotificationActions({ rpcClient });
+    const send = notificationSendAction;
 
-    const result = await send!.execute({
+    const result = await send.execute({
       ...ctxBase,
+      rpcClient,
       consumedArtifacts: {},
       config: {
         userId: "user-1",
@@ -169,10 +171,11 @@ describe("notification.send", () => {
         ],
       },
     });
-    const [send] = createNotificationActions({ rpcClient });
+    const send = notificationSendAction;
 
-    const result = await send!.execute({
+    const result = await send.execute({
       ...ctxBase,
+      rpcClient,
       consumedArtifacts: {},
       config: {
         userId: "user-1",
@@ -192,10 +195,11 @@ describe("notification.send", () => {
       ok: true,
       result: { deliveredCount: 1, results: [] },
     });
-    const [send] = createNotificationActions({ rpcClient });
+    const send = notificationSendAction;
 
-    await send!.execute({
+    await send.execute({
       ...ctxBase,
+      rpcClient,
       consumedArtifacts: {},
       config: {
         userId: "user-1",
@@ -220,10 +224,11 @@ describe("notification.send", () => {
       ok: true,
       result: { deliveredCount: 1, results: [] },
     });
-    const [send] = createNotificationActions({ rpcClient });
+    const send = notificationSendAction;
 
-    await send!.execute({
+    await send.execute({
       ...ctxBase,
+      rpcClient,
       consumedArtifacts: {},
       config: {
         userId: "user-1",
@@ -244,10 +249,11 @@ describe("notification.send", () => {
       ok: false,
       error: new Error("rpc unreachable"),
     });
-    const [send] = createNotificationActions({ rpcClient });
+    const send = notificationSendAction;
 
-    const result = await send!.execute({
+    const result = await send.execute({
       ...ctxBase,
+      rpcClient,
       consumedArtifacts: {},
       config: {
         userId: "user-1",

package/src/automations.ts

@@ -15,7 +15,7 @@
  * ones.
  */
 import { z } from "zod";
-import { Versioned, type RpcClient } from "@checkstack/backend-api";
+import { Versioned } from "@checkstack/backend-api";
 import type {
   ActionDefinition,
   TriggerDefinition,
@@ -127,74 +127,67 @@ export const notificationSendArtifactType = {
   schema: notificationSendArtifactSchema,
 } as const;
 
-// ─── Action factory ────────────────────────────────────────────────────
-
-export interface NotificationActionDeps {
-  /**
-   * Plugin rpcClient. The action invokes
-   * `sendTransactional` (service-mode) so notification-backend's
-   * existing dispatch loop runs — same strategy fan-out + per-attempt
-   * persistence + (now) delivered/failed hook emission as a
-   * code-driven send.
-   */
-  rpcClient: RpcClient;
-}
-
-export function createNotificationActions(
-  deps: NotificationActionDeps,
-): ActionDefinition<unknown, unknown>[] {
-  const sendAction: ActionDefinition<
-    NotificationSendConfig,
-    NotificationSendArtifact
-  > = {
-    id: "send",
-    displayName: "Send Notification",
-    description:
-      "Send a transactional notification to a specific user via all enabled strategies",
-    category: "Notifications",
-    icon: "BellRing",
-    config: new Versioned({
-      version: 1,
-      schema: notificationSendConfigSchema,
-    }),
-    produces: "notification.send_result",
-    execute: async ({ config, logger }) => {
-      const notificationClient = deps.rpcClient.forPlugin(NotificationApi);
-      const action =
-        config.actionLabel && config.actionUrl
-          ? { label: config.actionLabel, url: config.actionUrl }
-          : undefined;
-      try {
-        const result = await notificationClient.sendTransactional({
+// ─── Action: notification.send ─────────────────────────────────────────
+
+/**
+ * Sends a transactional notification via `sendTransactional` through the run's
+ * `rpcClient` (the automation's `runAs` service account). Same strategy
+ * fan-out + per-attempt persistence + delivered/failed hook emission as a
+ * code-driven send. The service account must hold `notification.send`.
+ */
+export const notificationSendAction: ActionDefinition<
+  NotificationSendConfig,
+  NotificationSendArtifact
+> = {
+  id: "send",
+  displayName: "Send Notification",
+  description:
+    "Send a transactional notification to a specific user via all enabled strategies",
+  category: "Notifications",
+  icon: "BellRing",
+  config: new Versioned({
+    version: 1,
+    schema: notificationSendConfigSchema,
+  }),
+  produces: "notification.send_result",
+  execute: async ({ config, logger, rpcClient }) => {
+    const notificationClient = rpcClient.forPlugin(NotificationApi);
+    const action =
+      config.actionLabel && config.actionUrl
+        ? { label: config.actionLabel, url: config.actionUrl }
+        : undefined;
+    try {
+      const result = await notificationClient.sendTransactional({
+        userId: config.userId,
+        notification: {
+          title: config.title,
+          body: config.body,
+          importance: config.importance,
+          action,
+        },
+      });
+      logger.info(
+        `Automation sent notification to ${config.userId} (${result.deliveredCount} delivered)`,
+      );
+      return {
+        success: result.deliveredCount > 0,
+        // No single externalId — but recording the user keeps the
+        // run-detail UI useful when there are several send steps.
+        externalId: config.userId,
+        artifact: {
           userId: config.userId,
-          notification: {
-            title: config.title,
-            body: config.body,
-            importance: config.importance,
-            action,
-          },
-        });
-        logger.info(
-          `Automation sent notification to ${config.userId} (${result.deliveredCount} delivered)`,
-        );
-        return {
-          success: result.deliveredCount > 0,
-          // No single externalId — but recording the user keeps the
-          // run-detail UI useful when there are several send steps.
-          externalId: config.userId,
-          artifact: {
-            userId: config.userId,
-            deliveredCount: result.deliveredCount,
-            results: result.results,
-          },
-        };
-      } catch (error) {
-        const message = extractErrorMessage(error);
-        logger.error(`Notification send failed: ${message}`);
-        return { success: false, error: message };
-      }
-    },
-  };
-
-  return [sendAction as ActionDefinition<unknown, unknown>];
-}
+          deliveredCount: result.deliveredCount,
+          results: result.results,
+        },
+      };
+    } catch (error) {
+      const message = extractErrorMessage(error);
+      logger.error(`Notification send failed: ${message}`);
+      return { success: false, error: message };
+    }
+  },
+};
+
+export const notificationActions: ActionDefinition<unknown, unknown>[] = [
+  notificationSendAction as ActionDefinition<unknown, unknown>,
+];

package/src/index.ts

@@ -31,7 +31,7 @@ import {
   automationTriggerExtensionPoint,
 } from "@checkstack/automation-backend";
 import {
-  createNotificationActions,
+  notificationActions,
   notificationSendArtifactType,
   notificationTriggers,
 } from "./automations";
@@ -255,7 +255,6 @@ export default createBackendPlugin({
         logger,
         onHook,
         emitHook,
-        rpcClient,
       }) => {
         const db = database;
 
@@ -269,14 +268,14 @@ export default createBackendPlugin({
             emitHook(notificationHooks.failed, event),
         };
 
-        // Register automation actions now that `rpcClient` (= the
-        // service-mode caller for `sendTransactional`) is available
-        // and all other plugins have registered their access rules.
-        const automationActions = env.getExtensionPoint(
+        // Register automation actions. The send action calls
+        // `sendTransactional` through the run's `rpcClient` (the automation's
+        // `runAs` service account), so no client is captured here.
+        const automationActionsExt = env.getExtensionPoint(
           automationActionExtensionPoint,
         );
-        for (const action of createNotificationActions({ rpcClient })) {
-          automationActions.registerAction(action, pluginMetadata);
+        for (const action of notificationActions) {
+          automationActionsExt.registerAction(action, pluginMetadata);
         }
 
         // Log registered strategies

package/src/migration-chain-contract.test.ts

@@ -0,0 +1,37 @@
+/**
+ * Contract test: every notification Versioned config that this package
+ * registers MUST have a COMPLETE, contiguous migration chain from version 1 to
+ * its current `version`. Pure STRUCTURAL check (`validateMigrationChainFromV1`
+ * — no `migrate()` is run), so it carries zero per-config upkeep: the day
+ * someone bumps a config's `version` without shipping a covering migration,
+ * `parseAssumingV1` would silently fail at runtime on a genuinely-v1 stored
+ * blob — this test turns that into a CI failure instead. See the HTTP plugin's
+ * equivalent test for the full rationale.
+ *
+ * It enumerates the automation actions this package registers, so a new
+ * built-in action config is covered automatically.
+ *
+ * NOTE: notification strategies (and their `config` / `userConfig` /
+ * `layoutConfig` Versioned wrappers) are registered by the strategy plugins
+ * (e.g. notification-smtp-backend), NOT by this core package, so they are
+ * guarded by an equivalent contract test in their owning plugin package — the
+ * test lives where the registration lives to keep the dependency direction
+ * intact.
+ */
+import { describe, expect, it } from "bun:test";
+import { notificationActions } from "./automations";
+
+describe("notification config migration-chain contract", () => {
+  it("every registered action config has a complete v1->version chain", () => {
+    const actions = notificationActions;
+    expect(actions.length).toBeGreaterThan(0);
+
+    for (const action of actions) {
+      const problem = action.config.validateMigrationChainFromV1();
+      expect(
+        problem,
+        `Action "${action.id}" config (version ${action.config.version}) has a broken migration chain: ${problem}`,
+      ).toBeUndefined();
+    }
+  });
+});

package/src/resolve-user-config.test.ts

@@ -0,0 +1,112 @@
+import { describe, test, expect } from "bun:test";
+import { z } from "zod";
+import { Versioned } from "@checkstack/backend-api";
+import { resolveStrategyUserConfig } from "./resolve-user-config";
+
+/**
+ * The per-strategy `userConfig` is stored as a bare blob in the user-preference
+ * record and was previously handed to `send()` verbatim, skipping the
+ * strategy's own `userConfig` schema. `resolveStrategyUserConfig` closes that
+ * gap by treating the stored blob as a `version: 1` record and running it
+ * through `strategy.userConfig.parseAssumingV1` (migrate-then-validate).
+ */
+describe("resolveStrategyUserConfig", () => {
+  test("validates the stored blob against the strategy schema (strips stray keys)", async () => {
+    const userConfigSchema = new Versioned({
+      version: 1,
+      schema: z.object({ phoneNumber: z.string() }),
+    });
+
+    const result = await resolveStrategyUserConfig({
+      userConfigSchema,
+      storedUserConfig: {
+        phoneNumber: "+15551234567",
+        // Not part of the schema — must be stripped by validation.
+        legacy: "drop-me",
+      },
+    });
+
+    expect(result).toEqual({ phoneNumber: "+15551234567" });
+  });
+
+  test("applies schema defaults during validation", async () => {
+    const userConfigSchema = new Versioned({
+      version: 1,
+      schema: z.object({
+        phoneNumber: z.string(),
+        verbose: z.boolean().default(false),
+      }),
+    });
+
+    const result = await resolveStrategyUserConfig({
+      userConfigSchema,
+      storedUserConfig: { phoneNumber: "+1" },
+    });
+
+    expect(result).toEqual({ phoneNumber: "+1", verbose: false });
+  });
+
+  test("migrates a stored v1 blob forward via the strategy migration chain", async () => {
+    // A v2 schema that renamed `phone` -> `phoneNumber`. Stored data is the
+    // bare v1 shape; assume-v1 + migration must reshape it before validation.
+    const userConfigSchema = new Versioned({
+      version: 2,
+      schema: z.object({ phoneNumber: z.string() }),
+      migrations: [
+        {
+          fromVersion: 1,
+          toVersion: 2,
+          description: "rename phone -> phoneNumber",
+          migrate: (data: unknown) => {
+            const old = data as { phone?: string };
+            return { phoneNumber: old.phone ?? "" };
+          },
+        },
+      ],
+    });
+
+    const result = await resolveStrategyUserConfig({
+      userConfigSchema,
+      storedUserConfig: { phone: "+15550000000" },
+    });
+
+    expect(result).toEqual({ phoneNumber: "+15550000000" });
+  });
+
+  test("rejects a stored blob that fails validation", async () => {
+    const userConfigSchema = new Versioned({
+      version: 1,
+      schema: z.object({ phoneNumber: z.string() }),
+    });
+
+    await expect(
+      resolveStrategyUserConfig({
+        userConfigSchema,
+        storedUserConfig: { phoneNumber: 123 },
+      }),
+    ).rejects.toThrow();
+  });
+
+  test("returns undefined when the strategy declares no userConfig schema", async () => {
+    const result = await resolveStrategyUserConfig({
+      userConfigSchema: undefined,
+      storedUserConfig: { anything: true },
+    });
+
+    expect(result).toBeUndefined();
+  });
+
+  test("returns undefined when no userConfig was stored", async () => {
+    const userConfigSchema = new Versioned({
+      version: 1,
+      schema: z.object({ phoneNumber: z.string() }),
+    });
+
+    const result = await resolveStrategyUserConfig({
+      userConfigSchema,
+      storedUserConfig: undefined,
+    });
+
+    expect(result).toBeUndefined();
+  });
+});

package/src/resolve-user-config.ts

@@ -0,0 +1,34 @@
+import type { Versioned } from "@checkstack/backend-api";
+
+/**
+ * Migrate-then-validate a stored per-strategy `userConfig` blob against the
+ * strategy's own {@link Versioned} schema before it is handed to `send()`.
+ *
+ * The user-preference record stores `userConfig` as a bare object (see
+ * `UserPreferenceConfigSchema.userConfig`), so it is never validated against
+ * the strategy's `userConfig` schema on the read path. This helper closes that
+ * gap: the raw blob is treated as a `version: 1` record and run through
+ * `strategy.userConfig.parseAssumingV1`, which migrates it forward and
+ * validates it. The result is the value `send()` actually receives.
+ *
+ * Returns `undefined` when the strategy declares no `userConfig` schema or the
+ * user has not stored one yet, matching the previous pass-through behaviour.
+ */
+export async function resolveStrategyUserConfig({
+  userConfigSchema,
+  storedUserConfig,
+}: {
+  /** The strategy's own per-user config schema, if it declares one. */
+  userConfigSchema: Versioned<unknown> | undefined;
+  /** The raw `userConfig` blob read from the user-preference record. */
+  storedUserConfig: unknown;
+}): Promise<unknown> {
+  if (!userConfigSchema || storedUserConfig === undefined) {
+    return undefined;
+  }
+
+  // Stored userConfig blobs are unversioned today, so assume-v1: wrap as
+  // { version: 1, data } and run migrate-then-validate. The shared
+  // `parseAssumingV1` helper lives on `Versioned`.
+  return userConfigSchema.parseAssumingV1(storedUserConfig);
+}

package/src/router.ts

@@ -50,6 +50,7 @@ import {
   type StrategyService,
 } from "./strategy-service";
 import { dispatchWithAttempt } from "./delivery-attempts";
+import { resolveStrategyUserConfig } from "./resolve-user-config";
 import { extractErrorMessage } from "@checkstack/common";
 
 /**
@@ -282,6 +283,13 @@ export const createNotificationRouter = (
           type: "notification",
         };
 
+        // Migrate-then-validate the stored per-strategy userConfig against the
+        // strategy's own schema before handing it to send().
+        const userConfig = await resolveStrategyUserConfig({
+          userConfigSchema: strategy.userConfig,
+          storedUserConfig: pref?.userConfig,
+        });
+
         // Build send context
         const sendContext: NotificationSendContext<unknown, unknown, unknown> =
           {
@@ -293,7 +301,7 @@ export const createNotificationRouter = (
             contact,
             notification: payload,
             strategyConfig,
-            userConfig: pref?.userConfig,
+            userConfig,
             layoutConfig,
             logger,
           };
@@ -1014,11 +1022,6 @@ export const createNotificationRouter = (
     notifyForSubscription: os.notifyForSubscription.handler(
       async ({ input, context }) => {
         const caller = context.user as { type: string; pluginId?: string };
-        if (caller.type !== "service" || !caller.pluginId) {
-          throw new ORPCError("FORBIDDEN", {
-            message: "notifyForSubscription is only callable from a service",
-          });
-        }
 
         const [spec] = await database
           .select()
@@ -1030,9 +1033,19 @@ export const createNotificationRouter = (
             message: `Subscription spec ${input.specId} is not registered`,
           });
         }
-        if (spec.ownerPlugin !== caller.pluginId) {
+        // Authorization:
+        // - SERVICE callers are trusted but may dispatch ONLY under their own
+        //   spec (a plugin cannot notify under another plugin's spec).
+        // - USER / APPLICATION callers (e.g. an automation's `runAs` service
+        //   account) are authorized by the `notification.send` access rule,
+        //   enforced by autoAuthMiddleware before this handler runs; the
+        //   spec-ownership rule does not apply to them (they own no specs).
+        if (
+          caller.type === "service" &&
+          (!caller.pluginId || spec.ownerPlugin !== caller.pluginId)
+        ) {
           throw new ORPCError("FORBIDDEN", {
-            message: `Plugin ${caller.pluginId} cannot dispatch under spec ${input.specId} (owned by ${spec.ownerPlugin})`,
+            message: `Plugin ${caller.pluginId ?? "(unknown)"} cannot dispatch under spec ${input.specId} (owned by ${spec.ownerPlugin})`,
           });
         }
 
@@ -1265,6 +1278,13 @@ export const createNotificationRouter = (
           type: "transactional",
         };
 
+        // Migrate-then-validate the stored per-strategy userConfig against the
+        // strategy's own schema before handing it to send().
+        const userConfig = await resolveStrategyUserConfig({
+          userConfigSchema: strategy.userConfig,
+          storedUserConfig: userPref?.userConfig,
+        });
+
         // Build send context
         const sendContext: NotificationSendContext<unknown, unknown, unknown> =
           {
@@ -1276,7 +1296,7 @@ export const createNotificationRouter = (
             contact,
             notification: payload,
             strategyConfig,
-            userConfig: userPref?.userConfig,
+            userConfig,
             layoutConfig,
             logger,
           };
@@ -1666,6 +1686,13 @@ export const createNotificationRouter = (
           }
         }
 
+        // Migrate-then-validate the stored per-strategy userConfig against the
+        // strategy's own schema before handing it to send().
+        const userConfig = await resolveStrategyUserConfig({
+          userConfigSchema: strategy.userConfig,
+          storedUserConfig: pref?.userConfig,
+        });
+
         // Build send context
         const sendContext: NotificationSendContext<unknown, unknown, unknown> =
           {
@@ -1677,7 +1704,7 @@ export const createNotificationRouter = (
             contact,
             notification: testNotification,
             strategyConfig,
-            userConfig: pref?.userConfig,
+            userConfig,
             layoutConfig,
             logger,
           };

package/src/strategy-service.ts

@@ -10,6 +10,7 @@ import {
   configBoolean,
   configString,
   type ConfigService,
+  type Migration,
 } from "@checkstack/backend-api";
 import type { SafeDatabase } from "@checkstack/backend-api";
 import type { NotificationStrategyRegistry } from "@checkstack/backend-api";
@@ -58,6 +59,15 @@ export type UserPreferenceConfig = z.infer<typeof UserPreferenceConfigSchema>;
 
 const USER_PREFERENCE_VERSION = 1;
 
+/**
+ * Migration chain for user-preference records. Empty today (`version: 1`), but
+ * threaded through every {@link ConfigService.get}/`getRedacted` read so a
+ * future reshape only needs to append a step here instead of touching every
+ * call site. Omitting the argument would silently drop the migrate-then-validate
+ * capability and leave reads validate-only.
+ */
+const USER_PREFERENCE_MIGRATIONS: Migration<unknown, unknown>[] = [];
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Strategy Config Schema (admin settings)
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -73,6 +83,13 @@ export type StrategyMetaConfig = z.infer<typeof StrategyMetaConfigSchema>;
 
 const STRATEGY_META_VERSION = 1;
 
+/**
+ * Migration chain for strategy meta-config records. Empty today (`version: 1`),
+ * threaded through the read so future reshapes migrate-then-validate. See
+ * {@link USER_PREFERENCE_MIGRATIONS}.
+ */
+const STRATEGY_META_MIGRATIONS: Migration<unknown, unknown>[] = [];
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Service Interface
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -224,7 +241,8 @@ export function createStrategyService(
       const meta = await configService.get(
         strategyMetaId(strategyId),
         StrategyMetaConfigSchema,
-        STRATEGY_META_VERSION
+        STRATEGY_META_VERSION,
+        STRATEGY_META_MIGRATIONS
       );
       return meta ?? { enabled: false };
     },
@@ -346,7 +364,8 @@ export function createStrategyService(
       return configService.get(
         userPreferenceId(userId, strategyId),
         UserPreferenceConfigSchema,
-        USER_PREFERENCE_VERSION
+        USER_PREFERENCE_VERSION,
+        USER_PREFERENCE_MIGRATIONS
       );
     },
 
@@ -357,7 +376,8 @@ export function createStrategyService(
       return configService.getRedacted(
         userPreferenceId(userId, strategyId),
         UserPreferenceConfigSchema,
-        USER_PREFERENCE_VERSION
+        USER_PREFERENCE_VERSION,
+        USER_PREFERENCE_MIGRATIONS
       );
     },
 
@@ -402,7 +422,8 @@ export function createStrategyService(
         const pref = await configService.get(
           id,
           UserPreferenceConfigSchema,
-          USER_PREFERENCE_VERSION
+          USER_PREFERENCE_VERSION,
+          USER_PREFERENCE_MIGRATIONS
         );
         if (pref) {
           results.push({ strategyId, preference: pref });
@@ -433,7 +454,8 @@ export function createStrategyService(
         const pref = await configService.getRedacted(
           id,
           UserPreferenceConfigSchema,
-          USER_PREFERENCE_VERSION
+          USER_PREFERENCE_VERSION,
+          USER_PREFERENCE_MIGRATIONS
         );
         if (pref) {
           results.push({ strategyId, preference: pref });