@warpgogol/werkstatt-shared 0.2.0

package/src/observability/tests/conventions.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from "vitest";
+import { buildResourceAttributes, type WarpgogolResourceInput } from "../conventions.ts";
+
+describe("buildResourceAttributes", () => {
+  it("builds correct attributes for a site-layer signal", () => {
+    const attrs = buildResourceAttributes({
+      serviceName: "warpgogol-com",
+      layer: "site",
+      environment: "production",
+      siteId: "warpgogol-com",
+    });
+    expect(attrs).toEqual([
+      { key: "service.name", value: { stringValue: "warpgogol-com" } },
+      { key: "deployment.environment", value: { stringValue: "production" } },
+      { key: "warpgogol.layer", value: { stringValue: "site" } },
+      { key: "warpgogol.site_id", value: { stringValue: "warpgogol-com" } },
+    ]);
+  });
+
+  it("includes service.version when provided", () => {
+    const attrs = buildResourceAttributes({
+      serviceName: "fleet-probe-runner",
+      layer: "probe",
+      environment: "production",
+      siteId: "warpgogol-com",
+      serviceVersion: "abc1234",
+    });
+    expect(attrs.some((a) => a.key === "service.version")).toBe(true);
+    expect(attrs.find((a) => a.key === "service.version")?.value.stringValue).toBe("abc1234");
+  });
+
+  it("throws when siteId is missing for site layer", () => {
+    expect(() =>
+      buildResourceAttributes({
+        serviceName: "warpgogol-com",
+        layer: "site",
+        environment: "production",
+      } as WarpgogolResourceInput),
+    ).toThrow(/siteId is required/);
+  });
+
+  it("throws when siteId is missing for probe layer", () => {
+    expect(() =>
+      buildResourceAttributes({
+        serviceName: "fleet-probe-runner",
+        layer: "probe",
+        environment: "production",
+      } as WarpgogolResourceInput),
+    ).toThrow(/siteId is required/);
+  });
+
+  it("throws when siteId is missing for delivery layer", () => {
+    expect(() =>
+      buildResourceAttributes({
+        serviceName: "cf-analytics-poller",
+        layer: "delivery",
+        environment: "production",
+      } as WarpgogolResourceInput),
+    ).toThrow(/siteId is required/);
+  });
+
+  it("does not require siteId for factory layer", () => {
+    const attrs = buildResourceAttributes({
+      serviceName: "site-kernel",
+      layer: "factory",
+      environment: "ci",
+    });
+    expect(attrs.some((a) => a.key === "warpgogol.site_id")).toBe(false);
+  });
+
+  it("throws for invalid layer", () => {
+    expect(() =>
+      buildResourceAttributes({
+        serviceName: "test",
+        layer: "invalid" as never,
+        environment: "production",
+      }),
+    ).toThrow(/not in the closed vocabulary/);
+  });
+
+  it("throws for invalid environment", () => {
+    expect(() =>
+      buildResourceAttributes({
+        serviceName: "test",
+        layer: "factory",
+        environment: "staging" as never,
+      }),
+    ).toThrow(/not in the closed vocabulary/);
+  });
+
+  it("throws when serviceName is empty", () => {
+    expect(() =>
+      buildResourceAttributes({
+        serviceName: "",
+        layer: "factory",
+        environment: "ci",
+      }),
+    ).toThrow(/serviceName is required/);
+  });
+});

