@oneuptime/common 12.0.31 → 12.0.33

package/Tests/Utils/Slo/SloEvaluation.test.ts

@@ -0,0 +1,171 @@
+import fs from "fs";
+import path from "path";
+import { describe, expect, test } from "@jest/globals";
+import {
+  SLO_CURRENT_BURN_RATE_WINDOW_MINUTES,
+  SLO_EVALUATION_CADENCE_MINUTES,
+} from "../../../Utils/Slo/SloEvaluation";
+
+/*
+ * The SLO cadence constants.
+ *
+ * These two numbers were prose before they were code — the worker owned them
+ * and the dashboard described them in words ("evaluated every few minutes",
+ * "1x spends the budget exactly over the window") without naming the lookback
+ * the headline burn rate is measured over. Naming them once was the fix, and
+ * each carries a claim about a number that lives somewhere else:
+ *
+ *   - the burn-rate window is "deliberately equal to the default fast-burn
+ *     rule's long window, so the tile and that rule move together", and
+ *   - the cadence is how often a due SLO is re-evaluated.
+ *
+ * Nothing makes either claim fail to compile. The seeded rules are written by
+ * ServiceLevelObjectiveService as plain literals, so someone retuning the
+ * fast-burn default there would leave an overview tile silently measuring a
+ * different span from the rule it is meant to agree with — the two would
+ * disagree on screen with no error anywhere.
+ *
+ * The defaults are read as text because seeding them is a database write
+ * behind a full SLO create, which is not what is under test here.
+ */
+
+const SLO_SERVICE_SOURCE: string = fs.readFileSync(
+  path.join(
+    __dirname,
+    "../../../Server/Services/ServiceLevelObjectiveService.ts",
+  ),
+  "utf8",
+);
+
+/*
+ * The literal block for one seeded rule, so "Fast burn" and "Slow burn"
+ * cannot be confused for one another — they differ only in their numbers.
+ */
+function seededRuleBlock(ruleName: string): string {
+  const start: number = SLO_SERVICE_SOURCE.indexOf(`name: "${ruleName}"`);
+
+  expect(start).toBeGreaterThan(-1);
+
+  const end: number = SLO_SERVICE_SOURCE.indexOf("}", start);
+  expect(end).toBeGreaterThan(start);
+
+  return SLO_SERVICE_SOURCE.slice(start, end);
+}
+
+function minutesFieldIn(block: string, field: string): number {
+  const match: RegExpMatchArray | null = block.match(
+    new RegExp(`${field}:\\s*(\\d+)`),
+  );
+
+  expect(match).not.toBeNull();
+
+  return Number(match![1]);
+}
+
+describe("SLO evaluation cadence constants", () => {
+  describe("the values themselves", () => {
+    /*
+     * Both are used as minutes and multiplied out to seconds by their
+     * callers, so a zero would ask for a zero-length lookback and a
+     * fractional value would land the query on a boundary no bucket starts
+     * on.
+     */
+    test("both are positive whole numbers of minutes", () => {
+      for (const value of [
+        SLO_EVALUATION_CADENCE_MINUTES,
+        SLO_CURRENT_BURN_RATE_WINDOW_MINUTES,
+      ]) {
+        expect(Number.isInteger(value)).toBe(true);
+        expect(value).toBeGreaterThan(0);
+      }
+    });
+
+    /*
+     * A burn rate measured over a span shorter than the gap between
+     * evaluations would be recomputed from data the worker has not refreshed,
+     * so the tile would repeat itself and call it a new reading.
+     */
+    test("the burn-rate lookback is at least one evaluation apart", () => {
+      expect(SLO_CURRENT_BURN_RATE_WINDOW_MINUTES).toBeGreaterThanOrEqual(
+        SLO_EVALUATION_CADENCE_MINUTES,
+      );
+    });
+  });
+
+  /*
+   * The claim in the doc comment, checked against the thing it is a claim
+   * about. If the fast-burn default is ever retuned, this fails here rather
+   * than as two numbers quietly disagreeing on the SLO overview.
+   */
+  describe("the tile and the default fast-burn rule move together", () => {
+    test("the burn-rate window equals the fast-burn rule's long window", () => {
+      expect(
+        minutesFieldIn(seededRuleBlock("Fast burn"), "longWindowInMinutes"),
+      ).toBe(SLO_CURRENT_BURN_RATE_WINDOW_MINUTES);
+    });
+
+    /*
+     * The fast-burn short window is the tightest span the worker is ever
+     * asked to answer for. Evaluating less often than that would leave it
+     * reading a window that has already closed.
+     */
+    test("the evaluation cadence keeps up with the fast-burn short window", () => {
+      expect(
+        minutesFieldIn(seededRuleBlock("Fast burn"), "shortWindowInMinutes"),
+      ).toBeGreaterThanOrEqual(SLO_EVALUATION_CADENCE_MINUTES);
+    });
+
+    /*
+     * Slow burn is the deliberately longer pair. Pinned only as an ordering
+     * against fast burn: if the two ever crossed over, the names would be
+     * backwards and the rule an operator reaches for in an incident would be
+     * the slower of the two.
+     */
+    test("slow burn is genuinely slower than fast burn", () => {
+      const fast: string = seededRuleBlock("Fast burn");
+      const slow: string = seededRuleBlock("Slow burn");
+
+      expect(minutesFieldIn(slow, "longWindowInMinutes")).toBeGreaterThan(
+        minutesFieldIn(fast, "longWindowInMinutes"),
+      );
+      expect(minutesFieldIn(slow, "shortWindowInMinutes")).toBeGreaterThan(
+        minutesFieldIn(fast, "shortWindowInMinutes"),
+      );
+    });
+  });
+
+  /*
+   * Both constants exist so the worker and the UI read the same number. A
+   * caller that inlined the value instead would drift the moment the constant
+   * changed, which is the exact failure the constants were introduced to end.
+   */
+  describe("everything reads the shared constants rather than its own copy", () => {
+    const WORKER_SOURCE: string = fs.readFileSync(
+      path.join(
+        __dirname,
+        "../../../../App/FeatureSet/Workers/Jobs/Slo/EvaluateSlos.ts",
+      ),
+      "utf8",
+    );
+
+    test("the evaluation worker imports both from here", () => {
+      expect(WORKER_SOURCE).toContain("SLO_CURRENT_BURN_RATE_WINDOW_MINUTES");
+      expect(WORKER_SOURCE).toContain("SLO_EVALUATION_CADENCE_MINUTES");
+      expect(WORKER_SOURCE).toContain('from "Common/Utils/Slo/SloEvaluation"');
+    });
+
+    test("the SLO overview reads the window from here too", () => {
+      const overview: string = fs.readFileSync(
+        path.join(
+          __dirname,
+          "../../../../App/FeatureSet/Dashboard/src/Pages/Slo/View/Index.tsx",
+        ),
+        "utf8",
+      );
+
+      expect(overview).toContain(
+        'import { SLO_CURRENT_BURN_RATE_WINDOW_MINUTES } from "Common/Utils/Slo/SloEvaluation"',
+      );
+    });
+  });
+});

