@warpgogol/werkstatt-shared 0.14.0 → 0.15.0

package/src/remediation/remediation-catalog.ts

@@ -0,0 +1,316 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  Canonical remediation catalog mapping ruleId to structured remediation patterns.
+  Consumed by diagnosticsResult() for auto-population and by remediation.hint.validate
+  for coverage checking (RFC-1027).
+</purpose>
+<non-goals>
+  <item>Does not own the Diagnostic schema — that lives in werkstatt-engine schemas.</item>
+  <item>Does not aggregate remediation hints into KernelExecutionReport — that is the engine's job.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1027: Create REMEDIATION_CATALOG with 30+ patterns for the most common ruleIds.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface RemediationPattern {
+  ruleId: string;
+  action: string;
+  template?: string;
+  docRef?: string;
+  targetFiles?: string[];
+}
+
+const REMEDIATION_ENTRIES: RemediationPattern[] = [
+  {
+    ruleId: "SEO-RUNTIME.CANONICAL-MISMATCH",
+    action:
+      "Ensure the canonical URL in the rendered HTML matches the production domain without language prefix for the default locale.",
+    docRef: "docs/authoring/site-composition.md",
+    targetFiles: ["src/layouts/**/*.astro"],
+  },
+  {
+    ruleId: "WORKSPACE.SURFACE.VALIDATE",
+    action:
+      "Fix surface validation errors by checking the surface block declarations against the schema.",
+    docRef: "docs/authoring/site-composition.md",
+  },
+  {
+    ruleId: "TEST.SIGNAL.POLICY.VALIDATE",
+    action:
+      "Align test signal declarations with the policy schema — check signal name, severity, and evidence path.",
+    docRef: "docs/agents/domain.md",
+  },
+  {
+    ruleId: "PUBLIC.ICONS.VALIDATE",
+    action:
+      "Replace invalid icon references with valid SurfaceLabels entries or remove the icon field.",
+    docRef: "docs/authoring/site-composition.md",
+  },
+  {
+    ruleId: "PARITY-SECTION-COUNT",
+    action: "Add or remove sections so the locale overlay matches the base locale section count.",
+    docRef: "docs/authoring/preventive-measures-parity-and-templates.md",
+  },
+  {
+    ruleId: "GEN-FILES-01",
+    action:
+      "Regenerate generated files by running the owning kernel command, then commit the updated output.",
+    docRef: "docs/authoring/generated-files-and-templates.md",
+  },
+  {
+    ruleId: "DEPS-GEN-01",
+    action:
+      "Run pnpm exec werkstatt run deps.peer.check to regenerate the peer dependency manifest.",
+    docRef: "docs/authoring/generated-files-and-templates.md",
+  },
+  {
+    ruleId: "AGC-01",
+    action:
+      "Fix the agent gate configuration — ensure the gate metadata matches the declared gate catalog.",
+    docRef: "docs/agents/domain.md",
+  },
+  {
+    ruleId: "WORKPIECE-IMPORTS-01",
+    action:
+      "Resolve the broken import in the workpiece — check the module path and ensure the package is installed.",
+  },
+  {
+    ruleId: "SNAP-01",
+    action:
+      "Regenerate the behavior snapshot by running pnpm exec werkstatt run behavior.snapshot.generate.",
+  },
+  {
+    ruleId: "CREG-04",
+    action:
+      "Fix the content regression — review the content diff and update the review.yaml before closing the mission.",
+    docRef: "docs/authoring/site-composition.md",
+  },
+  {
+    ruleId: "CREG-03",
+    action:
+      "Fix the content regression — ensure all locale overlays are consistent with the base content.",
+    docRef: "docs/authoring/preventive-measures-parity-and-templates.md",
+  },
+  {
+    ruleId: "CREG-01",
+    action:
+      "Fix the content regression — the base content was changed without a review.yaml. Run content.regression.review.generate.",
+    docRef: "docs/authoring/site-composition.md",
+  },
+  {
+    ruleId: "BRK-04",
+    action:
+      "Fix the bordbuch entry — ensure the hash chain is intact and the entry is properly signed.",
+  },
+  {
+    ruleId: "PROPS-01",
+    action:
+      "Fix the content props schema violation — check the frontmatter against the schema declaration.",
+  },
+  {
+    ruleId: "MAINTENANCE.DEBT.BASELINE.VALIDATE",
+    action:
+      "Regenerate the maintenance debt baseline by running pnpm exec werkstatt run maintenance.debt.baseline.generate.",
+  },
+  {
+    ruleId: "HDR-04",
+    action: "Fix the header configuration — ensure the header block matches the surface schema.",
+    docRef: "docs/authoring/site-composition.md",
+  },
+  {
+    ruleId: "HDR-02",
+    action: "Fix the header navigation — ensure all nav items have valid href and label.",
+    docRef: "docs/authoring/site-composition.md",
+  },
+  {
+    ruleId: "HDR-01",
+    action:
+      "Fix the header structure — ensure the header block is declared in the surface composition.",
+    docRef: "docs/authoring/site-composition.md",
+  },
+  {
+    ruleId: "GEN-EDIT-01",
+    action: "Do not hand-edit generated files. Modify the source template and regenerate.",
+    docRef: "docs/authoring/generated-files-and-templates.md",
+  },
+  {
+    ruleId: "DEPS-PEER-01",
+    action:
+      "Add the missing peer dependency to the package.json or remove the import that requires it.",
+  },
+  {
+    ruleId: "CW-EVID-01",
+    action:
+      "Fix the changelog evidence — ensure the evidence file exists and is referenced correctly.",
+  },
+  {
+    ruleId: "CMD-MAN-03",
+    action:
+      "Regenerate the command manifest by running pnpm exec werkstatt run command.manifest.generate.",
+  },
+  {
+    ruleId: "CI-LOCAL-05",
+    action:
+      "Fix the CI configuration — ensure the local CI workflow matches the pipeline definitions.",
+  },
+  {
+    ruleId: "AGS-05",
+    action:
+      "Fix the agent gate search configuration — ensure the search manifest is generated and accessible.",
+    docRef: "docs/agents/domain.md",
+  },
+  {
+    ruleId: "AGS-02",
+    action:
+      "Fix the agent gate search schema — ensure the search chunk text is within the max length.",
+    docRef: "docs/agents/domain.md",
+  },
+  {
+    ruleId: "AGO-01",
+    action: "Fix the agent gate output — ensure the gate output matches the declared schema.",
+    docRef: "docs/agents/domain.md",
+  },
+  {
+    ruleId: "AGK-03",
+    action:
+      "Fix the agent gate key — ensure the gate key is unique and matches the declared catalog.",
+    docRef: "docs/agents/domain.md",
+  },
+  {
+    ruleId: "WS-WRITE-02",
+    action:
+      "Fix the workspace write — ensure the write intent is declared and the path is within the workspace root.",
+  },
+  {
+    ruleId: "SUPPRESS-VAL-04",
+    action:
+      "Fix the suppression validation — ensure the suppression rule matches the declared schema.",
+    docRef: "docs/authoring/guide-suppression-matching.md",
+  },
+  {
+    ruleId: "ENV-CONTRACT-02",
+    action:
+      "Fix the environment contract — ensure the env variable is declared in .env.example and matches the contract.",
+  },
+  {
+    ruleId: "ENV-CONTRACT-04",
+    action:
+      "Fix the environment contract — ensure the env variable type matches the declared schema.",
+  },
+  {
+    ruleId: "ENV-CONTRACT-05",
+    action:
+      "Fix the environment contract — ensure the env variable is documented in the .env.example file.",
+  },
+  {
+    ruleId: "DEPLOY-SCRIPTS-03",
+    action:
+      "Fix the deploy script — ensure the script is executable and matches the deployment pipeline.",
+  },
+  {
+    ruleId: "FLEET-05",
+    action: "Fix the fleet configuration — ensure the fleet entry matches the declared schema.",
+  },
+  {
+    ruleId: "TYPO-NUM-01",
+    action:
+      "Replace English number format (1,234.56) with German format (1.234,56) in German text.",
+    docRef:
+      "docs/rfcs/rfc-1070-extend-typography-validate-with-tier-2-locale-rules-for-numbers-abbreviations-and-apostrophes.md",
+    targetFiles: ["src/content/**/*.md"],
+  },
+  {
+    ruleId: "TYPO-NUM-02",
+    action:
+      "Replace dot-thousands format (1.234,56) with Ukrainian format using NNBSP (1\u202F234,56) in Ukrainian text.",
+    docRef:
+      "docs/rfcs/rfc-1070-extend-typography-validate-with-tier-2-locale-rules-for-numbers-abbreviations-and-apostrophes.md",
+    targetFiles: ["src/content/**/*.md"],
+  },
+  {
+    ruleId: "TYPO-NUM-03",
+    action: "Replace regular space thousands separator with NNBSP (U+202F) in Ukrainian numbers.",
+    docRef:
+      "docs/rfcs/rfc-1070-extend-typography-validate-with-tier-2-locale-rules-for-numbers-abbreviations-and-apostrophes.md",
+    targetFiles: ["src/content/**/*.md"],
+  },
+  {
+    ruleId: "TYPO-ABBR-01",
+    action: "Add the required trailing period to the abbreviation (e.g. Nr → Nr., usw → usw.).",
+    docRef:
+      "docs/rfcs/rfc-1070-extend-typography-validate-with-tier-2-locale-rules-for-numbers-abbreviations-and-apostrophes.md",
+    targetFiles: ["src/content/**/*.md"],
+  },
+  {
+    ruleId: "TYPO-ABBR-02",
+    action:
+      "Add the required internal space in German multi-part abbreviations (e.g. z.B. → z. B., u.a. → u. a.).",
+    docRef:
+      "docs/rfcs/rfc-1070-extend-typography-validate-with-tier-2-locale-rules-for-numbers-abbreviations-and-apostrophes.md",
+    targetFiles: ["src/content/**/*.md"],
+  },
+  {
+    ruleId: "TYPO-APOS-01",
+    action: "Replace curly apostrophe (U+2019) with straight apostrophe (') in Ukrainian text.",
+    docRef:
+      "docs/rfcs/rfc-1070-extend-typography-validate-with-tier-2-locale-rules-for-numbers-abbreviations-and-apostrophes.md",
+    targetFiles: ["src/content/**/*.md"],
+  },
+  {
+    ruleId: "TYPO-APOS-02",
+    action:
+      "Replace modifier letter apostrophe (U+02BC) with straight apostrophe (') in Ukrainian text.",
+    docRef:
+      "docs/rfcs/rfc-1070-extend-typography-validate-with-tier-2-locale-rules-for-numbers-abbreviations-and-apostrophes.md",
+    targetFiles: ["src/content/**/*.md"],
+  },
+  {
+    ruleId: "TYPO-UNICODE-01",
+    action: "Remove zero-width characters (U+200B, U+200C, U+200D, U+FEFF) from the source text.",
+    docRef:
+      "docs/rfcs/rfc-1071-extend-typography-validate-with-tier-3-advisory-rules-for-unicode-hygiene-link-text-and-sentence-length.md",
+    targetFiles: ["src/content/**/*.md"],
+  },
+  {
+    ruleId: "TYPO-UNICODE-02",
+    action:
+      "Remove soft hyphen (U+00AD) from the source text — it is invisible in most editors but affects rendering.",
+    docRef:
+      "docs/rfcs/rfc-1071-extend-typography-validate-with-tier-3-advisory-rules-for-unicode-hygiene-link-text-and-sentence-length.md",
+    targetFiles: ["src/content/**/*.md"],
+  },
+  {
+    ruleId: "TYPO-LINK-01",
+    action:
+      "Replace bare URL link text with descriptive link text (e.g. [Learn more](url) instead of [https://example.com](url)).",
+    docRef:
+      "docs/rfcs/rfc-1071-extend-typography-validate-with-tier-3-advisory-rules-for-unicode-hygiene-link-text-and-sentence-length.md",
+    targetFiles: ["src/content/**/*.md"],
+  },
+  {
+    ruleId: "TYPO-LINK-02",
+    action:
+      "Replace generic link text (click here, hier klicken, тут, here, hier) with a descriptive phrase that indicates the link target.",
+    docRef:
+      "docs/rfcs/rfc-1071-extend-typography-validate-with-tier-3-advisory-rules-for-unicode-hygiene-link-text-and-sentence-length.md",
+    targetFiles: ["src/content/**/*.md"],
+  },
+  {
+    ruleId: "TYPO-SENT-01",
+    action: "Split the long sentence (more than 40 words) into shorter sentences for readability.",
+    docRef:
+      "docs/rfcs/rfc-1071-extend-typography-validate-with-tier-3-advisory-rules-for-unicode-hygiene-link-text-and-sentence-length.md",
+    targetFiles: ["src/content/**/*.md"],
+  },
+];
+
+export const REMEDIATION_CATALOG: ReadonlyMap<string, RemediationPattern> = new Map(
+  REMEDIATION_ENTRIES.map((entry) => [entry.ruleId, entry]),
+);
+
+export function lookupRemediation(ruleId: string): RemediationPattern | undefined {
+  return REMEDIATION_CATALOG.get(ruleId);
+}

