/** * Pins 0pt's MIRROR of cl0ud's canonical request-context contract * (src/platform/siax-context.ts + src/platform/errors.ts) to the canonical * values from sax3l/cl0ud `packages/contract/src/request-context.ts`. * If cl0ud evolves the contract, this test is the tripwire that forces the * mirror (and this pin) to be updated deliberately, never by drift. */ import { describe, it, expect } from "vitest"; import { SIAX_CONTEXT_HEADERS, toPropagationHeaders, validateSiaxRequestContext, } from "@/src/platform/siax-context"; import { SIAX_ERROR_CODES, SiaxError, httpStatusForSiaxErrorCode, siaxErrorCodeForUpstreamStatus, } from "@/src/platform/errors"; describe("SIAX context header names (pinned to cl0ud @siax/contract)", () => { it("uses the canonical wire header names, verbatim", () => { expect(SIAX_CONTEXT_HEADERS).toEqual({ tenant: "x-tenant-id", actor: "x-actor-id", capability: "x-siax-capability", purpose: "x-siax-purpose", project: "x-siax-project-id", correlation: "x-siax-correlation-id", causation: "x-siax-causation-id", trace: "x-siax-trace-id", idempotency: "idempotency-key", }); }); it("serializes required fields always and optional fields only when present", () => { const minimal = toPropagationHeaders({ tenantId: "t_x", actorId: "svc_0pt", capability: "0pt.search.query.v1", correlationId: "corr-1", }); expect(minimal).toEqual({ "x-tenant-id": "t_x", "x-actor-id": "svc_0pt", "x-siax-capability": "0pt.search.query.v1", "x-siax-correlation-id": "corr-1", }); const full = toPropagationHeaders({ tenantId: "t_x", projectId: "p_1", actorId: "svc_0pt", capability: "0pt.search.query.v1", purpose: "valuation", correlationId: "corr-1", causationId: "cause-1", traceId: "trace-1", idempotencyKey: "idem-1", }); expect(full["x-siax-project-id"]).toBe("p_1"); expect(full["x-siax-purpose"]).toBe("valuation"); expect(full["x-siax-causation-id"]).toBe("cause-1"); expect(full["x-siax-trace-id"]).toBe("trace-1"); expect(full["idempotency-key"]).toBe("idem-1"); }); it("validates required fields (tenantId/actorId/capability/correlationId)", () => { expect( validateSiaxRequestContext({ tenantId: "t_x", actorId: "a", capability: "c", correlationId: "x", }) ).toEqual([]); const problems = validateSiaxRequestContext({ tenantId: " " }); expect(problems.join(" ")).toMatch(/tenantId/); expect(problems.join(" ")).toMatch(/actorId/); expect(problems.join(" ")).toMatch(/capability/); expect(problems.join(" ")).toMatch(/correlationId/); }); }); describe("Canonical SIAX error vocabulary (pinned to Master-DoD §6 / cl0ud)", () => { it("carries exactly the 12 canonical codes, in canonical order", () => { expect([...SIAX_ERROR_CODES]).toEqual([ "UNAUTHENTICATED", "AUTHORIZATION_DENIED", "ENTITLEMENT_REQUIRED", "CAPABILITY_UNAVAILABLE", "QUOTA_EXCEEDED", "RATE_LIMITED", "INVALID_REQUEST", "NOT_FOUND", "CONFLICT", "DEPENDENCY_UNAVAILABLE", "RETRYABLE_FAILURE", "PERMANENT_FAILURE", ]); }); it("maps codes to the canonical HTTP statuses (pinned to cl0ud's mapping)", () => { expect(httpStatusForSiaxErrorCode("UNAUTHENTICATED")).toBe(401); expect(httpStatusForSiaxErrorCode("AUTHORIZATION_DENIED")).toBe(403); expect(httpStatusForSiaxErrorCode("ENTITLEMENT_REQUIRED")).toBe(402); expect(httpStatusForSiaxErrorCode("QUOTA_EXCEEDED")).toBe(402); expect(httpStatusForSiaxErrorCode("CAPABILITY_UNAVAILABLE")).toBe(404); expect(httpStatusForSiaxErrorCode("RATE_LIMITED")).toBe(429); expect(httpStatusForSiaxErrorCode("INVALID_REQUEST")).toBe(400); expect(httpStatusForSiaxErrorCode("NOT_FOUND")).toBe(404); expect(httpStatusForSiaxErrorCode("CONFLICT")).toBe(409); expect(httpStatusForSiaxErrorCode("DEPENDENCY_UNAVAILABLE")).toBe(503); expect(httpStatusForSiaxErrorCode("RETRYABLE_FAILURE")).toBe(503); expect(httpStatusForSiaxErrorCode("PERMANENT_FAILURE")).toBe(500); }); it("classifies upstream statuses with retryable-vs-permanent explicit (§6)", () => { expect(siaxErrorCodeForUpstreamStatus(503)).toBe("DEPENDENCY_UNAVAILABLE"); expect(siaxErrorCodeForUpstreamStatus(429)).toBe("RATE_LIMITED"); expect(siaxErrorCodeForUpstreamStatus(500)).toBe("RETRYABLE_FAILURE"); const retryable = new SiaxError("DEPENDENCY_UNAVAILABLE", "st0re", "down"); expect(retryable.retryable).toBe(true); const permanent = new SiaxError("PERMANENT_FAILURE", "st0re", "broken"); expect(permanent.retryable).toBe(false); }); it("carries correlation id in the error and its JSON form (§6)", () => { const err = new SiaxError("NOT_FOUND", "n0d", "job missing", { correlationId: "corr-9" }); expect(err.correlationId).toBe("corr-9"); expect(err.toJSON()).toMatchObject({ error: "NOT_FOUND", source: "n0d", correlation_id: "corr-9" }); }); });