@warpgogol/werkstatt-shared 0.14.0 → 0.15.0

package/src/passport/key-rotate.ts

@@ -1,13 +1,21 @@
 /*
 <MODULE_CONTRACT>
-<purpose>Facilitates the generation and rotation of Ed25519 keypairs for secure application authentication.</purpose>
+<purpose>key-rotate — facilitates the generation and rotation of Ed25519 keypairs for secure application authentication.</purpose>
 <non-goals>
   <item>Do not handle raw key parsing or validation beyond schema checks.</item>
   <item>Do not manage application configuration or orchestration.</item>
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Tidied by compass.changesummary.tidy; see git history for prior entries.</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 — 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>
+  <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/passport/schema.ts

@@ -11,7 +11,12 @@
 </MODULE_CONTRACT> 
  
 <CHANGE_SUMMARY>
-  <item>Tidied by compass.changesummary.tidy; see git history for prior entries.</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/passport/sign.ts

@@ -7,8 +7,13 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Tidied by compass.changesummary.tidy; see git history for prior entries.</item>
-  <item>RFC-0921: delegate Ed25519 sign/verify/keygen to shared signing core (@warpgogol/werkstatt-engine/signing). Remove @noble/ed25519 import.</item>
+  <item>RFC-0921: delegate Ed25519 sign/verify/keygen to shared signing core (@warpgogol/werkstatt-shared/signing). Remove @noble/ed25519 import.</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> */
 
 /**
@@ -32,7 +37,7 @@ import {
   verifyBytes as signingVerifyBytes,
   fromHex,
   toHex,
-} from "@warpgogol/werkstatt-engine/signing";
+} from "@warpgogol/werkstatt-shared/signing";
 import type { VCProof, VerifiableCredential } from "./schema.ts";
 
 // ---------------------------------------------------------------------------

package/src/passport/vitest.config.ts

@@ -3,6 +3,7 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   test: {
     environment: "node",
+    testTimeout: 30_000,
     include: ["src/**/*.test.ts"],
   },
 });

package/src/pbt/index.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from "vitest";
+import {
+  fcAssert,
+  letterString,
+  composeWord,
+  safeText,
+  DEFAULT_NUM_RUNS,
+  DEFAULT_MAX_SKIPS_PER_RUN,
+} from "./index.ts";
+import fc from "fast-check";
+
+describe("PBT helpers", () => {
+  describe("constants", () => {
+    it("DEFAULT_NUM_RUNS is 50", () => {
+      expect(DEFAULT_NUM_RUNS).toBe(50);
+    });
+
+    it("DEFAULT_MAX_SKIPS_PER_RUN is 100", () => {
+      expect(DEFAULT_MAX_SKIPS_PER_RUN).toBe(100);
+    });
+  });
+
+  describe("letterString", () => {
+    it("generates only letters (\\p{L}+)", () => {
+      fcAssert(
+        fc.property(letterString(1, 10), (word) => {
+          return /^\p{L}+$/u.test(word);
+        }),
+      );
+    });
+
+    it("respects minLength", () => {
+      fcAssert(
+        fc.property(letterString(3, 5), (word) => {
+          return word.length >= 3 && word.length <= 5;
+        }),
+      );
+    });
+
+    it("never generates empty string when minLength=1", () => {
+      fcAssert(
+        fc.property(letterString(1, 5), (word) => {
+          return word.length > 0;
+        }),
+      );
+    });
+  });
+
+  describe("composeWord", () => {
+    it("generates letter + separator + letter", () => {
+      const sep = "\u2019";
+      fcAssert(
+        fc.property(composeWord(sep), (word) => {
+          return /\p{L}+\u2019\p{L}+/u.test(word);
+        }),
+      );
+    });
+
+    it("contains exactly one separator", () => {
+      const sep = "-";
+      fcAssert(
+        fc.property(composeWord(sep), (word) => {
+          const count = (word.match(/-/g) ?? []).length;
+          return count === 1;
+        }),
+      );
+    });
+  });
+
+  describe("safeText", () => {
+    it("respects maxLength", () => {
+      fcAssert(
+        fc.property(safeText(50), (text) => {
+          return text.length <= 50;
+        }),
+      );
+    });
+  });
+
+  describe("fcAssert", () => {
+    it("accepts custom numRuns", () => {
+      fcAssert(
+        fc.property(letterString(1, 3), (word) => word.length > 0),
+        { numRuns: 10 },
+      );
+    });
+
+    it("accepts custom maxSkipsPerRun", () => {
+      fcAssert(
+        fc.property(letterString(1, 3), (word) => word.length > 0),
+        { maxSkipsPerRun: 50 },
+      );
+    });
+  });
+});

