@checkstack/backend 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,125 @@
 # @checkstack/backend
 
+## 0.8.0
+
+### Minor Changes
+
+- 32d52c6: feat: notification target pattern + per-spec subscriptions
+
+  Replaces the all-or-nothing catalog system/group notification model with a
+  platform-level target pattern. Each notification-emitting plugin declares
+  _subscription specs_ against typed _target_ objects exported from the
+  target's owning plugin (catalog ships `catalogSystemTarget` and
+  `catalogGroupTarget`). Notification-backend handles every per-resource
+  group lifecycle, parent-edge inheritance, and legacy-subscription seeding
+  — plugins never author groupId helpers, lifecycle hooks, or migration
+  code again.
+
+  **Plugin-author surface area is now ~12 lines per emitter:**
+
+  ```ts
+  // <plugin>-common
+  const { defineSubscription } = createSubscriptionFactory(pluginMetadata);
+  export const fooSystemSubscription = defineSubscription({
+    localId: "system",
+    target: catalogSystemTarget,
+    display: { title: "Foo Alerts", description: "...", iconName: "Bell" },
+  });
+
+  // <plugin>-backend register()
+  env.registerSubscriptionSpecs([fooSystemSubscription]);
+  //   ^ feeds the plugin loader's dependency sorter — each spec's
+  //     target.ownerPlugin becomes an implicit init-order dep, so this
+  //     plugin automatically waits for catalog (the target owner) to
+  //     finish init + afterPluginsReady before its own runs.
+
+  // <plugin>-backend afterPluginsReady
+  await notificationClient.registerSubscriptionSpec(
+    specToRegistration(fooSystemSubscription)
+  );
+  // dispatch
+  await notificationClient.notifyForSubscription({
+    specId: fooSystemSubscription.specId,
+    resourceKeys: [systemId],
+    title,
+    body,
+    importance,
+    action,
+    collapseKey,
+    subjects,
+  });
+
+  // <plugin>-frontend
+  createNotificationSubscriptionExtension({ spec: fooSystemSubscription });
+  ```
+
+  **Migrated plugins**: anomaly, incident, maintenance, healthcheck,
+  dependency. Each lost its bespoke `notification-groups.ts`,
+  `bootstrap*NotificationGroups`, `ensure*Group`, and inheritance walk —
+  all of that is now centralized in notification-backend's
+  `subscription-engine`.
+
+  **Plugin loader change** (`@checkstack/backend-api`,
+  `@checkstack/backend`): the register-time API gains
+  `env.registerSubscriptionSpecs([...specs])`. The dependency sorter
+  walks `spec.target.ownerPlugin` for every declared spec and adds the
+  target owner as an init-order dependency of the emitting plugin. This
+  guarantees that catalog (the owner of the platform's `system` and
+  `group` targets) completes init + afterPluginsReady before any
+  emitting plugin tries to register its specs against the notification
+  service — no string-prefix heuristics, no manual `dependsOnPlugins`
+  list, no stub rows. Plugins that fail to declare their specs at
+  register time get a clear `Target type X is not registered. Did the
+emitting plugin declare this spec via env.registerSubscriptionSpecs?`
+  error from the dispatcher.
+
+  **Removed** (no backwards compat):
+
+  - `catalogClient.notifySystemSubscribers` and
+    `catalogClient.notifyManySystemSubscribers`
+  - `notificationClient.notifyUsers` and `notificationClient.notifyGroups`
+    as direct dispatch primitives — replaced by spec-bound
+    `notifyForSubscription`
+  - catalog's `bootstrapNotificationGroups` (replaced by
+    `bootstrapNotificationTargets`)
+
+  **Enforcement**: the dispatcher rejects calls referencing unregistered
+  specIds, specs owned by other plugins, or resourceKeys that haven't been
+  pushed via `upsertNotificationResource`. Display metadata for any
+  groupId is recoverable via the spec registry, so audit lists render
+  correct labels even when an emitter's frontend isn't loaded.
+
+  **Per-field anomaly mute** keeps working — it now lives inside the
+  generic SubscriptionRow's optional `SubControls` panel
+  (`AnomalyFieldMuteList`), exposed through the catalog system detail
+  page's notifications card.
+
+  The catalog system detail page renders a "Notifications" card hosting
+  `SystemNotificationSubscriptionsSlot`. The matching group surface is
+  not yet rendered — group-level subscriptions are wired end-to-end on
+  the backend; a follow-up will add the host UI.
+
+  **Migration of existing subscribers**: target types declare a
+  `legacyGroupIdTemplate`; on first registration of each spec,
+  notification-backend reads subscribers from the legacy
+  `catalog.system.<id>` / `catalog.group.<id>` groups and seeds the new
+  spec groups exactly once per (spec × resource) pair, tracked in
+  `subscription_migrations`. Anomaly stays opt-in (its target also
+  declares the template, but the user-explicit nature of the original
+  opt-in flow means the seeding produces the same set of subscribers
+  they already had).
+
+### Patch Changes
+
+- Updated dependencies [32d52c6]
+- Updated dependencies [32d52c6]
+- Updated dependencies [32d52c6]
+  - @checkstack/backend-api@0.14.0
+  - @checkstack/auth-common@0.6.4
+  - @checkstack/cache-api@0.2.2
+  - @checkstack/queue-api@0.2.16
+  - @checkstack/signal-backend@0.2.1
+
 ## 0.7.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "checkstack": {
     "type": "backend"
   },
