import { describe, expect, it } from "vitest"; import { DIAGNOSTIC_CONTEXT_ALLOWLIST, DIAGNOSTIC_CONTEXT_CARDINALITY, projectDiagnosticRecord, statusGroup, } from "../../src/contracts/diagnostics.ts"; import { TELEMETRY_ATTRIBUTE_ALLOWLIST, projectTelemetryEvent, } from "../../src/contracts/telemetry.ts"; describe("observability cardinality policy", () => { it("classifies every diagnostic context key exactly once", () => { expect(Object.keys(DIAGNOSTIC_CONTEXT_CARDINALITY).sort()).toEqual( [...DIAGNOSTIC_CONTEXT_ALLOWLIST].sort(), ); expect(DIAGNOSTIC_CONTEXT_CARDINALITY.correlation_id).toBe("request"); expect(DIAGNOSTIC_CONTEXT_CARDINALITY.route_id).toBe("topology"); expect(DIAGNOSTIC_CONTEXT_CARDINALITY.operation_id).toBe("topology"); expect(DIAGNOSTIC_CONTEXT_CARDINALITY.duration_bucket).toBe("bounded"); }); it("keeps request-cardinality keys out of telemetry dimensions", () => { for (const key of TELEMETRY_ATTRIBUTE_ALLOWLIST) { expect(DIAGNOSTIC_CONTEXT_CARDINALITY[key]).not.toBe("request"); } expect(TELEMETRY_ATTRIBUTE_ALLOWLIST).not.toContain("correlation_id"); }); it("rejects free-form values for bounded diagnostic dimensions", () => { expect( projectDiagnosticRecord({ level: "info", eventId: "http.request.completed", context: { outcome: "customer-123", http_status_group: "599", attempt_count_bucket: "37", duration_bucket: "12345ms", }, }), ).toEqual({ success: false, reason: "invalid-context" }); }); // 1103/03-05. The effect certainty is a closed five-value dimension in // both sinks. it.each(["NOT_APPLICABLE", "NOT_STARTED", "NOT_APPLIED", "APPLIED_CONFIRMED", "MAYBE_APPLIED"])( "admits effect_certainty %s in diagnostics and failure telemetry", (effect) => { expect(DIAGNOSTIC_CONTEXT_CARDINALITY.effect_certainty).toBe("bounded"); expect( projectDiagnosticRecord({ level: "warn", eventId: "http.request.completed", context: { effect_certainty: effect }, }).success, ).toBe(true); expect( projectTelemetryEvent("api.request.failed", { error_kind: "PROBLEM", http_status_group: "4xx", attempt_count_bucket: "1", route_id: "TEST_ROUTE", effect_certainty: effect, }).success, ).toBe(true); }, ); it.each(["maybe", "UNKNOWN", "MAYBE_APPLIED_ON_RETRY"])( "rejects effect_certainty %j in both sinks", (effect) => { expect( projectDiagnosticRecord({ level: "warn", eventId: "http.request.completed", context: { effect_certainty: effect }, }), ).toEqual({ success: false, reason: "invalid-context" }); expect( projectTelemetryEvent("api.request.failed", { error_kind: "PROBLEM", http_status_group: "4xx", attempt_count_bucket: "1", route_id: "TEST_ROUTE", effect_certainty: effect, }), ).toEqual({ success: false, reason: "invalid-attribute-value" }); }, ); it("allows request correlation only in bounded diagnostics evidence", () => { const projected = projectDiagnosticRecord({ level: "info", eventId: "http.request.completed", context: { correlation_id: "request-a1b2c3", outcome: "success", http_status_group: "2xx", attempt_count_bucket: "1", duration_bucket: "lt100ms", }, }); expect(projected.success).toBe(true); }); }); /** * R-7.5. One operationId grammar. The V3 composition accepts camelCase ids of * up to 128 characters; a failure for such an operation must not be dropped * as an invalid telemetry attribute, and diagnostics apply the same rule. */ describe("shared operationId and status-group grammar", () => { function telemetryFailure(operationId: string, httpStatusGroup = "5xx") { return projectTelemetryEvent("api.request.failed", { error_kind: "SERVER_FAILURE", http_status_group: httpStatusGroup, attempt_count_bucket: "1", route_id: "TEST_ROUTE", operation_id: operationId, }); } function diagnosticCompletion(operationId: string, httpStatusGroup = "5xx") { return projectDiagnosticRecord({ level: "warn", eventId: "http.request.completed", context: { operation_id: operationId, http_status_group: httpStatusGroup }, }); } it.each([ "getUser", "LIST_ORDER_ITEMS", "users.v1.get-item", `a${"b".repeat(127)}`, ])("keeps both observability records for operationId %s", (operationId) => { expect(telemetryFailure(operationId).success).toBe(true); expect(diagnosticCompletion(operationId).success).toBe(true); }); it.each(["", "1getUser", "get user", "get:user", "get/user", `a${"b".repeat(128)}`])( "rejects operationId %j in both sinks", (operationId) => { expect(telemetryFailure(operationId)).toEqual({ success: false, reason: "invalid-attribute-value", }); expect(diagnosticCompletion(operationId)).toEqual({ success: false, reason: "invalid-context", }); }, ); it.each([undefined, 0, 101, 204, 302, 404, 503, 999])( "accepts the status group statusGroup(%s) produces in both sinks", (status) => { const group = statusGroup(status); expect(telemetryFailure("GET_USER", group).success).toBe(true); expect(diagnosticCompletion("GET_USER", group).success).toBe(true); }, ); });