package/src/pbt/index.ts

@@ -0,0 +1,251 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  Canonical PBT (property-based testing) helpers for the Werkstatt.
+  Provides safe defaults for `fc.assert` (numRuns, maxSkips) and efficient
+  arbitraries that avoid the `fc.string().filter()` anti-pattern that causes
+  test hangs when the filter regex rejects most generated candidates.
+</purpose>
+<non-goals>
+  <item>Does not wrap every fast-check arbitrary — only the ones that need safety defaults.</item>
+  <item>Does not replace `fc.assert` entirely — callers can still use it directly with explicit options.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1070: Create PBT helpers (fcAssert, letterString, composeWord) to prevent filter-induced hangs.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fc from "fast-check";
+
+// ---------------------------------------------------------------------------
+// Default PBT configuration
+// ---------------------------------------------------------------------------
+
+/** Default number of property runs. fast-check default is 100; we use 50 for speed. */
+export const DEFAULT_NUM_RUNS = 50;
+
+/**
+ * Default max pre-condition skips per run.
+ * fast-check default is 100. We keep it at 100 — this covers `fc.pre()` failures,
+ * NOT `.filter()` rejections (which have no limit and are the real hang cause).
+ * The hang prevention comes from using `letterString`/`composeWord` instead of
+ * `fc.string().filter()`, plus the vitest `testTimeout: 30_000` safety net.
+ */
+export const DEFAULT_MAX_SKIPS_PER_RUN = 100;
+
+// ---------------------------------------------------------------------------
+// fcAssert — safe wrapper around fc.assert with defaults
+// ---------------------------------------------------------------------------
+
+export interface FcAssertOptions {
+  numRuns?: number;
+  maxSkipsPerRun?: number;
+}
+
+/**
+ * Wraps `fc.assert` with safe defaults: `numRuns: 50`, `maxSkipsPerRun: 100`.
+ * Callers can override either value.
+ *
+ * Note: `maxSkipsPerRun` only covers `fc.pre()` pre-condition failures.
+ * It does NOT cover `.filter()` rejections on arbitraries — those have no
+ * limit and are the primary cause of test hangs. Use `letterString` or
+ * `composeWord` instead of `fc.string().filter()` to avoid this entirely.
+ *
+ * @example
+ * fcAssert(fc.property(letterString, (word) => { ... }));
+ * fcAssert(fc.property(letterString, (word) => { ... }), { numRuns: 100 });
+ */
+export function fcAssert<T>(property: fc.IProperty<T>, options?: FcAssertOptions): void {
+  fc.assert(property, {
+    numRuns: options?.numRuns ?? DEFAULT_NUM_RUNS,
+    maxSkipsPerRun: options?.maxSkipsPerRun ?? DEFAULT_MAX_SKIPS_PER_RUN,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Efficient letter-only arbitrary — replaces fc.string().filter(/^\p{L}+$/u)
+// ---------------------------------------------------------------------------
+
+/**
+ * Latin + Cyrillic letter characters for efficient generation.
+ * Uses `fc.constantFrom` (no filtering) instead of `fc.string().filter()`.
+ */
+const LETTER_CHARS = [
+  // Latin lowercase
+  "a",
+  "b",
+  "c",
+  "d",
+  "e",
+  "f",
+  "g",
+  "h",
+  "i",
+  "j",
+  "k",
+  "l",
+  "m",
+  "n",
+  "o",
+  "p",
+  "q",
+  "r",
+  "s",
+  "t",
+  "u",
+  "v",
+  "w",
+  "x",
+  "y",
+  "z",
+  // Latin uppercase
+  "A",
+  "B",
+  "C",
+  "D",
+  "E",
+  "F",
+  "G",
+  "H",
+  "I",
+  "J",
+  "K",
+  "L",
+  "M",
+  "N",
+  "O",
+  "P",
+  "Q",
+  "R",
+  "S",
+  "T",
+  "U",
+  "V",
+  "W",
+  "X",
+  "Y",
+  "Z",
+  // Cyrillic lowercase (Ukrainian + Russian)
+  "а",
+  "б",
+  "в",
+  "г",
+  "д",
+  "е",
+  "ж",
+  "з",
+  "и",
+  "і",
+  "к",
+  "л",
+  "м",
+  "н",
+  "о",
+  "п",
+  "р",
+  "с",
+  "т",
+  "у",
+  "ф",
+  "х",
+  "ц",
+  "ч",
+  "ш",
+  "щ",
+  "ь",
+  "ю",
+  "я",
+  "ї",
+  "є",
+  "ґ",
+  // Cyrillic uppercase
+  "А",
+  "Б",
+  "В",
+  "Г",
+  "Д",
+  "Е",
+  "Ж",
+  "З",
+  "И",
+  "І",
+  "К",
+  "Л",
+  "М",
+  "Н",
+  "О",
+  "П",
+  "Р",
+  "С",
+  "Т",
+  "У",
+  "Ф",
+  "Х",
+  "Ц",
+  "Ч",
+  "Ш",
+  "Щ",
+  "Ь",
+  "Ю",
+  "Я",
+  "Ї",
+  "Є",
+  "Ґ",
+];
+
+const letterArb = fc.constantFrom(...LETTER_CHARS);
+
+/**
+ * Generates strings consisting only of letters (Latin + Cyrillic).
+ * Efficient: uses `fc.constantFrom` + `fc.array` — no filtering.
+ *
+ * @example
+ * const word = letterString(1, 5); // 1-5 letter word
+ * fcAssert(fc.property(word, (w) => /^\p{L}+$/u.test(w)));
+ */
+export function letterString(minLength = 1, maxLength = 10): fc.Arbitrary<string> {
+  return fc.array(letterArb, { minLength, maxLength }).map((arr) => arr.join(""));
+}
+
+// ---------------------------------------------------------------------------
+// composeWord — builds words with guaranteed structure (no filter needed)
+// ---------------------------------------------------------------------------
+
+export interface ComposeWordOptions {
+  minLength?: number;
+  maxLength?: number;
+}
+
+/**
+ * Generates words with a guaranteed `letter + separator + letter` structure.
+ * Eliminates the need for `fc.string().filter()` when testing pattern-based rules.
+ *
+ * @example
+ * const curlyAposWord = composeWord("\u2019"); // e.g. "ім'я"
+ * const modAposWord = composeWord("\u02BC");   // e.g. "імʼя"
+ */
+export function composeWord(separator: string, options?: ComposeWordOptions): fc.Arbitrary<string> {
+  const min = options?.minLength ?? 1;
+  const max = options?.maxLength ?? 5;
+  return fc
+    .tuple(letterString(min, max), letterString(min, max))
+    .map(([a, b]) => `${a}${separator}${b}`);
+}
+
+// ---------------------------------------------------------------------------
+// safeText — bounded-length string for negative tests (no filter needed)
+// ---------------------------------------------------------------------------
+
+/**
+ * Generates random strings with a max length for negative property tests.
+ * Use when the property should NOT fire on arbitrary text — the test verifies
+ * that no findings are produced. The `maxLength` bound prevents excessive
+ * string generation time.
+ *
+ * @example
+ * fcAssert(fc.property(safeText(80), (text) => runRule("TYPO-XX", text).length === 0));
+ */
+export function safeText(maxLength = 80): fc.Arbitrary<string> {
+  return fc.string({ maxLength });
+}

package/src/plugin/plugin-contract.ts

@@ -14,7 +14,7 @@ are shared infrastructure, not engine internals.</purpose>
   <item>RFC-0942: moved from werkstatt-engine/src/plugin-contract.ts to werkstatt-shared/src/plugin/plugin-contract.ts.</item>
 </CHANGE_SUMMARY>
 */
-import type { KernelModule, KernelPipelineStep } from "@warpgogol/werkstatt-engine/kernel/types";
+import type { KernelModule, KernelPipelineStep } from "@warpgogol/werkstatt-shared/kernel";
 
 /**
  * Placeholder type for deploy adapter factories.

package/src/{share → policy}/entitlement.ts

@@ -10,10 +10,16 @@ agnostic contract consumed by the build-time resolver, the feature gates, and ru
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0169: initial implementation.</item>
   <item>RFC-0706: add nachweis feature for Nachweisregister commercial module.</item>
   <item>RFC-0741: add multi-currency feature for multi-currency build pipeline.</item>
   <item>RFC-0932: add external-link-qr feature for QR code modal entitlement module.</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>
+  <history>RFC-0169</history>
 </CHANGE_SUMMARY>
 */
 
@@ -42,6 +48,12 @@ export const ENTITLED_FEATURES = [
   "external-link-qr",
 ] as const;
 
+/**
+ * Features that are always enabled for all sites, regardless of Stripe or override state.
+ * These are platform-level capabilities that every site gets for free.
+ */
+export const FREE_ENTITLED_FEATURES: EntitledFeature[] = ["external-link-qr"];
+
 export type EntitledFeature = (typeof ENTITLED_FEATURES)[number];
 
 /** Stripe Feature `lookup_key` → EntitledFeature. The single mapping point. */
@@ -149,10 +161,13 @@ export function resolveEntitlements(input: {
       ? { pseo: { indexBudget: input.pseoIndexBudget, regionalUnlocked } }
       : {};
 
+  const mergeFree = (features: string[]): EntitledFeature[] =>
+    dedupe([...features, ...FREE_ENTITLED_FEATURES]);
+
   if (input.override && input.override.length > 0) {
     return {
       customerId: input.customerId,
-      features: dedupe(input.override),
+      features: mergeFree(input.override),
       source: "override",
       ...pseo,
     };
@@ -160,12 +175,17 @@ export function resolveEntitlements(input: {
   if (input.stripeFeatures) {
     return {
       customerId: input.customerId,
-      features: dedupe(input.stripeFeatures),
+      features: mergeFree(input.stripeFeatures),
       source: "stripe",
       ...pseo,
     };
   }
-  return { customerId: input.customerId, features: [], source: "none", ...pseo };
+  return {
+    customerId: input.customerId,
+    features: dedupe([...FREE_ENTITLED_FEATURES]),
+    source: "none",
+    ...pseo,
+  };
 }
 
 /** Reader used by build gates (which modules compile) and runtime endpoints. */

package/src/{share → policy}/feature-policy.ts

@@ -9,7 +9,12 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0183: Initial runtime resolver for Feature Policy without Feature Graph dependency.</item>
-  <item>Removed false async from resolveFeaturePolicy; resolveFeaturePolicySync is now a thin alias.</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>
 */
 
@@ -19,7 +24,7 @@ import type {
   FeaturePolicyTargetRef,
   FeaturePolicyVisibility,
   ResolvedFeaturePolicy,
-} from "./schemas/features.ts";
+} from "../schemas/features.ts";
 
 // Re-export types for consumers
 export type {
@@ -29,7 +34,7 @@ export type {
   FeaturePolicyTargetRef,
   FeaturePolicyVisibility,
   ResolvedFeaturePolicy,
-} from "./schemas/features.ts";
+} from "../schemas/features.ts";
 
 export interface FeaturePolicyResolverOptions {
   /**

package/src/{share → policy}/visibility.ts

@@ -15,12 +15,17 @@ requires a superseding RFC.
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Wave 1 (RFC-0026): Initial creation — unified VisibilityExpr grammar with build-time evaluator.</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 { z } from "zod";
-import type { RuntimeContext } from "./runtime-context.ts";
+import type { RuntimeContext } from "../runtime/runtime-context.ts";
 
 // ---------------------------------------------------------------------------
 // VisibilityExpr — closed discriminated union (DNA-19, RFC-0026)

package/src/redirects/redirects.ts

@@ -0,0 +1,117 @@
+/*
+<MODULE_CONTRACT>
+<purpose>App-agnostic _redirects file parsing for reuse across site-kernel-checks and site-kernel-handoff (RFC-0588).</purpose>
+<non-goals>
+  <item>Do not handle advanced Cloudflare Pages syntax (query parameters, placeholders) — only whitespace-delimited `from to status` lines.</item>
+  <item>Do not perform glob-to-regex conversion — that is the consumer's responsibility.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0588: extracted parseRedirectRules and RedirectRule from site-kernel-checks/managed-public.ts into @warpgogol/werkstatt-shared/redirects subpath.</item>
+  <item>RFC-0595: add extractRedirectTarget helper for parsing url= from meta-refresh tags.</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>
+*/
+
+export type RedirectRule = {
+  from: string;
+  to: string | undefined;
+  status: number;
+  line: string;
+};
+
+/**
+ * File extensions excluded from trailing-slash normalization in the Cloudflare Worker
+ * `isPageRoute` function. If a request URL ends with one of these extensions, the Worker
+ * must NOT 308-redirect it to a trailing-slash URL (which would cause a 404).
+ *
+ * This is the single source of truth — injected into worker.ts.template and
+ * markdown-negotiation.ts.template via the `{{EXCLUDED_EXTENSIONS}}` placeholder.
+ * The `trailing.slash.config.validate` SLASH-04 rule scans `public/` for file extensions
+ * not in this list and fails the build.
+ *
+ * When adding a new media/asset type to `public/`, add its extension here.
+ */
+export const PAGE_ROUTE_EXCLUDED_EXTENSIONS: readonly string[] = [
+  "ico",
+  "png",
+  "jpg",
+  "jpeg",
+  "webp",
+  "avif",
+  "gif",
+  "bmp",
+  "svg",
+  "css",
+  "js",
+  "mjs",
+  "json",
+  "txt",
+  "xml",
+  "woff",
+  "woff2",
+  "ttf",
+  "otf",
+  "webmanifest",
+  "md",
+  "pdf",
+  "webm",
+  "mp4",
+  "wasm",
+  "map",
+  "m3u8",
+  "ts",
+  "html",
+  "ndjson",
+  "vtt",
+  "yaml",
+];
+
+/**
+ * Build a regex string (without delimiters) that matches any of the excluded extensions.
+ * Used by the codegen to inject the alternation into the `isPageRoute` regex.
+ */
+export function buildPageRouteExclusionAlternation(
+  extensions: readonly string[] = PAGE_ROUTE_EXCLUDED_EXTENSIONS,
+): string {
+  return extensions.join("|");
+}
+
+export function parseRedirectRules(body: string): RedirectRule[] {
+  return body
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith("#"))
+    .map((line) => {
+      const [from, to, statusRaw] = line.split(/\s+/);
+      return {
+        from: from ?? "",
+        to,
+        status: Number(statusRaw ?? 301),
+        line,
+      };
+    })
+    .filter((rule) => rule.from.length > 0);
+}
+
+/**
+ * Extract the redirect target URL from a `<meta http-equiv="refresh" content="0;url=...">` tag.
+ * Returns the immediate target only (first hop). Returns null if the tag is
+ * absent or the url= value cannot be parsed.
+ */
+export function extractRedirectTarget(html: string): string | null {
+  const m = html.match(
+    /<meta[^>]+http-equiv=["']refresh["'][^>]*content=["']\s*\d+\s*;\s*url=([^"']+)['"][^>]*>/i,
+  );
+  if (m?.[1]) return m[1].trim();
+  const m2 = html.match(
+    /<meta[^>]+content=["']\s*\d+\s*;\s*url=([^"']+)['"][^>]*http-equiv=["']refresh["'][^>]*>/i,
+  );
+  if (m2?.[1]) return m2[1].trim();
+  return null;
+}

package/src/{share → redirects/tests}/redirects.test.ts

@@ -8,7 +8,7 @@
 */
 
 import { test, expect } from "vitest";
-import { extractRedirectTarget, parseRedirectRules } from "./redirects.ts";
+import { extractRedirectTarget, parseRedirectRules } from "../redirects.ts";
 
 test("extractRedirectTarget: extracts url from standard meta-refresh tag", () => {
   const html = `<html><head><meta http-equiv="refresh" content="0;url=/de/agb"></head><body></body></html>`;