package/src/observability/tests/metric-registry.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect } from "vitest";
+import {
+  WARPGOGOL_METRIC_REGISTRY,
+  findMetricSpec,
+  isMetricNameValid,
+  isLabelKeyForbidden,
+  FORBIDDEN_LABEL_KEYS,
+} from "../metric-registry.ts";
+
+describe("WARPGOGOL_METRIC_REGISTRY", () => {
+  it("contains the smoke metric", () => {
+    const smoke = findMetricSpec("warpgogol_factory_smoke_total");
+    expect(smoke).toBeDefined();
+    expect(smoke?.kind).toBe("counter");
+    expect(smoke?.labelKeys).toEqual([]);
+  });
+
+  it("has no duplicate names", () => {
+    const names = WARPGOGOL_METRIC_REGISTRY.map((s) => s.name);
+    const unique = new Set(names);
+    expect(names.length).toBe(unique.size);
+  });
+
+  it("all names match the naming grammar", () => {
+    for (const spec of WARPGOGOL_METRIC_REGISTRY) {
+      expect(isMetricNameValid(spec.name)).toBe(true);
+    }
+  });
+
+  it("no entry has a forbidden label key", () => {
+    for (const spec of WARPGOGOL_METRIC_REGISTRY) {
+      for (const key of spec.labelKeys) {
+        expect(isLabelKeyForbidden(key)).toBe(false);
+      }
+    }
+  });
+
+  it("contains all 5 back metrics with correct kinds and labels (RFC-0807)", () => {
+    const requests = findMetricSpec("warpgogol_back_requests_total");
+    expect(requests).toBeDefined();
+    expect(requests?.kind).toBe("counter");
+    expect(requests?.labelKeys).toEqual(["service", "status_class"]);
+
+    const up = findMetricSpec("warpgogol_back_up");
+    expect(up).toBeDefined();
+    expect(up?.kind).toBe("gauge");
+    expect(up?.labelKeys).toEqual(["service"]);
+
+    const lastRun = findMetricSpec("warpgogol_back_last_run_total");
+    expect(lastRun).toBeDefined();
+    expect(lastRun?.kind).toBe("counter");
+    expect(lastRun?.labelKeys).toEqual(["service", "status"]);
+
+    const lastError = findMetricSpec("warpgogol_back_last_error_total");
+    expect(lastError).toBeDefined();
+    expect(lastError?.kind).toBe("counter");
+    expect(lastError?.labelKeys).toEqual(["service"]);
+
+    const queueDepth = findMetricSpec("warpgogol_back_queue_depth");
+    expect(queueDepth).toBeDefined();
+    expect(queueDepth?.kind).toBe("gauge");
+    expect(queueDepth?.labelKeys).toEqual(["service"]);
+  });
+});
+
+describe("isMetricNameValid", () => {
+  it("accepts valid factory metric names", () => {
+    expect(isMetricNameValid("warpgogol_factory_smoke_total")).toBe(true);
+    expect(isMetricNameValid("warpgogol_factory_command_duration_seconds")).toBe(true);
+  });
+
+  it("accepts valid probe metric names", () => {
+    expect(isMetricNameValid("warpgogol_probe_up")).toBe(true);
+  });
+
+  it("accepts valid delivery metric names", () => {
+    expect(isMetricNameValid("warpgogol_delivery_requests_total")).toBe(true);
+  });
+
+  it("accepts valid workers metric names", () => {
+    expect(isMetricNameValid("warpgogol_workers_errors_total")).toBe(true);
+  });
+
+  it("accepts valid back metric names (RFC-0807)", () => {
+    expect(isMetricNameValid("warpgogol_back_requests_total")).toBe(true);
+    expect(isMetricNameValid("warpgogol_back_up")).toBe(true);
+    expect(isMetricNameValid("warpgogol_back_last_run_total")).toBe(true);
+    expect(isMetricNameValid("warpgogol_back_last_error_total")).toBe(true);
+    expect(isMetricNameValid("warpgogol_back_queue_depth")).toBe(true);
+  });
+
+  it("rejects names without the warpgogol_ prefix", () => {
+    expect(isMetricNameValid("factory_smoke_total")).toBe(false);
+  });
+
+  it("rejects names with wrong prefix domain", () => {
+    expect(isMetricNameValid("warpgogol_foo_smoke_total")).toBe(false);
+  });
+
+  it("rejects names with uppercase", () => {
+    expect(isMetricNameValid("warpgogol_factory_Smoke")).toBe(false);
+  });
+});
+
+describe("isLabelKeyForbidden", () => {
+  it("returns true for all forbidden keys", () => {
+    for (const key of FORBIDDEN_LABEL_KEYS) {
+      expect(isLabelKeyForbidden(key)).toBe(true);
+    }
+  });
+
+  it("returns false for allowed keys", () => {
+    expect(isLabelKeyForbidden("site_id")).toBe(false);
+    expect(isLabelKeyForbidden("status_class")).toBe(false);
+    expect(isLabelKeyForbidden("command")).toBe(false);
+  });
+});