@@ -15,13 +15,13 @@
   "dependencies": {
     "@checkstack/api-docs-common": "0.1.10",
     "@checkstack/auth-common": "0.6.3",
-    "@checkstack/backend-api": "0.13.0",
+    "@checkstack/backend-api": "0.13.1",
     "@checkstack/common": "0.7.0",
     "@checkstack/drizzle-helper": "0.0.4",
-    "@checkstack/cache-api": "0.2.0",
-    "@checkstack/queue-api": "0.2.14",
-    "@checkstack/signal-backend": "0.1.20",
-    "@checkstack/signal-common": "0.1.10",
+    "@checkstack/cache-api": "0.2.1",
+    "@checkstack/queue-api": "0.2.15",
+    "@checkstack/signal-backend": "0.2.0",
+    "@checkstack/signal-common": "0.2.0",
     "@hono/zod-validator": "^0.7.6",
     "@orpc/client": "^1.13.14",
     "@orpc/contract": "^1.13.14",
@@ -41,6 +41,7 @@
     "@types/bun": "latest",
     "@checkstack/tsconfig": "0.0.5",
     "@checkstack/scripts": "0.1.2",
-    "@checkstack/test-utils-backend": "0.1.20"
+    "@checkstack/test-utils-backend": "0.1.21",
+    "drizzle-kit": "^0.31.10"
   }
 }

package/src/plugin-manager/dependency-sorter.ts

@@ -14,6 +14,15 @@ export function sortPlugins({
   pendingInits: {
     metadata: PluginMetadata;
     deps: Record<string, ServiceRef<unknown>>;
+    /**
+     * Optional plugin-id-level dependencies. Each id adds an edge
+     * `dep -> consumer`, ensuring the consumer's init and
+     * afterPluginsReady run after the dep's. Used by the notification
+     * subscription pattern: emitter plugins automatically depend on
+     * the plugins that own the targets they emit subscriptions for,
+     * derived at register time from `spec.target.ownerPlugin`.
+     */
+    pluginDependencies?: Set<string>;
   }[];
   providedBy: Map<string, string>;
   logger: Logger;
@@ -59,6 +68,26 @@ export function sortPlugins({
       }
     }
 
+    // Plugin-id-level deps (currently sourced from declared
+    // notification subscription specs). Each entry forces the consumer
+    // to load after the named plugin even when there's no shared
+    // ServiceRef between them.
+    if (p.pluginDependencies) {
+      for (const depPluginId of p.pluginDependencies) {
+        if (depPluginId === consumerId) continue;
+        if (!graph.has(depPluginId)) {
+          // Dep plugin isn't loaded — skip silently. The runtime RPC
+          // layer (notification-backend) will produce a clearer error
+          // if the dep was actually required.
+          continue;
+        }
+        if (!graph.get(depPluginId)!.includes(consumerId)) {
+          graph.get(depPluginId)!.push(consumerId);
+          inDegree.set(consumerId, (inDegree.get(consumerId) || 0) + 1);
+        }
+      }
+    }
+
     // Special handling: if this plugin uses queueManager, it must wait for all queue plugin providers
     const usesQueueManager = Object.values(p.deps).some(
       (ref) => ref.id === coreServices.queueManager.id

package/src/plugin-manager/plugin-loader.ts

@@ -88,6 +88,13 @@ export function registerPlugin({
   // Store metadata for request-time context injection
   deps.pluginMetadataRegistry.set(pluginId, backendPlugin.metadata);
 
+  // Plugin dependencies derived from declared subscription specs.
+  // Populated by `registerSubscriptionSpecs` below; attached to the
+  // PendingInit when registerInit fires (a plugin's register block
+  // calls registerInit at most once, so timing is deterministic
+  // regardless of registration order within register()).
+  const pluginDependencies = new Set<string>();
+
   // Execute Register
   backendPlugin.register({
     registerInit: <
@@ -108,8 +115,22 @@ export function registerPlugin({
         init: args.init as InitCallback,
         afterPluginsReady: args.afterPluginsReady as InitCallback | undefined,
         schema: args.schema,
+        pluginDependencies,
       });
     },
+    registerSubscriptionSpecs: (specs) => {
+      for (const spec of specs) {
+        if (spec.ownerPlugin !== pluginId) {
+          throw new Error(
+            `Plugin ${pluginId} declared a subscription spec it does not own (ownerPlugin=${spec.ownerPlugin})`,
+          );
+        }
+        const targetOwner = spec.target.ownerPlugin;
+        if (targetOwner && targetOwner !== pluginId) {
+          pluginDependencies.add(targetOwner);
+        }
+      }
+    },
     registerService: (ref: ServiceRef<unknown>, impl: unknown) => {
       deps.registry.register(ref, impl);
       providedBy.set(ref.id, pluginId);

package/src/plugin-manager/types.ts

@@ -11,4 +11,14 @@ export interface PendingInit {
   init: InitCallback;
   afterPluginsReady?: InitCallback;
   schema?: Record<string, unknown>;
+  /**
+   * Plugin ids this plugin must load *after*. Derived (not authored) —
+   * computed at register time from the owners of any notification
+   * subscription specs the plugin declared via
+   * `registerSubscriptionSpecs`. Each declared spec contributes its
+   * target's `ownerPlugin` to this set, so emitter plugins
+   * automatically wait for the target owner without anyone
+   * maintaining a manual dependency list.
+   */
+  pluginDependencies: Set<string>;
 }

package/src/plugin-manager.ts

@@ -423,6 +423,10 @@ export class PluginManager {
           handlers.push(cleanup);
           this.cleanupHandlers.set(metaPluginId, handlers);
         },
+        registerSubscriptionSpecs: () => {
+          // No-op in this single-plugin registration path; ordering
+          // only matters during full-system load (plugin-loader).
+        },
         getExtensionPoint: <T>(ref: ExtensionPoint<T>) =>
           this.extensionPointManager.getExtensionPoint(ref),
         registerRouter: (router: unknown, contract: AnyContractRouter) => {