package/Tests/Utils/Slug.test.ts

@@ -1,4 +1,5 @@
-import Slug from "../../Utils/Slug";
+import Slug, { SLUG_SUFFIX_LENGTH } from "../../Utils/Slug";
+import ColumnLength from "../../Types/Database/ColumnLength";
 
 describe("Slug.getSlug()", () => {
   test("should return empty string, if name is empty ", () => {
@@ -21,3 +22,62 @@ describe("Slug.getSlug()", () => {
     );
   });
 });
+
+/*
+ * The ceiling exists because the create path THROWS on an oversized value
+ * rather than truncating it (DatabaseService.checkMaxLengthOfFields), and slug
+ * sources are routinely wider than the slug column they feed: Incident.title
+ * is varchar(500) against a varchar(100) slug. DatabaseService.generateSlug
+ * passes the destination column's declared width in.
+ */
+describe("Slug.getSlug() — clamped to a destination column", () => {
+  const LONG_NAME: string = "a very long incident title indeed ".repeat(10);
+
+  test("leaves a name that already fits alone", () => {
+    expect(Slug.getSlug("short name", ColumnLength.Slug)).toMatch(
+      /^short-name-[\d]{10}$/,
+    );
+  });
+
+  test("fits the result inside the ceiling", () => {
+    expect(
+      Slug.getSlug(LONG_NAME, ColumnLength.Slug).length,
+    ).toBeLessThanOrEqual(ColumnLength.Slug);
+  });
+
+  test("cuts the readable half and keeps the unique tail whole", () => {
+    const slug: string = Slug.getSlug(LONG_NAME, ColumnLength.Slug);
+
+    expect(slug.substring(slug.length - SLUG_SUFFIX_LENGTH)).toMatch(
+      /^-[\d]{10}$/,
+    );
+    expect(slug.startsWith("a-very-long-incident-title-indeed")).toBe(true);
+  });
+
+  test("leaves no dash dangling where the cut fell", () => {
+    /*
+     * 44 puts the ceiling exactly on the dash after the second "indeed",
+     * which is the case that would otherwise read `...indeed--0123456789`.
+     */
+    expect(Slug.getSlug(LONG_NAME, 45)).not.toMatch(/--[\d]{10}$/);
+
+    /* Every nearby ceiling, so the case above is not the only one covered. */
+    for (let ceiling: number = 20; ceiling <= 100; ceiling++) {
+      const slug: string = Slug.getSlug(LONG_NAME, ceiling);
+
+      expect(slug.length).toBeLessThanOrEqual(ceiling);
+      expect(slug).not.toMatch(/--[\d]{10}$/);
+    }
+  });
+
+  test("still answers with a random name for a null source", () => {
+    const slug: string = Slug.getSlug(null, ColumnLength.Slug);
+
+    expect(slug).toMatch(/^[a-z0-9-]+-[\d]{10}$/);
+    expect(slug.length).toBeLessThanOrEqual(ColumnLength.Slug);
+  });
+
+  test("still answers with an empty string for an empty name", () => {
+    expect(Slug.getSlug("", ColumnLength.Slug)).toEqual("");
+  });
+});

package/Tests/Utils/Telemetry/CaptureSpanExportGating.test.ts

@@ -45,6 +45,16 @@ jest.mock("../../../Server/Utils/Telemetry", () => {
       recordExceptionMarkSpanAsErrorAndEndSpan: (data: unknown): unknown => {
         return recordExceptionMock(data);
       },
+      /*
+       * CaptureSpan ends spans through Telemetry.endSpan rather than calling
+       * span.end() directly, so that ending twice on the error path (the
+       * recorder's finally, then the decorator's) is a no-op instead of an SDK
+       * "You can only call end() on a span once" diagnostic. The real
+       * implementation guards on the span's endTime; the fake just forwards.
+       */
+      endSpan: (span: { end: () => void }): void => {
+        span.end();
+      },
     },
   };
 });
