@warpgogol/werkstatt-shared 0.14.1 → 0.15.0

package/src/stack/tests/walk-files.test.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  walkFiles,
+  readTextFile,
+  readTextFiles,
+  readBinaryFiles,
+} from "../walk-files.ts";
+
+describe("walkFiles", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "walk-files-"));
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("returns relative paths with forward slashes, recursively by default", async () => {
+    await mkdir(join(root, "a", "b"), { recursive: true });
+    await writeFile(join(root, "top.ts"), "");
+    await writeFile(join(root, "a", "mid.ts"), "");
+    await writeFile(join(root, "a", "b", "deep.ts"), "");
+
+    const files = await walkFiles(root);
+
+    expect(files.sort()).toEqual(["a/b/deep.ts", "a/mid.ts", "top.ts"]);
+  });
+
+  it("returns only top-level files when recursive is false", async () => {
+    await mkdir(join(root, "sub"), { recursive: true });
+    await writeFile(join(root, "top.ts"), "");
+    await writeFile(join(root, "sub", "nested.ts"), "");
+
+    const files = await walkFiles(root, { recursive: false });
+
+    expect(files).toEqual(["top.ts"]);
+  });
+
+  it("applies the filter to relative paths", async () => {
+    await mkdir(join(root, "sub"), { recursive: true });
+    await writeFile(join(root, "keep.ts"), "");
+    await writeFile(join(root, "skip.js"), "");
+    await writeFile(join(root, "sub", "keep.ts"), "");
+
+    const files = await walkFiles(root, { filter: (rel) => rel.endsWith(".ts") });
+
+    expect(files.sort()).toEqual(["keep.ts", "sub/keep.ts"]);
+  });
+
+  it("returns an empty array for a missing directory", async () => {
+    expect(await walkFiles(join(root, "nope"))).toEqual([]);
+  });
+
+  it("skips non-file entries", async () => {
+    await mkdir(join(root, "dir-only"), { recursive: true });
+    await writeFile(join(root, "file.ts"), "");
+
+    const files = await walkFiles(root);
+
+    expect(files).toEqual(["file.ts"]);
+  });
+});
+
+describe("readTextFile", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "walk-read-"));
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("reads utf-8 content", async () => {
+    await writeFile(join(root, "a.txt"), "hello ünïcode");
+
+    expect(await readTextFile(join(root, "a.txt"))).toBe("hello ünïcode");
+  });
+
+  it("returns null for a missing file", async () => {
+    expect(await readTextFile(join(root, "missing.txt"))).toBeNull();
+  });
+});
+
+describe("readTextFiles / readBinaryFiles", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "walk-reads-"));
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("reads multiple files keyed by relative path", async () => {
+    await mkdir(join(root, "sub"), { recursive: true });
+    await writeFile(join(root, "a.ts"), "aaa");
+    await writeFile(join(root, "sub", "b.ts"), "bbb");
+
+    const contents = await readTextFiles(root, ["a.ts", "sub/b.ts"]);
+
+    expect(contents.get("a.ts")).toBe("aaa");
+    expect(contents.get("sub/b.ts")).toBe("bbb");
+    expect(contents.size).toBe(2);
+  });
+
+  it("omits unreadable entries", async () => {
+    await writeFile(join(root, "a.ts"), "aaa");
+
+    const contents = await readTextFiles(root, ["a.ts", "missing.ts"]);
+
+    expect(contents.size).toBe(1);
+    expect(contents.has("missing.ts")).toBe(false);
+  });
+
+  it("reads binary content without utf-8 corruption", async () => {
+    const bytes = Buffer.from([0x00, 0xff, 0xfe, 0x42]);
+    await writeFile(join(root, "bin.dat"), bytes);
+
+    const contents = await readBinaryFiles(root, ["bin.dat"]);
+
+    expect(contents.get("bin.dat")).toEqual(bytes);
+  });
+});

package/src/stack/walk-files.ts

