@cosmicdrift/kumiko-server-runtime 0.1.0

package/LICENSE

@@ -0,0 +1,57 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Marc Frost
+
+Licensed Work:        @cosmicdrift/kumiko-framework
+                      The Licensed Work is © 2026 Marc Frost.
+
+Additional Use Grant: 
+You may use the Licensed Work in production for any purpose, including 
+commercially, EXCEPT for the Restricted Use. 
+
+"Restricted Use" is defined as using the Licensed Work to provide a platform 
+or service to third parties that allows them to host, deploy, or run their 
+own applications built with the Licensed Work. This includes, but is not 
+limited to: managed hosting services, software-as-a-service (SaaS) platforms, 
+platform-as-a-service (PaaS), developer platforms, or any multi-tenant 
+managed offering of the Licensed Work.
+
+This restriction does not apply to the Licensor, any entity controlled by, 
+controlling, or under common control with the Licensor ("Affiliates"), or 
+contractors acting on their behalf. The Licensor remains free to use the 
+Licensed Work for any purpose, including for the operation of kumiko.rocks.
+
+Change Date:          2030-05-05
+Change License:       Apache License, Version 2.0
+
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative works, 
+redistribute, and make non-production use of the Licensed Work. The Licensor may 
+make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly 
+available distribution of the Licensed Work under this License, whichever comes 
+first, this License will convert to the Change License.
+
+This Business Source License governs use of the Licensed Work in all cases, except 
+as to any use that is explicitly granted in the Additional Use Grant above or 
+under the Change License after the Change Date.
+
+If your use of the Licensed Work does not comply with the requirements of this 
+License, you must cease use of the Licensed Work immediately.
+
+All copies of the Licensed Work, and all derivative works thereof, must include 
+this License.
+
+This License does not grant you any right, title, or interest in any trademark, 
+logo, or branding of the Licensor, except as required to comply with this License.
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN 
+“AS IS” BASIS. LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
+WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 
+TITLE, AND NON-INFRINGEMENT. IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES 
+ARISING OUT OF OR RELATED TO THIS LICENSE OR THE USE OF THE LICENSED WORK.

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@cosmicdrift/kumiko-server-runtime",
+  "version": "0.1.0",
+  "description": "Production server-boot runtime for Kumiko apps: connections, schema-drift-gate, seeds, lifecycle, graceful shutdown. Symmetric to kumiko-dev-server's runDevApp, without dev/scaffold/codegen tooling.",
+  "license": "BUSL-1.1",
+  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CosmicDriftGameStudio/kumiko-framework.git",
+    "directory": "packages/server-runtime"
+  },
+  "bugs": {
+    "url": "https://github.com/CosmicDriftGameStudio/kumiko-framework/issues"
+  },
+  "homepage": "https://kumiko.rocks",
+  "type": "module",
+  "kumiko": {
+    "runtime": "prod"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./compose-features": {
+      "types": "./src/compose-features.ts",
+      "default": "./src/compose-features.ts"
+    },
+    "./run-prod-app": {
+      "types": "./src/run-prod-app.ts",
+      "default": "./src/run-prod-app.ts"
+    },
+    "./bun-serve-options": {
+      "types": "./src/bun-serve-options.ts",
+      "default": "./src/bun-serve-options.ts"
+    },
+    "./pii-boot-gate": {
+      "types": "./src/pii-boot-gate.ts",
+      "default": "./src/pii-boot-gate.ts"
+    },
+    "./boot/apply-boot-seeds": {
+      "types": "./src/boot/apply-boot-seeds.ts",
+      "default": "./src/boot/apply-boot-seeds.ts"
+    },
+    "./boot/boot-crypto": {
+      "types": "./src/boot/boot-crypto.ts",
+      "default": "./src/boot/boot-crypto.ts"
+    },
+    "./boot/job-run-logger": {
+      "types": "./src/boot/job-run-logger.ts",
+      "default": "./src/boot/job-run-logger.ts"
+    },
+    "./extra-routes-deps": {
+      "types": "./src/extra-routes-deps.ts",
+      "default": "./src/extra-routes-deps.ts"
+    },
+    "./inject-schema": {
+      "types": "./src/inject-schema.ts",
+      "default": "./src/inject-schema.ts"
+    },
+    "./resolve-tailwind-cli": {
+      "types": "./src/resolve-tailwind-cli.ts",
+      "default": "./src/resolve-tailwind-cli.ts"
+    },
+    "./try-hono-first": {
+      "types": "./src/try-hono-first.ts",
+      "default": "./src/try-hono-first.ts"
+    },
+    "./build-prod-bundle": {
+      "types": "./src/build-prod-bundle.ts",
+      "default": "./src/build-prod-bundle.ts"
+    }
+  },
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "0.152.0",
+    "@cosmicdrift/kumiko-framework": "0.152.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/__tests__/boot-extra-context.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, test } from "bun:test";
+import { createDeliveryFeature } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { createRegistry, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import type { MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
+import { buildBootExtraContext } from "../run-prod-app";
+
+// Pins runProdApp's framework-default-provider autowire (buildBootExtraContext):
+// textContent unconditional, secrets feature-gated, KEK-env trap avoided, the
+// money-horse regression (no secrets feature → no forced KEK → no throw), and
+// the delivery _notifyFactory wiring that makes ctx.notify work in prod (only
+// test-wired before — runProdApp/runDevApp call THIS, not createDeliveryTestContext).
+
+// db is never touched at construction time — createTextContentApi /
+// createSecretsContext only store the handle and query lazily. A bare stub
+// keeps this a fast unit test (no Postgres) instead of a full boot.
+const fakeDb = {} as unknown as DbConnection;
+const registry = createRegistry([]);
+const KEK = Buffer.alloc(32, 7).toString("base64");
+
+const otherFeature = defineFeature("widgets", () => {});
+
+describe("buildBootExtraContext — framework-default provider autowire", () => {
+  test("textContent is wired unconditionally (no secrets feature, no auth)", () => {
+    const ctx = buildBootExtraContext({
+      db: fakeDb,
+      features: [otherFeature],
+      envSource: {},
+      registry,
+      hasAuth: false,
+    });
+    expect(typeof (ctx["textContent"] as { getBlock?: unknown }).getBlock).toBe("function");
+    expect(ctx["secrets"]).toBeUndefined();
+    expect(ctx["configResolver"]).toBeUndefined();
+    expect(ctx["_notifyFactory"]).toBeUndefined();
+  });
+
+  test("delivery feature mounted → _notifyFactory wired (ctx.notify works in prod)", () => {
+    const ctx = buildBootExtraContext({
+      db: fakeDb,
+      features: [createDeliveryFeature()],
+      envSource: {},
+      registry,
+      hasAuth: false,
+    });
+    expect(typeof ctx["_notifyFactory"]).toBe("function");
+  });
+
+  test("no delivery feature → _notifyFactory not wired", () => {
+    const ctx = buildBootExtraContext({
+      db: fakeDb,
+      features: [otherFeature],
+      envSource: {},
+      registry,
+      hasAuth: false,
+    });
+    expect(ctx["_notifyFactory"]).toBeUndefined();
+  });
+
+  test("secrets feature mounted + valid KEK env → ctx.secrets wired", () => {
+    const ctx = buildBootExtraContext({
+      db: fakeDb,
+      features: [createSecretsFeature()],
+      envSource: {
+        KUMIKO_SECRETS_MASTER_KEY_V1: KEK,
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+      },
+      registry,
+      hasAuth: false,
+    });
+    const secrets = ctx["secrets"] as {
+      get?: unknown;
+      set?: unknown;
+      has?: unknown;
+      delete?: unknown;
+    };
+    expect(typeof secrets.get).toBe("function");
+    expect(typeof secrets.set).toBe("function");
+  });
+
+  test("secrets feature mounted, only V1 set (no CURRENT_VERSION) → wired (default '1')", () => {
+    const ctx = buildBootExtraContext({
+      db: fakeDb,
+      features: [createSecretsFeature()],
+      envSource: { KUMIKO_SECRETS_MASTER_KEY_V1: KEK },
+      registry,
+      hasAuth: false,
+    });
+    expect(ctx["secrets"]).toBeDefined();
+  });
+
+  test("secrets feature mounted but NO KEK + no override → skipped, no throw (dev DEV_KEY path)", () => {
+    // dev wires its own DEV_KEY secrets explicitly; the auto-wire must not
+    // eagerly construct an env-provider and crash the boot when no env KEK
+    // exists. ctx.secrets stays unset so the app's explicit wiring wins.
+    let ctx: Record<string, unknown> | undefined;
+    expect(() => {
+      ctx = buildBootExtraContext({
+        db: fakeDb,
+        features: [createSecretsFeature()],
+        envSource: {},
+        registry,
+        hasAuth: false,
+      });
+    }).not.toThrow();
+    expect(ctx?.["secrets"]).toBeUndefined();
+  });
+
+  test("no secrets feature → no KEK ever read, boots green (money-horse regression)", () => {
+    const ctx = buildBootExtraContext({
+      db: fakeDb,
+      features: [otherFeature],
+      envSource: {}, // no KEK — must NOT matter when secrets isn't mounted
+      registry,
+      hasAuth: false,
+    });
+    expect(ctx["secrets"]).toBeUndefined();
+  });
+
+  test("masterKey override is used verbatim — no env-provider built", () => {
+    const override: MasterKeyProvider = {
+      wrapDek: async () => ({ encryptedDek: Buffer.alloc(0), kekVersion: 1 }),
+      unwrapDek: async () => Buffer.alloc(0),
+      currentVersion: () => 1,
+      isAvailable: async () => true,
+    };
+    // envSource is empty: if the override weren't honoured, createEnvMasterKeyProvider
+    // would throw "no KEK". It doesn't → the override path is taken.
+    const ctx = buildBootExtraContext({
+      db: fakeDb,
+      features: [createSecretsFeature()],
+      envSource: {},
+      registry,
+      hasAuth: false,
+      masterKey: override,
+    });
+    expect(ctx["secrets"]).toBeDefined();
+  });
+});

package/src/__tests__/build-prod-bundle.test.ts

@@ -0,0 +1,278 @@
+// Unit-Tests für die Pure-Logic-Helpers von build-prod-bundle.
+//
+// Bun.build und Tailwind-CLI brauchen einen Bun-Runtime, deshalb
+// werden die hier nicht aufgerufen — nur Discovery + HTML-Injection
+// die unter Node funktionieren. End-to-End-Tests (mit echtem Bun.build)
+// laufen im CI als `bun run build` auf der Showcase-App; das ist der
+// ehrlichere Smoke-Test.
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  type ClientEntry,
+  computeBuildId,
+  discoverClientEntries,
+  discoverHtmlTemplate,
+  injectAssetTags,
+} from "../build-prod-bundle";
+
+// Synthetic single-entry helper. Realer Build erzeugt das via
+// discoverClientEntries; hier reicht die Form für injectAssetTags-Tests.
+function clientEntry(): ClientEntry {
+  return {
+    name: "client",
+    sourceFile: "src/client.tsx",
+    manifestKey: "client.js",
+    htmlPath: "index.html",
+  };
+}
+
+function namedEntry(name: string): ClientEntry {
+  return {
+    name,
+    sourceFile: `src/client-${name}.tsx`,
+    manifestKey: `client-${name}.js`,
+    htmlPath: name === "public" ? "index.html" : `${name}.html`,
+  };
+}
+
+describe("build-prod-bundle/discovery", () => {
+  let workDir = "";
+
+  beforeEach(async () => {
+    workDir = await mkdtemp(join(tmpdir(), "kumiko-build-test-"));
+  });
+
+  afterEach(async () => {
+    await rm(workDir, { recursive: true, force: true });
+  });
+
+  test("discoverClientEntries findet single-mode src/client.tsx", async () => {
+    await mkdir(join(workDir, "src"), { recursive: true });
+    await writeFile(join(workDir, "src/client.tsx"), "// single");
+
+    const entries = discoverClientEntries(workDir);
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.name).toBe("client");
+    expect(entries[0]?.manifestKey).toBe("client.js");
+    expect(entries[0]?.htmlPath).toBe("index.html");
+  });
+
+  test("discoverClientEntries findet multi-mode client-public + client-admin", async () => {
+    await mkdir(join(workDir, "src"), { recursive: true });
+    await writeFile(join(workDir, "src/client-public.tsx"), "// public");
+    await writeFile(join(workDir, "src/client-admin.tsx"), "// admin");
+
+    const entries = discoverClientEntries(workDir);
+
+    // Sortiert nach name.
+    expect(entries.map((e) => e.name)).toEqual(["admin", "public"]);
+
+    const admin = entries.find((e) => e.name === "admin");
+    expect(admin?.manifestKey).toBe("client-admin.js");
+    expect(admin?.htmlPath).toBe("admin.html");
+
+    const pub = entries.find((e) => e.name === "public");
+    expect(pub?.manifestKey).toBe("client-public.js");
+    // "public" mappt auf das Default-Template (index.html), nicht
+    // public.html — das ist Convention damit das default-served-Template
+    // den vom-User-erwarteten Namen behält.
+    expect(pub?.htmlPath).toBe("index.html");
+  });
+
+  test("discoverClientEntries multi-mode dominiert über single-mode wenn beide da", async () => {
+    await mkdir(join(workDir, "src"), { recursive: true });
+    await writeFile(join(workDir, "src/client.tsx"), "// single");
+    await writeFile(join(workDir, "src/client-admin.tsx"), "// admin");
+
+    const entries = discoverClientEntries(workDir);
+
+    // Multi-mode aktiv → "client" wird ignoriert.
+    expect(entries.map((e) => e.name)).toEqual(["admin"]);
+  });
+
+  test("discoverClientEntries gibt leeres Array zurück wenn nichts da", () => {
+    expect(discoverClientEntries(workDir)).toEqual([]);
+  });
+
+  test("discoverHtmlTemplate findet index.html im cwd", async () => {
+    await writeFile(join(workDir, "index.html"), "<html></html>");
+
+    expect(discoverHtmlTemplate(workDir)).toBe(join(workDir, "index.html"));
+  });
+
+  test("discoverHtmlTemplate findet public/index.html als Fallback", async () => {
+    await mkdir(join(workDir, "public"), { recursive: true });
+    await writeFile(join(workDir, "public/index.html"), "<html></html>");
+
+    expect(discoverHtmlTemplate(workDir)).toBe(join(workDir, "public/index.html"));
+  });
+
+  test("discoverHtmlTemplate bevorzugt cwd-index.html über public/index.html", async () => {
+    await mkdir(join(workDir, "public"), { recursive: true });
+    await writeFile(join(workDir, "index.html"), "<!-- root -->");
+    await writeFile(join(workDir, "public/index.html"), "<!-- public -->");
+
+    expect(discoverHtmlTemplate(workDir)).toBe(join(workDir, "index.html"));
+  });
+
+  test("discoverHtmlTemplate gibt undefined zurück wenn nichts da ist", () => {
+    expect(existsSync(workDir)).toBe(true);
+    expect(discoverHtmlTemplate(workDir)).toBeUndefined();
+  });
+});
+
+describe("build-prod-bundle/injectAssetTags", () => {
+  test("ersetzt /client.js durch hashed URL im script-tag", () => {
+    const html = `<html><body><script type="module" src="/client.js"></script></body></html>`;
+    const result = injectAssetTags(
+      html,
+      { "client.js": "/assets/client-abc123.js" },
+      clientEntry(),
+    );
+
+    expect(result).toContain('src="/assets/client-abc123.js"');
+    expect(result).not.toContain('src="/client.js"');
+  });
+
+  test("ersetzt /styles.css durch hashed URL im link-tag", () => {
+    const html = `<html><head><link rel="stylesheet" href="/styles.css" /></head><body></body></html>`;
+    const result = injectAssetTags(
+      html,
+      { "styles.css": "/assets/styles-def456.css" },
+      clientEntry(),
+    );
+
+    expect(result).toContain('href="/assets/styles-def456.css"');
+    expect(result).not.toContain('href="/styles.css"');
+  });
+
+  test("wirft mit Anweisung wenn /client.js Placeholder fehlt", () => {
+    const html = `<html><body><div id="root"></div></body></html>`;
+
+    expect(() =>
+      injectAssetTags(html, { "client.js": "/assets/client-abc.js" }, clientEntry()),
+    ).toThrow(/keinen Entry-Tag für \/client\.js/);
+    expect(() =>
+      injectAssetTags(html, { "client.js": "/assets/client-abc.js" }, clientEntry()),
+    ).toThrow(/<script type="module" src="\/client\.js"><\/script>/);
+  });
+
+  test("wirft mit Anweisung wenn /styles.css Placeholder fehlt", () => {
+    const html = `<html><head><title>App</title></head><body></body></html>`;
+
+    expect(() =>
+      injectAssetTags(html, { "styles.css": "/assets/styles-xyz.css" }, clientEntry()),
+    ).toThrow(/keinen Entry-Tag für \/styles\.css/);
+    expect(() =>
+      injectAssetTags(html, { "styles.css": "/assets/styles-xyz.css" }, clientEntry()),
+    ).toThrow(/<link rel="stylesheet" href="\/styles\.css" \/>/);
+  });
+
+  test("ist idempotent — zweite Injection auf bereits ersetztem HTML ändert nichts", () => {
+    const html = `<html><body><script type="module" src="/client.js"></script></body></html>`;
+    const manifest = { "client.js": "/assets/client-abc.js" };
+    const first = injectAssetTags(html, manifest, clientEntry());
+    const second = injectAssetTags(first, manifest, clientEntry());
+
+    expect(first).toBe(second);
+    expect(first).toContain('src="/assets/client-abc.js"');
+  });
+
+  test("ändert template ohne client/styles im manifest nicht", () => {
+    const html = `<html><body>Hello</body></html>`;
+    const result = injectAssetTags(html, {}, clientEntry());
+
+    expect(result).toBe(html);
+  });
+
+  test("verträgt mehrere script-tags und ersetzt nur den /client.js", () => {
+    const html = `<html><body>
+      <script>console.log("inline");</script>
+      <script type="module" src="/client.js"></script>
+    </body></html>`;
+    const result = injectAssetTags(html, { "client.js": "/assets/client-x.js" }, clientEntry());
+
+    expect(result).toContain('console.log("inline")');
+    expect(result).toContain('src="/assets/client-x.js"');
+    expect(result).not.toContain('src="/client.js"');
+  });
+
+  test("multi-mode: admin-entry ersetzt nur /client-admin.js, lässt /client-public.js liegen", () => {
+    const html = `<html><body>
+      <script type="module" src="/client-admin.js"></script>
+      <script type="module" src="/client-public.js"></script>
+    </body></html>`;
+    const manifest = {
+      "client-admin.js": "/assets/client-admin-aaa.js",
+      "client-public.js": "/assets/client-public-bbb.js",
+    };
+    const result = injectAssetTags(html, manifest, namedEntry("admin"));
+
+    expect(result).toContain('src="/assets/client-admin-aaa.js"');
+    // public-bundle bleibt unangetastet — admin.html lädt nur sein eigenes Bundle.
+    expect(result).toContain('src="/client-public.js"');
+    expect(result).not.toContain('src="/client-admin.js"');
+  });
+
+  test("multi-mode: error-message nennt den richtigen Template-Namen", () => {
+    const html = `<html><body>no admin script</body></html>`;
+    const manifest = { "client-admin.js": "/assets/client-admin-x.js" };
+
+    expect(() => injectAssetTags(html, manifest, namedEntry("admin"))).toThrow(
+      /admin\.html hat keinen Entry-Tag für \/client-admin\.js/,
+    );
+  });
+});
+
+describe("build-prod-bundle/computeBuildId", () => {
+  test("identisches Manifest → gleiche id", () => {
+    const manifest = {
+      "client.js": "/assets/client-abc.js",
+      "styles.css": "/assets/styles-xyz.css",
+    };
+    expect(computeBuildId(manifest)).toBe(computeBuildId({ ...manifest }));
+  });
+
+  test("Key-Reihenfolge egal — nur die URL-Werte zählen", () => {
+    const a = { "client.js": "/assets/client-abc.js", "styles.css": "/assets/styles-xyz.css" };
+    const b = { "styles.css": "/assets/styles-xyz.css", "client.js": "/assets/client-abc.js" };
+    expect(computeBuildId(a)).toBe(computeBuildId(b));
+  });
+
+  test("geändertes Asset (neuer Hash) → andere id", () => {
+    const before = { "client.js": "/assets/client-abc.js" };
+    const after = { "client.js": "/assets/client-def.js" };
+    expect(computeBuildId(before)).not.toBe(computeBuildId(after));
+  });
+
+  test("12 Hex-Zeichen", () => {
+    expect(computeBuildId({ "client.js": "/assets/client-abc.js" })).toMatch(/^[0-9a-f]{12}$/);
+  });
+});
+
+describe("build-prod-bundle/injectAssetTags build-info", () => {
+  test("bäckt window.__KUMIKO_BUILD__ vor </head> wenn buildInfo gesetzt", () => {
+    const html = `<html><head><title>x</title></head><body><script type="module" src="/client.js"></script></body></html>`;
+    const result = injectAssetTags(html, { "client.js": "/assets/client-abc.js" }, clientEntry(), {
+      id: "deadbeef0000",
+      builtAt: "2026-06-18T12:00:00.000Z",
+    });
+
+    expect(result).toContain(
+      'window.__KUMIKO_BUILD__={"id":"deadbeef0000","builtAt":"2026-06-18T12:00:00.000Z"}',
+    );
+    expect(result.indexOf("__KUMIKO_BUILD__")).toBeLessThan(result.indexOf("</head>"));
+  });
+
+  test("ohne buildInfo kein __KUMIKO_BUILD__-Script", () => {
+    const html = `<html><head></head><body><script type="module" src="/client.js"></script></body></html>`;
+    const result = injectAssetTags(html, { "client.js": "/assets/client-abc.js" }, clientEntry());
+
+    expect(result).not.toContain("__KUMIKO_BUILD__");
+  });
+});