@@ -286,3 +296,138 @@ describe("Telemetry.isSpanExportEnabled (real module)", () => {
     expect(RealTelemetry.isSpanExportEnabled()).toBe(false);
   });
 });
+
+/*
+ * THE MULTI-FRAME CONTRACT.
+ *
+ * One thrown error propagates through every decorated frame on its way out,
+ * and each frame's catch calls the recorder on its OWN span. Nothing here
+ * deduplicates — the report-once marker lives inside the recorder, where it
+ * can be asserted against real exception events (see
+ * Tests/Server/Utils/Telemetry.test.ts). What this file pins is the shape the
+ * recorder depends on: N frames means N recorder calls carrying the SAME
+ * object identity, and every frame still ends its own span exactly once.
+ *
+ * Nothing covered this before, which is why the N-fold occuranceCount
+ * inflation shipped.
+ */
+describe("CaptureSpan across nested frames", () => {
+  beforeEach(() => {
+    spanExportEnabled = true;
+  });
+
+  test("an error crossing three frames reaches the recorder three times, as one object", () => {
+    const boom: Error = new Error("one failure, three frames");
+
+    const inner: (...args: Array<any>) => any = decorate(
+      undefined,
+      () => {
+        throw boom;
+      },
+      "inner",
+    );
+    const middle: (...args: Array<any>) => any = decorate(
+      undefined,
+      () => {
+        return inner();
+      },
+      "middle",
+    );
+    const outer: (...args: Array<any>) => any = decorate(
+      undefined,
+      () => {
+        return middle();
+      },
+      "outer",
+    );
+
+    expect(() => {
+      return outer();
+    }).toThrow(boom);
+
+    expect(recordExceptionMock).toHaveBeenCalledTimes(3);
+
+    /*
+     * Identity, not equality. The report-once marker is a non-enumerable
+     * symbol written onto the thrown value itself, so it only works if every
+     * frame sees the very same object — a wrapped or copied error would
+     * report N times again.
+     */
+    for (const call of recordExceptionMock.mock.calls) {
+      expect((call[0] as { exception: unknown }).exception).toBe(boom);
+    }
+
+    // Three spans created, three ended. No double-end, no leak.
+    expect(startActiveSpanMock).toHaveBeenCalledTimes(3);
+    expect(fakeSpan.end).toHaveBeenCalledTimes(3);
+  });
+
+  test("the same holds for async frames", async () => {
+    const boom: Error = new Error("async, three frames");
+
+    const inner: (...args: Array<any>) => any = decorate(
+      undefined,
+      async (): Promise<never> => {
+        throw boom;
+      },
+      "inner",
+    );
+    const middle: (...args: Array<any>) => any = decorate(
+      undefined,
+      async (): Promise<unknown> => {
+        return inner();
+      },
+      "middle",
+    );
+    const outer: (...args: Array<any>) => any = decorate(
+      undefined,
+      async (): Promise<unknown> => {
+        return middle();
+      },
+      "outer",
+    );
+
+    await expect(outer()).rejects.toBe(boom);
+
+    expect(recordExceptionMock).toHaveBeenCalledTimes(3);
+    expect(fakeSpan.end).toHaveBeenCalledTimes(3);
+  });
+
+  /*
+   * A span that already carries an ERROR must not be downgraded to OK. That is
+   * reachable whenever a decorated method swallows an error and signals
+   * failure another way — Express middleware calling next(err) is the case
+   * that actually occurs — because the decorator then sees a normal return.
+   * The SDK's own setStatus guard does not help: it only early-returns when
+   * the CURRENT status is already OK.
+   */
+  test("a success return does not overwrite an ERROR status set from inside", () => {
+    const erroredSpan: FakeSpan & { status?: { code: number } } = {
+      setStatus: jest.fn(),
+      end: jest.fn(),
+      status: { code: 2 }, // SpanStatusCode.ERROR
+    };
+
+    startActiveSpanMock.mockImplementationOnce((data: any) => {
+      return data.fn(erroredSpan);
+    });
+
+    const wrapped: (...args: Array<any>) => any = decorate(undefined, () => {
+      return "swallowed the error and returned normally";
+    });
+
+    wrapped();
+
+    expect(erroredSpan.setStatus).not.toHaveBeenCalled();
+  });
+
+  test("a span with no observable status is still marked OK", () => {
+    const wrapped: (...args: Array<any>) => any = decorate(undefined, () => {
+      return "fine";
+    });
+
+    wrapped();
+
+    expect(fakeSpan.setStatus).toHaveBeenCalledWith({ code: 1 });
+  });
+});