package/src/observability/tests/otlp-converter.pbt.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect } from "vitest";
+import fc from "fast-check";
+import { convertAccumulatedToOtlp, type AccumulatedPoint } from "../otlp-converter.ts";
+
+const START_TIME = "1751884500000000000";
+
+const metricNameArb = fc.constantFrom(
+  "warpgogol_factory_smoke_total",
+  "warpgogol_factory_command_runs_total",
+  "warpgogol_probe_up",
+  "warpgogol_probe_ttfb_seconds",
+  "warpgogol_factory_command_duration_seconds",
+);
+
+const kindArb = fc.constantFrom<"counter" | "gauge" | "histogram">("counter", "gauge", "histogram");
+
+const pointArb: fc.Arbitrary<AccumulatedPoint> = fc.record({
+  name: metricNameArb,
+  labels: fc.dictionary(fc.string({ maxLength: 10 }), fc.string({ maxLength: 20 })),
+  value: fc.double({ min: 0, max: 1000, noDefaultInfinity: true, noNaN: true }),
+  kind: kindArb,
+});
+
+const pointsArb = fc.array(pointArb, { maxLength: 50 });
+
+describe("convertAccumulatedToOtlp — property-based tests (DNA-41)", () => {
+  it("bucket counts sum equals total points per histogram metric", () => {
+    fc.assert(
+      fc.property(pointsArb, (points) => {
+        const result = convertAccumulatedToOtlp(points, START_TIME);
+        for (const otlp of result) {
+          if (otlp.kind === "histogram" && otlp.histogramPoints) {
+            const hp = otlp.histogramPoints[0]!;
+            const bucketSum = hp.bucketCounts.reduce((acc, c) => acc + Number(c), 0);
+            const histogramPoints = points.filter((p) => p.name === otlp.name);
+            expect(bucketSum).toBe(histogramPoints.length);
+            expect(hp.count).toBe(String(histogramPoints.length));
+          }
+        }
+      }),
+    );
+  });
+
+  it("output metric names are a subset of input metric names", () => {
+    fc.assert(
+      fc.property(pointsArb, (points) => {
+        const result = convertAccumulatedToOtlp(points, START_TIME);
+        const inputNames = new Set(points.map((p) => p.name));
+        for (const otlp of result) {
+          expect(inputNames.has(otlp.name)).toBe(true);
+        }
+      }),
+    );
+  });
+
+  it("each output metric appears exactly once (grouping is stable)", () => {
+    fc.assert(
+      fc.property(pointsArb, (points) => {
+        const result = convertAccumulatedToOtlp(points, START_TIME);
+        const outputNames = result.map((r) => r.name);
+        const uniqueNames = new Set(outputNames);
+        expect(outputNames.length).toBe(uniqueNames.size);
+      }),
+    );
+  });
+
+  it("empty input always produces empty output", () => {
+    fc.assert(
+      fc.property(pointsArb, (points) => {
+        if (points.length === 0) {
+          const result = convertAccumulatedToOtlp(points, START_TIME);
+          expect(result).toEqual([]);
+        }
+      }),
+    );
+  });
+});

package/src/observability/tests/otlp-converter.test.ts

