@oneuptime/common 11.7.3 → 12.0.0

package/Tests/Types/Runbook/RunbookStepType.test.ts

@@ -0,0 +1,242 @@
+import RunbookStepType, {
+  RUNNER_EXECUTED_STEP_TYPES,
+  isRunnerExecutedStepType,
+} from "../../../Types/Runbook/RunbookStepType";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * Contract under test — the one list that decides where a runbook step runs.
+ *
+ * Every step type is in exactly one of two lanes: it executes on a Runner
+ * inside the customer's network (JavaScript, Bash, SSH, Kubernetes), or it
+ * executes on the OneUptime Worker (Manual, HttpRequest, AI). The lane is not
+ * a preference — a Runner has no implementation for an AI step, and the
+ * Worker has no route to a customer's SSH host.
+ *
+ * Getting the lane wrong is not a graceful failure. Classifying a Worker type
+ * as Runner work enqueues a RunnerJob a Runner will claim and cannot
+ * execute; classifying a Runner type as Worker work drops the step's agentId
+ * on the floor and tries to run customer infrastructure commands on shared
+ * OneUptime infrastructure. RunnerJobService.enqueue is the gate, and
+ * it asks this function.
+ *
+ * So the list is pinned member by member, and the partition is checked to be
+ * total and disjoint — a new step type must be placed deliberately rather
+ * than defaulting into a lane.
+ */
+
+const WORKER_EXECUTED_STEP_TYPES: Array<RunbookStepType> = [
+  RunbookStepType.Manual,
+  RunbookStepType.HttpRequest,
+  RunbookStepType.AI,
+];
+
+describe("RunbookStepType enum", () => {
+  test("the full set of step types is what these tests assume", () => {
+    /*
+     * If this fails, a step type was added. Decide which lane it belongs in,
+     * add it to RUNNER_EXECUTED_STEP_TYPES or to WORKER_EXECUTED_STEP_TYPES
+     * above, and only then update this list. Leaving it unplaced is what the
+     * partition tests below exist to prevent.
+     */
+    expect(Object.values(RunbookStepType).sort()).toEqual(
+      ["AI", "Bash", "HttpRequest", "JavaScript", "Kubernetes", "Manual", "SSH"]
+        .slice()
+        .sort(),
+    );
+  });
+
+  test("each member's value matches its name", () => {
+    /*
+     * stepType is persisted as a plain string column and travels to the
+     * Runner as JSON, so the string IS the wire contract. Renaming a member
+     * without keeping the value would orphan every stored step.
+     */
+    expect(RunbookStepType.Manual).toBe("Manual");
+    expect(RunbookStepType.JavaScript).toBe("JavaScript");
+    expect(RunbookStepType.HttpRequest).toBe("HttpRequest");
+    expect(RunbookStepType.Bash).toBe("Bash");
+    expect(RunbookStepType.AI).toBe("AI");
+    expect(RunbookStepType.SSH).toBe("SSH");
+    expect(RunbookStepType.Kubernetes).toBe("Kubernetes");
+  });
+});
+
+describe("RUNNER_EXECUTED_STEP_TYPES", () => {
+  test("contains exactly JavaScript, Bash, SSH and Kubernetes", () => {
+    /*
+     * Pinned as an exact list, order included. This array is the whole
+     * definition of "work a Runner may be handed" — a silent addition would
+     * widen it everywhere at once.
+     */
+    expect(RUNNER_EXECUTED_STEP_TYPES).toEqual([
+      RunbookStepType.JavaScript,
+      RunbookStepType.Bash,
+      RunbookStepType.SSH,
+      RunbookStepType.Kubernetes,
+    ]);
+  });
+
+  test("has exactly four entries and no duplicates", () => {
+    expect(RUNNER_EXECUTED_STEP_TYPES).toHaveLength(4);
+    expect(new Set(RUNNER_EXECUTED_STEP_TYPES).size).toBe(
+      RUNNER_EXECUTED_STEP_TYPES.length,
+    );
+  });
+
+  test("every entry is a real member of the enum", () => {
+    /*
+     * The array is typed Array<RunbookStepType>, but the values reach the
+     * database and the Runner as strings. A typo'd literal that widened past
+     * the type (or arrived through a cast) would be a lane nobody can enter.
+     */
+    const members: Array<string> = Object.values(RunbookStepType);
+
+    for (const type of RUNNER_EXECUTED_STEP_TYPES) {
+      expect(members).toContain(type);
+    }
+  });
+
+  test("contains no Worker-executed type", () => {
+    for (const type of WORKER_EXECUTED_STEP_TYPES) {
+      expect(RUNNER_EXECUTED_STEP_TYPES).not.toContain(type);
+    }
+  });
+
+  test("holds the two step types the credential store exists for", () => {
+    // SSH and Kubernetes are useless unless a Runner can be handed them.
+    expect(RUNNER_EXECUTED_STEP_TYPES).toContain(RunbookStepType.SSH);
+    expect(RUNNER_EXECUTED_STEP_TYPES).toContain(RunbookStepType.Kubernetes);
+  });
+});
+
+describe("isRunnerExecutedStepType", () => {
+  test.each([
+    RunbookStepType.JavaScript,
+    RunbookStepType.Bash,
+    RunbookStepType.SSH,
+    RunbookStepType.Kubernetes,
+  ])("%s runs on a Runner", (type: RunbookStepType) => {
+    expect(isRunnerExecutedStepType(type)).toBe(true);
+  });
+
+  test.each([
+    RunbookStepType.Manual,
+    RunbookStepType.HttpRequest,
+    RunbookStepType.AI,
+  ])("%s runs on the Worker, not a Runner", (type: RunbookStepType) => {
+    /*
+     * Manual waits on a human, HttpRequest is an outbound call the Worker can
+     * already make, and AI needs the model provider and the project's budget
+     * — none of which exist on a Runner. Answering true here would hand a
+     * Runner a step it has no executor for, and the job would sit claimed
+     * until it timed out.
+     */
+    expect(isRunnerExecutedStepType(type)).toBe(false);
+  });
+
+  test("returns a boolean for every member of the enum", () => {
+    /*
+     * No member may fall through to undefined: RunnerJobService.enqueue
+     * branches on `!isRunnerExecutedStepType(...)`, so an undefined answer
+     * would read as "the Worker handles it" and quietly refuse to dispatch.
+     */
+    for (const type of Object.values(RunbookStepType)) {
+      const answer: boolean = isRunnerExecutedStepType(type);
+
+      expect(typeof answer).toBe("boolean");
+    }
+  });
+
+  test("the two lanes together cover every member exactly once", () => {
+    /*
+     * Total and disjoint. A future step type that is added to the enum but to
+     * neither lane fails here rather than being discovered by whichever
+     * dispatcher happens to see it first.
+     */
+    const members: Array<RunbookStepType> = Object.values(RunbookStepType);
+    const runner: Array<RunbookStepType> = members.filter(
+      (type: RunbookStepType) => {
+        return isRunnerExecutedStepType(type);
+      },
+    );
+    const worker: Array<RunbookStepType> = members.filter(
+      (type: RunbookStepType) => {
+        return !isRunnerExecutedStepType(type);
+      },
+    );
+
+    expect(runner.length + worker.length).toBe(members.length);
+    expect(runner.slice().sort()).toEqual(
+      RUNNER_EXECUTED_STEP_TYPES.slice().sort(),
+    );
+    expect(worker.slice().sort()).toEqual(
+      WORKER_EXECUTED_STEP_TYPES.slice().sort(),
+    );
+  });
+
+  test("agrees with the exported list for every member", () => {
+    /*
+     * The point of exporting both is that callers may read either one. They
+     * must never disagree — the list is the source, the function is a lookup
+     * over it.
+     */
+    for (const type of Object.values(RunbookStepType)) {
+      expect(isRunnerExecutedStepType(type)).toBe(
+        RUNNER_EXECUTED_STEP_TYPES.includes(type),
+      );
+    }
+  });
+
+  test("does not match on anything that is not a step type", () => {
+    /*
+     * stepType arrives from a stored JSON step config, so at run time it is
+     * whatever string is in the row — not necessarily an enum member.
+     */
+    const notStepTypes: Array<string> = [
+      "",
+      " ",
+      "Runner",
+      "Shell",
+      "Docker",
+      "undefined",
+      "null",
+    ];
+
+    for (const value of notStepTypes) {
+      expect(isRunnerExecutedStepType(value as RunbookStepType)).toBe(false);
+    }
+  });
+
+  test("is case- and whitespace-sensitive", () => {
+    /*
+     * "ssh" is not SSH. A near-miss must be refused outright rather than
+     * normalised here, so that the mismatch surfaces at enqueue with a
+     * message naming the bad type instead of silently selecting a lane.
+     */
+    const nearMisses: Array<string> = [
+      "ssh",
+      "Ssh",
+      "SSH ",
+      " SSH",
+      "kubernetes",
+      "KUBERNETES",
+      "bash",
+      "JAVASCRIPT",
+    ];
+
+    for (const value of nearMisses) {
+      expect(isRunnerExecutedStepType(value as RunbookStepType)).toBe(false);
+    }
+  });
+
+  test("null and undefined are not Runner work", () => {
+    // Older step rows can carry no stepType at all.
+    expect(
+      isRunnerExecutedStepType(undefined as unknown as RunbookStepType),
+    ).toBe(false);
+    expect(isRunnerExecutedStepType(null as unknown as RunbookStepType)).toBe(
+      false,
+    );
+  });
+});

