@checkstack/automation-backend 0.2.0 → 0.3.0

package/src/dispatch/entity-scope.test.ts

@@ -0,0 +1,176 @@
+import { describe, it, expect } from "bun:test";
+import type { Logger } from "@checkstack/backend-api";
+import {
+  enrichScopeWithEntities,
+  MAX_RESOLVED_SYSTEMS,
+  type EntityKindResolver,
+} from "./state-scope";
+
+const noopLogger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+} as unknown as Logger;
+
+function collectingLogger(): { logger: Logger; warnings: string[] } {
+  const warnings: string[] = [];
+  const logger = {
+    debug: () => {},
+    info: () => {},
+    warn: (msg: string) => warnings.push(msg),
+    error: () => {},
+  } as unknown as Logger;
+  return { logger, warnings };
+}
+
+/** Resolver factory recording the ids each kind was asked for. */
+function makeResolvers(
+  data: Record<string, Record<string, Record<string, unknown>>>,
+  opts?: { throwsKind?: string },
+) {
+  const calls: Record<string, string[][]> = {};
+  const resolverFor = (kind: string): EntityKindResolver | undefined => {
+    if (!(kind in data) && kind !== opts?.throwsKind) return undefined;
+    return async (ids) => {
+      (calls[kind] ??= []).push([...ids]);
+      if (opts?.throwsKind === kind) throw new Error("resolver down");
+      const out: Record<string, Record<string, unknown>> = {};
+      for (const id of ids) {
+        const row = data[kind]?.[id];
+        if (row) out[id] = row;
+      }
+      return out;
+    };
+  };
+  return { calls, resolverFor };
+}
+
+describe("enrichScopeWithEntities", () => {
+  it("folds state.<kind>.<id> for resolved refs", async () => {
+    const { resolverFor } = makeResolvers({
+      incident: { "inc-1": { status: "open", severity: "high" } },
+    });
+    const scope: Record<string, unknown> = {};
+    await enrichScopeWithEntities({
+      scope,
+      logger: noopLogger,
+      refs: [{ kind: "incident", id: "inc-1" }],
+      resolverFor,
+    });
+    const state = scope.state as Record<
+      string,
+      Record<string, Record<string, unknown>>
+    >;
+    expect(state.incident!["inc-1"]).toEqual({ status: "open", severity: "high" });
+  });
+
+  it("groups + de-dupes ids per kind into one resolver call", async () => {
+    const { calls, resolverFor } = makeResolvers({
+      incident: {
+        "inc-1": { status: "open" },
+        "inc-2": { status: "resolved" },
+      },
+    });
+    const scope: Record<string, unknown> = {};
+    await enrichScopeWithEntities({
+      scope,
+      logger: noopLogger,
+      refs: [
+        { kind: "incident", id: "inc-1" },
+        { kind: "incident", id: "inc-2" },
+        { kind: "incident", id: "inc-1" }, // duplicate
+      ],
+      resolverFor,
+    });
+    expect(calls.incident).toEqual([["inc-1", "inc-2"]]);
+  });
+
+  it("folds state.<kind>.<id> only and never sets scope.health", async () => {
+    // `scope.health` is owned exclusively by the rich `enrichScopeWithState`
+    // path; this generic entity path must never write it, even for an
+    // entity kind. (The dispatch wait re-eval also excludes the `health`
+    // kind here, so health is resolved at most once per scope build.)
+    const { resolverFor } = makeResolvers({
+      incident: { "inc-1": { status: "open", severity: "high" } },
+    });
+    const scope: Record<string, unknown> = {};
+    await enrichScopeWithEntities({
+      scope,
+      logger: noopLogger,
+      refs: [{ kind: "incident", id: "inc-1" }],
+      resolverFor,
+    });
+    const state = scope.state as Record<
+      string,
+      Record<string, Record<string, unknown>>
+    >;
+    expect(state.incident!["inc-1"]).toEqual({
+      status: "open",
+      severity: "high",
+    });
+    expect(scope.health).toBeUndefined();
+  });
+
+  it("fails open and warns when a kind has no resolver", async () => {
+    const { resolverFor } = makeResolvers({ incident: {} });
+    const { logger, warnings } = collectingLogger();
+    const scope: Record<string, unknown> = {};
+    await enrichScopeWithEntities({
+      scope,
+      logger,
+      refs: [{ kind: "unknownkind", id: "x" }],
+      resolverFor,
+    });
+    expect(warnings.some((w) => w.includes("no resolver for kind"))).toBe(true);
+    expect(scope.state).toEqual({});
+  });
+
+  it("fails open and warns when a resolver throws", async () => {
+    const { resolverFor } = makeResolvers(
+      { incident: {} },
+      { throwsKind: "incident" },
+    );
+    const { logger, warnings } = collectingLogger();
+    const scope: Record<string, unknown> = {};
+    await enrichScopeWithEntities({
+      scope,
+      logger,
+      refs: [{ kind: "incident", id: "inc-1" }],
+      resolverFor,
+    });
+    expect(warnings.some((w) => w.includes("failed to resolve kind"))).toBe(true);
+  });
+
+  it("caps the resolved set and warns over the limit", async () => {
+    const incident: Record<string, Record<string, unknown>> = {};
+    const refs = Array.from({ length: MAX_RESOLVED_SYSTEMS + 5 }, (_, i) => {
+      incident[`inc-${i}`] = { status: "open" };
+      return { kind: "incident", id: `inc-${i}` };
+    });
+    const { calls, resolverFor } = makeResolvers({ incident });
+    const { logger, warnings } = collectingLogger();
+    const scope: Record<string, unknown> = {};
+    await enrichScopeWithEntities({ scope, logger, refs, resolverFor });
+    expect(calls.incident![0]!.length).toBe(MAX_RESOLVED_SYSTEMS);
+    expect(warnings.some((w) => w.includes("cap reached"))).toBe(true);
+  });
+
+  it("preserves an existing scope.state namespace", async () => {
+    const { resolverFor } = makeResolvers({
+      incident: { "inc-1": { status: "open" } },
+    });
+    const scope: Record<string, unknown> = {
+      state: { maintenance: { "m-1": { status: "scheduled" } } },
+    };
+    await enrichScopeWithEntities({
+      scope,
+      logger: noopLogger,
+      refs: [{ kind: "incident", id: "inc-1" }],
+      resolverFor,
+    });
+    const state = scope.state as Record<string, Record<string, unknown>>;
+    expect(state.maintenance!["m-1"]).toEqual({ status: "scheduled" });
+    expect(state.incident!["inc-1"]).toEqual({ status: "open" });
+  });
+});