@@ -0,0 +1,114 @@
+/*
+<MODULE_CONTRACT>
+<purpose>walkFiles — the single file-discovery and file-reading seam for stack plugins
+(RFC-1100). Returns workspace-relative paths with forward slashes and reads file
+contents in bulk, so validators never import node:fs directly.</purpose>
+
+<non-goals>
+  <item>Does not write files — writes flow through writeFileIfChanged / WorkspaceIO.</item>
+  <item>Does not apply implicit ignore rules (no dotfile or prefix skipping) — callers scope by directory and filter.</item>
+  <item>Does not run in the browser — server-only (Node fs/promises).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1100: initial shared walker — walkFiles plus readTextFile/readTextFiles/readBinaryFiles companions; replaces per-validator private readdir walkers in stack plugins.</item>
+  <item>RFC-1100: step 1 — shared tool/fs/check seams (walkFiles, runTool, defineStackChecks)</item>
+</CHANGE_SUMMARY>
+*/
+
+// Server-only. Do not import from browser/client scripts.
+
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export interface WalkFilesOptions {
+  /** Recurse into subdirectories. Default true. */
+  recursive?: boolean;
+  /** Return true to include a file by its directory-relative path (forward slashes). */
+  filter?: (relPath: string) => boolean;
+}
+
+/**
+ * Lists files under `dir` as relative paths with forward slashes.
+ * Missing or unreadable directories yield an empty array.
+ */
+export async function walkFiles(
+  dir: string,
+  options: WalkFilesOptions = {},
+): Promise<string[]> {
+  const { recursive = true, filter } = options;
+  const results: string[] = [];
+
+  async function walk(current: string, relPrefix: string): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const relPath = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (recursive) {
+          await walk(join(current, entry.name), relPath);
+        }
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (filter && !filter(relPath)) continue;
+      results.push(relPath);
+    }
+  }
+
+  await walk(dir, "");
+  return results;
+}
+
+/**
+ * Reads a single file as utf-8. Returns null when the file is missing or unreadable.
+ */
+export async function readTextFile(path: string): Promise<string | null> {
+  try {
+    return await readFile(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reads multiple files under `dir` as utf-8, keyed by their walkFiles-relative path.
+ * Unreadable entries are omitted from the result.
+ */
+export async function readTextFiles(
+  dir: string,
+  relPaths: string[],
+): Promise<Map<string, string>> {
+  const contents = new Map<string, string>();
+  for (const relPath of relPaths) {
+    const content = await readTextFile(join(dir, relPath));
+    if (content !== null) {
+      contents.set(relPath, content);
+    }
+  }
+  return contents;
+}
+
+/**
+ * Reads multiple files under `dir` as raw buffers, keyed by their walkFiles-relative
+ * path. Use for byte-accurate work (hashing, gzip measurement) where utf-8 decoding
+ * would corrupt binary content. Unreadable entries are omitted from the result.
+ */
+export async function readBinaryFiles(
+  dir: string,
+  relPaths: string[],
+): Promise<Map<string, Buffer>> {
+  const contents = new Map<string, Buffer>();
+  for (const relPath of relPaths) {
+    try {
+      contents.set(relPath, await readFile(join(dir, relPath)));
+    } catch {
+      // Skip unreadable files — same tolerance as the walkers this replaces.
+    }
+  }
+  return contents;
+}

package/src/surface/blueprint.ts

@@ -12,11 +12,14 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0192: Blueprint type + entry assembly (no block baking yet).</item>
   <item>RFC-0199: resolveSlug/routesFor/assembleEntries/generateEntries take a LocalizedUniverse so URL segments localize per language while identity stays on the neutral tuple.</item>
   <item>RFC-0496: add BlueprintServiceConfig + ServicePublicationGate for website-service depth-1 service dossier configuration; add BlueprintLinkingParent for cross-surface parent linking.</item>
   <item>RFC-0497: add BlueprintIntersectionConfig + IntersectionGate + IntersectionSimilarity for website-local depth-5 intersection gate configuration.</item>
   <item>RFC-0500: add BlueprintHubConfig for depth-0 editorial knowledge hub configuration; add BlueprintStatusGate for record status filtering.</item>
+  <item>RFC-1106: step 5 — merge blueprint triplet
+
+surface/blueprint.ts now holds the blueprintSchema (sole declaration), all ~30 contract type names derived via z.infer, parseBlueprint, and the pure helpers. Deleted satellites blueprint-types.ts + blueprint-schema.ts, their package.json export entries, and the zero-consumer site shims (domain/surface/blueprint{,-types,-schema}.ts + 2 load-verification tests). All barrel consumers unchanged.</item>
+  <history>RFC-0192</history>
 </CHANGE_SUMMARY>
 */
 
@@ -38,71 +41,344 @@ import type {
   VirtualRouteEntry,
 } from "./types.ts";
 
-import type {
-  LocalizedString,
-  BlueprintAxis,
-  GeoDepth,
-  BlueprintLevelArticle,
-  BlueprintPillarHero,
-  BlueprintPillarAdaptationDimension,
-  BlueprintPillarAdaptation,
-  BlueprintPillarProductPrice,
-  BlueprintPillarFinalCta,
-  BlueprintPillar,
-  ServicePublicationGate,
-  BlueprintServiceConfig,
-  BlueprintLinkingParent,
-  IndustryPublicationGate,
-  BlueprintDossier,
-  IntersectionGate,
-  IntersectionSimilarity,
-  BlueprintIntersectionConfig,
-  BlueprintHubConfig,
-  BlueprintStatusGate,
-  BlueprintLevel,
-  BlueprintLinking,
-  BlueprintProjection,
-  EnrichedFieldSpec,
-  BlueprintDuplicatePolicy,
-  BlueprintEvidenceDepthPolicy,
-  BlueprintDemandDepthPolicy,
-  BlueprintDepthRolePolicy,
-  BlueprintPolicy,
-  Blueprint,
-} from "./blueprint-types.ts";
-
-export type {
-  LocalizedString,
-  BlueprintAxis,
-  GeoDepth,
-  BlueprintLevelArticle,
-  BlueprintPillarHero,
-  BlueprintPillarAdaptationDimension,
-  BlueprintPillarAdaptation,
-  BlueprintPillarProductPrice,
-  BlueprintPillarFinalCta,
-  BlueprintPillar,
-  ServicePublicationGate,
-  BlueprintServiceConfig,
-  BlueprintLinkingParent,
-  IndustryPublicationGate,
-  BlueprintDossier,
-  IntersectionGate,
-  IntersectionSimilarity,
-  BlueprintIntersectionConfig,
-  BlueprintHubConfig,
-  BlueprintStatusGate,
-  BlueprintLevel,
-  BlueprintLinking,
-  BlueprintProjection,
-  EnrichedFieldSpec,
-  BlueprintDuplicatePolicy,
-  BlueprintEvidenceDepthPolicy,
-  BlueprintDemandDepthPolicy,
-  BlueprintDepthRolePolicy,
-  BlueprintPolicy,
-  Blueprint,
-};
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Blueprint schema — RFC-1106: the sole declaration of the Blueprint contract.
+// All Blueprint types below derive from blueprintSchema via z.infer; the former
+// blueprint-types.ts / blueprint-schema.ts satellites are merged here.
+// ---------------------------------------------------------------------------
+
+const localizedString = z.record(z.string(), z.string());
+
+const intRecord = z.record(z.string(), z.number().int());
+
+// RFC-0490: pillar-hub configuration for depth-0 hub pages.
+const pillarCtaSchema = z.object({
+  label: localizedString,
+  target: z.string().min(1),
+});
+
+const pillarHeroSchema = z.object({
+  eyebrow: localizedString,
+  heading: localizedString,
+  lead: localizedString,
+  primaryCta: pillarCtaSchema,
+  secondaryCta: pillarCtaSchema,
+});
+
+const pillarAdaptationDimensionSchema = z.object({
+  heading: localizedString,
+  body: localizedString,
+});
+
+const pillarAdaptationSchema = z.object({
+  heading: localizedString,
+  dimensions: z.array(pillarAdaptationDimensionSchema).min(1),
+});
+
+const pillarProductPriceSchema = z.object({
+  heading: localizedString,
+  body: localizedString,
+  priceRef: z.string().min(1).optional(),
+});
+
+const pillarFinalCtaSchema = z.object({
+  heading: localizedString,
+  body: localizedString,
+  primaryCta: pillarCtaSchema,
+  secondaryCta: pillarCtaSchema,
+});
+
+const pillarSchema = z.object({
+  hero: pillarHeroSchema,
+  adaptation: pillarAdaptationSchema,
+  productPrice: pillarProductPriceSchema,
+  finalCta: pillarFinalCtaSchema,
+  catalogHeading: localizedString.optional(),
+});
+
+// RFC-0492: dossier configuration for depth-1 industry pages.
+const industryPublicationGateSchema = z.object({
+  minServiceCategories: z.number().int().min(0),
+  minCustomerJourneys: z.number().int().min(0),
+  minTrustSignals: z.number().int().min(0),
+  minArchitectureEntries: z.number().int().min(0),
+  minModuleMappings: z.number().int().min(0),
+  minUniqueFaq: z.number().int().min(0),
+});
+
+const dossierSchema = z.object({
+  gate: industryPublicationGateSchema,
+  claimRestrictions: z.array(z.string().min(1)),
+  doorwayMaxFlaggedShare: z.number().min(0).max(1),
+  duplicateMaxSimilarity: z.number().min(0).max(1),
+  mode: z.enum(["warn", "fail"]),
+});
+
+// RFC-0496: service configuration for depth-1 service dossier pages.
+const servicePublicationGateSchema = z.object({
+  minServiceVariants: z.number().int().min(0),
+  minCustomerQuestions: z.number().int().min(0),
+  minPriceModels: z.number().int().min(0),
+  minFaq: z.number().int().min(0),
+  minPageStructure: z.number().int().min(0),
+});
+
+const serviceSchema = z.object({
+  gate: servicePublicationGateSchema,
+  claimRestrictions: z.array(z.string().min(1)),
+  mode: z.enum(["warn", "fail"]),
+});
+
+const intersectionGateSchema = z.object({
+  minLocalServiceQuestions: z.number().int().min(0),
+  minScenarios: z.number().int().min(0),
+  minLocalEvidence: z.number().int().min(0),
+  minUniqueContentBlocks: z.number().int().min(0),
+  minUniqueFaq: z.number().int().min(0),
+  minSources: z.number().int().min(0),
+});
+
+const intersectionSimilaritySchema = z.object({
+  similarityToIndustryPage: z.number().min(0).max(1),
+  similarityToCityPage: z.number().min(0).max(1),
+  similarityToServicePage: z.number().min(0).max(1),
+  similarityToOtherIntersections: z.number().min(0).max(1),
+});
+
+const intersectionSchema = z.object({
+  gate: intersectionGateSchema,
+  similarity: intersectionSimilaritySchema,
+  substanceIndependenceThreshold: z.number().min(0).max(1),
+  mode: z.enum(["warn", "fail"]),
+});
+
+// RFC-0500: hub configuration for depth-0 editorial knowledge hubs (ratgeber).
+const hubSchema = z.object({
+  cardFields: z.array(z.string().min(1)).min(1),
+  reservedSlugs: z.array(z.string().min(1)),
+});
+
+// RFC-0500: status gate — only records with allowed statuses are emitted as surface entries.
+const statusGateSchema = z.object({
+  allowedStatuses: z.array(z.string().min(1)),
+  excludedStatuses: z.array(z.string().min(1)),
+});
+
+// RFC-0496: cross-surface parent linking.
+const linkingParentSchema = z.object({
+  surface: z.string().min(1),
+  depth: z.number().int().min(0),
+  joinField: z.string().min(1),
+});
+
+// RFC-0325: static article metadata for a level with no per-record binding (depth-0 hubs).
+const blueprintLevelArticleSchema = z.object({
+  publishedAt: z.string().min(1),
+  updatedAt: z.string().min(1).optional(),
+  author: z.string().min(1).optional(),
+  tags: z.array(z.string().min(1)).optional(),
+});
+
+const evidencePolicySchema = z.object({
+  approvedNarrative: z.enum(["required", "optional"]).optional(),
+  requiredRecordFields: z.array(z.string().min(1)).optional(),
+  preferredEvidenceSources: z.array(z.string().min(1)).optional(),
+  minTupleSpecificFacts: z.number().int().min(0).optional(),
+  minWerkEvidence: z.number().int().min(0).optional(),
+  existenceSource: z.enum(["records", "works"]).optional(),
+  freshness: z.enum(["valid-and-current", "valid"]).optional(),
+  duplicate: z
+    .object({
+      method: z.enum(["shingle", "simhash"]).optional(),
+      maxSimilarityWithinCluster: z.number().min(0).max(1).optional(),
+    })
+    .optional(),
+  leadImage: z.enum(["required", "warning", "optional"]).optional(),
+  mode: z.enum(["error", "warning"]).optional(),
+});
+
+const demandPolicySchema = z.object({
+  minVolume: z.number().min(0).optional(),
+  allowIntents: z
+    .array(z.enum(["informational", "commercial", "transactional", "navigational"]))
+    .optional(),
+  missing: z.enum(["noindex", "do-not-emit"]).optional(),
+  staleAfterDays: z.number().int().min(0).optional(),
+});
+
+const depthRolePolicySchema = z.object({
+  indexability: z.enum(["index", "navigation-noindex", "evidence-gated"]),
+  canonicalTarget: z.union([z.literal("tradeHub"), z.number().int().min(0)]).optional(),
+  follow: z.boolean().optional(),
+  includeInSitemap: z.boolean().optional(),
+  geo: z.enum(["full", "twin-only", "off"]).optional(),
+  localEvidence: z
+    .object({
+      minVerifiedFacts: z.number().int().min(0).optional(),
+      minCitySpecificQa: z.number().int().min(0).optional(),
+      minUniqueTokenShare: z.number().min(0).max(1).optional(),
+      maxBodySimilarityWithinBranch: z.number().min(0).max(1).optional(),
+    })
+    .optional(),
+});
+
+export const blueprintSchema = z.object({
+  id: z.string().min(1),
+  entitlement: z.string().min(1),
+  dataset: z.object({ collection: z.string().min(1), status: z.string().optional() }),
+  axes: z
+    .array(
+      z.object({
+        id: z.string().min(1),
+        universe: z.union([
+          z.object({ collection: z.string().min(1), field: z.string().min(1) }),
+          z.object({ provider: z.string().min(1) }),
+        ]),
+        match: z.object({ recordField: z.string().min(1) }),
+      }),
+    )
+    .min(1),
+  levels: z
+    .array(
+      z.object({
+        depth: z.number().int().min(0),
+        slug: localizedString,
+        redirectToPageId: z.string().min(1).optional(),
+        constellation: z.string().min(1),
+        geo: z.enum(["full", "twin-only", "off"]).optional(),
+        titleTemplate: localizedString.optional(),
+        descriptionTemplate: localizedString.optional(),
+        intro: localizedString.optional(),
+        semanticType: z.string().min(1).optional(),
+        article: blueprintLevelArticleSchema.optional(),
+        pillar: pillarSchema.optional(),
+        dossier: dossierSchema.optional(),
+        service: serviceSchema.optional(),
+        intersection: intersectionSchema.optional(),
+        hub: hubSchema.optional(),
+      }),
+    )
+    .min(1),
+  policy: z.object({
+    minRecordsPerDepth: intRecord,
+    noindexBelowPerDepth: intRecord.optional(),
+    redirectPolicy: z.enum(["nearest-ancestor", "root"]).optional(),
+    trailingSlash: z.boolean().optional(),
+    maxStubDepth: z.number().int().optional(),
+    substanceMin: z.number().min(0).max(100).optional(),
+    substanceMinPerDepth: intRecord.optional(),
+    evidencePerDepth: z.record(z.string(), evidencePolicySchema).optional(),
+    demandPerDepth: z.record(z.string(), demandPolicySchema).optional(),
+    depthRoles: z.record(z.string(), depthRolePolicySchema).optional(),
+    sitemapBudget: z.number().int().min(0).optional(),
+    maxThinShare: z.number().min(0).max(1).optional(),
+    regionalGateDepths: z.array(z.number().int().min(0)).optional(),
+    bake: z.enum(["inline", "lazy"]).optional(),
+    statusGate: statusGateSchema.optional(),
+  }),
+  linking: z
+    .object({
+      children: z.object({ limit: z.number().int() }).optional(),
+      siblings: z.object({ limit: z.number().int() }).optional(),
+      teasers: z
+        .object({
+          relevance: z.array(z.object({ sharedAxis: z.string(), weight: z.number() })).optional(),
+        })
+        .optional(),
+      parent: linkingParentSchema.optional(),
+    })
+    .optional(),
+  rotation: z.object({ variantsByTupleHash: z.boolean() }).optional(),
+  projection: z
+    .object({
+      title: localizedString.optional(),
+      description: z.union([localizedString, z.object({ ref: z.string() })]).optional(),
+    })
+    .optional(),
+  freshness: z
+    .object({
+      slaDaysPerDepth: intRecord,
+      field: z.string().min(1),
+      mode: z.enum(["any", "all", "median"]).optional(),
+    })
+    .optional(),
+  enrichedFields: z
+    .array(
+      z.object({
+        field: z.string().min(1),
+        promptId: z.string().min(1),
+        scopeDepth: z.number().int(),
+        maxTokens: z.number().int(),
+        // RFC-0207: output shape + generation granularity (both default to the original behavior).
+        kind: z.enum(["field", "narrative"]).optional(),
+        scope: z.enum(["tuple", "record"]).optional(),
+        axis: z.string().min(1).optional(),
+      }),
+    )
+    .optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Derived contract types — every name the deleted blueprint-types.ts exported,
+// now inferred from the schema above.
+// ---------------------------------------------------------------------------
+
+/** A localized string map: lang → value. */
+export type LocalizedString = z.infer<typeof localizedString>;
+
+export type Blueprint = z.infer<typeof blueprintSchema>;
+export type BlueprintAxis = Blueprint["axes"][number];
+export type BlueprintLevel = Blueprint["levels"][number];
+export type BlueprintPolicy = Blueprint["policy"];
+export type BlueprintLinking = NonNullable<Blueprint["linking"]>;
+export type BlueprintProjection = NonNullable<Blueprint["projection"]>;
+export type EnrichedFieldSpec = NonNullable<Blueprint["enrichedFields"]>[number];
+
+export type GeoDepth = NonNullable<BlueprintLevel["geo"]>;
+export type BlueprintLevelArticle = NonNullable<BlueprintLevel["article"]>;
+export type BlueprintPillar = NonNullable<BlueprintLevel["pillar"]>;
+export type BlueprintPillarHero = BlueprintPillar["hero"];
+export type BlueprintPillarAdaptation = BlueprintPillar["adaptation"];
+export type BlueprintPillarAdaptationDimension = BlueprintPillarAdaptation["dimensions"][number];
+export type BlueprintPillarProductPrice = BlueprintPillar["productPrice"];
+export type BlueprintPillarFinalCta = BlueprintPillar["finalCta"];
+export type BlueprintDossier = NonNullable<BlueprintLevel["dossier"]>;
+export type IndustryPublicationGate = BlueprintDossier["gate"];
+export type BlueprintServiceConfig = NonNullable<BlueprintLevel["service"]>;
+export type ServicePublicationGate = BlueprintServiceConfig["gate"];
+export type BlueprintIntersectionConfig = NonNullable<BlueprintLevel["intersection"]>;
+export type IntersectionGate = BlueprintIntersectionConfig["gate"];
+export type IntersectionSimilarity = BlueprintIntersectionConfig["similarity"];
+export type BlueprintHubConfig = NonNullable<BlueprintLevel["hub"]>;
+
+export type BlueprintStatusGate = NonNullable<BlueprintPolicy["statusGate"]>;
+export type BlueprintLinkingParent = NonNullable<BlueprintLinking["parent"]>;
+export type BlueprintEvidenceDepthPolicy = NonNullable<BlueprintPolicy["evidencePerDepth"]>[string];
+export type BlueprintDemandDepthPolicy = NonNullable<BlueprintPolicy["demandPerDepth"]>[string];
+export type BlueprintDepthRolePolicy = NonNullable<BlueprintPolicy["depthRoles"]>[string];
+export type BlueprintDuplicatePolicy = NonNullable<BlueprintEvidenceDepthPolicy["duplicate"]>;
+
+export interface ParseBlueprintResult {
+  ok: boolean;
+  blueprint?: Blueprint;
+  errors: string[];
+}
+
+/** Validate an unknown value (parsed YAML) into a typed Blueprint. */
+export function parseBlueprint(value: unknown): ParseBlueprintResult {
+  const result = blueprintSchema.safeParse(value);
+  if (result.success) {
+    return { ok: true, blueprint: result.data, errors: [] };
+  }
+  return {
+    ok: false,
+    errors: result.error.issues.map(
+      (issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`,
+    ),
+  };
+}
 
 const DEFAULT_SEGMENT_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 

package/src/surface/decision-composer.ts

@@ -13,7 +13,12 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Architecture review 2026-07-10: initial implementation of composeIndexDecision and pure gate functions.</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>
 */