package/Tests/Types/Telemetry/DropFilterSampling.test.ts

@@ -0,0 +1,241 @@
+import {
+  isSamplePercentageConfigured,
+  KEEP_ALL_PERCENTAGE,
+  MAX_SAMPLE_PERCENTAGE,
+  MIN_SAMPLE_PERCENTAGE,
+  resolveSamplePercentage,
+  shouldDropBySampling,
+} from "../../../Types/Telemetry/DropFilterSampling";
+import { describe, expect, it } from "@jest/globals";
+
+/*
+ * Contract under test — how a drop filter's `samplePercentage` turns into a
+ * keep/discard decision.
+ *
+ * This replaced `filter.samplePercentage || 50`, duplicated in the log and
+ * trace drop-filter engines. That expression silently destroyed data three
+ * ways, and each one has a test below:
+ *
+ *   1. `samplePercentage` is nullable with no default and its form field was
+ *      optional, so an UNSET percentage meant "discard half of every
+ *      matching record" — a number nobody chose.
+ *   2. A stored `0` is falsy, so it was indistinguishable from unset and
+ *      also kept 50%, contradicting both the literal reading ("keep 0%") and
+ *      the view page's display of "0% kept".
+ *   3. Two copies of the expression could drift apart.
+ *
+ * The rule now is to fail SAFE: any percentage we cannot honour makes the
+ * filter a no-op rather than a shredder. `drop` exists for "discard
+ * everything matching", so nothing of value is lost by refusing to guess.
+ */
+
+describe("resolveSamplePercentage", () => {
+  it("honours a percentage inside the usable range", () => {
+    expect(resolveSamplePercentage(1)).toBe(1);
+    expect(resolveSamplePercentage(10)).toBe(10);
+    expect(resolveSamplePercentage(50)).toBe(50);
+    expect(resolveSamplePercentage(99)).toBe(99);
+  });
+
+  it("honours a fractional percentage inside the range", () => {
+    expect(resolveSamplePercentage(0.5)).toBe(0.5);
+    expect(resolveSamplePercentage(99.9)).toBe(99.9);
+  });
+
+  /*
+   * The headline regression. `undefined || 50` was 50, so a sample filter
+   * saved with no percentage threw away roughly half of everything it
+   * matched, and nothing recorded that it had happened.
+   */
+  it("resolves an UNSET percentage to keep-everything, not the old 50", () => {
+    expect(resolveSamplePercentage(undefined)).toBe(KEEP_ALL_PERCENTAGE);
+    expect(resolveSamplePercentage(null)).toBe(KEEP_ALL_PERCENTAGE);
+    expect(resolveSamplePercentage(undefined)).not.toBe(50);
+    expect(resolveSamplePercentage(null)).not.toBe(50);
+  });
+
+  /*
+   * 0 never meant "keep nothing" in any shipped version — it was falsy, so
+   * it kept half. Honouring it literally now would start deleting data that
+   * used to survive, so it is treated as misconfigured instead.
+   */
+  it("treats 0 as misconfigured rather than 'discard everything'", () => {
+    expect(resolveSamplePercentage(0)).toBe(KEEP_ALL_PERCENTAGE);
+  });
+
+  it("treats a negative percentage as misconfigured", () => {
+    expect(resolveSamplePercentage(-1)).toBe(KEEP_ALL_PERCENTAGE);
+    expect(resolveSamplePercentage(-100)).toBe(KEEP_ALL_PERCENTAGE);
+  });
+
+  it("clamps 100 and above to keep-everything", () => {
+    expect(resolveSamplePercentage(100)).toBe(KEEP_ALL_PERCENTAGE);
+    expect(resolveSamplePercentage(1000)).toBe(KEEP_ALL_PERCENTAGE);
+  });
+
+  it("rejects non-finite numbers", () => {
+    expect(resolveSamplePercentage(NaN)).toBe(KEEP_ALL_PERCENTAGE);
+    expect(resolveSamplePercentage(Infinity)).toBe(KEEP_ALL_PERCENTAGE);
+    expect(resolveSamplePercentage(-Infinity)).toBe(KEEP_ALL_PERCENTAGE);
+  });
+
+  /*
+   * The column is nullable and typed `number`, but the value arrives through
+   * a bigint-free JSON boundary and a form. A string that happens to look
+   * like a number must not be treated as one — `"50" || 50` would have been
+   * "50", and `Math.random() * 100 >= "50"` coerces, so the old code would
+   * have sampled on a string. Now it fails safe.
+   */
+  it("rejects a value that is not a number at all", () => {
+    expect(resolveSamplePercentage("10" as unknown as number)).toBe(
+      KEEP_ALL_PERCENTAGE,
+    );
+    expect(resolveSamplePercentage({} as unknown as number)).toBe(
+      KEEP_ALL_PERCENTAGE,
+    );
+    expect(resolveSamplePercentage([] as unknown as number)).toBe(
+      KEEP_ALL_PERCENTAGE,
+    );
+    expect(resolveSamplePercentage(true as unknown as number)).toBe(
+      KEEP_ALL_PERCENTAGE,
+    );
+  });
+
+  it("accepts both ends of the range the validator enforces", () => {
+    expect(resolveSamplePercentage(MIN_SAMPLE_PERCENTAGE)).toBe(
+      MIN_SAMPLE_PERCENTAGE,
+    );
+    expect(resolveSamplePercentage(MAX_SAMPLE_PERCENTAGE)).toBe(
+      MAX_SAMPLE_PERCENTAGE,
+    );
+  });
+});
+
+describe("isSamplePercentageConfigured", () => {
+  it("is true only for a percentage the engine will actually sample on", () => {
+    expect(isSamplePercentageConfigured(1)).toBe(true);
+    expect(isSamplePercentageConfigured(50)).toBe(true);
+    expect(isSamplePercentageConfigured(99)).toBe(true);
+  });
+
+  /*
+   * This is what the view page keys off. It used to render `|| 0` as
+   * "0% kept / 100% discarded" for an unset percentage while the engine kept
+   * half — the display and the behaviour disagreed, and both were wrong.
+   */
+  it("is false for the values that used to render as '0% kept'", () => {
+    expect(isSamplePercentageConfigured(undefined)).toBe(false);
+    expect(isSamplePercentageConfigured(null)).toBe(false);
+    expect(isSamplePercentageConfigured(0)).toBe(false);
+  });
+
+  it("is false at and above 100, where sampling is a no-op", () => {
+    expect(isSamplePercentageConfigured(100)).toBe(false);
+    expect(isSamplePercentageConfigured(150)).toBe(false);
+  });
+});
+
+describe("shouldDropBySampling", () => {
+  /*
+   * `random` is injected so these are exact assertions rather than
+   * statistical ones. The engine keeps a record when
+   * `random() * 100 < keepPercentage`.
+   */
+  const fixedRandom: (value: number) => () => number = (
+    value: number,
+  ): (() => number) => {
+    return (): number => {
+      return value;
+    };
+  };
+
+  it("keeps a record when the draw lands inside the keep window", () => {
+    // 0.05 * 100 = 5, which is < 10, so this record is kept.
+    expect(shouldDropBySampling(10, fixedRandom(0.05))).toBe(false);
+  });
+
+  it("drops a record when the draw lands outside the keep window", () => {
+    // 0.5 * 100 = 50, which is >= 10, so this record is dropped.
+    expect(shouldDropBySampling(10, fixedRandom(0.5))).toBe(true);
+  });
+
+  it("drops exactly at the boundary, so keep-10% never keeps 11%", () => {
+    // >= is the comparison, so a draw of exactly the keep percentage drops.
+    expect(shouldDropBySampling(10, fixedRandom(0.1))).toBe(true);
+  });
+
+  it("keeps everything when the percentage is unset", () => {
+    for (const draw of [0, 0.25, 0.5, 0.75, 0.999]) {
+      expect(shouldDropBySampling(undefined, fixedRandom(draw))).toBe(false);
+    }
+  });
+
+  it("keeps everything when the percentage is 0", () => {
+    for (const draw of [0, 0.5, 0.999]) {
+      expect(shouldDropBySampling(0, fixedRandom(draw))).toBe(false);
+    }
+  });
+
+  /*
+   * A keep-everything filter should not even consume entropy: the cheap
+   * check has to come before the draw, because this runs once per ingested
+   * record on the hot path.
+   */
+  it("does not consult random at all when it is keeping everything", () => {
+    let calls: number = 0;
+    const countingRandom: () => number = (): number => {
+      calls++;
+      return 0.5;
+    };
+
+    expect(shouldDropBySampling(undefined, countingRandom)).toBe(false);
+    expect(shouldDropBySampling(0, countingRandom)).toBe(false);
+    expect(shouldDropBySampling(100, countingRandom)).toBe(false);
+    expect(calls).toBe(0);
+  });
+
+  it("consults random exactly once when it is sampling", () => {
+    let calls: number = 0;
+    const countingRandom: () => number = (): number => {
+      calls++;
+      return 0.5;
+    };
+
+    shouldDropBySampling(10, countingRandom);
+    expect(calls).toBe(1);
+  });
+
+  /*
+   * End-to-end sanity on the distribution, using a deterministic sweep
+   * rather than real randomness so this can never flake.
+   */
+  it("keeps approximately the requested share over a uniform sweep", () => {
+    const draws: Array<number> = [];
+    for (let i: number = 0; i < 1000; i++) {
+      draws.push(i / 1000);
+    }
+
+    for (const keepPercentage of [1, 10, 25, 50, 90, 99]) {
+      let kept: number = 0;
+      for (const draw of draws) {
+        if (!shouldDropBySampling(keepPercentage, fixedRandom(draw))) {
+          kept++;
+        }
+      }
+      // Exact for a uniform sweep of 1000 draws over [0, 1).
+      expect(kept / 10).toBeCloseTo(keepPercentage, 5);
+    }
+  });
+
+  it("defaults to Math.random when no generator is injected", () => {
+    // keep-99% over many real draws should keep at least one record.
+    let keptAtLeastOne: boolean = false;
+    for (let i: number = 0; i < 200; i++) {
+      if (!shouldDropBySampling(99)) {
+        keptAtLeastOne = true;
+        break;
+      }
+    }
+    expect(keptAtLeastOne).toBe(true);
+  });
+});