package/src/{share/routes → routes}/template-filter.ts

@@ -25,7 +25,7 @@ utility instead of reimplementing the bracket-detection check inline.
  * that avoids false positives when routes are missing or not yet resolved.
  *
  * Canonical utility (RFC-0917). All `system.md` consumers
- * MUST import from `@warpgogol/werkstatt-shared/share/routes/template-filter`.
+ * MUST import from `@warpgogol/werkstatt-shared/routes/template-filter`.
  * Enforcement: `utility.provenance.validate` (RFC-0916).
  */
 export function hasPlaceholderRoutes(routes?: Record<string, string> | null): boolean {

package/src/{share → runtime}/runtime-context.ts

@@ -13,7 +13,12 @@ become active when RFC-0027 activates the Growth Layer.
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Wave 1 (RFC-0026): Initial creation — RuntimeContext shape and EMPTY_RUNTIME_CONTEXT factory.</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>
 */
 
@@ -56,7 +61,7 @@ export interface RuntimeContext {
  *
  * Usage in page routes:
  * ```ts
- * import { EMPTY_RUNTIME_CONTEXT } from "@warpgogol/werkstatt-shared/share";
+ * import { EMPTY_RUNTIME_CONTEXT } from "@warpgogol/werkstatt-shared/runtime";
  * const ctx = EMPTY_RUNTIME_CONTEXT(lang);
  * const page = await buildPage(entry, ctx);
  * ```

package/src/{share → runtime}/shared-context.ts

@@ -15,7 +15,7 @@ priority order derived from system.md.
 </CHANGE_SUMMARY>
 */
 
-import { deepMergeEntryData } from "./content/merge.ts";
+import { deepMergeEntryData } from "../content/merge.ts";
 
 export interface SharedContextBlockLike {
   id?: string;

package/src/{share/schemas → schemas}/claims.ts

@@ -6,7 +6,7 @@ RFC-0212: the claim annotation surface. A per-record provenance sidecar
 into a CKL claim (RFC-0211) without touching the editable record body. Closed Zod
 schema so `content.claim.validate` can shape-check every sidecar.
 
-Moved from @warpgogol/business/schemas to @warpgogol/werkstatt-shared/share/schemas as part of RFC-0470
+Moved from @warpgogol/business/schemas to @warpgogol/werkstatt-shared/schemas as part of RFC-0470
 (legacy business layer deletion). This is Content Knowledge Lifecycle (CKL)
 infrastructure, not business-layer code.
 </purpose>
@@ -17,7 +17,7 @@ infrastructure, not business-layer code.
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0212: initial claim annotation + record-claims schemas.</item>
-  <item>RFC-0470: moved from @warpgogol/business/schemas/claims.ts to @warpgogol/werkstatt-shared/share/schemas/claims.ts.</item>
+  <item>RFC-0470: moved from @warpgogol/business/schemas/claims.ts to @warpgogol/werkstatt-shared/schemas/claims.ts.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/{share/schemas → schemas}/effects.ts

@@ -11,7 +11,12 @@ schema validation for the RFC-0134 glass-first effects model.
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Introduces RFC-0134 composable effects contracts with glass as the first supported effect kind.</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/schemas → schemas}/features.ts

@@ -12,7 +12,7 @@ copy-pasting. Canonical home per RFC-0033.
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0033: Moved from app content schemas/features to @warpgogol/werkstatt-shared/share. Import switched from "astro/zod" to "zod" for framework neutrality.</item>
+  <item>RFC-0033: Moved from app content schemas/features to @warpgogol/werkstatt-shared/schemas. Import switched from "astro/zod" to "zod" for framework neutrality.</item>
   <item>RFC-0183: Added Feature Policy schema for policy embedded in existing RFC-0047 content domains.</item>
 </CHANGE_SUMMARY>
 */

package/src/{share/schemas → schemas}/index.ts

@@ -1,10 +1,10 @@
 /*
 <MODULE_CONTRACT>
 <purpose>
-RFC-0264: barrel for the entire @warpgogol/werkstatt-shared/share schemas domain — base page schema,
+RFC-0264: barrel for the entire @warpgogol/werkstatt-shared/schemas domain — base page schema,
 navigation, feature policy, and the RFC-0101..0106/0202/0210/0220/0231/0257
 canonical section-visual / section-content / media / material-credit / print
-contracts. Consumers should prefer `@warpgogol/werkstatt-shared/share/schemas` over the deprecated
+contracts. Consumers should prefer `@warpgogol/werkstatt-shared/schemas` over the deprecated
 root barrel.
 </purpose>
 <non-goals>
@@ -12,7 +12,7 @@ root barrel.
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0264: initial creation — aggregates the schemas/ domain for the @warpgogol/werkstatt-shared/share/schemas subpath.</item>
+  <item>RFC-0264: initial creation — aggregates the schemas/ domain for the @warpgogol/werkstatt-shared/schemas subpath.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/{share/schemas → schemas}/navigation.ts

@@ -8,7 +8,12 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Implement RFC-0046: Move navigation schema to shared package with configurable groups.</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/schemas → schemas}/page-base.ts

@@ -12,8 +12,12 @@ Depends only on the zod peer dependency; no Astro or app-specific imports.
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Initial extraction from app content schemas/pages/base into packages/share.</item>
-  <item>Switched import from "astro/zod" to "zod" so the package is Astro-agnostic.</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/schemas → schemas}/person.ts

@@ -10,7 +10,7 @@ This is a closed vocabulary used by check infrastructure, not PBP entity code.
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0470: moved PERSON_AFFILIATIONS from @warpgogol/business/schemas/person.ts to @warpgogol/werkstatt-shared/share/schemas/person.ts.</item>
+  <item>RFC-0470: moved PERSON_AFFILIATIONS from @warpgogol/business/schemas/person.ts to @warpgogol/werkstatt-shared/schemas/person.ts.</item>
   <item>RFC-0471: @warpgogol/business package deleted. Person records now live in a standalone `people` content collection.</item>
 </CHANGE_SUMMARY>
 */

package/src/{share/schemas → schemas}/standard-list-item.ts

@@ -2,7 +2,7 @@
 <MODULE_CONTRACT>
 <purpose>
 [RFC-0100 + RFC-0103] Canonical StandardListItem schema mirrored in
-@warpgogol/werkstatt-shared/share so body components can validate items without importing from
+@warpgogol/werkstatt-shared/schemas so body components can validate items without importing from
 @warpgogol/werkstatt-site/ui (which would create a cyclic dependency). The same shape is
 re-exported by @warpgogol/werkstatt-site/ui/icons/icon-resolver for backwards compatibility.
 </purpose>

package/src/schemas/tests/claim-records.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { claimSourceRefSchema } from "../claim-records.ts";
+
+describe("claimSourceRefSchema", () => {
+  it("accepts a valid source ref", () => {
+    const ref = {
+      sourceId: "src-1",
+      url: "https://example.com",
+      title: "Example",
+      retrievedAt: "2026-01-01",
+    };
+    expect(claimSourceRefSchema.parse(ref)).toEqual(ref);
+  });
+
+  it("rejects missing required fields", () => {
+    expect(() => claimSourceRefSchema.parse({ sourceId: "src-1" })).toThrow();
+  });
+
+  it("rejects invalid URL", () => {
+    expect(() =>
+      claimSourceRefSchema.parse({
+        sourceId: "src-1",
+        url: "not-a-url",
+        title: "Example",
+        retrievedAt: "2026-01-01",
+      }),
+    ).toThrow();
+  });
+
+  it("rejects invalid date format", () => {
+    expect(() =>
+      claimSourceRefSchema.parse({
+        sourceId: "src-1",
+        url: "https://example.com",
+        title: "Example",
+        retrievedAt: "01/01/2026",
+      }),
+    ).toThrow();
+  });
+
+  it("rejects extra keys (strict)", () => {
+    expect(() =>
+      claimSourceRefSchema.parse({
+        sourceId: "src-1",
+        url: "https://example.com",
+        title: "Example",
+        retrievedAt: "2026-01-01",
+        extra: true,
+      }),
+    ).toThrow();
+  });
+});

package/src/schemas/tests/claims.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from "vitest";
+import { recordClaimsSchema } from "../claims.ts";
+
+describe("recordClaimsSchema", () => {
+  it("accepts empty record", () => {
+    expect(recordClaimsSchema.parse({})).toEqual({});
+  });
+
+  it("accepts a valid claims record", () => {
+    const claims = {
+      field1: {
+        provenance: "external",
+        asOf: "2026-01-01",
+      },
+    };
+    const result = recordClaimsSchema.safeParse(claims);
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects non-object", () => {
+    expect(() => recordClaimsSchema.parse("not an object")).toThrow();
+  });
+});

package/src/schemas/tests/effects.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from "vitest";
+import {
+  namedEffectTargetSchema,
+  effectTargetSchema,
+  glassEffectSchema,
+  effectSchema,
+  EFFECT_KIND_META,
+  allowedKindsForTarget,
+  resolveEffectsForTarget,
+  hasEnabledGlassEffect,
+} from "../effects.ts";
+import type { EffectAssignment } from "../effects.ts";
+import { z } from "zod";
+
+type ParsedEffect = z.infer<typeof effectSchema>;
+
+describe("namedEffectTargetSchema", () => {
+  it("accepts valid targets", () => {
+    expect(namedEffectTargetSchema.parse("section")).toBe("section");
+    expect(namedEffectTargetSchema.parse("heading")).toBe("heading");
+  });
+
+  it("rejects invalid target", () => {
+    expect(() => namedEffectTargetSchema.parse("unknown")).toThrow();
+  });
+});
+
+describe("effectTargetSchema", () => {
+  it("accepts slot targets", () => {
+    expect(effectTargetSchema.parse("slot:my-slot")).toBe("slot:my-slot");
+  });
+
+  it("rejects invalid slot format", () => {
+    expect(() => effectTargetSchema.parse("slot:")).toThrow();
+  });
+});
+
+describe("glassEffectSchema", () => {
+  it("accepts valid glass effect", () => {
+    const result = glassEffectSchema.safeParse({ kind: "glass", enabled: true });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects missing required fields", () => {
+    expect(() => glassEffectSchema.parse({ kind: "glass" })).toThrow();
+  });
+
+  it("rejects extra keys (strict)", () => {
+    expect(() => glassEffectSchema.parse({ kind: "glass", enabled: true, extra: true })).toThrow();
+  });
+});
+
+describe("effectSchema (discriminated union)", () => {
+  it("accepts glass effect", () => {
+    const result = effectSchema.safeParse({ kind: "glass", enabled: true });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts shadow effect", () => {
+    const result = effectSchema.safeParse({ kind: "shadow", enabled: true });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects unknown kind", () => {
+    expect(() => effectSchema.parse({ kind: "unknown", enabled: true })).toThrow();
+  });
+});
+
+describe("EFFECT_KIND_META", () => {
+  it("has metadata for all effect kinds", () => {
+    expect(EFFECT_KIND_META.glass.strategy).toBe("surface");
+    expect(EFFECT_KIND_META.shadow.strategy).toBe("text");
+  });
+});
+
+describe("allowedKindsForTarget", () => {
+  it("returns text kinds for heading", () => {
+    const kinds = allowedKindsForTarget("heading");
+    expect(kinds).toContain("shadow");
+    expect(kinds).not.toContain("glass");
+  });
+
+  it("returns glass-only default for body", () => {
+    const kinds = allowedKindsForTarget("body");
+    expect(kinds).toEqual(["glass"]);
+  });
+});
+
+describe("resolveEffectsForTarget", () => {
+  it("returns empty array when no assignments", () => {
+    expect(resolveEffectsForTarget(undefined, "section")).toEqual([]);
+  });
+
+  it("returns effects for matching target", () => {
+    const glassEffect: ParsedEffect = effectSchema.parse({ kind: "glass", enabled: true });
+    const assignments: EffectAssignment[] = [{ target: "section", stack: [glassEffect] }];
+    const effects = resolveEffectsForTarget(assignments, "section");
+    expect(effects).toHaveLength(1);
+  });
+});
+
+describe("hasEnabledGlassEffect", () => {
+  it("returns true when glass effect is enabled", () => {
+    const e: ParsedEffect = effectSchema.parse({ kind: "glass", enabled: true });
+    expect(hasEnabledGlassEffect([e])).toBe(true);
+  });
+
+  it("returns false when glass effect is disabled", () => {
+    const e: ParsedEffect = effectSchema.parse({ kind: "glass", enabled: false });
+    expect(hasEnabledGlassEffect([e])).toBe(false);
+  });
+
+  it("returns false when no effects", () => {
+    expect(hasEnabledGlassEffect(undefined)).toBe(false);
+  });
+});