import { describe, expect, it, vi } from "vitest"; import { createRuntimeAdapters, createRuntimeContractHttpExecutor, } from "../../src/bootstrap/runtime-adapters.ts"; import { createBrowserMutationIntentFactory } from "../../src/adapters/platform/browser-mutation-intent-factory.ts"; import { createApplication } from "../../src/application/create-application.ts"; import type { ApplicationFeatureId } from "../../src/application/ports/in/application-api.ts"; import { loadFeatureRuntime } from "../../src/features/feature-module.ts"; import { INSTALLED_PRODUCT_FEATURE_MODULES } from "../../src/features/installed-product-manifest.ts"; import { TEST_LIST_HTTP_CONTRACT } from "../helpers/external-contract-fixture.ts"; import { testRuntimeConfig } from "../helpers/runtime-config.ts"; import { scopeSnapshot } from "../helpers/traffic-test-kit.ts"; type Runtime = Parameters[0]["runtime"]; type Release = Parameters[0]["release"]; const runtime: Runtime = { config: testRuntimeConfig({ APP_ENV: "local", API_BASE_URL: "http://localhost:8080", TELEMETRY_ENABLED: false, AUTH_MODE: "demo", REQUEST_TIMEOUT_MS: 4321, MAX_RETRY_ATTEMPTS: 0, RELEASE_MANIFEST_URL: "/release-manifest.json", CONFIG_SCHEMA_VERSION: "2.0", CAPABILITY_OVERRIDES: { REALTIME: "DEFAULT", WEB_WORKER: "DEFAULT", SERVICE_WORKER: "DEFAULT", OFFLINE_COMMANDS: "DEFAULT", }, FEATURE_OVERRIDES: {}, }), configSchema: "V2", build: { buildId: "build-a", commitSha: "abc123", routerBasePath: "/", runtimeConfigUrl: "/config.json", }, validationDurationMs: 0, }; const release: Release = { schemaVersion: 2, appVersion: "0.1.0", buildId: "build-a", commitSha: "abc123", configSchemaVersion: "2.0", contractSet: { setAlgorithm: "CA_CONTRACT_SET_V1", setDigest: `sha256:${"0".repeat(64)}`, packages: [], }, assetManifestHash: "hash-a", releaseId: "release-a", builtAt: "2026-07-25T00:00:00Z", routeChunks: { "route-home": "assets/home.js" }, }; /** * 1103/09-04. The installed features that contribute an application API. The * template's example screens call none: loading them * installs no input. */ const API_FEATURE_IDS: readonly string[] = ( await Promise.all( INSTALLED_PRODUCT_FEATURE_MODULES.map(async (module) => (await loadFeatureRuntime(module)).adapters.length > 0 ? [module.id] : [], ), ) ).flat(); describe("runtime adapter composition", () => { it("creates validated intent and idempotency identities with independent UUID calls", () => { const randomUUID = vi .fn<() => string>() .mockReturnValueOnce("intent-uuid") .mockReturnValueOnce("idempotency-uuid"); const factory = createBrowserMutationIntentFactory({ randomUUID, monotonicNow: () => 12.5, }); const intent = factory.create({ operationId: "CREATE_ENTITY", canonicalInputIdentity: "opaque-canonical-input", requiresIdempotencyKey: true, }); expect(intent).toEqual({ intentId: "intent-uuid", operationId: "CREATE_ENTITY", canonicalInputIdentity: "opaque-canonical-input", idempotencyKey: "idempotency-uuid", createdAtMonotonicMs: 12.5, }); expect(Object.isFrozen(intent)).toBe(true); expect(randomUUID).toHaveBeenCalledTimes(2); }); it("rejects invalid or unbounded mutation intent values", () => { const factory = createBrowserMutationIntentFactory({ randomUUID: () => "opaque-runtime-identifier", monotonicNow: () => 1, }); expect(() => factory.create({ operationId: " ", canonicalInputIdentity: "valid-identity", requiresIdempotencyKey: false, }), ).toThrow(TypeError); expect(() => factory.create({ operationId: "CREATE_ENTITY", canonicalInputIdentity: "x".repeat(16_385), requiresIdempotencyKey: false, }), ).toThrow(TypeError); expect(() => createBrowserMutationIntentFactory({ randomUUID: () => "opaque-runtime-identifier", monotonicNow: () => -1, }).create({ operationId: "CREATE_ENTITY", canonicalInputIdentity: "valid-identity", requiresIdempotencyKey: false, }), ).toThrow(TypeError); }); it("constructs the local demo seam and infrastructure adapters", async () => { const adapters = await createRuntimeAdapters({ runtime, release, host: {}, }); expect(adapters.outputPorts.session.getState()).toBe("unauthenticated"); await expect(adapters.outputPorts.releaseInfo.getCurrent()).resolves.toMatchObject({ releaseId: "release-a", }); expect(adapters.infrastructure.queryClient).toBeDefined(); expect(adapters.infrastructure.queryInvalidation).toBeDefined(); expect(adapters.infrastructure.mutationIntentFactory).toBeDefined(); expect( adapters.infrastructure.crossContextInvalidationStatus(), ).toBe("DEGRADED_LOCAL_ONLY"); expect(adapters.outputPorts.diagnostics.record).toEqual(expect.any(Function)); expect(adapters.outputPorts.telemetry.emit).toEqual(expect.any(Function)); expect(adapters.outputPorts.telemetry.pendingCount()).toBe(0); expect(adapters).not.toHaveProperty("http"); expect(adapters).not.toHaveProperty("storage"); adapters.infrastructure.dispose(); }); it("runtime infrastructure disposal disposes telemetry first", async () => { const fetcher = vi.fn(async () => new Response(null, { status: 204 })); const adapters = await createRuntimeAdapters({ runtime: { ...runtime, config: { ...runtime.config, TELEMETRY_ENABLED: true, TELEMETRY_ENDPOINT: "https://telemetry.test/events", }, } as Runtime, release, host: {}, fetcher: fetcher as unknown as typeof fetch, }); adapters.outputPorts.telemetry.emit("api.request.failed", { error_kind: "SERVER_FAILURE", http_status_group: "5xx", attempt_count_bucket: "1", route_id: "TEST_ROUTE", }); expect(adapters.outputPorts.telemetry.pendingCount()).toBe(1); adapters.infrastructure.dispose(); expect(adapters.outputPorts.telemetry.pendingCount()).toBe(0); await Promise.resolve(); await Promise.resolve(); expect(fetcher).not.toHaveBeenCalled(); }); it("sends telemetry stamped with the release identity (13-11)", async () => { const bodies: { events: Record[] }[] = []; const fetcher = vi.fn(async (_url: RequestInfo | URL, init?: RequestInit) => { if (String(_url) === "https://telemetry.test/events") { bodies.push(JSON.parse(String(init?.body))); } return new Response(null, { status: 204 }); }); const adapters = await createRuntimeAdapters({ runtime: { ...runtime, config: { ...runtime.config, TELEMETRY_ENABLED: true, TELEMETRY_ENDPOINT: "https://telemetry.test/events", }, } as Runtime, release, host: {}, fetcher: fetcher as unknown as typeof fetch, }); adapters.outputPorts.telemetry.emit("api.request.failed", { error_kind: "SERVER_FAILURE", http_status_group: "5xx", attempt_count_bucket: "1", route_id: "TEST_ROUTE", }); await adapters.outputPorts.telemetry.flush(); expect(bodies[0]?.events[0]).toMatchObject({ eventName: "api.request.failed", build_id: "build-a", release_id: "release-a", }); adapters.infrastructure.dispose(); }); it("replaces the QueryClient and coordinator for each session generation", async () => { const adapters = await createRuntimeAdapters({ runtime, release, host: {} }); const previousClient = adapters.infrastructure.queryClient; const previousCoordinator = adapters.infrastructure.queryInvalidation; const runtimeMutationIntentFactory = adapters.infrastructure.mutationIntentFactory; const clearPrevious = vi.spyOn(previousClient, "clear"); await adapters.outputPorts.session.beginSignIn(); await vi.waitFor(() => expect(adapters.infrastructure.queryClient).not.toBe(previousClient), ); expect(adapters.infrastructure.queryInvalidation).not.toBe( previousCoordinator, ); expect(adapters.infrastructure.mutationIntentFactory).toBe( runtimeMutationIntentFactory, ); const clearCallsAfterReplacement = clearPrevious.mock.calls.length; await previousCoordinator.resetLocal(); expect(clearPrevious).toHaveBeenCalledTimes(clearCallsAfterReplacement); adapters.infrastructure.dispose(); }); it("does not fail boot when Web Storage capability getters throw", async () => { const host: Record = {}; Object.defineProperties(host, { localStorage: { get() { throw new DOMException("denied", "SecurityError"); }, }, sessionStorage: { get() { throw new DOMException("denied", "SecurityError"); }, }, }); const adapters = await createRuntimeAdapters({ runtime, release, host, }); expect(adapters.infrastructure.queryClient).toBeDefined(); expect(adapters.outputPorts.preferences.read("COLOR_SCHEME")).toEqual({ ok: true, value: undefined, }); adapters.infrastructure.dispose(); }); it("fails closed when an external auth owner was not installed", async () => { const adapters = await createRuntimeAdapters({ runtime: { ...runtime, config: { ...runtime.config, AUTH_MODE: "external" }, }, release, host: {}, }); expect(adapters.outputPorts.session.getState()).toBe("integration-failed"); }); describe("installed external auth owner shape", () => { const externalRuntime: Runtime = { ...runtime, config: { ...runtime.config, AUTH_MODE: "external" }, }; const completeOwner = () => ({ readState: () => "authenticated", readSubject: () => "user-a", subscribe: () => () => {}, beginSignIn: async () => {}, signOut: async () => {}, attachCredential: async () => ({ headers: {} }), recoverSession: async () => "no-session", notifyUnauthenticated: () => {}, }); it("uses an owner that implements every method", async () => { const adapters = await createRuntimeAdapters({ runtime: externalRuntime, release, host: { __CA_FRONTEND_AUTH_OWNER__: completeOwner() }, }); expect(adapters.outputPorts.session.getState()).toBe("authenticated"); expect(adapters.outputPorts.session.getSubject()).toBe("user-a"); adapters.infrastructure.dispose(); }); it.each(["readSubject", "readState"])( "fails closed when the owner lacks %s", async (method) => { const owner: Record = completeOwner(); delete owner[method]; const adapters = await createRuntimeAdapters({ runtime: externalRuntime, release, host: { __CA_FRONTEND_AUTH_OWNER__: owner }, }); expect(adapters.outputPorts.session.getState()).toBe( "integration-failed", ); adapters.infrastructure.dispose(); }, ); }); it("reports the static selection when no capability override disables it", async () => { const adapters = await createRuntimeAdapters({ runtime, release, host: {} }); const snapshot = adapters.outputPorts.runtimeCapabilities.getSnapshot(); expect(snapshot.map((status) => status.capabilityId)).toEqual([ "REALTIME", "WEB_WORKER", "SERVICE_WORKER", "OFFLINE_COMMANDS", ]); expect(snapshot.every((status) => status.override === "DEFAULT")).toBe(true); }); it("carries a disabling override into the capability snapshot", async () => { const adapters = await createRuntimeAdapters({ runtime: { ...runtime, config: { ...runtime.config, CAPABILITY_OVERRIDES: { ...runtime.config.CAPABILITY_OVERRIDES, SERVICE_WORKER: "DISABLED", }, FEATURE_OVERRIDES: {}, }, }, release, host: {}, }); const serviceWorker = adapters.outputPorts.runtimeCapabilities .getSnapshot() .find((status) => status.capabilityId === "SERVICE_WORKER"); expect(serviceWorker?.override).toBe("DISABLED"); expect(serviceWorker?.active).toBe(0); }); it("gives a feature switched off by FEATURE_OVERRIDES no application API (Q-6.9-5)", async () => { const [disabledId, ...activeIds] = API_FEATURE_IDS; const adapters = await createRuntimeAdapters({ runtime: { ...runtime, config: { ...runtime.config, FEATURE_OVERRIDES: { [disabledId!]: "DISABLED" }, }, }, release, host: {}, }); const application = createApplication( adapters.outputPorts, {}, adapters.featureLoaders, ); expect(adapters.outputPorts.productFeatures.isActive(disabledId!)).toBe(false); // 15-01. A switched-off feature gets no loader, so loading installs nothing. await application.features.load(disabledId!); expect(application.features.has(disabledId!)).toBe(false); expect(() => application.features.get(disabledId as ApplicationFeatureId), ).toThrow(/not installed/u); for (const featureId of activeIds) { await application.features.load(featureId); expect(application.features.has(featureId)).toBe(true); } adapters.infrastructure.dispose(); }); it("still resolves every installed feature API when nothing is switched off", async () => { const adapters = await createRuntimeAdapters({ runtime, release, host: {} }); const application = createApplication( adapters.outputPorts, {}, adapters.featureLoaders, ); for (const featureId of API_FEATURE_IDS) { // 15-01. Not loaded until the router asks for the feature's routes. expect(() => application.features.get(featureId as ApplicationFeatureId), ).toThrow(/not loaded yet/u); await application.features.load(featureId); expect(application.features.has(featureId)).toBe(true); expect( application.features.get(featureId as ApplicationFeatureId), ).toBeDefined(); } adapters.infrastructure.dispose(); }); it("states contract identity as a digest for a V2 release manifest", async () => { const adapters = await createRuntimeAdapters({ runtime, release, host: {} }); const current = await adapters.outputPorts.releaseInfo.getCurrent(); expect(current.contractSetDigest).toBe(release.contractSet?.setDigest); expect(current.apiContractVersion).toBeUndefined(); expect(current).not.toHaveProperty("contractSet"); }); it("states contract identity as the legacy scalar for a V1 release manifest", async () => { const adapters = await createRuntimeAdapters({ runtime, release: { ...release, schemaVersion: 1, contractSet: null, legacyApiContractVersion: "1.4", }, host: {}, }); const current = await adapters.outputPorts.releaseInfo.getCurrent(); expect(current.apiContractVersion).toBe("1.4"); expect(current.contractSetDigest).toBeUndefined(); expect(current).not.toHaveProperty("legacyApiContractVersion"); }); it("refetches the active release manifest with no-store semantics", async () => { const activeRelease = { ...release, buildId: "build-b", releaseId: "release-b", routeChunks: { "route-home": "assets/home-b.js" }, }; const fetcher = vi.fn(async () => new Response(JSON.stringify(activeRelease), { headers: { "content-type": "application/json" }, }), ); const adapters = await createRuntimeAdapters({ runtime, release, fetcher, host: {}, }); await expect(adapters.outputPorts.releaseInfo.refresh()).resolves.toMatchObject({ buildId: "build-b", releaseId: "release-b", }); expect(fetcher).toHaveBeenCalledWith( "/release-manifest.json", expect.objectContaining({ method: "GET", cache: "no-store", credentials: "same-origin", redirect: "error", referrerPolicy: "no-referrer", headers: { Accept: "application/json" }, }), ); }); }); /** * 1105/10-01. Runtime Config's two HTTP dials, on the test contracts. The * reference feature's composition test drives MAX_RETRY_ATTEMPTS through * `createRuntimeAdapters`, which needs an installed feature's HTTP. These need * none, so they stay when a product removes the sample * (`scripts/test-sample-removal.ts` keeps this file). */ describe("runtime contract HTTP executor", () => { const answerReady = () => ({ kind: "READY" as const, headers: {} }); // The test list read is SAFE and declares a retry budget of 2. it.each([ [0, 1], [1, 2], [2, 3], ])( "honours MAX_RETRY_ATTEMPTS %i: a retryable read goes out %i time(s)", async (maxRetryAttempts, sends) => { const fetcher = vi.fn(async (_input: RequestInfo | URL) => Response.json( { type: "about:blank", title: "temporary", status: 503 }, { status: 503 }, ), ); // No backoff wait: the jitter is the random draw times a ceiling. const random = vi.spyOn(Math, "random").mockReturnValue(0); try { const executor = createRuntimeContractHttpExecutor( { ...runtime.config, MAX_RETRY_ATTEMPTS: maxRetryAttempts }, { fetcher, attachCredentials: answerReady }, ); const outcome = await executor.execute( TEST_LIST_HTTP_CONTRACT, { limit: 20 }, { routeId: "TEST_ROUTE", scope: scopeSnapshot() }, ); expect(outcome.kind).not.toBe("SUCCESS"); expect(fetcher).toHaveBeenCalledTimes(sends); } finally { random.mockRestore(); } }, ); // The test list read declares a 10s deadline; REQUEST_TIMEOUT_MS may only // shorten it. it("holds a contract's deadline to REQUEST_TIMEOUT_MS", async () => { vi.useFakeTimers(); try { const fetcher = vi.fn( (_input: RequestInfo | URL, init?: RequestInit) => new Promise((_resolve, reject) => { init?.signal?.addEventListener( "abort", () => reject(new DOMException("Aborted", "AbortError")), { once: true }, ); }), ); const executor = createRuntimeContractHttpExecutor( { ...runtime.config, MAX_RETRY_ATTEMPTS: 0, REQUEST_TIMEOUT_MS: 5 }, { fetcher, attachCredentials: answerReady }, ); let settled = false; const result = executor .execute( TEST_LIST_HTTP_CONTRACT, { limit: 20 }, { routeId: "TEST_ROUTE", scope: scopeSnapshot() }, ) .then((outcome) => { settled = true; return outcome; }); await vi.advanceTimersByTimeAsync(5); await Promise.resolve(); await Promise.resolve(); expect(settled).toBe(true); await expect(result).resolves.toMatchObject({ kind: "TRANSPORT_FAILURE", failure: { kind: "TIMEOUT" }, }); } finally { vi.useRealTimers(); } }); });