@@ -0,0 +1,157 @@
+import { describe, it, expect } from "vitest";
+import { convertAccumulatedToOtlp, type AccumulatedPoint } from "../otlp-converter.ts";
+
+const START_TIME = "1751884500000000000";
+
+describe("convertAccumulatedToOtlp", () => {
+  it("returns empty array for empty input", () => {
+    const result = convertAccumulatedToOtlp([], START_TIME);
+    expect(result).toEqual([]);
+  });
+
+  it("skips points with undeclared metric names", () => {
+    const points: AccumulatedPoint[] = [
+      { name: "warpgogol_unknown_metric", labels: {}, value: 1, kind: "counter" },
+    ];
+    const result = convertAccumulatedToOtlp(points, START_TIME);
+    expect(result).toEqual([]);
+  });
+
+  it("converts a counter point to a sum metric", () => {
+    const points: AccumulatedPoint[] = [
+      { name: "warpgogol_factory_smoke_total", labels: {}, value: 1, kind: "counter" },
+    ];
+    const result = convertAccumulatedToOtlp(points, START_TIME);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.kind).toBe("sum");
+    expect(result[0]!.name).toBe("warpgogol_factory_smoke_total");
+    expect(result[0]!.isMonotonic).toBe(true);
+    expect(result[0]!.sumPoints).toHaveLength(1);
+    expect(result[0]!.sumPoints![0]!.asDouble).toBe(1);
+    expect(result[0]!.sumPoints![0]!.startTimeUnixNano).toBe(START_TIME);
+  });
+
+  it("groups multiple counter points by name into one sum metric", () => {
+    const points: AccumulatedPoint[] = [
+      {
+        name: "warpgogol_factory_command_runs_total",
+        labels: { command: "build.check", status: "pass" },
+        value: 1,
+        kind: "counter",
+      },
+      {
+        name: "warpgogol_factory_command_runs_total",
+        labels: { command: "build.check", status: "fail" },
+        value: 1,
+        kind: "counter",
+      },
+    ];
+    const result = convertAccumulatedToOtlp(points, START_TIME);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.sumPoints).toHaveLength(2);
+  });
+
+  it("converts a gauge point to a gauge metric", () => {
+    const points: AccumulatedPoint[] = [
+      {
+        name: "warpgogol_probe_up",
+        labels: { site_id: "warpgogol-com", route: "/" },
+        value: 1,
+        kind: "gauge",
+      },
+    ];
+    const result = convertAccumulatedToOtlp(points, START_TIME);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.kind).toBe("gauge");
+    expect(result[0]!.gaugePoints).toHaveLength(1);
+    expect(result[0]!.gaugePoints![0]!.asDouble).toBe(1);
+  });
+
+  it("converts histogram points with correct bucket counts", () => {
+    const points: AccumulatedPoint[] = [
+      {
+        name: "warpgogol_factory_command_duration_seconds",
+        labels: { command: "build.check" },
+        value: 0.3,
+        kind: "histogram",
+      },
+      {
+        name: "warpgogol_factory_command_duration_seconds",
+        labels: { command: "build.check" },
+        value: 1.5,
+        kind: "histogram",
+      },
+      {
+        name: "warpgogol_factory_command_duration_seconds",
+        labels: { command: "build.check" },
+        value: 700,
+        kind: "histogram",
+      },
+    ];
+    const result = convertAccumulatedToOtlp(points, START_TIME);
+    expect(result).toHaveLength(1);
+    expect(result[0]!.kind).toBe("histogram");
+    const hp = result[0]!.histogramPoints![0]!;
+    expect(hp.count).toBe("3");
+    expect(hp.sum).toBe(701.8);
+    expect(hp.bucketCounts).toHaveLength(11);
+    expect(hp.explicitBounds).toEqual([0.5, 1, 2, 5, 10, 30, 60, 120, 300, 600]);
+    expect(hp.bucketCounts[0]).toBe("1");
+    expect(hp.bucketCounts[2]).toBe("1");
+    expect(hp.bucketCounts[10]).toBe("1");
+  });
+
+  it("places value exactly on a bucket boundary in the lower bucket", () => {
+    const points: AccumulatedPoint[] = [
+      {
+        name: "warpgogol_factory_command_duration_seconds",
+        labels: { command: "build.check" },
+        value: 1,
+        kind: "histogram",
+      },
+    ];
+    const result = convertAccumulatedToOtlp(points, START_TIME);
+    const hp = result[0]!.histogramPoints![0]!;
+    expect(hp.bucketCounts[1]).toBe("1");
+    expect(hp.bucketCounts[2]).toBe("0");
+  });
+
+  it("handles mixed kinds in a single call", () => {
+    const points: AccumulatedPoint[] = [
+      { name: "warpgogol_factory_smoke_total", labels: {}, value: 1, kind: "counter" },
+      {
+        name: "warpgogol_probe_up",
+        labels: { site_id: "warpgogol-com", route: "/" },
+        value: 1,
+        kind: "gauge",
+      },
+      {
+        name: "warpgogol_factory_command_duration_seconds",
+        labels: { command: "build.check" },
+        value: 2,
+        kind: "histogram",
+      },
+    ];
+    const result = convertAccumulatedToOtlp(points, START_TIME);
+    expect(result).toHaveLength(3);
+    const kinds = result.map((r) => r.kind).sort();
+    expect(kinds).toEqual(["gauge", "histogram", "sum"]);
+  });
+
+  it("preserves label attributes in output points", () => {
+    const points: AccumulatedPoint[] = [
+      {
+        name: "warpgogol_probe_up",
+        labels: { site_id: "warpgogol-com", route: "/" },
+        value: 1,
+        kind: "gauge",
+      },
+    ];
+    const result = convertAccumulatedToOtlp(points, START_TIME);
+    const attrs = result[0]!.gaugePoints![0]!.attributes!;
+    expect(attrs).toEqual([
+      { key: "site_id", value: { stringValue: "warpgogol-com" } },
+      { key: "route", value: { stringValue: "/" } },
+    ]);
+  });
+});

