@checkstack/backend 0.7.1 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,154 @@
 # @checkstack/backend
 
+## 0.8.1
+
+### Patch Changes
+
+- 2a749d3: fix: run afterPluginsReady in topological order; merge daily rollups on conflict
+
+  Two resilience fixes for the dependency chain:
+
+  1. **Plugin loader**: Phase 3 (`afterPluginsReady`) now iterates plugins
+     in the same topologically-sorted order as Phase 2 (`init`). Previously
+     it iterated `pendingInits` in registration order, which raced
+     subscription-spec dependencies — catalog's afterPluginsReady registers
+     `catalog.system` and `catalog.group` notification targets, and emitting
+     plugins (incident, maintenance, …) call `registerSubscriptionSpec`
+     against those targets in their own afterPluginsReady. With registration
+     order, an emitter could run before catalog and hit
+     `Target type catalog.group is not registered`. Sorted order encodes
+     the dependency via `spec.target.ownerPlugin`, so the emitter now
+     always runs after the target owner.
+
+  2. **Healthcheck retention job**: the daily rollup now upserts
+     `health_check_aggregates` with `ON CONFLICT DO UPDATE` instead of a
+     plain insert. Previously, late-arriving hourly aggregates (e.g. from
+     a satellite that was offline when the prior rollup ran) would crash
+     the rollup with a unique-constraint violation on
+     `(configuration_id, system_id, bucket_start, bucket_size, source_id)`.
+     The merge sums counts and folds min/max/p95 into the existing daily
+     row.
+
+## 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.1",
   "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);
@@ -494,7 +515,15 @@ export async function loadPlugins({
       );
     }
   }
-  for (const p of pendingInits) {
+  // Run afterPluginsReady in topologically-sorted order, matching Phase
+  // 2 init order. Iterating `pendingInits` directly would use registration
+  // order, which races dependency chains: e.g. catalog's
+  // afterPluginsReady registers `catalog.group` as a notification target,
+  // and emitting plugins' afterPluginsReady call `registerSubscriptionSpec`
+  // against it — so the emitters MUST run after catalog. Topo order
+  // already encodes this dependency (via spec.target.ownerPlugin).
+  for (const id of sortedIds) {
+    const p = pendingInits.find((x) => x.metadata.pluginId === id)!;
     if (p.afterPluginsReady) {
       try {
         const resolvedDeps: Record<string, unknown> = {};

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) => {