@checkstack/anomaly-backend 1.0.2 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,221 @@
 # @checkstack/anomaly-backend
 
+## 1.1.0
+
+### Minor Changes
+
+- 42abfff: Remove global anomaly settings — configuration is now field-only.
+
+  `AnomalySettings` (template- and assignment-level) no longer carries
+  `sensitivity`, `confirmationWindow`, `driftEnabled`, or `driftThreshold`.
+  These were duplicating the per-field configuration path with awkward
+  cascade semantics, and a single global multiplier was meaningless across
+  fields with different units (ms, %, counts).
+
+  The schema retains only the truly global concerns:
+
+  - `enabled` — master kill switch for the assignment
+  - `baselineWindow` — there is one history per system, not per field
+  - `notify` — one notification preference per assignment
+  - `fieldOverrides` — per-field configuration (where everything else now lives)
+
+  `resolveEffectiveConfig` collapses to two layers: field override → schema
+  default → engine fallback constant. The plugin-author defaults set via
+  `x-anomaly-*` annotations now drive sensitivity/window/drift across the
+  detector and drift evaluator (previously only floors were threaded
+  through the schema layer).
+
+  **Breaking changes:**
+
+  - Any global `sensitivity`/`confirmationWindow`/`driftEnabled`/
+    `driftThreshold` values previously stored in `anomaly_configurations`
+    or `anomaly_assignments` are silently stripped on parse. Users who
+    customized these globals will revert to the plugin's tuned per-field
+    defaults; if they want to keep those values they must re-apply them
+    per field in the new UI.
+  - `AnomalySettingsForm` no longer renders the global sliders. The form
+    now shows: enable toggle, baseline window selector, notify toggle,
+    field overrides editor.
+  - `AnomalyFieldOverridesEditor` props `defaultSensitivity`,
+    `defaultConfirmationWindow`, `defaultDriftEnabled`, `defaultDriftThreshold`
+    are removed. Engine fallbacks (1.0, 3, true, 2) are now hard-coded
+    internal constants used only when neither field override nor schema
+    default is set.
+  - The GitOps `System.anomaly` entry schema (in `anomaly-gitops-kinds`)
+    drops `sensitivity`, `confirmationWindow`, `driftEnabled`, and
+    `driftThreshold` to match the new `AnomalySettings` shape. YAML files
+    declaring those fields will be rejected at parse time — operators
+    must move per-field tuning into `fieldOverrides`.
+
+  This change makes the override model trivial to explain ("plugin defaults,
+  overridden per field") and removes a class of confusing "where did this
+  threshold come from?" questions.
+
+- 42abfff: Add practical-significance floors to anomaly detection.
+
+  Two new schema annotations — `x-anomaly-min-absolute-delta` and `x-anomaly-min-relative-delta` — let plugin authors and operators suppress alerts whose statistical deviation is large but practical impact is negligible. Both floors must clear in addition to the existing μ ± Nσ trigger; defaults are 0 (disabled) so existing behaviour is unchanged.
+
+  This is the fix for cases like a 6 ms latency baseline whose σ ≈ 1 ms causes routine 20 ms blips to fire as anomalies despite Δ=14 ms being operationally irrelevant. With `min-absolute-delta: 50` and `min-relative-delta: 0.5`, those blips stay silent while a 6 ms → 200 ms spike still fires.
+
+  Built-in plugins ship with sensible defaults applied to every per-run field: 50 ms + 50 % for ms-unit fields, 5 percentage points for `%`-unit fields, 1 + 25 % for counter fields, 1 GB + 5 % for disk fields, 50 MB + 10 % for memory fields, 1 day for TLS expiry, 0.5 + 25 % for load average, 1 + 5 % for Minecraft TPS. Operators can override per-system or per-field via the assignment UI.
+
+- f6f9a5c: Add GitOps extensions for declarative anomaly configuration.
+
+  Two extensions are now registered against the kind registry:
+
+  - `Healthcheck.anomaly` — accepts the full `AnomalySettings` shape and
+    applies it to the healthcheck's anomaly template via
+    `updateAnomalyConfig` on reconcile.
+  - `System.anomaly` — accepts an array of per-healthcheck overrides,
+    each scoped via `healthcheckRef: { kind: Healthcheck, name: ... }`,
+    and applies them with `updateAnomalyAssignmentConfig`. The
+    healthcheck reference is the GitOps source of truth; UI edits to
+    managed entries are blocked by the existing assignment-level lock.
+
+  Spec schema documentation for `Healthcheck.anomaly.fieldOverrides` is
+  registered **per collector field**, conditioned on the selected
+  `collectors[].config` variant — same pattern the `collectors[].assertions`
+  docs use, so the kind-registry browser pre-populates the available
+  result fields once a collector is chosen. The System extension's
+  `fieldOverrides` falls back to a generic variant since the relevant
+  collector lives on the referenced Healthcheck rather than a sibling.
+
+### Patch Changes
+
+- Updated dependencies [42abfff]
+- Updated dependencies [42abfff]
+- Updated dependencies [f6f9a5c]
+- Updated dependencies [1ef2e79]
+- Updated dependencies [aa89bc5]
+  - @checkstack/anomaly-common@1.1.0
+  - @checkstack/common@0.9.0
+  - @checkstack/gitops-common@0.3.0
+  - @checkstack/gitops-backend@0.3.0
+  - @checkstack/catalog-common@2.1.0
+  - @checkstack/catalog-backend@1.1.0
+  - @checkstack/queue-api@0.3.0
+  - @checkstack/cache-api@0.3.0
+  - @checkstack/backend-api@0.15.1
+  - @checkstack/healthcheck-backend@1.0.4
+  - @checkstack/healthcheck-common@1.0.2
+  - @checkstack/notification-common@1.0.2
+  - @checkstack/signal-common@0.2.2
+  - @checkstack/cache-utils@0.2.5
+
+## 1.0.3
+
+### Patch Changes
+
+- 50e5f5f: Runtime plugin system: install + uninstall plugins from npm, GitHub releases
+  (including private GitHub Enterprise instances), or tarball uploads at
+  runtime, with multi-package bundles, dependency-derived compatibility checks,
+  multi-instance coordination via a Postgres artifact store, and
+  single-coordinator destructive cleanup.
+
+  Highlights:
+
+  - New `PluginSource` discriminated union and `PluginInstaller` /
+    `PluginInstallerRegistry` interfaces in `@checkstack/backend-api`. The
+    GitHub variant accepts an optional `apiBaseUrl` so deployments backed by
+    GitHub Enterprise can install from `https://ghe.example.com/api/v3`
+    instead of `api.github.com`.
+  - New `installPackageMetadataSchema` (Zod) in `@checkstack/common` validates
+    every plugin's `package.json` at install time. Required fields: `name`,
+    `version`, `description`, `author`, `license`, `checkstack.type`,
+    `checkstack.pluginId`. Optional: `checkstack.bundle`,
+    `checkstack.usageInstructions`, `checkstack.allowInstallScripts`.
+  - New `pluginManagerContract` in `@checkstack/pluginmanager-common` with
+    `list`, `previewInstall`, `install`, `previewUninstall`, `uninstall`, and
+    `events` procedures.
+  - New `@checkstack/pluginmanager-frontend` admin UI: installed-plugins list
+    with per-row uninstall (typed-confirmation modal, schema/configs/cascade
+    toggles), install page with NPM / Tarball Upload / GitHub Release tabs
+    (Catalog tab disabled — coming soon), and an events page surfacing the
+    install/uninstall audit log.
+  - New `bunx @checkstack/scripts plugin-pack` CLI for plugin authors —
+    per-package mode produces an npm-shaped tarball; `--bundle` mode produces
+    an outer tarball containing every sibling declared in
+    `package.json#checkstack.bundle`. Published to npm so external authors
+    can `bunx` it directly without a workspace checkout.
+  - Compatibility derived from `package.json#dependencies` ranges
+    (`semver.satisfies` against the platform's loaded `@checkstack/*`
+    versions) — no separate `compatibility` field.
+  - Multi-instance: originator persists artifacts + `plugins` rows + broadcasts
+    install/uninstall; receiving instances do in-process register/unregister
+    only. Destructive ops (drop schema, delete plugin_configs, delete
+    artifacts, delete `plugins` rows) run exactly once on the originator.
+  - Fresh-instance bootstrap: `loadPlugins()` hydrates any
+    `is_uninstallable=true` plugin missing from `node_modules` from the
+    artifact store before normal Phase 1 register.
+  - New schema: `plugin_artifacts` (tarball storage), `plugin_install_events`
+    (audit/error log). `plugins` extended with `version`, `metadata`,
+    `source`, `bundle_id`, `is_primary`. Local plugin sync now writes
+    `version` from each plugin's `package.json` so the admin UI shows real
+    versions instead of `—`.
+  - Tarball-upload endpoint (`POST /api/pluginmanager/upload-tarball`) for
+    the install UI; access-gated by `pluginmanager.plugin.manage`.
+  - Plugin Manager menu link added to the user menu (main grid, alongside
+    Profile / Notification Settings / etc.).
+
+  Cross-cutting changes:
+
+  - Backend request/response logging now flows through `rootLogger` (winston)
+    instead of `hono/logger`. 5xx responses include the response body inline
+    so swallowed early-return errors are visible in the log.
+  - The `/api/:pluginId/*` dispatcher now logs which core service is missing
+    or which `pluginId` had no metadata when it 500s.
+  - New `registerCorePluginMetadata` on `PluginManager` for core routers
+    (like the plugin manager itself) that need their metadata visible to the
+    RPC dispatcher without going through the full plugin lifecycle.
+  - ESLint: `unicorn/no-null` is now disabled globally. Drizzle distinguishes
+    between `null` (writes a real SQL NULL) and `undefined` (skip the column
+    on insert), so treating them as interchangeable produced latent bugs at
+    the persistence boundary. The bulk of the patch-bumped packages above
+    reflect lint-fix touches that landed when this rule was relaxed.
+  - Workspace-wide license normalization to `Elastic-2.0` (matches
+    `LICENSE.md`). Every `package.json` in the workspace now declares the
+    same SPDX identifier; the patch bumps capture this.
+
+  Plugin packages (every `plugins/*`): added a `pack` npm script
+  (`bunx @checkstack/scripts plugin-pack`), mirrored each plugin's
+  `pluginId` from `plugin-metadata.ts` into `package.json#checkstack.pluginId`
+  so install-time validation passes, stubbed any missing required metadata
+  fields (`description`, `author`, `license`), and added
+  `checkstack.bundle` to multi-package plugin primaries (telegram, rcon, ssh,
+  jira, queue-bullmq, queue-memory, cache-memory).
+
+  Breaking changes:
+
+  - The legacy single-method `PluginInstaller` interface (`install(packageName)`)
+    is removed. Callers must use `coreServices.pluginInstallerRegistry`.
+  - The old `pluginAdminContract` and `createPluginAdminRouter` are removed.
+    Replaced by `pluginManagerContract` in `@checkstack/pluginmanager-common`
+    and `createPluginManagerRouter` in `core/backend`.
+  - `@checkstack/test-utils-backend` no longer exports
+    `createMockPluginInstaller` / `MockPluginInstaller` (the legacy interface
+    it shimmed is gone).
+
+  Note: bumps are limited to `minor` (for packages with new public API
+  surface) and `patch` (for downstream consumers, license normalization,
+  and lint fixes). No `major` bumps despite the `PluginInstaller` removal —
+  the legacy interface had no third-party consumers in the wild before this
+  runtime plugin system landed, and the contract surface is the same shape
+  modulo the rename.
+
+- Updated dependencies [50e5f5f]
+  - @checkstack/backend-api@0.15.0
+  - @checkstack/catalog-backend@1.0.2
+  - @checkstack/catalog-common@2.0.1
+  - @checkstack/common@0.8.0
+  - @checkstack/healthcheck-backend@1.0.3
+  - @checkstack/queue-api@0.2.18
+  - @checkstack/anomaly-common@1.0.1
+  - @checkstack/cache-api@0.2.4
+  - @checkstack/cache-utils@0.2.4
+  - @checkstack/healthcheck-common@1.0.1
+  - @checkstack/notification-common@1.0.1
+  - @checkstack/signal-common@0.2.1
+
 ## 1.0.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@checkstack/anomaly-backend",
-  "version": "1.0.2",
+  "version": "1.1.0",
+  "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -13,28 +14,30 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.14.0",
-    "@checkstack/common": "0.7.0",
-    "@checkstack/anomaly-common": "1.0.0",
-    "@checkstack/signal-common": "0.2.0",
-    "@checkstack/healthcheck-common": "1.0.0",
-    "@checkstack/queue-api": "0.2.16",
-    "@checkstack/cache-api": "0.2.2",
-    "@checkstack/cache-utils": "0.2.2",
-    "@checkstack/healthcheck-backend": "1.0.1",
-    "@checkstack/catalog-backend": "1.0.0",
-    "@checkstack/catalog-common": "2.0.0",
-    "@checkstack/notification-common": "1.0.0",
+    "@checkstack/backend-api": "0.15.0",
+    "@checkstack/common": "0.8.0",
+    "@checkstack/anomaly-common": "1.0.1",
+    "@checkstack/signal-common": "0.2.1",
+    "@checkstack/healthcheck-common": "1.0.1",
+    "@checkstack/queue-api": "0.2.18",
+    "@checkstack/cache-api": "0.2.4",
+    "@checkstack/cache-utils": "0.2.4",
+    "@checkstack/healthcheck-backend": "1.0.3",
+    "@checkstack/catalog-backend": "1.0.2",
+    "@checkstack/gitops-backend": "0.2.8",
+    "@checkstack/gitops-common": "0.2.2",
+    "@checkstack/catalog-common": "2.0.1",
+    "@checkstack/notification-common": "1.0.1",
     "drizzle-orm": "^0.45.0",
     "hono": "^4.12.14",
     "zod": "^4.2.1",
     "@orpc/server": "^1.13.2"
   },
   "devDependencies": {
-    "@checkstack/drizzle-helper": "0.0.4",
-    "@checkstack/scripts": "0.1.2",
-    "@checkstack/test-utils-backend": "0.1.22",
-    "@checkstack/tsconfig": "0.0.5",
+    "@checkstack/drizzle-helper": "0.0.5",
+    "@checkstack/scripts": "0.3.0",
+    "@checkstack/test-utils-backend": "0.1.24",
+    "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.0.0",
     "date-fns": "^4.1.0",
     "drizzle-kit": "^0.31.10",

package/src/anomaly-gitops-kinds.test.ts

@@ -0,0 +1,189 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import type { ReconcileContext } from "@checkstack/gitops-common";
+import type { AnomalyService } from "./service";
+import {
+  buildHealthcheckAnomalyExtension,
+  buildSystemAnomalyExtension,
+} from "./anomaly-gitops-kinds";
+
+/**
+ * Reconcile-time tests for the anomaly-backend GitOps kind extensions.
+ *
+ * Exercises the `Healthcheck.anomaly` and `System.anomalyExceptions`
+ * extensions in isolation against a stub AnomalyService.
+ */
+
+const noopLogger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};
+
+const buildContext = (
+  overrides: Partial<ReconcileContext> = {},
+): ReconcileContext =>
+  ({
+    logger: noopLogger,
+    resolveEntityRef: async () => undefined,
+    resolveSecretsBySchema: async ({ value }) => ({
+      resolved: value,
+      warnings: [],
+    }),
+    ...overrides,
+  }) as ReconcileContext;
+
+const stubService = () => {
+  const updateAnomalyConfig = mock(async () => ({}));
+  const updateAnomalyAssignmentConfig = mock(async () => ({}));
+  return {
+    updateAnomalyConfig,
+    updateAnomalyAssignmentConfig,
+    service: {
+      updateAnomalyConfig,
+      updateAnomalyAssignmentConfig,
+    } as unknown as AnomalyService,
+  };
+};
+
+describe("buildHealthcheckAnomalyExtension", () => {
+  let stub: ReturnType<typeof stubService>;
+  let extension: ReturnType<typeof buildHealthcheckAnomalyExtension>;
+
+  beforeEach(() => {
+    stub = stubService();
+    extension = buildHealthcheckAnomalyExtension({
+      getService: () => stub.service,
+    });
+  });
+
+  it("registers under the right kind/namespace", () => {
+    expect(extension.kind).toBe("Healthcheck");
+    expect(extension.namespace).toBe("anomaly");
+  });
+
+  it("calls updateAnomalyConfig with the spec when present", async () => {
+    await extension.reconcile({
+      entity: {} as never,
+      extensionSpec: {
+        enabled: false,
+        baselineWindow: "14d",
+        notify: false,
+      },
+      entityId: "hc-1",
+      context: buildContext(),
+    });
+    expect(stub.updateAnomalyConfig).toHaveBeenCalledTimes(1);
+    expect(stub.updateAnomalyConfig).toHaveBeenCalledWith("hc-1", {
+      enabled: false,
+      baselineWindow: "14d",
+      notify: false,
+    });
+  });
+
+  it("is a no-op when extensionSpec is undefined", async () => {
+    await extension.reconcile({
+      entity: {} as never,
+      extensionSpec: undefined,
+      entityId: "hc-1",
+      context: buildContext(),
+    });
+    expect(stub.updateAnomalyConfig).not.toHaveBeenCalled();
+  });
+});
+
+describe("buildSystemAnomalyExtension", () => {
+  let stub: ReturnType<typeof stubService>;
+  let extension: ReturnType<typeof buildSystemAnomalyExtension>;
+
+  beforeEach(() => {
+    stub = stubService();
+    extension = buildSystemAnomalyExtension({
+      getService: () => stub.service,
+    });
+  });
+
+  it("registers on the System kind under namespace 'anomaly'", () => {
+    expect(extension.kind).toBe("System");
+    expect(extension.namespace).toBe("anomaly");
+  });
+
+  it("resolves each healthcheckRef and writes assignment overrides", async () => {
+    const refMap: Record<string, string> = {
+      "hc-cpu": "cfg-cpu",
+      "hc-mem": "cfg-mem",
+    };
+
+    await extension.reconcile({
+      entity: {} as never,
+      extensionSpec: [
+        {
+          healthcheckRef: { kind: "Healthcheck", name: "hc-cpu" },
+          enabled: false,
+          fieldOverrides: {
+            "cpu.usage": { sensitivity: 0.5 },
+          },
+        },
+        {
+          healthcheckRef: { kind: "Healthcheck", name: "hc-mem" },
+          baselineWindow: "30d",
+        },
+      ],
+      entityId: "sys-1",
+      context: buildContext({
+        resolveEntityRef: async ({ entityName }) => refMap[entityName],
+      }),
+    });
+
+    expect(stub.updateAnomalyAssignmentConfig).toHaveBeenCalledTimes(2);
+    expect(stub.updateAnomalyAssignmentConfig).toHaveBeenNthCalledWith(
+      1,
+      "sys-1",
+      "cfg-cpu",
+      {
+        enabled: false,
+        fieldOverrides: { "cpu.usage": { sensitivity: 0.5 } },
+      },
+    );
+    expect(stub.updateAnomalyAssignmentConfig).toHaveBeenNthCalledWith(
+      2,
+      "sys-1",
+      "cfg-mem",
+      { baselineWindow: "30d" },
+    );
+  });
+
+  it("throws when a healthcheck ref cannot be resolved", async () => {
+    await expect(
+      extension.reconcile({
+        entity: {} as never,
+        extensionSpec: [
+          {
+            healthcheckRef: { kind: "Healthcheck", name: "missing" },
+            enabled: false,
+          },
+        ],
+        entityId: "sys-1",
+        context: buildContext({
+          resolveEntityRef: async () => undefined,
+        }),
+      }),
+    ).rejects.toThrow(/Cannot resolve Healthcheck ref "missing"/);
+  });
+
+  it("is a no-op for empty/undefined specs", async () => {
+    await extension.reconcile({
+      entity: {} as never,
+      extensionSpec: [],
+      entityId: "sys-1",
+      context: buildContext(),
+    });
+    await extension.reconcile({
+      entity: {} as never,
+      extensionSpec: undefined,
+      entityId: "sys-1",
+      context: buildContext(),
+    });
+    expect(stub.updateAnomalyAssignmentConfig).not.toHaveBeenCalled();
+  });
+});

