@warpgogol/werkstatt-shared 0.14.1 → 0.16.0

package/src/passport/claim-sign.ts

@@ -0,0 +1,120 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-1124: Fleet claim signing and verification — canonicalization and
+sign/verify wrappers for FleetClaim, built on the existing Ed25519
+signBytes/verifyBytes primitives from sign.ts. Analogous to dht-sign.ts
+but for the git-native fleet claims registry claim shape.
+</purpose>
+<non-goals>
+  <item>Do not handle key storage or management — private keys arrive as env vars.</item>
+  <item>Do not assemble W3C VC envelopes — claims use a simple signature string, not VCProof.</item>
+  <item>Do not modify sign.ts — this module wraps signBytes/verifyBytes.</item>
+  <item>Do not implement claim legitimacy rules (self-claim vs transfer claim) — that lives in the engine's claims-repo.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1124: initial fleet claim signing module — FleetClaim contract, claimBytes, signClaim, verifyClaim.</item>
+</CHANGE_SUMMARY>
+*/
+
+/**
+ * @warpgogol/werkstatt-shared/passport/claim-sign — fleet claim signing (RFC-1124)
+ *
+ * Uses signBytes/verifyBytes from sign.ts with a dedicated canonicalization
+ * function for fleet claims. The signature field is excluded from
+ * canonicalization (it is computed over the claim data without the signature).
+ */
+
+import { fromHex } from "@warpgogol/werkstatt-shared/signing";
+import { signBytes, toMultibase, verifyBytes } from "./sign.ts";
+
+/**
+ * One signed claim file: claims/<system-id>.json in the fleet claims repo.
+ *
+ * The claim is self-contained for offline signature verification:
+ * `signerPublicKey` is embedded, so a verifier needs nothing but the claim
+ * file to check the signature. Legitimacy (is this signer allowed to claim?)
+ * is decided by the engine — self-claims sign with the creator key, transfer
+ * claims sign with the PREVIOUS creator's key and carry `authorizationHash`
+ * binding them to the bordbuch `handover` event.
+ */
+export interface FleetClaim {
+  /** SHA-256 of the canonical passport.json at claim time. */
+  passportHash: string;
+  systemId: string;
+  /** did:web-style creator identity from passport.creator.identity. */
+  creatorIdentity: string;
+  /** deriveInstanceId(creator.publicKey) — first 16 hex of sha256. */
+  instanceId: string;
+  /** ISO 8601 — LWW field. */
+  claimedAt: string;
+  /** Bordbuch tip hash at claim time. */
+  bordbuchHead: string;
+  /**
+   * Tombstone marker — non-null ONLY on a tombstone file: a claim explicitly
+   * superseded without a same-id successor (e.g. system-id migration).
+   * Normal replacement never writes a tombstone — the new claim replaces the
+   * file and git history is the supersession chain.
+   */
+  supersededBy: string | null;
+  /**
+   * Hex Ed25519 public key of the signer — same format as
+   * passport.creator.publicKey, so deriveInstanceId(signerPublicKey) matches
+   * instanceId for self-claims. Embedded so the claims repo is self-contained
+   * for offline verification. Equals the creator's key for self-claims;
+   * equals the PREVIOUS creator's key for transfer claims.
+   */
+  signerPublicKey: string;
+  /**
+   * Transfer claims only: sha256 of the handover-authorization.json that
+   * authorizes the creator change (matches bordbuch `handover` event
+   * metadata.authorizationHash). Null for self-claims.
+   */
+  authorizationHash: string | null;
+  /** Ed25519 signature over the canonical JSON of all fields above. */
+  signature: string;
+}
+
+/**
+ * FleetClaim without the signature field — the data that is actually signed.
+ */
+export type FleetClaimData = Omit<FleetClaim, "signature">;
+
+/**
+ * Produce canonical UTF-8 bytes from a fleet claim (excluding signature).
+ * DETERMINISM: identical inputs → identical bytes (sorted-key JSON, no whitespace).
+ */
+export function claimBytes(claim: FleetClaimData): Uint8Array {
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(claim).sort()) {
+    sorted[key] = (claim as Record<string, unknown>)[key];
+  }
+  const canonical = JSON.stringify(sorted);
+  return new TextEncoder().encode(canonical);
+}
+
+/**
+ * Sign a fleet claim and return a multibase Ed25519 signature string.
+ *
+ * @param claim          — claim data (without signature)
+ * @param privateKeyHex  — 32-byte Ed25519 private key as hex (from env secret)
+ * @returns multibase base58btc signature string
+ */
+export async function signClaim(claim: FleetClaimData, privateKeyHex: string): Promise<string> {
+  return signBytes(privateKeyHex, claimBytes(claim));
+}
+
+/**
+ * Verify a fleet claim signature against the claim's embedded signerPublicKey.
+ *
+ * @param claim — full fleet claim (including signature)
+ * @returns true if signature is valid
+ */
+export async function verifyClaim(claim: FleetClaim): Promise<boolean> {
+  const { signature, ...claimData } = claim;
+  // signerPublicKey is hex (passport.creator.publicKey format); verifyBytes
+  // expects multibase — convert here so callers never juggle encodings.
+  const signerMultibase = toMultibase(fromHex(claim.signerPublicKey));
+  return verifyBytes(signerMultibase, claimBytes(claimData), signature);
+}

package/src/passport/index.ts

@@ -7,7 +7,12 @@
 </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 — 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>
 */
 
@@ -51,3 +56,6 @@ export type { IdentityCredentialSubject } from "./identity-sign.ts";
 
 export { dhtEntryBytes, signDhtEntry, verifyDhtEntry } from "./dht-sign.ts";
 export type { DHTEntryData } from "./dht-sign.ts";
+
+export { claimBytes, signClaim, verifyClaim } from "./claim-sign.ts";
+export type { FleetClaim, FleetClaimData } from "./claim-sign.ts";

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.
@@ -95,7 +95,7 @@ export interface WerkstattPlugin {
   schema: "werkstatt/plugin@1";
   /** Plugin id: "werkstatt-site" | "werkstatt-phaser-game" | "werkstatt-godot-game". */
   id: string;
-  /** Forge stack profile id, e.g. "astro-typescript-turborepo". */
+  /** Forge stack profile id, e.g. "site". */
   profileId: string;
   /** Kernel modules the plugin contributes (validators, codegen, content, onboarding). */
   moduleLoaders: Record<string, () => Promise<KernelModule>>;

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 {
   /**