package/Tests/jest.setup.ts

@@ -1,4 +1,5 @@
 import "@testing-library/jest-dom";
+import { configure } from "@testing-library/react";
 import { jest } from "@jest/globals";
 import { TextEncoder, TextDecoder } from "util";
 import { webcrypto, randomUUID } from "crypto";
@@ -31,3 +32,21 @@ Object.defineProperty(window, "scrollTo", {
   value: jest.fn(),
   writable: true,
 });
+
+/*
+ * Testing Library waits a default of one second for findBy/waitFor. That is a
+ * generous budget for a state update and a hopeless one for a React.lazy
+ * boundary: the first component to render LazyMarkdownViewer has to resolve
+ * the dynamic import and put MarkdownViewer (plus its mermaid mock) through
+ * ts-jest before any assertion on the markdown text can pass. Locally that is
+ * ~400 ms; on a CI runner with the other shard workers competing for the same
+ * cores it goes past a second, and the test fails having rendered the Suspense
+ * fallback -- a timeout wearing the costume of a missing element.
+ *
+ * ~20 components reach the viewer through that wrapper (FeedItem, EventItem,
+ * Detail, BaseModelTable and the rest), so this is a whole class of flake
+ * rather than one test, and it belongs here rather than at one call site.
+ * Five seconds is still short enough that a genuinely broken assertion fails
+ * promptly instead of sitting out the 60 s testTimeout.
+ */
+configure({ asyncUtilTimeout: 5000 });

package/Types/AI/ExceptionAIClassification.ts

