@checkstack/healthcheck-backend 0.13.1 → 0.14.1

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @checkstack/healthcheck-backend
 
+## 0.14.1
+
+### Patch Changes
+
+- Updated dependencies [b01078f]
+  - @checkstack/catalog-backend@0.4.0
+  - @checkstack/satellite-backend@0.2.3
+
+## 0.14.0
+
+### Minor Changes
+
+- 6c40b5b: ### GitOps Ecosystem: Healthcheck Kind Registration (Phase 5)
+
+  **gitops-common**: Added required `resolveEntityRef` to `ReconcileContext`, enabling extension reconcilers to resolve cross-kind entity references (e.g., healthcheck refs in System extensions).
+
+  **gitops-backend**: Updated reconciler to populate `resolveEntityRef` by querying local provenance — no RPC round-trip needed.
+
+  **healthcheck-backend**: Registered `kind: Healthcheck` and `System → healthchecks` extension with the EntityKindRegistry:
+
+  - Validates strategy configs against registered strategy schemas at reconcile time
+  - Validates collector configs against registered collector schemas at reconcile time
+  - Manages system ↔ healthcheck associations with automatic stale removal
+
+  **healthcheck-frontend**: Added GitOps provenance locking to the HealthCheck IDE editor — GitOps-managed health checks show a lock banner and disable editing.
+
+  **catalog-backend**: Updated test fixtures for new required `resolveEntityRef` context field.
+
+### Patch Changes
+
+- Updated dependencies [6c40b5b]
+- Updated dependencies [6c40b5b]
+- Updated dependencies [6c40b5b]
+- Updated dependencies [6c40b5b]
+- Updated dependencies [6c40b5b]
+- Updated dependencies [6c40b5b]
+  - @checkstack/catalog-backend@0.3.0
+  - @checkstack/gitops-backend@0.1.0
+  - @checkstack/gitops-common@0.1.0
+  - @checkstack/satellite-backend@0.2.2
+
 ## 0.13.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-backend",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -13,17 +13,19 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.11.1",
-    "@checkstack/catalog-backend": "0.2.23",
+    "@checkstack/backend-api": "0.12.0",
+    "@checkstack/catalog-backend": "0.2.24",
     "@checkstack/catalog-common": "1.3.1",
-    "@checkstack/command-backend": "0.1.18",
+    "@checkstack/command-backend": "0.1.19",
     "@checkstack/common": "0.6.5",
-    "@checkstack/healthcheck-common": "0.10.1",
+    "@checkstack/gitops-backend": "0.0.1",
+    "@checkstack/gitops-common": "0.0.1",
+    "@checkstack/healthcheck-common": "0.11.0",
     "@checkstack/incident-common": "0.4.7",
-    "@checkstack/integration-backend": "0.1.18",
+    "@checkstack/integration-backend": "0.1.19",
     "@checkstack/maintenance-common": "0.4.9",
-    "@checkstack/queue-api": "0.2.12",
-    "@checkstack/satellite-backend": "0.1.0",
+    "@checkstack/queue-api": "0.2.13",
+    "@checkstack/satellite-backend": "0.2.1",
     "@checkstack/signal-common": "0.1.9",
     "@hono/zod-validator": "^0.7.6",
     "drizzle-orm": "^0.45.0",
@@ -35,7 +37,7 @@
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.4",
     "@checkstack/scripts": "0.1.2",
-    "@checkstack/test-utils-backend": "0.1.18",
+    "@checkstack/test-utils-backend": "0.1.19",
     "@checkstack/tsconfig": "0.0.5",
     "@types/bun": "^1.0.0",
     "@types/tdigest": "^0.1.5",

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