package/src/observability/tests/otlp-json.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect } from "vitest";
+import { encodeOtlpMetrics, nowUnixNano, type OtlpMetricPoint } from "../otlp-json.ts";
+import type { OtlpKeyValue } from "../conventions.ts";
+
+const resourceAttrs: OtlpKeyValue[] = [
+  { key: "service.name", value: { stringValue: "fleet-probe-runner" } },
+  { key: "deployment.environment", value: { stringValue: "production" } },
+  { key: "warpgogol.layer", value: { stringValue: "probe" } },
+  { key: "warpgogol.site_id", value: { stringValue: "warpgogol-com" } },
+];
+
+describe("encodeOtlpMetrics", () => {
+  it("encodes a gauge metric", () => {
+    const points: OtlpMetricPoint[] = [
+      {
+        name: "warpgogol_probe_up",
+        kind: "gauge",
+        gaugePoints: [
+          {
+            asDouble: 1,
+            timeUnixNano: "1751884800000000000",
+            attributes: [{ key: "site_id", value: { stringValue: "warpgogol-com" } }],
+          },
+        ],
+      },
+    ];
+    const env = encodeOtlpMetrics(resourceAttrs, points, "@warpgogol/werkstatt-shared/observability", "1");
+    expect(env.resourceMetrics).toHaveLength(1);
+    expect(env.resourceMetrics[0]!.resource.attributes).toEqual(resourceAttrs);
+    const scope = env.resourceMetrics[0]!.scopeMetrics[0]!;
+    expect(scope.scope.name).toBe("@warpgogol/werkstatt-shared/observability");
+    expect(scope.scope.version).toBe("1");
+    expect(scope.metrics).toHaveLength(1);
+    const metric = scope.metrics[0] as Record<string, unknown>;
+    expect(metric["name"]).toBe("warpgogol_probe_up");
+    expect(metric["gauge"]).toBeDefined();
+    const gauge = metric["gauge"] as { dataPoints: unknown[] };
+    expect(gauge.dataPoints).toHaveLength(1);
+    const dp = gauge.dataPoints[0] as Record<string, unknown>;
+    expect(dp["asDouble"]).toBe(1);
+    expect(dp["timeUnixNano"]).toBe("1751884800000000000");
+  });
+
+  it("encodes a delta sum (counter) with aggregationTemporality 1", () => {
+    const points: OtlpMetricPoint[] = [
+      {
+        name: "warpgogol_probe_http_status_class_total",
+        kind: "sum",
+        unit: "1",
+        isMonotonic: true,
+        sumPoints: [
+          {
+            asDouble: 3,
+            startTimeUnixNano: "1751884500000000000",
+            timeUnixNano: "1751884800000000000",
+            attributes: [{ key: "status_class", value: { stringValue: "2xx" } }],
+          },
+        ],
+      },
+    ];
+    const env = encodeOtlpMetrics(resourceAttrs, points, "@warpgogol/werkstatt-shared/observability", "1");
+    const metric = env.resourceMetrics[0]!.scopeMetrics[0]!.metrics[0] as Record<string, unknown>;
+    expect(metric["name"]).toBe("warpgogol_probe_http_status_class_total");
+    expect(metric["unit"]).toBe("1");
+    const sum = metric["sum"] as {
+      aggregationTemporality: number;
+      isMonotonic: boolean;
+      dataPoints: unknown[];
+    };
+    expect(sum.aggregationTemporality).toBe(1);
+    expect(sum.isMonotonic).toBe(true);
+    const dp = sum.dataPoints[0] as Record<string, unknown>;
+    expect(dp["asDouble"]).toBe(3);
+    expect(dp["startTimeUnixNano"]).toBe("1751884500000000000");
+    expect(dp["timeUnixNano"]).toBe("1751884800000000000");
+  });
+
+  it("encodes a delta histogram with correct bucketCounts and explicitBounds", () => {
+    const points: OtlpMetricPoint[] = [
+      {
+        name: "warpgogol_factory_command_duration_seconds",
+        kind: "histogram",
+        unit: "s",
+        histogramPoints: [
+          {
+            startTimeUnixNano: "1751884500000000000",
+            timeUnixNano: "1751884800000000000",
+            count: "3",
+            sum: 42.5,
+            bucketCounts: ["0", "1", "1", "1", "0", "0", "0", "0", "0", "0", "0"],
+            explicitBounds: [0.5, 1, 2, 5, 10, 30, 60, 120, 300, 600],
+          },
+        ],
+      },
+    ];
+    const env = encodeOtlpMetrics(resourceAttrs, points, "@warpgogol/werkstatt-shared/observability", "1");
+    const metric = env.resourceMetrics[0]!.scopeMetrics[0]!.metrics[0] as Record<string, unknown>;
+    expect(metric["name"]).toBe("warpgogol_factory_command_duration_seconds");
+    expect(metric["unit"]).toBe("s");
+    const hist = metric["histogram"] as { aggregationTemporality: number; dataPoints: unknown[] };
+    expect(hist.aggregationTemporality).toBe(1);
+    const dp = hist.dataPoints[0] as Record<string, unknown>;
+    expect(dp["count"]).toBe("3");
+    expect(dp["sum"]).toBe(42.5);
+    expect(dp["bucketCounts"]).toEqual(["0", "1", "1", "1", "0", "0", "0", "0", "0", "0", "0"]);
+    expect(dp["explicitBounds"]).toEqual([0.5, 1, 2, 5, 10, 30, 60, 120, 300, 600]);
+  });
+});
+
+describe("nowUnixNano", () => {
+  it("returns a string of digits representing unix nanoseconds", () => {
+    const nano = nowUnixNano();
+    expect(typeof nano).toBe("string");
+    expect(nano).toMatch(/^\d+$/);
+    // Should be approximately Date.now() * 1e6
+    const approx = Date.now() * 1_000_000;
+    const parsed = Number(nano);
+    expect(Math.abs(parsed - approx)).toBeLessThan(5_000_000_000);
+  });
+});