@@ -1,27 +1,13 @@
 /*
- * AI triage verdict for a telemetry exception group. Decides how the
- * automatic fix lane treats the group:
+ * The AI triage verdict and the fault domain declared by the throwing code are
+ * the SAME vocabulary, so they are the same enum. It lives in
+ * Common/Types/Telemetry/ErrorClass.ts, which is importable from the emit path
+ * (Types-only, no server dependencies) as well as from the AI lane.
  *
- * - CodeFault: a defect in the monitored code — the only class the
- *   automatic lane opens fix pull requests for.
- * - UserError: expected consequence of invalid end-user input (bad
- *   parameters, malformed values). The right change, if any, is earlier
- *   validation and clearer error UX — routed to a human, never auto-fixed.
- * - ExpectedDenial: an intentional check doing its job (auth failure,
- *   plan/paywall denial, scanner/fuzzer probe tripping validation).
- *   Never auto-fixed; optionally auto-archived.
- * - Infrastructure: environmental conditions (timeouts, connection
- *   resets, resource exhaustion) where a code "fix" is usually tuning —
- *   routed to a human.
- * - Unknown: triage could not decide — treated conservatively (no
- *   automatic fix).
+ * This path is kept so the triage runner, the insight scanner and their tests
+ * keep compiling — and because "the AI's verdict" is a genuinely useful name
+ * at those call sites. It is one SOURCE of the field, not a separate concept:
+ * a class declared by the throwing code outranks it, and a human's click
+ * outranks both.
  */
-enum ExceptionAIClassification {
-  CodeFault = "code-fault",
-  UserError = "user-error",
-  ExpectedDenial = "expected-denial",
-  Infrastructure = "infrastructure",
-  Unknown = "unknown",
-}
-
-export default ExceptionAIClassification;
+export { default } from "../Telemetry/ErrorClass";

package/Types/Email/EmailTemplateType.ts

@@ -99,6 +99,8 @@ enum EmailTemplateType {
 
   EnterpriseLicenseUserLimitBreach = "EnterpriseLicenseUserLimitBreach.hbs",
   EnterpriseLicenseExpiryReminder = "EnterpriseLicenseExpiryReminder.hbs",
+
+  NotificationRollup = "NotificationRollup.hbs",
 }
 
 export default EmailTemplateType;

package/Types/EnterpriseLicense/EnterpriseLicenseInstanceSummary.ts

