/** * CONTRACT test for src/clients/st0re-client.ts against ST0RE's REAL wire * contract (sax3l/st0re main `src/api/routes/artifacts.ts` + * `src/api/validation.ts` ArtifactInputSchema, verified 2026-08-31): * * POST /v1/st0re/artifacts/register * headers: X-Tenant-Id (required), X-Actor-Id (required), * X-Idempotency-Key (optional) * body: camelCase — tenantId, projectId, appId, artifactType, * displayName, producedBy, primaryObjectId, schemaVersion, * retentionPolicy, createdBy, checksumSha256 (64 hex) * 201 → { artifactId, createdAt, ... } / 200 → idempotent replay * * The pre-2026-08-31 client sent snake_case + object_location{} — that shape * fails ST0RE's Zod validation with a 400. This test is the tripwire. */ import { describe, it, expect, afterEach } from "vitest"; import { createSt0reClient, type St0reArtifactInput } from "@/src/clients/st0re-client"; import { SiaxError } from "@/src/platform/errors"; import { startContractServer, type ContractServer } from "./contract-test-server"; let server: ContractServer | undefined; afterEach(async () => { await server?.close(); server = undefined; }); const CHECKSUM = "a".repeat(64); function input(overrides: Partial = {}): St0reArtifactInput { return { tenant_id: "t_test", project_id: "p_test", artifact_type: "dataset_export", app_id: "0pt", produced_by: "0pt.dataset.export", object_location: { provider: "minio", bucket: "siax-tenants", key: "t_test/exports/x.parquet" }, content_type: "application/vnd.apache.parquet", size_bytes: 1234, checksum_sha256: CHECKSUM, pii_level: "none", retention_policy: "standard", data_residency: "eu", risk_level: "L2", correlation_id: "corr-42", idempotency_key: "idem-artifact-1", ...overrides, }; } describe("St0reClient wire contract", () => { it("POSTs the REAL camelCase ArtifactInput to /v1/st0re/artifacts/register with tenant/actor/idempotency headers", async () => { server = await startContractServer([ { method: "POST", path: "/v1/st0re/artifacts/register", status: 201, respond: () => ({ artifactId: "art_r3al", tenantId: "t_test", createdAt: 1756640000000 }), }, ]); const client = createSt0reClient(server.baseUrl); const artifact = await client.createArtifact(input()); expect(server.requests).toHaveLength(1); const req = server.requests[0]; expect(req.method).toBe("POST"); expect(req.path).toBe("/v1/st0re/artifacts/register"); // Required ST0RE headers. expect(req.headers["x-tenant-id"]).toBe("t_test"); expect(req.headers["x-actor-id"]).toBe("0pt.dataset.export"); expect(req.headers["x-idempotency-key"]).toBe("idem-artifact-1"); // REAL body contract: camelCase, required fields present, s3:// URI. const body = req.body as Record; expect(body.tenantId).toBe("t_test"); expect(body.projectId).toBe("p_test"); expect(body.appId).toBe("0pt"); expect(body.artifactType).toBe("dataset_export"); expect(body.displayName).toBe("x.parquet"); expect(body.producedBy).toBe("0pt.dataset.export"); expect(body.primaryObjectId).toBe("s3://siax-tenants/t_test/exports/x.parquet"); expect(body.schemaVersion).toBe("v1"); expect(body.retentionPolicy).toBe("standard"); expect(body.createdBy).toBe("0pt.dataset.export"); expect(body.checksumSha256).toBe(CHECKSUM); expect(body.idempotencyKey).toBe("idem-artifact-1"); // The invented pre-rewrite fields must NOT be on the wire. expect(body.object_location).toBeUndefined(); expect(body.tenant_id).toBeUndefined(); // Response mapping. expect(artifact.artifact_id).toBe("art_r3al"); expect(artifact.created_at).toBe(new Date(1756640000000).toISOString()); }); it("treats HTTP 200 as an idempotent replay success (ST0RE's documented semantics)", async () => { server = await startContractServer([ { method: "POST", path: "/v1/st0re/artifacts/register", status: 200, respond: () => ({ artifactId: "art_existing", createdAt: 1756000000000 }), }, ]); const client = createSt0reClient(server.baseUrl); const artifact = await client.createArtifact(input()); expect(artifact.artifact_id).toBe("art_existing"); }); it("maps a 400 to SiaxError INVALID_REQUEST without leaking the upstream body", async () => { server = await startContractServer([ { method: "POST", path: "/v1/st0re/artifacts/register", status: 400, respond: () => ({ error: { code: "ST0RE_VALIDATION_ERROR", message: "secret-internal-detail" } }), }, ]); const client = createSt0reClient(server.baseUrl); try { await client.createArtifact(input()); expect.unreachable("must throw"); } catch (err) { expect(err).toBeInstanceOf(SiaxError); expect((err as SiaxError).code).toBe("INVALID_REQUEST"); expect((err as SiaxError).message).toContain("ST0RE_VALIDATION_ERROR"); expect((err as SiaxError).message).not.toContain("secret-internal-detail"); } }); it("maps a 503 to a RETRYABLE SiaxError DEPENDENCY_UNAVAILABLE", async () => { server = await startContractServer([ { method: "POST", path: "/v1/st0re/artifacts/register", status: 503, respond: () => ({ error: { code: "ST0RE_UNAVAILABLE" } }), }, ]); const client = createSt0reClient(server.baseUrl); try { await client.createArtifact(input()); expect.unreachable("must throw"); } catch (err) { expect((err as SiaxError).code).toBe("DEPENDENCY_UNAVAILABLE"); expect((err as SiaxError).retryable).toBe(true); } }); });