@@ -0,0 +1,596 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import { CHECKSTACK_API_VERSION } from "@checkstack/gitops-common";
+import type { ReconcileContext } from "@checkstack/gitops-common";
+import {
+  buildHealthcheckKind,
+  buildSystemHealthcheckExtension,
+} from "./healthcheck-gitops-kinds";
+import type {
+  HealthCheckConfiguration,
+  CreateHealthCheckConfiguration,
+  UpdateHealthCheckConfiguration,
+} from "@checkstack/healthcheck-common";
+import { z } from "zod";
+import { Versioned } from "@checkstack/backend-api";
+
+/**
+ * Tests for the healthcheck-backend's GitOps entity kind registrations.
+ *
+ * Exercises reconcile/delete for kind: Healthcheck and the
+ * System → healthchecks extension in isolation with mock services.
+ */
+
+// ─── Mock Healthcheck Service ──────────────────────────────────────────────
+
+interface MockConfig {
+  id: string;
+  name: string;
+  strategyId: string;
+  config: Record<string, unknown>;
+  intervalSeconds: number;
+  collectors?: unknown[];
+  paused: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+interface MockAssociation {
+  systemId: string;
+  configurationId: string;
+  enabled: boolean;
+}
+
+function createMockService() {
+  const configs: MockConfig[] = [];
+  const associations: MockAssociation[] = [];
+
+  return {
+    configs,
+    associations,
+    createConfiguration: mock(async (data: CreateHealthCheckConfiguration) => {
+      const config: MockConfig = {
+        id: `hc-${configs.length + 1}`,
+        name: data.name,
+        strategyId: data.strategyId,
+        config: data.config,
+        intervalSeconds: data.intervalSeconds,
+        collectors: data.collectors,
+        paused: false,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+      configs.push(config);
+      return config as unknown as HealthCheckConfiguration;
+    }),
+    updateConfiguration: mock(
+      async (id: string, data: UpdateHealthCheckConfiguration) => {
+        const config = configs.find((c) => c.id === id);
+        if (config) {
+          Object.assign(config, data, { updatedAt: new Date() });
+        }
+        return config as unknown as HealthCheckConfiguration | undefined;
+      },
+    ),
+    deleteConfiguration: mock(async (id: string) => {
+      const idx = configs.findIndex((c) => c.id === id);
+      if (idx >= 0) configs.splice(idx, 1);
+    }),
+    associateSystem: mock(
+      async (props: {
+        systemId: string;
+        configurationId: string;
+        enabled?: boolean;
+      }) => {
+        const existing = associations.find(
+          (a) =>
+            a.systemId === props.systemId &&
+            a.configurationId === props.configurationId,
+        );
+        if (existing) {
+          existing.enabled = props.enabled ?? true;
+        } else {
+          associations.push({
+            systemId: props.systemId,
+            configurationId: props.configurationId,
+            enabled: props.enabled ?? true,
+          });
+        }
+      },
+    ),
+    disassociateSystem: mock(
+      async (systemId: string, configurationId: string) => {
+        const idx = associations.findIndex(
+          (a) =>
+            a.systemId === systemId && a.configurationId === configurationId,
+        );
+        if (idx >= 0) associations.splice(idx, 1);
+      },
+    ),
+    getSystemConfigurations: mock(async (systemId: string) => {
+      return associations
+        .filter((a) => a.systemId === systemId)
+        .map((a) => {
+          const config = configs.find((c) => c.id === a.configurationId);
+          return config as unknown as HealthCheckConfiguration;
+        })
+        .filter(Boolean);
+    }),
+  };
+}
+
+// ─── Mock Registries ───────────────────────────────────────────────────────
+
+const postgresConfigSchema = z.object({
+  host: z.string(),
+  port: z.number().optional(),
+  database: z.string(),
+  user: z.string(),
+  password: z.string(),
+});
+
+const cpuCollectorConfigSchema = z.object({
+  warningThreshold: z.number().optional(),
+});
+
+function createMockHealthCheckRegistry() {
+  const strategies = new Map<
+    string,
+    { id: string; config: Versioned<unknown> }
+  >();
+
+  // Register a test strategy
+  strategies.set("postgres", {
+    id: "postgres",
+    config: new Versioned({
+      version: 1,
+      schema: postgresConfigSchema,
+    }),
+  });
+
+  return {
+    getStrategy: (id: string) => strategies.get(id) as ReturnType<import("@checkstack/backend-api").HealthCheckRegistry["getStrategy"]>,
+    getStrategies: () =>
+      [...strategies.values()] as ReturnType<import("@checkstack/backend-api").HealthCheckRegistry["getStrategies"]>,
+    getStrategiesWithMeta: () => [],
+    register: () => {},
+  };
+}
+
+function createMockCollectorRegistry() {
+  const collectors = new Map<
+    string,
+    { qualifiedId: string; collector: { config: Versioned<unknown> } }
+  >();
+
+  collectors.set("collector-hardware.cpu", {
+    qualifiedId: "collector-hardware.cpu",
+    collector: {
+      config: new Versioned({
+        version: 1,
+        schema: cpuCollectorConfigSchema,
+      }),
+    },
+  });
+
+  return {
+    getCollector: (id: string) => collectors.get(id) as ReturnType<import("@checkstack/backend-api").CollectorRegistry["getCollector"]>,
+    getCollectors: () =>
+      [...collectors.values()] as ReturnType<import("@checkstack/backend-api").CollectorRegistry["getCollectors"]>,
+    getCollectorsForPlugin: () => [],
+    register: () => {},
+  };
+}
+
+// ─── Test Context ──────────────────────────────────────────────────────────
+
+const mockContext: ReconcileContext = {
+  logger: {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+  },
+  resolveEntityRef: async () => undefined,
+};
+
+// ─── Tests: kind: Healthcheck ──────────────────────────────────────────────
+
+describe("Healthcheck GitOps Kind: Healthcheck", () => {
+  let mockService: ReturnType<typeof createMockService>;
+  let mockHCRegistry: ReturnType<typeof createMockHealthCheckRegistry>;
+  let mockCollectorRegistry: ReturnType<typeof createMockCollectorRegistry>;
+
+  beforeEach(() => {
+    mockService = createMockService();
+    mockHCRegistry = createMockHealthCheckRegistry();
+    mockCollectorRegistry = createMockCollectorRegistry();
+  });
+
+  function buildKind() {
+    return buildHealthcheckKind({
+      createService: () =>
+        ({
+          createConfiguration: mockService.createConfiguration,
+          updateConfiguration: mockService.updateConfiguration,
+          deleteConfiguration: mockService.deleteConfiguration,
+        }) as never,
+      getHealthCheckRegistry: () => mockHCRegistry as never,
+      getCollectorRegistry: () => mockCollectorRegistry as never,
+    });
+  }
+
+  it("creates a new healthcheck configuration and returns entityId", async () => {
+    const kind = buildKind();
+
+    const result = await kind.reconcile({
+      entity: {
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Healthcheck",
+        metadata: { name: "payment-db-check", title: "Payment DB Health" },
+        spec: {
+          strategy: "postgres",
+          intervalSeconds: 30,
+          config: {
+            host: "db.internal",
+            port: 5432,
+            database: "payments",
+            user: "monitor",
+            password: "secret",
+          },
+        },
+      },
+      context: mockContext,
+    });
+
+    expect(result.entityId).toBe("hc-1");
+    expect(mockService.createConfiguration).toHaveBeenCalledTimes(1);
+    expect(mockService.configs).toHaveLength(1);
+    expect(mockService.configs[0].name).toBe("Payment DB Health");
+    expect(mockService.configs[0].strategyId).toBe("postgres");
+  });
+
+  it("updates an existing configuration using existingEntityId", async () => {
+    const kind = buildKind();
+
+    mockService.configs.push({
+      id: "hc-existing",
+      name: "Old Name",
+      strategyId: "postgres",
+      config: {},
+      intervalSeconds: 60,
+      paused: false,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    const result = await kind.reconcile({
+      entity: {
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Healthcheck",
+        metadata: { name: "payment-db-check", title: "Updated Check" },
+        spec: {
+          strategy: "postgres",
+          intervalSeconds: 15,
+          config: {
+            host: "db.new",
+            port: 5432,
+            database: "payments",
+            user: "monitor",
+            password: "new-secret",
+          },
+        },
+      },
+      existingEntityId: "hc-existing",
+      context: mockContext,
+    });
+
+    expect(result.entityId).toBe("hc-existing");
+    expect(mockService.updateConfiguration).toHaveBeenCalledTimes(1);
+    expect(mockService.createConfiguration).not.toHaveBeenCalled();
+    expect(mockService.configs[0].name).toBe("Updated Check");
+  });
+
+  it("deletes a configuration by entityId", async () => {
+    const kind = buildKind();
+
+    mockService.configs.push({
+      id: "hc-del",
+      name: "To Delete",
+      strategyId: "postgres",
+      config: {},
+      intervalSeconds: 30,
+      paused: false,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    await kind.delete!({
+      entityName: "old-check",
+      entityId: "hc-del",
+      context: mockContext,
+    });
+
+    expect(mockService.deleteConfiguration).toHaveBeenCalledWith("hc-del");
+    expect(mockService.configs).toHaveLength(0);
+  });
+
+  it("skips delete when entityId is missing", async () => {
+    const kind = buildKind();
+
+    await kind.delete!({
+      entityName: "unknown-check",
+      context: mockContext,
+    });
+
+    expect(mockService.deleteConfiguration).not.toHaveBeenCalled();
+  });
+
+  it("throws on unknown strategy", async () => {
+    const kind = buildKind();
+
+    await expect(
+      kind.reconcile({
+        entity: {
+          apiVersion: CHECKSTACK_API_VERSION,
+          kind: "Healthcheck",
+          metadata: { name: "bad-check" },
+          spec: {
+            strategy: "nonexistent",
+            intervalSeconds: 30,
+            config: {},
+          },
+        },
+        context: mockContext,
+      }),
+    ).rejects.toThrow(/Unknown health check strategy "nonexistent"/);
+  });
+
+  it("validates config against strategy schema", async () => {
+    const kind = buildKind();
+
+    await expect(
+      kind.reconcile({
+        entity: {
+          apiVersion: CHECKSTACK_API_VERSION,
+          kind: "Healthcheck",
+          metadata: { name: "bad-config" },
+          spec: {
+            strategy: "postgres",
+            intervalSeconds: 30,
+            config: {
+              // Missing required fields: host, database, user, password
+              port: "not-a-number",
+            },
+          },
+        },
+        context: mockContext,
+      }),
+    ).rejects.toThrow(/config validation failed/);
+  });
+
+  it("validates collector configs against collector registry schemas", async () => {
+    const kind = buildKind();
+
+    await expect(
+      kind.reconcile({
+        entity: {
+          apiVersion: CHECKSTACK_API_VERSION,
+          kind: "Healthcheck",
+          metadata: { name: "bad-collector" },
+          spec: {
+            strategy: "postgres",
+            intervalSeconds: 30,
+            config: {
+              host: "db.local",
+              database: "test",
+              user: "root",
+              password: "pass",
+            },
+            collectors: [
+              {
+                collectorId: "unknown-collector",
+                config: {},
+              },
+            ],
+          },
+        },
+        context: mockContext,
+      }),
+    ).rejects.toThrow(/Unknown collector "unknown-collector"/);
+  });
+
+  it("accepts valid collector configs", async () => {
+    const kind = buildKind();
+
+    const result = await kind.reconcile({
+      entity: {
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Healthcheck",
+        metadata: { name: "with-collector" },
+        spec: {
+          strategy: "postgres",
+          intervalSeconds: 30,
+          config: {
+            host: "db.local",
+            database: "test",
+            user: "root",
+            password: "pass",
+          },
+          collectors: [
+            {
+              collectorId: "collector-hardware.cpu",
+              config: { warningThreshold: 90 },
+            },
+          ],
+        },
+      },
+      context: mockContext,
+    });
+
+    expect(result.entityId).toBe("hc-1");
+    expect(mockService.createConfiguration).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ─── Tests: System → healthchecks extension ────────────────────────────────
+
+describe("Healthcheck GitOps Kind: System Extension", () => {
+  let mockService: ReturnType<typeof createMockService>;
+
+  beforeEach(() => {
+    mockService = createMockService();
+  });
+
+  function buildExtension() {
+    return buildSystemHealthcheckExtension({
+      createService: () =>
+        ({
+          associateSystem: mockService.associateSystem,
+          disassociateSystem: mockService.disassociateSystem,
+          getSystemConfigurations: mockService.getSystemConfigurations,
+        }) as never,
+      getHealthCheckRegistry: () => createMockHealthCheckRegistry() as never,
+      getCollectorRegistry: () => createMockCollectorRegistry() as never,
+    });
+  }
+
+  it("creates associations from ref array", async () => {
+    const ext = buildExtension();
+
+    // Setup: two healthchecks exist in provenance
+    const contextWithRefs: ReconcileContext = {
+      ...mockContext,
+      resolveEntityRef: async ({ kind, entityName }) => {
+        const entries: Record<string, Record<string, string>> = {
+          Healthcheck: {
+            "db-check": "hc-1",
+            "api-check": "hc-2",
+          },
+        };
+        return entries[kind]?.[entityName];
+      },
+    };
+
+    await ext.reconcile({
+      entity: {
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "System",
+        metadata: { name: "payment-service" },
+        spec: {},
+      },
+      extensionSpec: [
+        { ref: { kind: "Healthcheck", name: "db-check" }, degradedThreshold: 3, unhealthyThreshold: 5 },
+        { ref: { kind: "Healthcheck", name: "api-check" } },
+      ],
+      entityId: "sys-123",
+      context: contextWithRefs,
+    });
+
+    expect(mockService.associateSystem).toHaveBeenCalledTimes(2);
+    expect(mockService.associations).toHaveLength(2);
+    expect(mockService.associations[0].systemId).toBe("sys-123");
+    expect(mockService.associations[0].configurationId).toBe("hc-1");
+    expect(mockService.associations[1].configurationId).toBe("hc-2");
+  });
+
+  it("removes stale associations not in spec", async () => {
+    const ext = buildExtension();
+
+    // Pre-populate: system has 2 existing associations, spec only wants 1
+    mockService.configs.push(
+      {
+        id: "hc-keep",
+        name: "Keep",
+        strategyId: "postgres",
+        config: {},
+        intervalSeconds: 30,
+        paused: false,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+      {
+        id: "hc-remove",
+        name: "Remove",
+        strategyId: "postgres",
+        config: {},
+        intervalSeconds: 30,
+        paused: false,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+    );
+    mockService.associations.push(
+      { systemId: "sys-123", configurationId: "hc-keep", enabled: true },
+      { systemId: "sys-123", configurationId: "hc-remove", enabled: true },
+    );
+
+    const contextWithRefs: ReconcileContext = {
+      ...mockContext,
+      resolveEntityRef: async ({ kind, entityName }) => {
+        const entries: Record<string, Record<string, string>> = {
+          Healthcheck: { "keep-check": "hc-keep" },
+        };
+        return entries[kind]?.[entityName];
+      },
+    };
+
+    await ext.reconcile({
+      entity: {
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "System",
+        metadata: { name: "my-system" },
+        spec: {},
+      },
+      extensionSpec: [{ ref: { kind: "Healthcheck", name: "keep-check" } }],
+      entityId: "sys-123",
+      context: contextWithRefs,
+    });
+
+    expect(mockService.disassociateSystem).toHaveBeenCalledTimes(1);
+    expect(mockService.disassociateSystem).toHaveBeenCalledWith(
+      "sys-123",
+      "hc-remove",
+    );
+  });
+
+  it("errors on unresolvable healthcheck ref", async () => {
+    const ext = buildExtension();
+
+    const contextEmpty: ReconcileContext = {
+      ...mockContext,
+      resolveEntityRef: async () => undefined,
+    };
+
+    await expect(
+      ext.reconcile({
+        entity: {
+          apiVersion: CHECKSTACK_API_VERSION,
+          kind: "System",
+          metadata: { name: "my-system" },
+          spec: {},
+        },
+        extensionSpec: [{ ref: { kind: "Healthcheck", name: "nonexistent-check" } }],
+        entityId: "sys-123",
+        context: contextEmpty,
+      }),
+    ).rejects.toThrow(/Cannot resolve Healthcheck ref "nonexistent-check"/);
+  });
+
+  it("skips when extensionSpec is empty", async () => {
+    const ext = buildExtension();
+
+    await ext.reconcile({
+      entity: {
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "System",
+        metadata: { name: "my-system" },
+        spec: {},
+      },
+      extensionSpec: [],
+      entityId: "sys-123",
+      context: mockContext,
+    });
+
+    expect(mockService.associateSystem).not.toHaveBeenCalled();
+  });
+});

package/src/healthcheck-gitops-kinds.ts

@@ -0,0 +1,312 @@
+import { z } from "zod";
+import type {
+  EntityKindDefinition,
+  EntityKindExtensionDefinition,
+  EntityKindRegistry,
+  ReconcileContext,
+} from "@checkstack/gitops-common";
+import { CHECKSTACK_API_VERSION, secretField, entityRefSchema } from "@checkstack/gitops-common";
+import type {
+  HealthCheckRegistry,
+  CollectorRegistry,
+} from "@checkstack/backend-api";
+import { HealthCheckService } from "./service";
+
+
+/**
+ * Lazy accessor functions — populated during init(), consumed during reconcile.
+ * Safe because reconcile only runs during sync (afterPluginsReady), by which
+ * point init() has completed.
+ */
+interface HealthcheckGitOpsKindsDeps {
+  createService: () => HealthCheckService;
+  getHealthCheckRegistry: () => HealthCheckRegistry;
+  getCollectorRegistry: () => CollectorRegistry;
+}
+
+// ─── Healthcheck Spec Schema ───────────────────────────────────────────────
+
+/**
+ * GitOps spec schema for kind: Healthcheck.
+ *
+ * Strategy `config` fields use `secretField()` for sensitive values
+ * (passwords, tokens) that are resolved by the reconciliation engine.
+ */
+const healthcheckSpecSchema = z.object({
+  strategy: z.string().min(1),
+  intervalSeconds: z.number().int().min(1),
+  config: z.record(z.string(), z.union([z.unknown(), secretField()])),
+  collectors: z
+    .array(
+      z.object({
+        collectorId: z.string().min(1),
+        config: z.record(z.string(), z.unknown()),
+        assertions: z
+          .array(
+            z.object({
+              field: z.string(),
+              jsonPath: z.string().optional(),
+              operator: z.string(),
+              value: z.unknown().optional(),
+            }),
+          )
+          .optional(),
+      }),
+    )
+    .optional(),
+});
+
+type HealthcheckSpec = z.infer<typeof healthcheckSpecSchema>;
+
+// ─── System Extension Schema ───────────────────────────────────────────────
+
+const systemHealthcheckExtensionSchema = z
+  .array(
+    z.object({
+      ref: entityRefSchema,
+      degradedThreshold: z.number().int().min(1).optional(),
+      unhealthyThreshold: z.number().int().min(1).optional(),
+      satelliteIds: z.array(z.string()).optional(),
+      includeLocal: z.boolean().optional(),
+    }),
+  )
+  .optional();
+
+type SystemHealthcheckExtension = z.infer<
+  typeof systemHealthcheckExtensionSchema
+>;
+
+// ─── Kind Builder Functions ────────────────────────────────────────────────
+
+/**
+ * Build the ``kind: Healthcheck`` definition.
+ *
+ * Exported for isolated unit testing — the register() phase calls this
+ * and passes the result to `kindRegistry.registerKind()`.
+ */
+export function buildHealthcheckKind(
+  deps: HealthcheckGitOpsKindsDeps,
+): EntityKindDefinition<HealthcheckSpec> {
+  return {
+    apiVersion: CHECKSTACK_API_VERSION,
+    kind: "Healthcheck",
+    specSchema: healthcheckSpecSchema,
+
+    reconcile: async ({
+      entity,
+      existingEntityId,
+      context,
+    }: {
+      entity: { metadata: { name: string; title?: string; description?: string }; spec: HealthcheckSpec };
+      existingEntityId?: string;
+      context: ReconcileContext;
+    }) => {
+      const service = deps.createService();
+      const spec = entity.spec;
+
+      // Validate strategy exists in registry
+      const healthCheckRegistry = deps.getHealthCheckRegistry();
+      const strategy = healthCheckRegistry.getStrategy(spec.strategy);
+      if (!strategy) {
+        throw new Error(
+          `Unknown health check strategy "${spec.strategy}". ` +
+            `Available: ${healthCheckRegistry.getStrategies().map((s) => s.id).join(", ")}`,
+        );
+      }
+
+      // Validate config against strategy's Zod schema
+      const configValidation = strategy.config.schema.safeParse(spec.config);
+      if (!configValidation.success) {
+        throw new Error(
+          `Strategy "${spec.strategy}" config validation failed: ${configValidation.error.message}`,
+        );
+      }
+
+      // Validate collector configs against their registry schemas
+      if (spec.collectors) {
+        for (const collector of spec.collectors) {
+          const collectorReg = deps.getCollectorRegistry();
+          const registered = collectorReg.getCollector(
+            collector.collectorId,
+          );
+          if (!registered) {
+            throw new Error(
+              `Unknown collector "${collector.collectorId}". ` +
+                `Available: ${collectorReg.getCollectors().map((c) => c.qualifiedId).join(", ")}`,
+            );
+          }
+          const collectorConfigValidation =
+            registered.collector.config.schema.safeParse(collector.config);
+          if (!collectorConfigValidation.success) {
+            throw new Error(
+              `Collector "${collector.collectorId}" config validation failed: ${collectorConfigValidation.error.message}`,
+            );
+          }
+        }
+      }
+
+      // Create or update configuration
+      const displayName = entity.metadata.title ?? entity.metadata.name;
+
+      if (existingEntityId) {
+        await service.updateConfiguration(existingEntityId, {
+          name: displayName,
+          strategyId: spec.strategy,
+          config: spec.config,
+          intervalSeconds: spec.intervalSeconds,
+          collectors: spec.collectors?.map((c) => ({
+            id: c.collectorId,
+            collectorId: c.collectorId,
+            config: c.config,
+            assertions: c.assertions,
+          })),
+        });
+        context.logger.info(
+          `GitOps: updated Healthcheck "${displayName}" (id: ${existingEntityId})`,
+        );
+        return { entityId: existingEntityId };
+      }
+
+      const config = await service.createConfiguration({
+        name: displayName,
+        strategyId: spec.strategy,
+        config: spec.config,
+        intervalSeconds: spec.intervalSeconds,
+        collectors: spec.collectors?.map((c) => ({
+          id: c.collectorId,
+          collectorId: c.collectorId,
+          config: c.config,
+          assertions: c.assertions,
+        })),
+      });
+      context.logger.info(
+        `GitOps: created Healthcheck "${displayName}" (id: ${config.id})`,
+      );
+      return { entityId: config.id };
+    },
+
+    delete: async ({
+      entityId,
+      context,
+    }: {
+      entityName: string;
+      entityId?: string;
+      context: ReconcileContext;
+    }) => {
+      if (!entityId) return;
+      const service = deps.createService();
+      await service.deleteConfiguration(entityId);
+      context.logger.info(`GitOps: deleted Healthcheck (id: ${entityId})`);
+    },
+  };
+}
+
+/**
+ * Build the System → healthchecks extension definition.
+ *
+ * Resolves health check entity references to configuration IDs via
+ * `context.resolveEntityRef`, then manages system ↔ health check associations.
+ */
+export function buildSystemHealthcheckExtension(
+  deps: HealthcheckGitOpsKindsDeps,
+): EntityKindExtensionDefinition<SystemHealthcheckExtension> {
+  return {
+    apiVersion: CHECKSTACK_API_VERSION,
+    kind: "System",
+    namespace: "healthchecks",
+    specSchema: systemHealthcheckExtensionSchema,
+
+    reconcile: async ({
+      entity,
+      extensionSpec,
+      entityId,
+      context,
+    }: {
+      entity: { metadata: { name: string } };
+      extensionSpec: SystemHealthcheckExtension;
+      entityId: string;
+      context: ReconcileContext;
+    }) => {
+      if (!extensionSpec || extensionSpec.length === 0) return;
+
+      const service = deps.createService();
+
+      // entityId is injected directly from the base reconciler — no provenance lookup needed
+      const systemEntityId = entityId;
+
+      // Resolve each healthcheck ref → configurationId
+      const desiredConfigIds = new Set<string>();
+
+      for (const entry of extensionSpec) {
+        const configId = await context.resolveEntityRef({
+          kind: entry.ref.kind,
+          entityName: entry.ref.name,
+        });
+
+        if (!configId) {
+          throw new Error(
+            `Cannot resolve ${entry.ref.kind} ref "${entry.ref.name}" — ensure the entity exists`,
+          );
+        }
+
+        desiredConfigIds.add(configId);
+
+        // Build state thresholds from the shorthand
+        const stateThresholds =
+          entry.degradedThreshold || entry.unhealthyThreshold
+            ? ({
+                mode: "consecutive" as const,
+                healthy: { minSuccessCount: 1 },
+                degraded: {
+                  minFailureCount: entry.degradedThreshold ?? 2,
+                },
+                unhealthy: {
+                  minFailureCount: entry.unhealthyThreshold ?? 5,
+                },
+              })
+            : undefined;
+
+        await service.associateSystem({
+          systemId: systemEntityId,
+          configurationId: configId,
+          enabled: true,
+          stateThresholds,
+          satelliteIds: entry.satelliteIds,
+          includeLocal: entry.includeLocal,
+        });
+
+        context.logger.info(
+          `GitOps: associated ${entry.ref.kind} "${entry.ref.name}" (${configId}) with System "${entity.metadata.name}"`,
+        );
+      }
+
+      // Remove stale associations not in the spec
+      const currentAssociations =
+        await service.getSystemConfigurations(systemEntityId);
+      for (const existing of currentAssociations) {
+        if (!desiredConfigIds.has(existing.id)) {
+          await service.disassociateSystem(systemEntityId, existing.id);
+          context.logger.info(
+            `GitOps: removed stale association ${existing.id} from System "${entity.metadata.name}"`,
+          );
+        }
+      }
+    },
+  };
+}
+
+// ─── Registration Entry Point ──────────────────────────────────────────────
+
+/**
+ * Register all healthcheck-related GitOps entity kinds and extensions.
+ * Called from healthcheck-backend's `register()` phase.
+ */
+export function registerHealthcheckGitOpsKinds({
+  kindRegistry,
+  ...deps
+}: HealthcheckGitOpsKindsDeps & {
+  kindRegistry: EntityKindRegistry;
+}): void {
+  kindRegistry.registerKind(buildHealthcheckKind(deps));
+  kindRegistry.registerKindExtension(buildSystemHealthcheckExtension(deps));
+}

package/src/index.ts

@@ -16,11 +16,15 @@ import {
   coreServices,
   type EmitHookFn,
   type SafeDatabase,
+  type HealthCheckRegistry,
+  type CollectorRegistry,
 } from "@checkstack/backend-api";
 import { integrationEventExtensionPoint } from "@checkstack/integration-backend";
+import { entityKindExtensionPoint } from "@checkstack/gitops-backend";
 import { z } from "zod";
 import { createHealthCheckRouter } from "./router";
 import { HealthCheckService } from "./service";
+import { registerHealthcheckGitOpsKinds } from "./healthcheck-gitops-kinds";
 import { catalogHooks } from "@checkstack/catalog-backend";
 import { satelliteHooks } from "@checkstack/satellite-backend";
 import { CatalogApi } from "@checkstack/catalog-common";
@@ -89,6 +93,39 @@ export default createBackendPlugin({
       pluginMetadata,
     );
 
+    // ─── GitOps Entity Kind Registration ───────────────────────────────
+    // Mutable refs — populated during init(), consumed by reconcile closures.
+    let gitopsDb: SafeDatabase<typeof schema> | undefined;
+    let gitopsHealthCheckRegistry: HealthCheckRegistry | undefined;
+    let gitopsCollectorRegistry: CollectorRegistry | undefined;
+
+    const kindRegistry = env.getExtensionPoint(entityKindExtensionPoint);
+    registerHealthcheckGitOpsKinds({
+      kindRegistry,
+      createService: () => {
+        if (!gitopsDb) throw new Error("Healthcheck database not initialized");
+        if (!gitopsHealthCheckRegistry)
+          throw new Error("HealthCheckRegistry not initialized");
+        if (!gitopsCollectorRegistry)
+          throw new Error("CollectorRegistry not initialized");
+        return new HealthCheckService(
+          gitopsDb,
+          gitopsHealthCheckRegistry,
+          gitopsCollectorRegistry,
+        );
+      },
+      getHealthCheckRegistry: () => {
+        if (!gitopsHealthCheckRegistry)
+          throw new Error("HealthCheckRegistry not initialized");
+        return gitopsHealthCheckRegistry;
+      },
+      getCollectorRegistry: () => {
+        if (!gitopsCollectorRegistry)
+          throw new Error("CollectorRegistry not initialized");
+        return gitopsCollectorRegistry;
+      },
+    });
+
     env.registerInit({
       schema,
       deps: {
@@ -113,6 +150,11 @@ export default createBackendPlugin({
       }) => {
         logger.debug("🏥 Initializing Health Check Backend...");
 
+        // Populate mutable refs for GitOps reconcile closures
+        gitopsDb = database;
+        gitopsHealthCheckRegistry = healthCheckRegistry;
+        gitopsCollectorRegistry = collectorRegistry;
+
         // Create catalog client for notification delegation
         const catalogClient = rpcClient.forPlugin(CatalogApi);