@@ -11,6 +11,11 @@ type EnterpriseLicenseInstanceSummary = {
   instanceId: string;
   host: string | null;
   userCount: number | null;
+  /*
+   * Whether this row contributed to currentUserCount at the server's cutoff.
+   * Optional so installations remain compatible with older license servers.
+   */
+  isCountedTowardsUsage?: boolean | undefined;
   // ISO date string of the most recent usage report from this instance.
   lastReportedAt: string | null;
   /*

package/Types/EnterpriseLicense/EnterpriseLicenseUsageSnapshot.ts

@@ -0,0 +1,13 @@
+/*
+ * A point-in-time, privacy-preserving view of enterprise license usage for
+ * the Admin Dashboard. Email hashes stay on the server; instance ids are
+ * enough to render statuses from the exact same cutoff as the aggregate.
+ */
+export default interface EnterpriseLicenseUsageSnapshot {
+  currentUserCount: number | null;
+  activeInstanceIds: Array<string>;
+  masterAdminEmails: Array<string>;
+  calculatedAt: string;
+  lastUsageReportedAt: string | null;
+  nextInstanceStatusChangeAt: string | null;
+}

package/Types/EnterpriseLicense/EnterpriseLicenseUserCountSource.ts

@@ -0,0 +1,6 @@
+enum EnterpriseLicenseUserCountSource {
+  Instance = "instance",
+  Legacy = "legacy",
+}
+
+export default EnterpriseLicenseUserCountSource;

package/Types/Exception/ApiException.ts

@@ -1,5 +1,6 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class APIException extends Exception {
   private _error: Error | null = null;
@@ -16,4 +17,13 @@ export default class APIException extends Exception {
       this.error = error;
     }
   }
+
+  /*
+   * The environment failed, not our code and not the caller. Stays an
+   * Issue: it is a real failure worth a human, it is just never something the
+   * automatic fix lane should open a pull request for.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.Infrastructure;
+  }
 }

package/Types/Exception/BadDataException.ts

@@ -1,8 +1,19 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class BadDataException extends Exception {
   public constructor(message: string) {
     super(ExceptionCode.BadDataException, message);
   }
+
+  /*
+   * The caller sent something we cannot accept. Nothing is broken; the
+   * request was. Promoted back to CodeFault by ErrorClassResolver when it is
+   * raised outside an HTTP request, because a background job has no client to
+   * blame — see Common/Server/Utils/Telemetry/ErrorClassResolver.ts.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.UserError;
+  }
 }

package/Types/Exception/BadRequestException.ts

@@ -1,8 +1,19 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class BadRequestException extends Exception {
   public constructor(message: string) {
     super(ExceptionCode.BadDataException, message);
   }
+
+  /*
+   * The caller sent something we cannot accept. Nothing is broken; the
+   * request was. Promoted back to CodeFault by ErrorClassResolver when it is
+   * raised outside an HTTP request, because a background job has no client to
+   * blame — see Common/Server/Utils/Telemetry/ErrorClassResolver.ts.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.UserError;
+  }
 }

package/Types/Exception/Exception.ts

@@ -1,4 +1,8 @@
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass, {
+  tagErrorClass,
+  tagErrorClassAuthoritative,
+} from "../Telemetry/ErrorClass";
 
 export default class Exception extends Error {
   private _code: ExceptionCode = ExceptionCode.GeneralException;
@@ -14,6 +18,67 @@ export default class Exception extends Error {
   public constructor(code: ExceptionCode, message: string) {
     super(message);
     this.code = code;
+
+    /*
+     * Tag the fault domain at construction. Calling a prototype method from
+     * the base constructor dispatches to the subclass override (prototypes are
+     * wired before the constructor body runs), so each subclass answers for
+     * itself. getErrorClass must therefore never read subclass FIELDS — those
+     * initialize after super() returns — which is why every override returns a
+     * constant.
+     */
+    tagErrorClass(this, this.getErrorClass());
+  }
+
+  /*
+   * The fault domain for this exception class.
+   *
+   * CODE-FAULT IS THE BASE DEFAULT ON PURPOSE. A new subclass added without an
+   * override, or an exception whose author never thought about this, stays
+   * NOISY. The failure mode of the whole classification scheme must be
+   * over-reporting — there is no configuration in which silence is the
+   * default.
+   *
+   * This is deliberately keyed on the CLASS, not on `code`: BadDataException
+   * and BadRequestException are both 400, ServerException and
+   * DatabaseNotConnectedException are both 500, and five ExceptionCode members
+   * (NotImplemented=0, General=1, API=2, BadOperation=5, WebRequest=6) are not
+   * HTTP statuses at all.
+   *
+   * Note that declaring a class here is not the last word: a user-error or
+   * expected-denial raised OUTSIDE an HTTP request is promoted back to
+   * code-fault by ErrorClassResolver, because a background job has no client
+   * to blame.
+   */
+  protected getErrorClass(): ErrorClass {
+    return ErrorClass.CodeFault;
+  }
+
+  /**
+   * Override the declared fault domain for one particular throw, where the
+   * class-level default is wrong at a specific site. Chainable:
+   * `throw new BadDataException(msg).asCodeFault()`.
+   *
+   * These are AUTHORITATIVE: a developer looked at this one site and said what
+   * it is, so unlike the class-level default they are exempt from the
+   * unit-of-work promotion. Use them when the surrounding context genuinely
+   * changes the answer — e.g. a probe reporting that the endpoint it was asked
+   * to check is down, which is the product working, not a defect.
+   */
+  public asCodeFault(): this {
+    return tagErrorClassAuthoritative(this, ErrorClass.CodeFault);
+  }
+
+  public asUserError(): this {
+    return tagErrorClassAuthoritative(this, ErrorClass.UserError);
+  }
+
+  public asExpectedDenial(): this {
+    return tagErrorClassAuthoritative(this, ErrorClass.ExpectedDenial);
+  }
+
+  public asInfrastructure(): this {
+    return tagErrorClassAuthoritative(this, ErrorClass.Infrastructure);
   }
 
   public getMessage(): string {

package/Types/Exception/ForbiddenException.ts

@@ -1,8 +1,18 @@
 import Exception from "./Exception";
 import ExceptionCode from "./ExceptionCode";
+import ErrorClass from "../Telemetry/ErrorClass";
 
 export default class ForbiddenException extends Exception {
   public constructor(message: string) {
     super(ExceptionCode.ForbiddenException, message);
   }
+
+  /*
+   * A check we deliberately wrote, doing exactly its job. Denying this
+   * request IS the correct behaviour, so it is not an Issue. Promoted back to
+   * CodeFault outside an HTTP request — see ErrorClassResolver.
+   */
+  protected override getErrorClass(): ErrorClass {
+    return ErrorClass.ExpectedDenial;
+  }
 }