package/src/dispatch/get-service-wiring.test.ts

@@ -0,0 +1,318 @@
+import { describe, expect, it } from "bun:test";
+import { z } from "zod";
+import { Versioned, createServiceRef } from "@checkstack/backend-api";
+// Deep import: the ServiceRegistry is a tiny, side-effect-free class. We use
+// the REAL one (not a stub) so this test proves the production resolution
+// path — `registry.get(ref, { pluginId })` — actually hands a registered
+// service to a provider action at execute time. Importing `@checkstack/backend`'s
+// index would connect to a DB at import; the deep path avoids that.
+import { ServiceRegistry } from "@checkstack/backend/src/services/service-registry";
+import { connectionStoreRef } from "@checkstack/integration-backend";
+import { AutomationDefinitionSchema } from "@checkstack/automation-common";
+import { createActionRegistry } from "../action-registry";
+import { createArtifactTypeRegistry } from "../artifact-type-registry";
+import type { ActionDefinition, ArtifactTypeDefinition } from "../action-types";
+import { dispatchTrigger } from "./engine";
+import { makeDispatchDeps, testPlugin } from "./test-fixtures";
+import { createRunSecretRegistry } from "./run-secret-registry";
+import { assembleDispatchGetService } from "./assemble-get-service";
+import {
+  CONNECTION_STORE_REF_ID,
+  SECRET_RESOLVER_REF_ID,
+} from "./secret-ref-ids";
+import type { DispatchDeps, LoadedAutomation } from "./types";
+
+/**
+ * Integration coverage for the cross-plugin service-resolution seam used by
+ * the automation dispatch engine.
+ *
+ * Background: provider actions (Jira / Teams / Webex create-issue etc.) and
+ * the `secretEnv` script action resolve their deps through `getService` at
+ * EXECUTE time — e.g. `await getService(connectionStoreRef)`. In production
+ * the dispatch `getService` is the plugin `env.getService`, which resolves
+ * through the real `ServiceRegistry`. The whole dispatch suite stubs
+ * `getService` (via `makeDispatchDeps`), so a throwing stub in the
+ * production assembly went unnoticed: every provider action would throw at
+ * runtime.
+ *
+ * These tests use a REAL `ServiceRegistry` and build the dispatch
+ * `getService` the way the plugin loader assembles `env.getService`:
+ * `(ref) => registry.get(ref, { pluginId })`.
+ */
+
+const CONSUMER_PLUGIN_ID = "automation";
+
+/** Build the dispatch `getService` exactly as the plugin loader's `env`. */
+function makeRegistryBackedGetService(registry: ServiceRegistry) {
+  return <T>(ref: { id: string; T: T; toString(): string }): Promise<T> =>
+    registry.get(ref, { pluginId: CONSUMER_PLUGIN_ID });
+}
+
+/** A provider-style fake connection store keyed by the real ref id. */
+interface FakeConnectionStore {
+  getConnectionWithCredentials(
+    connectionId: string,
+  ): Promise<{ config: Record<string, unknown> } | undefined>;
+}
+
+function automation(actions: unknown[]): LoadedAutomation {
+  const definition = AutomationDefinitionSchema.parse({
+    name: "Test",
+    triggers: [{ event: "test.event" }],
+    conditions: [],
+    actions,
+    mode: "single",
+    max_runs: 10,
+  });
+  return { id: "auto-1", name: "Test", status: "enabled", definition };
+}
+
+/**
+ * A provider-style action that resolves the connection store via
+ * `getService` (mirroring `integration-jira-backend`'s `create_issue`) and
+ * produces an artifact echoing the resolved credential — so we can assert
+ * (a) resolution succeeded and (b) the credential is masked in step output.
+ */
+function makeProviderAction(opts?: { storeRefId?: string }): {
+  definition: ActionDefinition<{ connectionId: string }, { token: string }>;
+  artifactType: ArtifactTypeDefinition<{ token: string }>;
+  resolved: string[];
+} {
+  const resolved: string[] = [];
+  const storeRefId = opts?.storeRefId ?? CONNECTION_STORE_REF_ID;
+  // Ref typed to the minimal shape the action uses; same id as the real
+  // `connectionStoreRef` so the run-secret masking interceptor matches.
+  const storeRef = createServiceRef<FakeConnectionStore>(storeRefId);
+  return {
+    artifactType: {
+      id: "issue",
+      displayName: "Issue (fake provider)",
+      schema: z.object({ token: z.string() }),
+    },
+    definition: {
+      id: "create_issue",
+      displayName: "Create Issue (fake provider)",
+      produces: "issue",
+      config: new Versioned({
+        version: 1,
+        schema: z.object({ connectionId: z.string() }),
+      }),
+      execute: async ({ config, getService }) => {
+        const store = await getService(storeRef);
+        const conn = await store.getConnectionWithCredentials(
+          config.connectionId,
+        );
+        const token = String(conn?.config.token ?? "");
+        resolved.push(token);
+        return { success: true, artifact: { token } };
+      },
+    },
+    resolved,
+  };
+}
+
+describe("dispatch getService wiring (cross-plugin resolution)", () => {
+  it("resolves a registered connection store through the real ServiceRegistry-backed getService", async () => {
+    const registry = new ServiceRegistry();
+    const fakeStore: FakeConnectionStore = {
+      async getConnectionWithCredentials() {
+        return { config: { token: "live-token-123", baseUrl: "https://x" } };
+      },
+    };
+    // Register under the REAL connection-store ref (typed `ConnectionStore`);
+    // the action resolves a same-id ref with a minimal structural shape.
+    registry.register(
+      connectionStoreRef,
+      fakeStore as unknown as (typeof connectionStoreRef)["T"],
+    );
+
+    const actions = createActionRegistry();
+    const artifactTypes = createArtifactTypeRegistry();
+    const provider = makeProviderAction();
+    actions.register(
+      provider.definition as ActionDefinition<unknown, unknown>,
+      testPlugin,
+    );
+    artifactTypes.register(
+      provider.artifactType as ArtifactTypeDefinition<unknown>,
+      testPlugin,
+    );
+
+    const { deps } = makeDispatchDeps({ actions, artifactTypes });
+    // Replace the test stub with the PRODUCTION assembly: env.getService.
+    const wired: DispatchDeps = {
+      ...deps,
+      getService: makeRegistryBackedGetService(registry),
+    };
+
+    const result = await dispatchTrigger(wired, {
+      automation: automation([
+        {
+          id: "create",
+          action: "test.create_issue",
+          config: { connectionId: "conn-1" },
+        },
+      ]),
+      triggerId: "test_event",
+      triggerEventId: "test.event",
+      payload: {},
+      contextKey: null,
+    });
+
+    expect(result.status).toBe("success");
+    // The action RESOLVED the fake store (did not throw "not yet wired").
+    expect(provider.resolved).toEqual(["live-token-123"]);
+  });
+
+  it("captures a credential resolved through the real getService into the run mask set (5c end-to-end)", async () => {
+    const registry = new ServiceRegistry();
+    const fakeStore: FakeConnectionStore = {
+      async getConnectionWithCredentials() {
+        return { config: { token: "secret-cred-XYZ" } };
+      },
+    };
+    registry.register(
+      connectionStoreRef,
+      fakeStore as unknown as (typeof connectionStoreRef)["T"],
+    );
+
+    const actions = createActionRegistry();
+    const artifactTypes = createArtifactTypeRegistry();
+    const provider = makeProviderAction();
+    actions.register(
+      provider.definition as ActionDefinition<unknown, unknown>,
+      testPlugin,
+    );
+    artifactTypes.register(
+      provider.artifactType as ArtifactTypeDefinition<unknown>,
+      testPlugin,
+    );
+
+    const { deps, runs } = makeDispatchDeps({ actions, artifactTypes });
+    // Production assembly: real getService + run-secret registry + ref ids.
+    // The engine wraps each run's getService (wrapGetServiceForRun): once
+    // the real getService is wired, resolving the connection store
+    // registers the credential into the run's mask set, which the run-state
+    // persistence choke point then masks before write (covered by
+    // run-state-masking.test.ts).
+    const secretRegistry = createRunSecretRegistry();
+    const wired: DispatchDeps = {
+      ...deps,
+      getService: makeRegistryBackedGetService(registry),
+      secretRegistry,
+      secretResolverRefId: SECRET_RESOLVER_REF_ID,
+      connectionStoreRefId: CONNECTION_STORE_REF_ID,
+    };
+
+    const result = await dispatchTrigger(wired, {
+      automation: automation([
+        {
+          id: "create",
+          action: "test.create_issue",
+          config: { connectionId: "conn-1" },
+        },
+      ]),
+      triggerId: "test_event",
+      triggerEventId: "test.event",
+      payload: {},
+      contextKey: null,
+    });
+
+    expect(result.status).toBe("success");
+    expect(provider.resolved).toEqual(["secret-cred-XYZ"]);
+    // The run's mask set captured the resolved credential — proving the
+    // real getService activates Phase-5c masking. Without the fix (throwing
+    // stub) the action never resolves and nothing is captured.
+    const runId = runs.runs.keys().next().value as string;
+    expect(secretRegistry.maskText(runId, "token=secret-cred-XYZ")).toBe(
+      "token=****",
+    );
+  });
+
+  it("throws a clear error when an action resolves an UNregistered ref (fail loud, not undefined)", async () => {
+    const registry = new ServiceRegistry();
+    // Intentionally register nothing.
+    const actions = createActionRegistry();
+    const artifactTypes = createArtifactTypeRegistry();
+    const provider = makeProviderAction();
+    actions.register(
+      provider.definition as ActionDefinition<unknown, unknown>,
+      testPlugin,
+    );
+    artifactTypes.register(
+      provider.artifactType as ArtifactTypeDefinition<unknown>,
+      testPlugin,
+    );
+
+    const { deps, runs } = makeDispatchDeps({ actions, artifactTypes });
+    const wired: DispatchDeps = {
+      ...deps,
+      getService: makeRegistryBackedGetService(registry),
+    };
+
+    const result = await dispatchTrigger(wired, {
+      automation: automation([
+        {
+          id: "create",
+          action: "test.create_issue",
+          config: { connectionId: "conn-1" },
+        },
+      ]),
+      triggerId: "test_event",
+      triggerEventId: "test.event",
+      payload: {},
+      contextKey: null,
+    });
+
+    // The run fails loudly (resolution threw) rather than the action seeing
+    // `undefined` and behaving unpredictably.
+    expect(result.status).toBe("failed");
+    const step = runs.steps.find((s) => s.actionId === "create");
+    expect(step?.status).toBe("failed");
+    expect(step?.errorMessage).toContain(CONNECTION_STORE_REF_ID);
+  });
+});
+
+/**
+ * Guard for the EXACT regression class: the production dispatchDeps must
+ * assemble a REAL, registry-backed `getService` — never a throwing stub.
+ * `index.ts` builds it via `assembleDispatchGetService({ envGetService })`,
+ * so exercising that helper with a real ServiceRegistry-backed env proves
+ * the assembled value resolves registered refs and fails loud on missing
+ * ones.
+ */
+describe("assembleDispatchGetService (production dispatchDeps.getService)", () => {
+  function envGetServiceFor(registry: ServiceRegistry) {
+    return <T>(ref: { id: string; T: T; toString(): string }): Promise<T> =>
+      registry.get(ref, { pluginId: CONSUMER_PLUGIN_ID });
+  }
+
+  it("is NOT a throwing stub — resolves a registered ref", async () => {
+    const registry = new ServiceRegistry();
+    const ref = createServiceRef<{ ok: boolean }>("some.service");
+    registry.register(ref, { ok: true });
+
+    const getService = assembleDispatchGetService({
+      envGetService: envGetServiceFor(registry),
+    });
+    const resolved = await getService(ref);
+    expect(resolved.ok).toBe(true);
+  });
+
+  it("propagates a clear error on a missing ref (fail loud)", async () => {
+    const registry = new ServiceRegistry();
+    const getService = assembleDispatchGetService({
+      envGetService: envGetServiceFor(registry),
+    });
+    const ref = createServiceRef<{ ok: boolean }>("absent.service");
+
+    let error: unknown;
+    try {
+      await getService(ref);
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toContain("absent.service");
+  });
+});

package/src/dispatch/numeric.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "bun:test";
+import {
+  extractNumericField,
+  matchesThreshold,
+  toNumberOrNull,
+} from "./numeric";
+
+describe("toNumberOrNull", () => {
+  it("passes finite numbers", () => {
+    expect(toNumberOrNull(42)).toBe(42);
+    expect(toNumberOrNull(0)).toBe(0);
+  });
+  it("coerces numeric strings", () => {
+    expect(toNumberOrNull("500")).toBe(500);
+    expect(toNumberOrNull("3.14")).toBeCloseTo(3.14, 5);
+  });
+  it("rejects non-numeric / empty / nullish", () => {
+    expect(toNumberOrNull("abc")).toBeNull();
+    expect(toNumberOrNull("")).toBeNull();
+    expect(toNumberOrNull(null)).toBeNull();
+    expect(toNumberOrNull(undefined)).toBeNull();
+    expect(toNumberOrNull({})).toBeNull();
+    expect(toNumberOrNull(Number.POSITIVE_INFINITY)).toBeNull();
+  });
+});
+
+describe("matchesThreshold", () => {
+  it("above only", () => {
+    expect(matchesThreshold({ value: 600, above: 500 })).toBe(true);
+    expect(matchesThreshold({ value: 500, above: 500 })).toBe(false); // strict
+    expect(matchesThreshold({ value: 400, above: 500 })).toBe(false);
+  });
+  it("below only", () => {
+    expect(matchesThreshold({ value: 50, below: 100 })).toBe(true);
+    expect(matchesThreshold({ value: 100, below: 100 })).toBe(false);
+    expect(matchesThreshold({ value: 150, below: 100 })).toBe(false);
+  });
+  it("both bounds require a band", () => {
+    expect(matchesThreshold({ value: 75, above: 50, below: 100 })).toBe(true);
+    expect(matchesThreshold({ value: 25, above: 50, below: 100 })).toBe(false);
+    expect(matchesThreshold({ value: 125, above: 50, below: 100 })).toBe(false);
+  });
+  it("null value never matches; no bounds never matches", () => {
+    expect(matchesThreshold({ value: null, above: 1 })).toBe(false);
+    expect(matchesThreshold({ value: 5 })).toBe(false);
+  });
+});
+
+describe("extractNumericField", () => {
+  it("reads top-level latencyMs", () => {
+    expect(extractNumericField({ latencyMs: 123 }, "latencyMs")).toBe(123);
+  });
+  it("reads a collector field under result (the collectors map)", () => {
+    const payload = {
+      result: { http: { responseTimeMs: 250 } },
+    };
+    expect(
+      extractNumericField(payload, "collectors.http.responseTimeMs"),
+    ).toBe(250);
+    // the `collectors.` prefix is optional
+    expect(
+      extractNumericField(payload, "http.responseTimeMs"),
+    ).toBe(250);
+  });
+  it("returns null for an absent / non-numeric path", () => {
+    expect(extractNumericField({}, "latencyMs")).toBeNull();
+    expect(
+      extractNumericField({ result: {} }, "collectors.x.y"),
+    ).toBeNull();
+  });
+});

package/src/dispatch/numeric.ts

@@ -0,0 +1,96 @@
+/**
+ * Shared pure helpers for numeric threshold evaluation, used by both the
+ * `numeric_state` trigger and the `numeric_state` condition.
+ *
+ * No I/O, fully synchronous.
+ */
+
+/**
+ * Resolve a numeric value from an unknown input. Accepts numbers and
+ * numeric strings; everything else (null, undefined, non-numeric string,
+ * object) is "no value" → null.
+ */
+export function toNumberOrNull(value: unknown): number | null {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+
+/**
+ * Compare a numeric value against optional `above` / `below` bounds.
+ * Returns true when the value is strictly above `above` AND/OR strictly
+ * below `below` (whichever bounds are provided). With both bounds set,
+ * the value must satisfy BOTH (i.e. `above < value < below` for a band,
+ * or `value > above && value < below`). With neither bound, returns
+ * false (a threshold with no bounds never matches).
+ *
+ * A null value never matches.
+ */
+export function matchesThreshold(args: {
+  value: number | null;
+  above?: number;
+  below?: number;
+}): boolean {
+  const { value, above, below } = args;
+  if (value === null) return false;
+  if (above === undefined && below === undefined) return false;
+  if (above !== undefined && !(value > above)) return false;
+  if (below !== undefined && !(value < below)) return false;
+  return true;
+}
+
+/**
+ * Extract a numeric field from a `healthcheck.check.completed` payload.
+ *
+ * The hook payload's shape is:
+ *
+ *   { systemId, configurationId, status, latencyMs?, result?, timestamp }
+ *
+ * where `result` is the per-check collectors map
+ * (`{ <collectorId>: { <field>: value, … }, … }`).
+ *
+ * Supported field paths:
+ *   - `latencyMs`                → payload.latencyMs (top-level)
+ *   - `collectors.<id>.<field>`  → payload.result.<id>.<field>
+ *   - `<id>.<field>`             → payload.result.<id>.<field>
+ *
+ * (`p95LatencyMs` is a windowed aggregate, absent per-check — read it via
+ * the `health.*` scope / a `numeric_state` condition instead.)
+ *
+ * Returns null when the path is absent or non-numeric.
+ */
+export function extractNumericField(
+  payload: Record<string, unknown>,
+  field: string,
+): number | null {
+  // Top-level latency is the common case.
+  if (field === "latencyMs") {
+    return toNumberOrNull(payload.latencyMs);
+  }
+
+  // Everything else is a collector field under `result` (the collectors
+  // map). Accept an optional leading `collectors.` for readability.
+  const collectors = isRecord(payload.result) ? payload.result : undefined;
+  if (!collectors) return null;
+  const path = field.startsWith("collectors.")
+    ? field.slice("collectors.".length)
+    : field;
+  return toNumberOrNull(resolvePath(collectors, path));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Resolve a dotted path against a nested record. Returns undefined on miss. */
+function resolvePath(root: Record<string, unknown>, path: string): unknown {
+  let current: unknown = root;
+  for (const segment of path.split(".")) {
+    if (!isRecord(current)) return undefined;
+    current = current[segment];
+  }
+  return current;
+}