package/src/__tests__/cache-headers.test.ts

@@ -0,0 +1,83 @@
+// Unit-Tests für staticCachePolicy — die Cache-Strategie hinter
+// runProdApp's static-fallback. Pure function, leicht zu testen.
+//
+// Strategie (siehe run-prod-app.ts):
+//   /assets/*               → immutable
+//   /, /index.html          → revalidate (max-age=0, must-revalidate)
+//   /manifest.json, /sw.js,
+//   /build-info.json        → no-cache
+//   alles andere            → none
+
+import { describe, expect, test } from "bun:test";
+import { cacheControlHeader } from "@cosmicdrift/kumiko-framework/api";
+import { staticCachePolicy } from "../run-prod-app";
+
+function cacheControlFor(pathname: string): Record<string, string> {
+  const header = cacheControlHeader(staticCachePolicy(pathname));
+  return header === undefined ? {} : { "cache-control": header };
+}
+
+describe("staticCachePolicy", () => {
+  test("hashed asset → immutable + 1 Jahr", () => {
+    expect(cacheControlFor("/assets/client-abc123.js")).toEqual({
+      "cache-control": "public, max-age=31536000, immutable",
+    });
+  });
+
+  test("hashed CSS asset → immutable + 1 Jahr", () => {
+    expect(cacheControlFor("/assets/styles-def456.css")).toEqual({
+      "cache-control": "public, max-age=31536000, immutable",
+    });
+  });
+
+  test("nested asset path → immutable", () => {
+    expect(cacheControlFor("/assets/chunks/foo-789.js")).toEqual({
+      "cache-control": "public, max-age=31536000, immutable",
+    });
+  });
+
+  test("/ → revalidate", () => {
+    expect(cacheControlFor("/")).toEqual({
+      "cache-control": "public, max-age=0, must-revalidate",
+    });
+  });
+
+  test("/index.html → revalidate", () => {
+    expect(cacheControlFor("/index.html")).toEqual({
+      "cache-control": "public, max-age=0, must-revalidate",
+    });
+  });
+
+  test("/manifest.json → no-cache", () => {
+    expect(cacheControlFor("/manifest.json")).toEqual({
+      "cache-control": "no-cache",
+    });
+  });
+
+  test("/sw.js → no-cache", () => {
+    expect(cacheControlFor("/sw.js")).toEqual({
+      "cache-control": "no-cache",
+    });
+  });
+
+  test("/build-info.json → no-cache (sonst pollt UpdateChecker eine veraltete id)", () => {
+    expect(cacheControlFor("/build-info.json")).toEqual({
+      "cache-control": "no-cache",
+    });
+  });
+
+  test("public-folder file (favicon) → kein expliziter Header", () => {
+    expect(cacheControlFor("/favicon.ico")).toEqual({});
+  });
+
+  test("public-folder file (og-image) → kein expliziter Header", () => {
+    expect(cacheControlFor("/og-image.png")).toEqual({});
+  });
+
+  test("path mit assets als Substring (kein /assets/ prefix) → kein immutable", () => {
+    // Schutz: /myassets/foo.js soll NICHT immutable kriegen — wäre ein Bug
+    // weil die nicht gehashed sind.
+    expect(cacheControlFor("/myassets/foo.js")).toEqual({});
+    expect(cacheControlFor("/foo/assets/bar.js")).toEqual({});
+  });
+});