clean-architecture-frontend-template/tests/runtime-schema/release-manifest.test.ts

import { describe, expect, it } from "vitest";

import {
  loadReleaseManifest,
  ReleaseManifestError,
} from "../../src/bootstrap/load-release-manifest.ts";
import { computeContractSetDigest } from "../../src/contracts/contract-set-canonical.ts";

const EMPTY_SET_DIGEST = await computeContractSetDigest([]);

const runtime: Parameters<typeof loadReleaseManifest>[0] = {
  build: {
    buildId: "build-a",
    commitSha: "abc123",
    routerBasePath: "/",
    runtimeConfigUrl: "/config.json",
  },
  config: {
    APP_ENV: "local",
    API_BASE_URL: "https://api.test",
    REQUEST_TIMEOUT_MS: 10_000,
    MAX_RETRY_ATTEMPTS: 2,
    TELEMETRY_ENABLED: false,
    AUTH_MODE: "external",
    RELEASE_MANIFEST_URL: "/release-manifest.json",
    BUILD_ID: "build-a",
    RELEASE_ID: "release-a",
    CONFIG_SCHEMA_VERSION: "2.0",
    CAPABILITY_OVERRIDES: {
      REALTIME: "DEFAULT",
      WEB_WORKER: "DEFAULT",
      SERVICE_WORKER: "DEFAULT",
      OFFLINE_COMMANDS: "DEFAULT",
    },
    FEATURE_OVERRIDES: {},
  },
  configSchema: "V2",
  validationDurationMs: 0,
};
const manifest = {
  schemaVersion: 2,
  appVersion: "0.1.0",
  buildId: "build-a",
  commitSha: "abc123",
  configSchemaVersion: "2.0",
  assetManifestHash: "hash-a",
  releaseId: "release-a",
  builtAt: "2026-07-25T00:00:00Z",
  routeChunks: { "route-home": "assets/home.js" },
  contractSet: {
    setAlgorithm: "CA_CONTRACT_SET_V1",
    setDigest: EMPTY_SET_DIGEST,
    packages: [],
  },
};

const runtimeV1: Parameters<typeof loadReleaseManifest>[0] = {
  ...runtime,
  config: {
    ...runtime.config,
    CONFIG_SCHEMA_VERSION: "1",
    LEGACY_API_CONTRACT_VERSION: "1",
  },
  configSchema: "V1",
};

const manifestV1 = {
  schemaVersion: 1,
  appVersion: "0.1.0",
  buildId: "build-a",
  commitSha: "abc123",
  configSchemaVersion: "1",
  apiContractVersion: "1",
  assetManifestHash: "hash-a",
  releaseId: "release-a",
  builtAt: "2026-07-25T00:00:00Z",
  routeChunks: { "route-home": "assets/home.js" },
};

function jsonResponse(body: unknown): Response {
  return new Response(JSON.stringify(body), {
    headers: { "content-type": "application/json" },
  });
}

describe("release manifest boot boundary", () => {
  it("loads a coherent release tuple", async () => {
    await expect(
      loadReleaseManifest(
        runtime,
        { fetcher: async () => jsonResponse(manifest) },
      ),
    ).resolves.toMatchObject({ releaseId: "release-a" });
  });

  it("fails before mount when release and runtime differ", async () => {
    await expect(
      loadReleaseManifest(
        runtime,
        {
          fetcher: async () =>
            jsonResponse({ ...manifest, buildId: "build-b" }),
        },
      ),
    ).rejects.toMatchObject({
      kind: "BUILD_MISMATCH",
      code: "MANIFEST_BUILD_MISMATCH",
    });
  });

  it.each([
    [
      { releaseId: "release-b" },
      {},
      "RELEASE_MISMATCH",
      "MANIFEST_RELEASE_MISMATCH",
    ],
    [
      {},
      { expectedAssetManifestHash: "different" },
      "ASSET_MISMATCH",
      "MANIFEST_ASSET_MISMATCH",
    ],
  ])(
    "classifies tuple mismatch %# without a generic deploy error",
    async (manifestOverride, options, kind, code) => {
      await expect(
        loadReleaseManifest(
          runtime,
          {
            fetcher: async () =>
              jsonResponse({ ...manifest, ...manifestOverride }),
            ...options,
          },
        ),
      ).rejects.toMatchObject({ kind, code });
    },
  );

  it.each(["3.0", "9.0"])(
    "rejects unsupported V2 manifest config version %s at the schema boundary",
    async (configSchemaVersion) => {
      await expect(
        loadReleaseManifest(runtime, {
          fetcher: async () =>
            jsonResponse({ ...manifest, configSchemaVersion }),
        }),
      ).rejects.toMatchObject({
        kind: "RELEASE_MANIFEST_FAILURE",
        code: "MANIFEST_SCHEMA_INVALID",
      });
    },
  );

  it("rejects a contract set the build did not compile", async () => {
    await expect(
      loadReleaseManifest(runtime, {
        fetcher: async () =>
          jsonResponse({
            ...manifest,
            contractSet: {
              setAlgorithm: "CA_CONTRACT_SET_V1",
              setDigest: EMPTY_SET_DIGEST,
              packages: [
                {
                  packageId: "@org-contracts/worklog",
                  version: "1.2.3",
                  digest: `sha256:${"a".repeat(64)}`,
                  runtimeProtocolVersion: 1,
                  sourceRevision: "abc1234",
                },
              ],
            },
          }),
      }),
    ).rejects.toMatchObject({
      kind: "CONTRACT_SET_MISMATCH",
      code: "CONTRACT_SET_PACKAGE_UNEXPECTED",
    });
  });

  it("still reads a V1 manifest during the compatibility window", async () => {
    await expect(
      loadReleaseManifest(
        runtimeV1,
        {
          fetcher: async () => jsonResponse(manifestV1),
        },
      ),
    ).resolves.toMatchObject({ schemaVersion: 1, contractSet: null });
  });

  it("rejects a V2 runtime paired with a V1 manifest", async () => {
    await expect(
      loadReleaseManifest(runtime, {
        fetcher: async () => jsonResponse({
          ...manifestV1,
          configSchemaVersion: "2.0",
        }),
      }),
    ).rejects.toMatchObject({
      kind: "PROTOCOL_PAIR_MISMATCH",
      code: "MANIFEST_PROTOCOL_PAIR_MISMATCH",
    });
  });

  it("rejects a V1 runtime paired with a V2 manifest", async () => {
    await expect(
      loadReleaseManifest(runtimeV1, {
        fetcher: async () => jsonResponse(manifest),
      }),
    ).rejects.toMatchObject({
      kind: "PROTOCOL_PAIR_MISMATCH",
      code: "MANIFEST_PROTOCOL_PAIR_MISMATCH",
    });
  });

  it("requires matching legacy scalar versions for a V1 pair", async () => {
    await expect(
      loadReleaseManifest(runtimeV1, {
        fetcher: async () => jsonResponse({
          ...manifestV1,
          apiContractVersion: "2",
        }),
      }),
    ).rejects.toMatchObject({
      kind: "API_CONTRACT_MISMATCH",
      code: "MANIFEST_API_CONTRACT_MISMATCH",
    });
  });

  it("rejects a manifest without a complete route chunk map", async () => {
    const malformed = Object.fromEntries(
      Object.entries(manifest).filter(([key]) => key !== "routeChunks"),
    );
    await expect(
      loadReleaseManifest(
        runtime,
        { fetcher: async () => jsonResponse(malformed) },
      ),
    ).rejects.toBeInstanceOf(ReleaseManifestError);
  });
});