package/Tests/Types/Telemetry/TelemetryRetentionConfig.test.ts

@@ -0,0 +1,225 @@
+import TelemetryRetentionConfig, {
+  HARDCODED_DEFAULT_TELEMETRY_RETENTION_IN_DAYS,
+  resolveTelemetryRetentionInDays,
+} from "../../../Types/Telemetry/TelemetryRetentionConfig";
+import LogSeverity from "../../../Types/Log/LogSeverity";
+import { SpanStatus } from "../../../Models/AnalyticsModels/Span";
+import { describe, expect, it } from "@jest/globals";
+
+type RetentionInput = {
+  pillar: "logs";
+  bucketKey?: LogSeverity | null;
+  serviceConfig?: TelemetryRetentionConfig | null;
+  serviceRetentionInDays?: number | null;
+  projectConfig?: TelemetryRetentionConfig | null;
+  projectRetentionInDays?: number | null;
+};
+
+describe("resolveTelemetryRetentionInDays", () => {
+  describe("hardcoded fallback", () => {
+    it("returns the hardcoded default when nothing is configured", () => {
+      expect(resolveTelemetryRetentionInDays({ pillar: "logs" })).toBe(
+        HARDCODED_DEFAULT_TELEMETRY_RETENTION_IN_DAYS,
+      );
+    });
+
+    it("keeps the hardcoded default at 15 days", () => {
+      // Pinning the constant guards the sessionReplay comment's assumptions.
+      expect(HARDCODED_DEFAULT_TELEMETRY_RETENTION_IN_DAYS).toBe(15);
+    });
+
+    it("falls back to hardcoded default when every candidate is non-positive", () => {
+      expect(
+        resolveTelemetryRetentionInDays({
+          pillar: "metrics",
+          serviceRetentionInDays: 0,
+          projectRetentionInDays: -5,
+          serviceConfig: { metrics: { default: 0 } },
+          projectConfig: { metrics: { default: null } },
+        }),
+      ).toBe(HARDCODED_DEFAULT_TELEMETRY_RETENTION_IN_DAYS);
+    });
+  });
+
+  describe("precedence order (narrowest first)", () => {
+    /*
+     * A fully-populated config where every one of the six levels holds a
+     * distinct positive value, so each test can prove exactly which level won
+     * by the number it returns.
+     */
+    const fullInput: () => RetentionInput = (): RetentionInput => {
+      return {
+        pillar: "logs",
+        bucketKey: LogSeverity.Error,
+        serviceConfig: {
+          logs: { default: 2, bySeverity: { [LogSeverity.Error]: 1 } },
+        },
+        serviceRetentionInDays: 3,
+        projectConfig: {
+          logs: { default: 5, bySeverity: { [LogSeverity.Error]: 4 } },
+        },
+        projectRetentionInDays: 6,
+      };
+    };
+
+    it("1. service bucket value wins over everything else", () => {
+      expect(resolveTelemetryRetentionInDays(fullInput())).toBe(1);
+    });
+
+    it("2. service pillar default wins when no service bucket value", () => {
+      const input: RetentionInput = fullInput();
+      input.serviceConfig = { logs: { default: 2 } };
+      expect(resolveTelemetryRetentionInDays(input)).toBe(2);
+    });
+
+    it("3. service retention days wins when no service pillar config", () => {
+      const input: RetentionInput = fullInput();
+      input.serviceConfig = null;
+      expect(resolveTelemetryRetentionInDays(input)).toBe(3);
+    });
+
+    it("4. project bucket value wins when no service-level value", () => {
+      const input: RetentionInput = fullInput();
+      input.serviceConfig = null;
+      input.serviceRetentionInDays = null;
+      expect(resolveTelemetryRetentionInDays(input)).toBe(4);
+    });
+
+    it("5. project pillar default wins when no project bucket value", () => {
+      const input: RetentionInput = fullInput();
+      input.serviceConfig = null;
+      input.serviceRetentionInDays = null;
+      input.projectConfig = { logs: { default: 5 } };
+      expect(resolveTelemetryRetentionInDays(input)).toBe(5);
+    });
+
+    it("6. project retention days is the last configured candidate", () => {
+      const input: RetentionInput = fullInput();
+      input.serviceConfig = null;
+      input.serviceRetentionInDays = null;
+      input.projectConfig = null;
+      expect(resolveTelemetryRetentionInDays(input)).toBe(6);
+    });
+  });
+
+  describe("non-positive values are skipped, not treated as configured", () => {
+    it("skips a zero service bucket value and falls to the next candidate", () => {
+      expect(
+        resolveTelemetryRetentionInDays({
+          pillar: "logs",
+          bucketKey: LogSeverity.Warning,
+          serviceConfig: {
+            logs: { default: 30, bySeverity: { [LogSeverity.Warning]: 0 } },
+          },
+        }),
+      ).toBe(30);
+    });
+
+    it("skips a negative pillar default and falls through to project retention", () => {
+      expect(
+        resolveTelemetryRetentionInDays({
+          pillar: "metrics",
+          serviceConfig: { metrics: { default: -10 } },
+          projectRetentionInDays: 45,
+        }),
+      ).toBe(45);
+    });
+
+    it("treats a null bucket value as unset", () => {
+      expect(
+        resolveTelemetryRetentionInDays({
+          pillar: "traces",
+          bucketKey: SpanStatus.Error,
+          serviceConfig: {
+            traces: { default: 12, byStatus: { [SpanStatus.Error]: null } },
+          },
+        }),
+      ).toBe(12);
+    });
+  });
+
+  describe("bucket keys", () => {
+    it("ignores the bucket when bucketKey is not provided", () => {
+      expect(
+        resolveTelemetryRetentionInDays({
+          pillar: "logs",
+          serviceConfig: {
+            logs: { default: 20, bySeverity: { [LogSeverity.Error]: 99 } },
+          },
+        }),
+      ).toBe(20);
+    });
+
+    it("only matches the bucket for the exact key", () => {
+      const config: TelemetryRetentionConfig = {
+        logs: {
+          default: 20,
+          bySeverity: {
+            [LogSeverity.Error]: 99,
+            [LogSeverity.Warning]: 50,
+          },
+        },
+      };
+      expect(
+        resolveTelemetryRetentionInDays({
+          pillar: "logs",
+          bucketKey: LogSeverity.Warning,
+          serviceConfig: config,
+        }),
+      ).toBe(50);
+      expect(
+        resolveTelemetryRetentionInDays({
+          pillar: "logs",
+          bucketKey: LogSeverity.Fatal,
+          serviceConfig: config,
+        }),
+      ).toBe(20);
+    });
+
+    it("resolves trace retention by span status bucket", () => {
+      expect(
+        resolveTelemetryRetentionInDays({
+          pillar: "traces",
+          bucketKey: SpanStatus.Ok,
+          serviceConfig: {
+            traces: { default: 10, byStatus: { [SpanStatus.Ok]: 7 } },
+          },
+        }),
+      ).toBe(7);
+    });
+
+    it("ignores a bucketKey for pillars that have no buckets", () => {
+      // metrics has no per-bucket overrides; bucketKey must be a no-op.
+      expect(
+        resolveTelemetryRetentionInDays({
+          pillar: "metrics",
+          bucketKey: LogSeverity.Error,
+          serviceConfig: { metrics: { default: 8 } },
+        }),
+      ).toBe(8);
+    });
+  });
+
+  describe("null and undefined configs", () => {
+    it("handles null configs alongside a positive project retention", () => {
+      expect(
+        resolveTelemetryRetentionInDays({
+          pillar: "profiles",
+          serviceConfig: null,
+          projectConfig: null,
+          projectRetentionInDays: 21,
+        }),
+      ).toBe(21);
+    });
+
+    it("handles a config object that omits the requested pillar", () => {
+      expect(
+        resolveTelemetryRetentionInDays({
+          pillar: "profiles",
+          serviceConfig: { logs: { default: 30 } },
+          serviceRetentionInDays: 9,
+        }),
+      ).toBe(9);
+    });
+  });
+});