package/src/anomaly-gitops-kinds.ts

@@ -0,0 +1,234 @@
+import { z } from "zod";
+import {
+  CHECKSTACK_API_VERSION,
+  type EntityKindExtensionDefinition,
+  type EntityKindRegistry,
+  type ReconcileContext,
+} from "@checkstack/gitops-common";
+import {
+  AnomalySettingsSchema,
+  AnomalyFieldConfigSchema,
+} from "@checkstack/anomaly-common";
+import type { CollectorRegistry } from "@checkstack/backend-api";
+import type { AnomalyService } from "./service";
+
+interface AnomalyGitOpsKindsDeps {
+  /**
+   * Lazy accessor — populated during init(), invoked at reconcile time.
+   * Mirrors the pattern healthcheck-backend uses to expose its service to
+   * the GitOps reconciler without bleeding init order into kind registration.
+   */
+  getService: () => AnomalyService;
+}
+
+// ─── Shared schemas ─────────────────────────────────────────────────────────
+
+/**
+ * A reference to a Healthcheck entity. Constrained so YAML callers can't
+ * accidentally point an anomaly override at a non-Healthcheck kind.
+ */
+const healthcheckRefSchema = z
+  .object({
+    kind: z.literal("Healthcheck"),
+    name: z.string().min(1),
+  })
+  .describe("Reference to the Healthcheck this anomaly override applies to.");
+
+// ─── Healthcheck → anomaly extension ────────────────────────────────────────
+//
+// Declares the *template-level* AnomalySettings for a Healthcheck. GitOps is
+// the source of truth, so the entire AnomalySettings record is replaced.
+
+const healthcheckAnomalyExtensionSchema = AnomalySettingsSchema.optional();
+type HealthcheckAnomalyExtension = z.infer<
+  typeof healthcheckAnomalyExtensionSchema
+>;
+
+export function buildHealthcheckAnomalyExtension(
+  deps: AnomalyGitOpsKindsDeps,
+): EntityKindExtensionDefinition<HealthcheckAnomalyExtension> {
+  return {
+    apiVersion: CHECKSTACK_API_VERSION,
+    kind: "Healthcheck",
+    namespace: "anomaly",
+    specSchema: healthcheckAnomalyExtensionSchema,
+
+    reconcile: async ({
+      extensionSpec,
+      entityId,
+      context,
+    }: {
+      extensionSpec: HealthcheckAnomalyExtension;
+      entityId: string;
+      context: ReconcileContext;
+    }) => {
+      if (!extensionSpec) return;
+      await deps.getService().updateAnomalyConfig(entityId, extensionSpec);
+      context.logger.info(
+        `GitOps: applied anomaly defaults to Healthcheck (id: ${entityId})`,
+      );
+    },
+  };
+}
+
+// ─── System → anomaly extension ─────────────────────────────────────────────
+//
+// Declares per-assignment AnomalySettings overrides ("exceptions"), keyed by
+// healthcheck ref. Lives under namespace `anomaly` on the System kind so the
+// YAML naming mirrors the Healthcheck.anomaly extension.
+
+const systemAnomalyEntrySchema = z.object({
+  healthcheckRef: healthcheckRefSchema,
+  enabled: z.boolean().optional(),
+  baselineWindow: z.string().optional(),
+  notify: z.boolean().optional(),
+  fieldOverrides: z.record(z.string(), AnomalyFieldConfigSchema).optional(),
+});
+
+const systemAnomalyExtensionSchema = z.array(systemAnomalyEntrySchema).optional();
+
+type SystemAnomalyExtension = z.infer<typeof systemAnomalyExtensionSchema>;
+
+export function buildSystemAnomalyExtension(
+  deps: AnomalyGitOpsKindsDeps,
+): EntityKindExtensionDefinition<SystemAnomalyExtension> {
+  return {
+    apiVersion: CHECKSTACK_API_VERSION,
+    kind: "System",
+    namespace: "anomaly",
+    specSchema: systemAnomalyExtensionSchema,
+
+    reconcile: async ({
+      extensionSpec,
+      entityId,
+      context,
+    }: {
+      extensionSpec: SystemAnomalyExtension;
+      entityId: string;
+      context: ReconcileContext;
+    }) => {
+      if (!extensionSpec || extensionSpec.length === 0) return;
+
+      const service = deps.getService();
+      const systemId = entityId;
+
+      for (const entry of extensionSpec) {
+        const configurationId = await context.resolveEntityRef({
+          kind: entry.healthcheckRef.kind,
+          entityName: entry.healthcheckRef.name,
+        });
+        if (!configurationId) {
+          throw new Error(
+            `Cannot resolve Healthcheck ref "${entry.healthcheckRef.name}" — anomaly overrides require the healthcheck to exist`,
+          );
+        }
+
+        const { healthcheckRef: _ref, ...overrides } = entry;
+        void _ref;
+
+        await service.updateAnomalyAssignmentConfig(
+          systemId,
+          configurationId,
+          overrides,
+        );
+
+        context.logger.info(
+          `GitOps: applied anomaly overrides for Healthcheck "${entry.healthcheckRef.name}" on System (id: ${systemId})`,
+        );
+      }
+    },
+  };
+}
+
+// ─── Documentation ──────────────────────────────────────────────────────────
+
+/**
+ * Mirrors the unwrap helper in healthcheck-gitops-kinds — peels Optional /
+ * Nullable / Default wrappers so we can introspect a collector's result
+ * shape and enumerate its field names.
+ */
+function unwrapZodType(type: z.ZodTypeAny): z.ZodTypeAny {
+  let current = type;
+  while (current) {
+    if (current instanceof z.ZodOptional || current instanceof z.ZodNullable) {
+      current = current.unwrap() as z.ZodTypeAny;
+    } else if (current instanceof z.ZodDefault) {
+      current = current._def.innerType as z.ZodTypeAny;
+    } else if ("innerType" in current && typeof current.innerType === "function") {
+      current = current.innerType() as z.ZodTypeAny;
+    } else {
+      break;
+    }
+  }
+  return current;
+}
+
+/**
+ * Register schema documentation for the anomaly extensions. Called from
+ * anomaly-backend's `afterPluginsReady` once the kind registry and the
+ * collector registry have been populated.
+ *
+ * The Healthcheck.anomaly.fieldOverrides documentation is registered
+ * **per collector field**: each variant is gated on the matching
+ * collectors[].config selection so the kind-registry browser can pre-populate
+ * the available result fields once the user picks a collector.
+ *
+ * The System.anomaly[].fieldOverrides path can't be conditioned on a sibling
+ * config (the collector lives on the referenced Healthcheck, not on the
+ * System spec), so it falls back to a generic AnomalyFieldConfig variant.
+ */
+export function registerAnomalyGitOpsDocumentation({
+  kindRegistry,
+  collectorRegistry,
+}: {
+  kindRegistry: EntityKindRegistry;
+  collectorRegistry: CollectorRegistry;
+}): void {
+  // Per-collector, per-field variants conditioned on the chosen collector.
+  for (const registered of collectorRegistry.getCollectors()) {
+    const unwrapped = unwrapZodType(registered.collector.result.schema);
+    if (!(unwrapped instanceof z.ZodObject)) continue;
+
+    for (const fieldName of Object.keys(unwrapped.shape)) {
+      kindRegistry.registerSpecSchemaDocumentation({
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Healthcheck",
+        fieldPath: "anomaly.fieldOverrides",
+        variantId: `${registered.qualifiedId}.field.${fieldName}`,
+        label: `Field: ${fieldName}`,
+        description: `Anomaly engine override for the "${fieldName}" result field of ${registered.collector.displayName}. The map key is "${fieldName}".`,
+        schema: AnomalyFieldConfigSchema,
+        conditions: [
+          {
+            fieldPath: "collectors[].config",
+            variantIds: [registered.qualifiedId],
+          },
+        ],
+      });
+    }
+  }
+
+  // Generic fallback for the System extension — the relevant collector lives
+  // on the referenced Healthcheck, so we can't gate on a sibling.
+  kindRegistry.registerSpecSchemaDocumentation({
+    apiVersion: CHECKSTACK_API_VERSION,
+    kind: "System",
+    fieldPath: "anomaly[].fieldOverrides",
+    label: "Anomaly field override",
+    description:
+      "Per-result-field overrides applied to the System ↔ Healthcheck assignment. The map key is the field path of the referenced healthcheck's result (e.g. \"cpu.usage\", \"latencyMs\").",
+    schema: AnomalyFieldConfigSchema,
+  });
+}
+
+// ─── Registration entry point ───────────────────────────────────────────────
+
+export function registerAnomalyGitOpsKinds({
+  kindRegistry,
+  ...deps
+}: AnomalyGitOpsKindsDeps & {
+  kindRegistry: EntityKindRegistry;
+}): void {
+  kindRegistry.registerKindExtension(buildHealthcheckAnomalyExtension(deps));
+  kindRegistry.registerKindExtension(buildSystemAnomalyExtension(deps));
+}