package/src/observability/tests/pusher.test.ts

@@ -0,0 +1,75 @@
+// @vitest-environment node
+import { describe, it, expect } from "vitest";
+import { createMetricsPusher } from "../pusher.ts";
+
+describe("createMetricsPusher", () => {
+  it("returns null when endpoint is missing", () => {
+    const pusher = createMetricsPusher(
+      { serviceName: "test", layer: "factory", environment: "ci" },
+      { token: "abc" },
+    );
+    expect(pusher).toBeNull();
+  });
+
+  it("returns null when token is missing", () => {
+    const pusher = createMetricsPusher(
+      { serviceName: "test", layer: "factory", environment: "ci" },
+      { endpoint: "https://ingest.example.com" },
+    );
+    expect(pusher).toBeNull();
+  });
+
+  it("returns null when both are missing", () => {
+    const pusher = createMetricsPusher(
+      { serviceName: "test", layer: "factory", environment: "ci" },
+      {},
+    );
+    expect(pusher).toBeNull();
+  });
+
+  it("returns a pusher when both env vars are present", () => {
+    const pusher = createMetricsPusher(
+      { serviceName: "test", layer: "factory", environment: "ci" },
+      { endpoint: "https://ingest.example.com", token: "abc" },
+    );
+    expect(pusher).not.toBeNull();
+  });
+
+  it("flush() resolves with delivered:true when no points accumulated", async () => {
+    const pusher = createMetricsPusher(
+      { serviceName: "test", layer: "factory", environment: "ci" },
+      { endpoint: "https://ingest.example.com", token: "abc" },
+    );
+    const result = await pusher!.flush();
+    expect(result.delivered).toBe(true);
+  });
+
+  it("flush() never throws even on network failure", async () => {
+    const pusher = createMetricsPusher(
+      { serviceName: "test", layer: "factory", environment: "ci" },
+      { endpoint: "https://nonexistent.invalid.example", token: "abc" },
+      { timeoutMs: 100 },
+    );
+    pusher!.counterAdd("warpgogol_factory_smoke_total", 1);
+    const result = await pusher!.flush();
+    expect(result.delivered).toBe(false);
+    expect(result.reason).toBeDefined();
+  });
+
+  it("flush() honors timeout via AbortController", async () => {
+    // Use a hanging endpoint — we can't easily mock fetch, but we can test
+    // with a very short timeout against a real (slow) endpoint.
+    const pusher = createMetricsPusher(
+      { serviceName: "test", layer: "factory", environment: "ci" },
+      { endpoint: "https://10.255.255.1", token: "abc" },
+      { timeoutMs: 50 },
+    );
+    pusher!.counterAdd("warpgogol_factory_smoke_total", 1);
+    const start = Date.now();
+    const result = await pusher!.flush();
+    const elapsed = Date.now() - start;
+    expect(result.delivered).toBe(false);
+    // Should abort within a reasonable window of the timeout
+    expect(elapsed).toBeLessThan(5000);
+  });
+});