Files
0pt/tests/contracts/siax-context.contract.test.ts
Simon AxelssonandClaude Fable 5 da58176735 test(contracts): per-client wire-contract suites + §3 production-guard tests
38 tests: recording provider double answers with the sibling services' real
response shapes; each suite asserts the exact request wire shape (path,
method, tenant/actor/idempotency headers, camelCase vs snake_case body) so a
regression to the pre-rewrite invented shapes fails loudly. Includes the
fail-closed policy cases (missing decision => deny, CL0UD down => typed
error, never implicit allow) and the production factory guard for all four
clients.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-31 16:37:57 +02:00

134 lines
5.0 KiB
TypeScript

/**
* 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" });
});
});