@warpgogol/werkstatt-shared 0.14.0 → 0.15.0

package/src/kernel/workspace-io.ts

@@ -0,0 +1,248 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0267: the WorkspaceIO port — the single seam through which kernel commands
+touch the filesystem and spawn processes. `KernelRuntimeContext.io` carries an
+adapter chosen by the executor: the default fs-backed adapter, a recording
+adapter (universal `--dry-run`: intercepts writes/deletes, records intents,
+touches nothing), or a read-only adapter (used for `mutatesState: false`
+commands; throws KERNEL-META-01 on any attempted mutation). Adoption is
+ratcheted — ambient `node:fs` imports keep working in unmigrated modules;
+`kernel.io.lint` (IO-01) only gates new/migrated modules.
+
+RFC-0326: `createDefaultIO` now returns `{ io, intents }` — the io writes to
+real disk AND records every mutation as a `WriteIntent` for execution-report
+surfacing (`filesModified`). This unifies the dry-run and real-run paths: both
+capture intents, just from different adapters.
+</purpose>
+<non-goals>
+  <item>Do not abstract network access — filesystem and process execution only.</item>
+  <item>Do not enforce IO at the module-import level — that is kernel.io.lint's static check.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>WorkspaceIO is the single filesystem seam — kernel commands never touch fs directly.</item>
+</KEY_DECISIONS>
+<CHANGE_SUMMARY>
+  <item>RFC-0267: initial implementation.</item>
+  <item>RFC-0267 follow-up: add readdir(path): Promise&lt;DirEntry[]&gt; to complete the port so directory-listing commands (e.g. sitemap.generate) migrate mechanically without importing node:fs for Dirent.</item>
+  <item>RFC-0326: createDefaultIO returns { io, intents } — writes touch real disk AND record WriteIntent[] for filesModified reporting.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
+</CHANGE_SUMMARY>
+*/
+
+import {
+  readFile as fsReadFile,
+  mkdir as fsMkdir,
+  rm as fsRm,
+  readdir as fsReaddir,
+  stat,
+} from "node:fs/promises";
+import { glob as fsGlob } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { dirname } from "node:path";
+import { writeFileAtomic } from "./fs-atomic.ts";
+
+export interface ExecOptions {
+  cwd?: string;
+  timeoutMs?: number;
+}
+
+export interface ExecResult {
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * A directory entry in a port-neutral shape — no `node:fs` `Dirent` leaks
+ * through the port, so command modules never need to import `node:fs` just to
+ * type a listing. `isFile`/`isDirectory` are plain booleans (not methods).
+ */
+export interface DirEntry {
+  name: string;
+  isFile: boolean;
+  isDirectory: boolean;
+}
+
+export interface WorkspaceIO {
+  readFile(path: string): Promise<string>;
+  readFileBytes(path: string): Promise<Uint8Array>;
+  exists(path: string): Promise<boolean>;
+  glob(pattern: string, opts?: { cwd?: string }): Promise<string[]>;
+  /** List a directory's immediate entries. Read-only; throws if the path is not a directory. */
+  readdir(path: string): Promise<DirEntry[]>;
+  /** Atomic by contract (rfc-0258). */
+  writeFile(path: string, content: string | Uint8Array): Promise<void>;
+  mkdir(path: string): Promise<void>;
+  rm(path: string, opts?: { recursive?: boolean }): Promise<void>;
+  exec(command: string, args: string[], opts?: ExecOptions): Promise<ExecResult>;
+}
+
+async function execImpl(command: string, args: string[], opts?: ExecOptions): Promise<ExecResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd: opts?.cwd });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    const timer = opts?.timeoutMs
+      ? setTimeout(() => {
+          child.kill();
+        }, opts.timeoutMs)
+      : undefined;
+    timer?.unref?.();
+    child.on("close", (exitCode) => {
+      if (timer) clearTimeout(timer);
+      resolve({ exitCode, stdout, stderr });
+    });
+    child.on("error", (error) => {
+      if (timer) clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+
+/**
+ * RFC-0326: the default, real fs-backed adapter. `writeFile` is atomic
+ * (rfc-0258). Now returns `{ io, intents }` matching `createRecordingIO`'s
+ * shape — the io writes to real disk; intents captures every mutation for
+ * `filesModified` reporting on execution reports.
+ */
+export function createDefaultIO(): { io: WorkspaceIO; intents: WriteIntent[] } {
+  const intents: WriteIntent[] = [];
+  const io: WorkspaceIO = {
+    async readFile(path) {
+      return fsReadFile(path, "utf8");
+    },
+    async readFileBytes(path) {
+      return fsReadFile(path);
+    },
+    async exists(path) {
+      try {
+        await stat(path);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    async glob(pattern, opts) {
+      const results: string[] = [];
+      for await (const entry of fsGlob(pattern, { cwd: opts?.cwd })) {
+        results.push(entry);
+      }
+      return results;
+    },
+    async readdir(path) {
+      const entries = await fsReaddir(path, { withFileTypes: true });
+      return entries.map((entry) => ({
+        name: entry.name,
+        isFile: entry.isFile(),
+        isDirectory: entry.isDirectory(),
+      }));
+    },
+    async writeFile(path, content) {
+      await fsMkdir(dirname(path), { recursive: true });
+      await writeFileAtomic(path, content);
+      const bytes =
+        typeof content === "string" ? Buffer.byteLength(content, "utf8") : content.byteLength;
+      intents.push({ kind: "write", path, bytes });
+    },
+    async mkdir(path) {
+      await fsMkdir(path, { recursive: true });
+      intents.push({ kind: "mkdir", path });
+    },
+    async rm(path, opts) {
+      await fsRm(path, { recursive: opts?.recursive ?? false, force: true });
+      intents.push({ kind: "rm", path });
+    },
+    exec: execImpl,
+  };
+  return { io, intents };
+}
+
+export interface WriteIntent {
+  kind: "write" | "mkdir" | "rm";
+  path: string;
+  bytes?: number;
+}
+
+/**
+ * Wraps a base adapter for universal `--dry-run`: reads pass through to the
+ * base adapter (so a command can still make write decisions based on real
+ * state), but writes/mkdir/rm are intercepted, recorded, and never touch disk.
+ */
+export function createRecordingIO(base: WorkspaceIO): { io: WorkspaceIO; intents: WriteIntent[] } {
+  const intents: WriteIntent[] = [];
+  const io: WorkspaceIO = {
+    readFile: base.readFile.bind(base),
+    readFileBytes: base.readFileBytes.bind(base),
+    exists: base.exists.bind(base),
+    glob: base.glob.bind(base),
+    readdir: base.readdir.bind(base),
+    async writeFile(path, content) {
+      const bytes =
+        typeof content === "string" ? Buffer.byteLength(content, "utf8") : content.byteLength;
+      intents.push({ kind: "write", path, bytes });
+    },
+    async mkdir(path) {
+      intents.push({ kind: "mkdir", path });
+    },
+    async rm(path) {
+      intents.push({ kind: "rm", path });
+    },
+    async exec() {
+      throw new Error("createRecordingIO: exec() is not supported under --dry-run.");
+    },
+  };
+  return { io, intents };
+}
+
+export class KernelMetaError extends Error {
+  constructor(
+    readonly commandName: string,
+    readonly attemptedPath: string,
+  ) {
+    super(
+      `KERNEL-META-01: command "${commandName}" declares mutatesState: false but attempted to write "${attemptedPath}". ` +
+        `Fix the command, or if the write is legitimate, set mutatesState: true and declare the path in writes (RFC-0266).`,
+    );
+    this.name = "KernelMetaError";
+  }
+}
+
+/**
+ * Wraps a base adapter so every mutation throws KERNEL-META-01 naming the
+ * command and the attempted path. Used for every `mutatesState: false`
+ * command (proves the metadata trustworthy) and by the test harness.
+ */
+export function createReadOnlyIO(base: WorkspaceIO, commandName: string): WorkspaceIO {
+  return {
+    readFile: base.readFile.bind(base),
+    readFileBytes: base.readFileBytes.bind(base),
+    exists: base.exists.bind(base),
+    glob: base.glob.bind(base),
+    readdir: base.readdir.bind(base),
+    async writeFile(path) {
+      throw new KernelMetaError(commandName, path);
+    },
+    async mkdir(path) {
+      throw new KernelMetaError(commandName, path);
+    },
+    async rm(path) {
+      throw new KernelMetaError(commandName, path);
+    },
+    async exec(command, args) {
+      throw new KernelMetaError(commandName, `${command} ${args.join(" ")}`);
+    },
+  };
+}

package/src/{share → knowledge}/tests/claim.test.ts

@@ -17,7 +17,7 @@ import {
   formatClaimSubject,
   claimSubjectsEqual,
   ClaimSubjectParseError,
-} from "../knowledge/claim.ts";
+} from "../claim.ts";
 
 test("parse: lang-scoped subject with simple field", () => {
   const s = parseClaimSubject("business/de/location#residents");

package/src/{share → knowledge}/tests/derivation.test.ts

@@ -8,7 +8,7 @@
 */
 
 import { test, expect } from "vitest";
-import { normalizeForHash, hashSourceValue, derivedState } from "../knowledge/derivation.ts";
+import { normalizeForHash, hashSourceValue, derivedState } from "../derivation.ts";
 
 test("normalize: whitespace and markdown are insensitive", () => {
   expect(normalizeForHash("Hello   world")).toBe("Hello world");

package/src/{share → knowledge}/tests/freshness.test.ts

@@ -8,7 +8,7 @@
 */
 
 import { test, expect } from "vitest";
-import { addDuration, evaluateFreshness } from "../knowledge/freshness.ts";
+import { addDuration, evaluateFreshness } from "../freshness.ts";
 
 test("addDuration: months and years are calendar-correct", () => {
   expect(addDuration("2026-01-15", "P1Y")).toBe("2027-01-15");

package/src/{share → knowledge}/tests/ledger.test.ts

@@ -18,7 +18,7 @@ import {
   projectGraph,
   projectTemporalSeo,
   type ClaimEvent,
-} from "../knowledge/ledger.ts";
+} from "../ledger.ts";
 
 function evt(partial: Partial<ClaimEvent>): ClaimEvent {
   const subject = partial.subject ?? "business/de/location#residents";

package/src/{share → knowledge}/tests/plan.test.ts

@@ -18,7 +18,7 @@ import {
   defaultCriticality,
   isRedTask,
   type MaintenanceTask,
-} from "../knowledge/plan.ts";
+} from "../plan.ts";
 
 test("stableTaskId: idempotent for the same (subject, trigger)", () => {
   const a = stableTaskId("business/de/offer#price.monthly", "expired");

package/src/{share → knowledge}/tests/source.test.ts

@@ -13,7 +13,7 @@ import {
   extractJsonPath,
   compareValues,
   coerceNumber,
-} from "../knowledge/source.ts";
+} from "../source.ts";
 
 test("descriptor: valid http-json passes", () => {
   const r = sourceDescriptorSchema.safeParse({

package/src/legal/index.ts

@@ -0,0 +1,15 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Legal share index — re-export the translation-policy surface for legal content consumers.</purpose>
+<non-goals>
+  <item>Do not implement legal policy logic here — the policy lives in translation-policy.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1097: sweep — tail packages clean
+
+Sweep batch 3: rewrote ~95 purposes across werkstatt-knowledge, werkstatt-shared, godot-game, phaser-game, lifecycle-core, projektarchiv-*, portal-*, billing-*, typescript (CONTRACT-02/PURPOSE-02). Real KEY_DECISIONS on 5 godot utils, non-goals on 5 CONTRACT-03 files, headers on 4 headerless files, CS-07 history literal fix on 2 files. Policy: vitest.config.ts + test-fixtures testPatterns, worker-configuration.d.ts excludedPath. All non-site/engine packages now 0 diagnostics.</item>
+</CHANGE_SUMMARY>
+*/
+
+export * from "./translation-policy.ts";

package/src/{share/middleware → middleware}/access-protection.ts

@@ -1,14 +1,8 @@
 /*
 <MODULE_CONTRACT>
 <purpose>RFC-0899: Runtime access protection middleware for dev/alt subdomains. Checks Host header and requires Basic Auth with a 4-digit PIN for dev.* and alt.* hosts. Sets X-Robots-Tag headers to prevent indexing.</purpose>
-<keywords>middleware, access-protection, basic-auth, pin, dev, alt, RFC-0899</keywords>
-<responsibilities>
-  <item>Check Host header against dev.* and alt.* patterns — pass through for main domain.</item>
-  <item>Require Basic Auth (username: warp, password: ACCESS_PIN env var) for dev/alt hosts.</item>
-  <item>Set X-Robots-Tag: noindex, nofollow, noai, noimageai on ALL dev/alt responses (including 401).</item>
-  <item>Use constant-time string comparison for auth check to prevent timing attacks.</item>
-  <item>Pass through when ACCESS_PIN is unset (allows new sites before protection is configured).</item>
-</responsibilities>
+
+
 <non-goals>
   <item>Do not modify the HTML response body — only headers and access gating.</item>
   <item>Do not activate for the main/production domain, even if the PIN secret is set on the main Worker.</item>
@@ -17,6 +11,12 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0899: Initial access protection middleware for dev/alt subdomains.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/{share → node}/dev-props-validator.ts

@@ -17,7 +17,12 @@ never crash rendering for a reason unrelated to the author's actual props.
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0262: initial implementation.</item>
-  <item>Replaced hand-rolled validateShape with ajv standard validator.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/{share → node}/import-scan.ts

@@ -3,7 +3,7 @@
 <purpose>Shared utility for scanning TypeScript source files for import specifiers
 matching a pattern. Used by werkstatt.autonomy.validate, werkstatt.shared.validate,
 and forge.autonomy.validate to avoid code duplication (Fowler: Duplicated Code).</purpose>
-<keywords>scan, import, utility, shared, validate, autonomy</keywords>
+
 <non-goals>
   <item>Does not define what is forbidden or exempt — callers provide the pattern and filter.</item>
   <item>Does not scan test files — .test.ts and .spec.ts are always excluded.</item>
@@ -12,6 +12,13 @@ and forge.autonomy.validate to avoid code duplication (Fowler: Duplicated Code).
 <CHANGE_SUMMARY>
   <item>RFC-0868: extract shared directory-scanning utility from autonomy-validate and shared-validate.</item>
   <item>RFC-0940: move to @warpgogol/werkstatt-shared so forge can import without depending on @warpgogol/werkstatt-engine.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1099: export EXCLUDE_DIRS + EXCLUDE_SUFFIXES; extend EXCLUDE_DIRS with cache/build/test dirs (.turbo, .astro, .wrangler, .cache, .stryker-tmp, coverage, __tests__) so the werkstatt-typescript workspace model and all import-scan consumers share one canonical exclusion set.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -23,8 +30,21 @@ export interface ImportViolation {
   specifier: string;
 }
 
-const EXCLUDE_DIRS = new Set(["node_modules", "tests", "tests-handoff", "dist", "templates"]);
-const EXCLUDE_SUFFIXES = [".test.ts", ".spec.ts"];
+export const EXCLUDE_DIRS = new Set([
+  "node_modules",
+  "tests",
+  "tests-handoff",
+  "dist",
+  "templates",
+  ".turbo",
+  ".astro",
+  ".wrangler",
+  ".cache",
+  ".stryker-tmp",
+  "coverage",
+  "__tests__",
+]);
+export const EXCLUDE_SUFFIXES = [".test.ts", ".spec.ts"];
 
 const IMPORT_PATTERN =
   /(?:^|\n)\s*(?:import\s+(?:type\s+)?[^;]+?\s+from\s+|require\s*\(\s*)["'`]([^"'`]+)["'`]/g;

package/src/{share → node}/semantic/derived-prices-loader.ts

@@ -8,12 +8,13 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0767: relocated loadDerivedPrices from packages/ui to packages/share to break circular dependency. Node-only subpath export.</item>
+  <item>RFC-1074: return null for empty {} content — semantically equivalent to "no derived prices".</item>
 </CHANGE_SUMMARY>
 */
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import type { DerivedPriceEntry } from "./price-marker-resolver.ts";
+import type { DerivedPriceEntry } from "../../semantic/price-marker-resolver.ts";
 
 export function loadDerivedPrices(
   cwd: string = process.cwd(),
@@ -32,5 +33,6 @@ export function loadDerivedPrices(
     }
     throw err;
   }
-  return JSON.parse(raw) as Record<string, DerivedPriceEntry[]>;
+  const parsed = JSON.parse(raw) as Record<string, DerivedPriceEntry[]>;
+  return Object.keys(parsed).length > 0 ? parsed : null;
 }

package/src/{share → node}/semantic/markdown-twin-provenance.ts

@@ -19,7 +19,7 @@ over the normalized Markdown body (excluding frontmatter).
 */
 
 import { createHash } from "node:crypto";
-import type { SemanticPageType } from "./models.ts";
+import type { SemanticPageType } from "../../semantic/models.ts";
 
 export interface MarkdownTwinSemanticMeta {
   id: string;

package/src/node/tests/derived-prices-loader.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { loadDerivedPrices } from "../semantic/derived-prices-loader.ts";
+
+describe("loadDerivedPrices", () => {
+  it("returns null when file does not exist", () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "test-prices-"));
+    try {
+      const result = loadDerivedPrices(tmpDir);
+      expect(result).toBeNull();
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  it("returns null for empty {} content (RFC-1074)", () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "test-prices-"));
+    try {
+      const srcDir = join(tmpDir, "src");
+      mkdirSync(srcDir, { recursive: true });
+      writeFileSync(join(srcDir, "derived-prices.generated.json"), "{}\n");
+      const result = loadDerivedPrices(tmpDir);
+      expect(result).toBeNull();
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  it("loads and parses JSON when file exists", () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "test-prices-"));
+    try {
+      const srcDir = join(tmpDir, "src");
+      mkdirSync(srcDir, { recursive: true });
+      writeFileSync(
+        join(srcDir, "derived-prices.generated.json"),
+        JSON.stringify({
+          "https://warpgogol.com/id/offerings/hosting": [
+            {
+              chargeRef: "monthly",
+              targetCurrency: "USD",
+              amount: { value: "15", currency: "USD" },
+              trace: {
+                source: { amount: "10", currency: "EUR" },
+                rate: { value: "0.9", pair: "EUR/USD" },
+              },
+            },
+          ],
+        }),
+      );
+      const result = loadDerivedPrices(tmpDir);
+      expect(result).not.toBeNull();
+      expect(Object.keys(result!)).toContain("https://warpgogol.com/id/offerings/hosting");
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+});

package/src/node/tests/markdown-twin-provenance.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from "vitest";
+import {
+  AUDIENCE_BY_PAGE_TYPE,
+  buildMarkdownTwin,
+  buildMarkdownTwinFrontmatter,
+  computeContentHash,
+  parseMarkdownTwinFrontmatter,
+  verifyMarkdownTwinHash,
+  type MarkdownTwinProvenance,
+} from "../semantic/markdown-twin-provenance.ts";
+
+const baseProvenance: MarkdownTwinProvenance = {
+  canonical: "https://example.com/de/page",
+  language: "de",
+  lastModified: "2024-01-15",
+  license: "CC-BY-4.0",
+  generator: "test",
+  sourceKind: "authored",
+};
+
+describe("computeContentHash", () => {
+  it("produces sha256: prefix", () => {
+    expect(computeContentHash("body text").startsWith("sha256:")).toBe(true);
+  });
+
+  it("is deterministic for same input", () => {
+    expect(computeContentHash("body")).toBe(computeContentHash("body"));
+  });
+
+  it("normalizes trailing whitespace", () => {
+    expect(computeContentHash("body\n\n")).toBe(computeContentHash("body"));
+  });
+
+  it("normalizes CRLF to LF", () => {
+    expect(computeContentHash("a\r\nb")).toBe(computeContentHash("a\nb"));
+  });
+});
+
+describe("buildMarkdownTwinFrontmatter", () => {
+  it("includes all core provenance fields", () => {
+    const fm = buildMarkdownTwinFrontmatter(baseProvenance, "sha256:abc");
+    expect(fm).toContain('canonical: "https://example.com/de/page"');
+    expect(fm).toContain('language: "de"');
+    expect(fm).toContain('lastModified: "2024-01-15"');
+    expect(fm).toContain('contentHash: "sha256:abc"');
+    expect(fm).toContain('license: "CC-BY-4.0"');
+    expect(fm).toContain('generator: "test"');
+    expect(fm).toContain('sourceKind: "authored"');
+    expect(fm).toContain('schema: "gogol.markdown-twin@2"');
+  });
+
+  it("emits null for lastModified when null", () => {
+    const fm = buildMarkdownTwinFrontmatter(
+      { ...baseProvenance, lastModified: null },
+      "sha256:abc",
+    );
+    expect(fm).toContain("lastModified: null");
+  });
+
+  it("includes pageId when provided", () => {
+    const fm = buildMarkdownTwinFrontmatter(
+      { ...baseProvenance, pageId: "about" },
+      "sha256:abc",
+    );
+    expect(fm).toContain('pageId: "about"');
+  });
+
+  it("includes sourceInputs when provided", () => {
+    const fm = buildMarkdownTwinFrontmatter(
+      { ...baseProvenance, sourceInputs: ["file1.md", "file2.md"] },
+      "sha256:abc",
+    );
+    expect(fm).toContain('sourceInputs:');
+    expect(fm).toContain('"file1.md"');
+  });
+
+  it("includes semantic meta when provided", () => {
+    const fm = buildMarkdownTwinFrontmatter(
+      {
+        ...baseProvenance,
+        semantic: {
+          id: "page-1",
+          route: "/de/page",
+          title: "Page",
+          type: "content",
+          domain: "content",
+          audience: "general",
+          lang: "de",
+          metaDescription: "A page",
+          priority: 0.7,
+          tags: ["tag1"],
+        },
+      },
+      "sha256:abc",
+    );
+    expect(fm).toContain('id: "page-1"');
+    expect(fm).toContain('type: "content"');
+    expect(fm).toContain("priority: 0.7");
+  });
+});
+
+describe("buildMarkdownTwin", () => {
+  it("produces frontmatter + body", () => {
+    const twin = buildMarkdownTwin("# Hello\n\nWorld", baseProvenance);
+    expect(twin.startsWith("---\n")).toBe(true);
+    expect(twin).toContain("# Hello");
+    expect(twin).toContain("World");
+  });
+});
+
+describe("parseMarkdownTwinFrontmatter", () => {
+  it("round-trips buildMarkdownTwin output", () => {
+    const body = "# Hello\n\nWorld";
+    const twin = buildMarkdownTwin(body, baseProvenance);
+    const parsed = parseMarkdownTwinFrontmatter(twin);
+    expect(parsed).not.toBeNull();
+    expect(parsed!.frontmatter.canonical).toBe("https://example.com/de/page");
+    expect(parsed!.frontmatter.language).toBe("de");
+    expect(parsed!.body).toBe("# Hello\n\nWorld\n");
+  });
+
+  it("returns null for no frontmatter", () => {
+    expect(parseMarkdownTwinFrontmatter("just text")).toBeNull();
+  });
+});
+
+describe("verifyMarkdownTwinHash", () => {
+  it("verifies correct hash", () => {
+    const twin = buildMarkdownTwin("# Hello", baseProvenance);
+    expect(verifyMarkdownTwinHash(twin)).toBe(true);
+  });
+
+  it("fails for tampered body", () => {
+    const twin = buildMarkdownTwin("# Hello", baseProvenance);
+    const tampered = twin.replace("# Hello", "# Tampered");
+    expect(verifyMarkdownTwinHash(tampered)).toBe(false);
+  });
+});
+
+describe("AUDIENCE_BY_PAGE_TYPE", () => {
+  it("maps home to general", () => {
+    expect(AUDIENCE_BY_PAGE_TYPE.home).toBe("general");
+  });
+
+  it("maps projects to developer", () => {
+    expect(AUDIENCE_BY_PAGE_TYPE.projects).toBe("developer");
+  });
+
+  it("maps legal to business_owner", () => {
+    expect(AUDIENCE_BY_PAGE_TYPE.legal).toBe("business_owner");
+  });
+});