package/src/detector.test.ts

@@ -516,7 +516,7 @@ describe("Anomaly Detector — processCheckCompleted", () => {
     const db = createMockDb({
       configRecord: {
         version: 1,
-        data: { enabled: false, sensitivity: 1, confirmationWindow: 3, baselineWindow: "7d", notify: true, driftEnabled: true, driftThreshold: 2 } satisfies AnomalySettings,
+        data: { enabled: false, baselineWindow: "7d", notify: true } satisfies AnomalySettings,
       },
     });
 

package/src/detector.ts

@@ -157,18 +157,13 @@ export async function processCheckCompleted({
       continue; // Learning phase (no baseline yet)
     }
 
-    const {
-      enabled: effectiveEnabled,
-      sensitivity: effectiveSensitivity,
-      confirmationWindow: effectiveConfirmation,
-      direction: effectiveDirection,
-    } = resolveEffectiveConfig(path, templateConfig, assignmentConfig);
-
-    if (!effectiveEnabled) {
-      continue;
-    }
-
     let schemaDirection: AnomalyDirection | undefined;
+    let schemaSensitivity: number | undefined;
+    let schemaConfirmationWindow: number | undefined;
+    let schemaDriftEnabled: boolean | undefined;
+    let schemaDriftThreshold: number | undefined;
+    let schemaMinAbsoluteDelta: number | undefined;
+    let schemaMinRelativeDelta: number | undefined;
     const collector = collectorRegistry.getCollector(collectorId);
     if (collector) {
       const collectorSchema = collector.collector.result.schema;
@@ -178,10 +173,36 @@ export async function processCheckCompleted({
         if (fieldSchema) {
           const meta = getHealthResultMeta(fieldSchema);
           schemaDirection = meta?.["x-anomaly-direction"];
+          schemaSensitivity = meta?.["x-anomaly-sensitivity"];
+          schemaConfirmationWindow = meta?.["x-anomaly-confirmation-window"];
+          schemaDriftEnabled = meta?.["x-anomaly-drift-enabled"];
+          schemaDriftThreshold = meta?.["x-anomaly-drift-threshold"];
+          schemaMinAbsoluteDelta = meta?.["x-anomaly-min-absolute-delta"];
+          schemaMinRelativeDelta = meta?.["x-anomaly-min-relative-delta"];
         }
       }
     }
 
+    const {
+      enabled: effectiveEnabled,
+      sensitivity: effectiveSensitivity,
+      confirmationWindow: effectiveConfirmation,
+      direction: effectiveDirection,
+      minAbsoluteDelta: effectiveMinAbsolute,
+      minRelativeDelta: effectiveMinRelative,
+    } = resolveEffectiveConfig(path, templateConfig, assignmentConfig, {
+      sensitivity: schemaSensitivity,
+      confirmationWindow: schemaConfirmationWindow,
+      driftEnabled: schemaDriftEnabled,
+      driftThreshold: schemaDriftThreshold,
+      minAbsoluteDelta: schemaMinAbsoluteDelta,
+      minRelativeDelta: schemaMinRelativeDelta,
+    });
+
+    if (!effectiveEnabled) {
+      continue;
+    }
+
     const direction = effectiveDirection ?? schemaDirection;
 
     if (!direction) {
@@ -206,7 +227,13 @@ export async function processCheckCompleted({
         direction,
         effectiveSensitivity,
       );
-      anomalous = isAnomalous(value, thresholds);
+      anomalous = isAnomalous({
+        value,
+        mean: baseline.mean,
+        thresholds,
+        minAbsoluteDelta: effectiveMinAbsolute,
+        minRelativeDelta: effectiveMinRelative,
+      });
       deviation =
         baseline.stdDev > 0
           ? Math.abs(value - baseline.mean) / baseline.stdDev

package/src/drift-evaluator.test.ts

@@ -121,12 +121,8 @@ const stableBaseline = createBaseline({
 
 const defaultTemplate: AnomalySettings = {
   enabled: true,
-  sensitivity: 1,
-  confirmationWindow: 3,
   baselineWindow: "7d",
   notify: true,
-  driftEnabled: true,
-  driftThreshold: 2,
 };
 
 describe("evaluateDrift", () => {
@@ -162,16 +158,21 @@ describe("evaluateDrift", () => {
       expect(db._insertCalls.length).toBe(0);
     });
 
-    test("does nothing when driftEnabled is false", async () => {
+    test("does nothing when drift is disabled at the field level", async () => {
       const db = createMockDb();
       await evaluateDrift({
         ...baseProps,
         baseline: driftingBaseline,
         schemaDirection: "lower-is-better",
-        templateConfig: { ...defaultTemplate, driftEnabled: false },
+        templateConfig: {
+          ...defaultTemplate,
+          fieldOverrides: {
+            "collectors.http.request.responseTimeMs": { driftEnabled: false },
+          },
+        },
         db: db as never,
         catalogClient: createMockCatalogClient() as never,
-      notificationClient: createMockNotificationClient() as never,
+        notificationClient: createMockNotificationClient() as never,
         logger: createMockLogger() as never,
       });
       expect(db._insertCalls.length).toBe(0);

package/src/drift-evaluator.ts

@@ -33,6 +33,18 @@ export interface EvaluateDriftInput {
   baseline: FieldBaseline;
   /** Direction declared by the schema for this field, if any. */
   schemaDirection?: AnomalyDirection;
+  /** Schema-declared sensitivity multiplier (plugin author default). */
+  schemaSensitivity?: number;
+  /** Schema-declared confirmation window (plugin author default). */
+  schemaConfirmationWindow?: number;
+  /** Schema-declared drift toggle (plugin author default). */
+  schemaDriftEnabled?: boolean;
+  /** Schema-declared drift threshold sigma multiplier (plugin author default). */
+  schemaDriftThreshold?: number;
+  /** Schema-declared practical-significance floor on absolute change. */
+  schemaMinAbsoluteDelta?: number;
+  /** Schema-declared practical-significance floor on relative change. */
+  schemaMinRelativeDelta?: number;
   templateConfig?: AnomalySettings;
   assignmentConfig?: Partial<AnomalySettings>;
 }
@@ -58,6 +70,12 @@ export async function evaluateDrift({
   fieldPath,
   baseline,
   schemaDirection,
+  schemaSensitivity,
+  schemaConfirmationWindow,
+  schemaDriftEnabled,
+  schemaDriftThreshold,
+  schemaMinAbsoluteDelta,
+  schemaMinRelativeDelta,
   templateConfig,
   assignmentConfig,
 }: EvaluateDriftInput): Promise<void> {
@@ -67,7 +85,16 @@ export async function evaluateDrift({
     direction: configDirection,
     driftEnabled,
     driftThreshold,
-  } = resolveEffectiveConfig(fieldPath, templateConfig, assignmentConfig);
+    minAbsoluteDelta,
+    minRelativeDelta,
+  } = resolveEffectiveConfig(fieldPath, templateConfig, assignmentConfig, {
+    sensitivity: schemaSensitivity,
+    confirmationWindow: schemaConfirmationWindow,
+    driftEnabled: schemaDriftEnabled,
+    driftThreshold: schemaDriftThreshold,
+    minAbsoluteDelta: schemaMinAbsoluteDelta,
+    minRelativeDelta: schemaMinRelativeDelta,
+  });
 
   const direction = configDirection ?? schemaDirection;
 
@@ -83,6 +110,9 @@ export async function evaluateDrift({
     direction,
     sensitivity,
     threshold: driftThreshold,
+    mean: baseline.mean,
+    minAbsoluteDelta,
+    minRelativeDelta,
   });
 
   const [existing] = await db

package/src/jobs/baseline-analyzer.ts

@@ -205,7 +205,7 @@ export async function setupBaselineAnalyzerJob({
           const fieldName = fieldNames[path];
           if (!collectorId || !fieldName) continue;
 
-          const schemaDirection = lookupSchemaDirection({
+          const schemaInfo = lookupSchemaInfo({
             collectorRegistry,
             collectorId,
             fieldName,
@@ -226,7 +226,13 @@ export async function setupBaselineAnalyzerJob({
             configurationId: assignment.configurationId,
             fieldPath: path,
             baseline: baselineDto,
-            schemaDirection,
+            schemaDirection: schemaInfo.direction,
+            schemaSensitivity: schemaInfo.sensitivity,
+            schemaConfirmationWindow: schemaInfo.confirmationWindow,
+            schemaDriftEnabled: schemaInfo.driftEnabled,
+            schemaDriftThreshold: schemaInfo.driftThreshold,
+            schemaMinAbsoluteDelta: schemaInfo.minAbsoluteDelta,
+            schemaMinRelativeDelta: schemaInfo.minRelativeDelta,
             templateConfig,
             assignmentConfig,
           });
@@ -252,7 +258,17 @@ export async function setupBaselineAnalyzerJob({
   logger.debug("Anomaly baseline analyzer job scheduled.");
 }
 
-function lookupSchemaDirection({
+interface SchemaInfo {
+  direction?: AnomalyDirection;
+  sensitivity?: number;
+  confirmationWindow?: number;
+  driftEnabled?: boolean;
+  driftThreshold?: number;
+  minAbsoluteDelta?: number;
+  minRelativeDelta?: number;
+}
+
+function lookupSchemaInfo({
   collectorRegistry,
   collectorId,
   fieldName,
@@ -260,14 +276,22 @@ function lookupSchemaDirection({
   collectorRegistry: CollectorRegistry;
   collectorId: string;
   fieldName: string;
-}): AnomalyDirection | undefined {
+}): SchemaInfo {
   const collector = collectorRegistry.getCollector(collectorId);
-  if (!collector) return undefined;
+  if (!collector) return {};
   const collectorSchema = collector.collector.result.schema;
-  if (!("shape" in collectorSchema)) return undefined;
+  if (!("shape" in collectorSchema)) return {};
   const shape = collectorSchema.shape as Record<string, z.ZodTypeAny>;
   const fieldSchema = shape[fieldName];
-  if (!fieldSchema) return undefined;
+  if (!fieldSchema) return {};
   const meta = getHealthResultMeta(fieldSchema);
-  return meta?.["x-anomaly-direction"];
+  return {
+    direction: meta?.["x-anomaly-direction"],
+    sensitivity: meta?.["x-anomaly-sensitivity"],
+    confirmationWindow: meta?.["x-anomaly-confirmation-window"],
+    driftEnabled: meta?.["x-anomaly-drift-enabled"],
+    driftThreshold: meta?.["x-anomaly-drift-threshold"],
+    minAbsoluteDelta: meta?.["x-anomaly-min-absolute-delta"],
+    minRelativeDelta: meta?.["x-anomaly-min-relative-delta"],
+  };
 }

package/src/plugin.ts

@@ -16,6 +16,11 @@ import {
 } from "@checkstack/anomaly-common";
 import { specToRegistration } from "@checkstack/notification-common";
 import { HealthCheckApi } from "@checkstack/healthcheck-common";
+import { entityKindExtensionPoint } from "@checkstack/gitops-backend";
+import {
+  registerAnomalyGitOpsKinds,
+  registerAnomalyGitOpsDocumentation,
+} from "./anomaly-gitops-kinds";
 
 import { definePluginMetadata } from "@checkstack/common";
 
@@ -37,6 +42,20 @@ export const plugin = createBackendPlugin({
 
     let routerCache: AnomalyRouterCache | undefined;
 
+    // ─── GitOps Entity Kind Registration ─────────────────────────────
+    // Mutable ref populated during init(); the reconciler closure pulls
+    // the service via the lazy accessor at sync time.
+    let gitopsService: AnomalyService | undefined;
+    const kindRegistry = env.getExtensionPoint(entityKindExtensionPoint);
+    registerAnomalyGitOpsKinds({
+      kindRegistry,
+      getService: () => {
+        if (!gitopsService)
+          throw new Error("AnomalyService not initialized");
+        return gitopsService;
+      },
+    });
+
     env.registerInit({
       schema,
       deps: {
@@ -71,6 +90,7 @@ export const plugin = createBackendPlugin({
         });
 
         const service = new AnomalyService(typedDb);
+        gitopsService = service;
         routerCache = createAnomalyRouterCache({ cacheManager, logger });
         const router = createRouter(service, logger, routerCache);
         rpc.registerRouter(router, anomalyContract);
@@ -97,6 +117,14 @@ export const plugin = createBackendPlugin({
           ),
         ]);
 
+        // GitOps spec-schema docs need the collector registry to be
+        // populated so we can enumerate per-collector result fields and
+        // register conditional variants under `anomaly.fieldOverrides`.
+        registerAnomalyGitOpsDocumentation({
+          kindRegistry,
+          collectorRegistry,
+        });
+
         onHook(healthCheckHooks.checkCompleted, async (payload) => {
           await processCheckCompleted({
             ...payload,

package/src/router.ts

@@ -62,7 +62,7 @@ export function createRouter(
     getAnomalyAssignmentConfig: os.getAnomalyAssignmentConfig.handler(
       async ({ input }) => {
         const result = await service.getAnomalyAssignmentConfig(input.systemId, input.configurationId);
-        // eslint-disable-next-line unicorn/no-null
+         
         return (result as VersionedRecord<Partial<AnomalySettings>>) ?? null;
       }
     ),

package/src/service.ts

@@ -44,9 +44,9 @@ export class AnomalyService {
     return results.map((r) => ({
       ...r,
       startedAt: r.startedAt.toISOString(),
-      // eslint-disable-next-line unicorn/no-null
+       
       confirmedAt: r.confirmedAt?.toISOString() ?? null,
-      // eslint-disable-next-line unicorn/no-null
+       
       recoveredAt: r.recoveredAt?.toISOString() ?? null,
     }));
   }
@@ -83,12 +83,8 @@ export class AnomalyService {
       // Return default configuration wrapper
       return anomalySettingsConfig.create({
         enabled: true,
-        sensitivity: 1,
-        confirmationWindow: 3,
         baselineWindow: "7d",
         notify: true,
-        driftEnabled: true,
-        driftThreshold: 2,
       });
     }
 

package/tsconfig.json

@@ -28,6 +28,12 @@
     {
       "path": "../drizzle-helper"
     },
+    {
+      "path": "../gitops-backend"
+    },
+    {
+      "path": "../gitops-common"
+    },
     {
       "path": "../healthcheck-backend"
     },