@warpgogol/werkstatt-shared 0.2.0

package/src/share/visibility.ts

@@ -0,0 +1,167 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Unified VisibilityExpr grammar and evaluator (DNA-26, RFC-0026).
+One grammar, two consumers: block-level visibility in page content and
+feature-graph visibility in RFC-0018.
+
+VisibilityExpr is a CLOSED discriminated union (DNA-19). Adding a new case
+requires a superseding RFC.
+</purpose>
+<non-goals>
+  <item>Do not add new VisibilityExpr cases (e.g. abTest, experiment) without a superseding RFC.</item>
+  <item>Do not implement runtime (edge) evaluation here — evalVisibility is build-time only.</item>
+  <item>Do not import from app-local code.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Wave 1 (RFC-0026): Initial creation — unified VisibilityExpr grammar with build-time evaluator.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+import type { RuntimeContext } from "./runtime-context.ts";
+
+// ---------------------------------------------------------------------------
+// VisibilityExpr — closed discriminated union (DNA-19, RFC-0026)
+// ---------------------------------------------------------------------------
+
+/**
+ * A closed discriminated union describing when a block or feature is visible.
+ *
+ * MVP semantics:
+ *   { feature }  — delegates to featureGraph.isEnabled(key)
+ *   { locale }   — checks ctx.locale against the given code(s)
+ *   { segment }  — ALWAYS returns false at MVP (ctx.segment === null). RFC-0027 activates.
+ *   { flag }     — ALWAYS returns false at MVP (ctx.flags === {}). RFC-0027 activates.
+ *   { all }      — logical AND of sub-expressions
+ *   { any }      — logical OR of sub-expressions
+ *   { not }      — logical NOT of a sub-expression
+ *
+ * Content authors may write segment/flag expressions today. They evaluate false
+ * at MVP but will become live without content changes when RFC-0027 ships.
+ *
+ * Do NOT add a new case without a superseding RFC (DNA-19).
+ */
+export type VisibilityExpr =
+  | { feature: string }
+  | { locale: string | string[] }
+  | { segment: string | string[] }
+  | { flag: string }
+  | { all: VisibilityExpr[] }
+  | { any: VisibilityExpr[] }
+  | { not: VisibilityExpr };
+
+// ---------------------------------------------------------------------------
+// VisibilityExprSchema — Zod validator (recursive via z.lazy)
+// ---------------------------------------------------------------------------
+
+const visibilityExprBase: z.ZodType<VisibilityExpr> = z.lazy(() =>
+  z.union([
+    z.object({ feature: z.string().min(1) }),
+    z.object({ locale: z.union([z.string().min(1), z.array(z.string().min(1))]) }),
+    z.object({ segment: z.union([z.string().min(1), z.array(z.string().min(1))]) }),
+    z.object({ flag: z.string().min(1) }),
+    z.object({ all: z.array(visibilityExprBase).min(1) }),
+    z.object({ any: z.array(visibilityExprBase).min(1) }),
+    z.object({ not: visibilityExprBase }),
+  ]),
+);
+
+/**
+ * Zod schema for VisibilityExpr.
+ * Used by page.block.validate and visibility.expr.validate to parse expressions
+ * found in page content and feature-graph YAML files.
+ */
+export const VisibilityExprSchema: z.ZodType<VisibilityExpr> = visibilityExprBase;
+
+// ---------------------------------------------------------------------------
+// ResolvedFeatureGraph — minimal interface for evalVisibility
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal interface that evalVisibility depends on for { feature: "..." } clauses.
+ * Consumers provide their own implementation (e.g. from getFeatureGraph() in RFC-0018).
+ * An empty/no-op implementation returns false for every key — safe for offline/preview.
+ */
+export interface ResolvedFeatureGraph {
+  /** Returns true when the feature with `key` is enabled in the current graph. */
+  isEnabled(key: string): boolean;
+}
+
+/** A no-op feature graph where every feature evaluates as disabled. */
+export const EMPTY_FEATURE_GRAPH: ResolvedFeatureGraph = {
+  isEnabled: () => true, // MVP: features default to enabled (graph opt-outs via explicit false)
+};
+
+// ---------------------------------------------------------------------------
+// exhaustive — compile-time union exhaustion helper
+// ---------------------------------------------------------------------------
+
+function exhaustive(x: never): never {
+  throw new Error(`[visibility] Unhandled VisibilityExpr case: ${JSON.stringify(x)}`);
+}
+
+// ---------------------------------------------------------------------------
+// evalVisibility — build-time evaluator
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluates a VisibilityExpr at build time.
+ *
+ * Returns true  → block/feature should be rendered in the output.
+ * Returns false → block/feature should be dropped from the output.
+ *
+ * A null expression (no `visibility:` key) is treated as unconditionally visible.
+ *
+ * MVP guarantees (enforced by runtime.context.shape):
+ *   - ctx.segment === null  → all { segment } clauses return false.
+ *   - ctx.flags === {}      → all { flag } clauses return false.
+ *
+ * @param expr        The parsed visibility expression (or null if absent).
+ * @param ctx         The RuntimeContext for this build locale.
+ * @param featureGraph The resolved feature graph from RFC-0018.
+ */
+export function evalVisibility(
+  expr: VisibilityExpr | null | undefined,
+  ctx: RuntimeContext,
+  featureGraph: ResolvedFeatureGraph,
+): boolean {
+  if (expr == null) return true;
+
+  if ("feature" in expr) {
+    return featureGraph.isEnabled(expr.feature);
+  }
+
+  if ("locale" in expr) {
+    const locales = Array.isArray(expr.locale) ? expr.locale : [expr.locale];
+    return locales.includes(ctx.locale);
+  }
+
+  if ("segment" in expr) {
+    // MVP contract: ctx.segment is always null → segment clauses always return false.
+    // RFC-0027 lifts this when persona detection lands.
+    if (ctx.segment === null) return false;
+    const segments = Array.isArray(expr.segment) ? expr.segment : [expr.segment];
+    return segments.includes(ctx.segment);
+  }
+
+  if ("flag" in expr) {
+    // MVP contract: ctx.flags is always {} → flag clauses always return false.
+    return ctx.flags[expr.flag] === true;
+  }
+
+  if ("all" in expr) {
+    return expr.all.every((e) => evalVisibility(e, ctx, featureGraph));
+  }
+
+  if ("any" in expr) {
+    return expr.any.some((e) => evalVisibility(e, ctx, featureGraph));
+  }
+
+  if ("not" in expr) {
+    return !evalVisibility(expr.not, ctx, featureGraph);
+  }
+
+  return exhaustive(expr);
+}

package/src/share/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+  },
+});

package/src/share/wrap-inline-numbers.ts

@@ -0,0 +1,139 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Server-side HTML post-processor that wraps qualifying inline numbers in prose HTML with GSAP-ready span elements. Zero DOM access — safe to call in Astro SSR/SSG frontmatter.</purpose>
+<non-goals>
+  <item>Do not import or call this from browser scripts — server-only.</item>
+  <item>Do not wrap numbers inside h1–h4, code, pre, or existing js-inline-number spans.</item>
+  <item>Do not use a full HTML parser — keep dependency-free.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0041: Created as SSR inline number pre-wrap utility in @warpgogol/werkstatt-shared/share.</item>
+</CHANGE_SUMMARY>
+*/
+
+// @ai-invariant: RFC-0041. Server-only. Never import in browser scripts.
+
+export interface WrapInlineNumbersOptions {
+  /** Also wrap year numbers (1200–currentYear+120). Default false — years are excluded by default. */
+  animateYears?: boolean;
+  /** GSAP tween duration in seconds written into data-duration. Default 3.0. */
+  duration?: number;
+}
+
+// Matches integers ≥ 2 digits bounded by whitespace, punctuation, or string edges.
+// Does NOT match:
+//   - compound tokens: 14-jährig, 1st, e.V., 1.234 (trailing period or hyphen)
+//   - paragraph refs:  § 53 (lookbehind excludes § via negative lookahead on the preceding char)
+//   - registration IDs: VR 1520 BHV (uppercase-letter word before the number)
+// Lookbehind: preceded by start-of-string OR whitespace/opening punctuation,
+//             AND NOT immediately preceded by an uppercase letter sequence + space (abbrev/code)
+// Lookahead:  followed by end-of-string OR whitespace/closing punctuation
+const NUMBER_RE = /(?<=^|[\s(\[«"–—,;:!?])(\d{2,})(?=[\s).,;:!?»"–—]|$)/gm;
+
+// Tags whose text content must not be wrapped.
+const SKIP_TAGS = new Set(["h1", "h2", "h3", "h4", "h5", "h6", "code", "pre", "li", "ol"]);
+
+/**
+ * Splits an HTML string into alternating text and tag tokens.
+ * Tags are strings starting with "<"; text segments are everything between tags.
+ */
+function tokenize(html: string): string[] {
+  return html.split(/(<[^>]*>)/);
+}
+
+/**
+ * Extracts the lowercase tag name from a tag token, e.g. "<h2 class=...>" → "h2".
+ * Returns empty string for comments, doctypes, etc.
+ */
+function tagName(token: string): string {
+  const m = token.match(/^<\/?([a-zA-Z][a-zA-Z0-9]*)/);
+  return m ? m[1].toLowerCase() : "";
+}
+
+function isOpeningTag(token: string): boolean {
+  return token.startsWith("<") && !token.startsWith("</") && !token.startsWith("<!--");
+}
+
+function isClosingTag(token: string): boolean {
+  return token.startsWith("</");
+}
+
+/**
+ * Accepts a rendered HTML string and returns the same string with qualifying
+ * inline numbers wrapped in `<span class="js-inline-number" …>` elements.
+ *
+ * - Numbers inside h1–h4, code, pre, and existing js-inline-number spans are skipped.
+ * - Year numbers (1200–currentYear+120) are always excluded (never wrapped).
+ * - `animateYears` is reserved but currently treated as always false.
+ * - Each span carries `style="display:inline;min-width:Nch"` to prevent CLS.
+ */
+export function wrapInlineNumbers(html: string, options: WrapInlineNumbersOptions = {}): string {
+  const { animateYears: _animateYears = false, duration = 3.0 } = options;
+  const currentYear = new Date().getFullYear();
+  const isYear = (n: number) => n >= 1200 && n <= currentYear + 120;
+
+  const tokens = tokenize(html);
+
+  // Stack of tag names currently open (depth tracking to skip nested content)
+  const skipStack: string[] = [];
+
+  const result: string[] = [];
+
+  for (const token of tokens) {
+    if (token.startsWith("<")) {
+      const name = tagName(token);
+
+      if (isOpeningTag(token)) {
+        if (SKIP_TAGS.has(name)) {
+          skipStack.push(name);
+        }
+        // Also skip if we're entering a js-inline-number span (no double-wrap)
+        if (name === "span" && token.includes("js-inline-number")) {
+          skipStack.push("__inline-number__");
+        }
+      } else if (isClosingTag(token)) {
+        const top = skipStack[skipStack.length - 1];
+        if (top === name || (top === "__inline-number__" && name === "span")) {
+          skipStack.pop();
+        }
+      }
+
+      result.push(token);
+      continue;
+    }
+
+    // Text segment — only wrap when not inside a skip context
+    if (skipStack.length > 0) {
+      result.push(token);
+      continue;
+    }
+
+    const wrapped = token.replace(
+      NUMBER_RE,
+      (match, digits: string, offset: number, str: string) => {
+        const num = parseInt(digits, 10);
+        const digitCount = digits.length;
+        const numIsYear = isYear(num);
+
+        // Never wrap year numbers
+        if (numIsYear) {
+          return match;
+        }
+
+        // Skip numbers preceded by an uppercase-letter word + space: "VR 1520", "§ 53"
+        // Look at the text before the match within the current segment
+        const before = str.slice(0, offset);
+        if (/(?:^|\s)(?:[A-ZÄÖܧ]{1,}|[A-ZÄÖÜ][a-zäöü]*[A-ZÄÖÜ]+)\s$/.test(before)) {
+          return match;
+        }
+
+        return `<span class="js-inline-number" data-numeric="${num}" data-duration="${duration}" style="display:inline;min-width:${digitCount}ch">${digits}</span>`;
+      },
+    );
+
+    result.push(wrapped);
+  }
+
+  return result.join("");
+}

package/src/surface/blueprint-schema.ts

@@ -0,0 +1,314 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  [RFC-0193] Zod schema for the Blueprint contract (the declarative surface spec). Co-located with
+  the Blueprint type in @warpgogol/werkstatt-shared/surface to avoid a package cycle (the engine owns its own contract).
+  The Blueprint YAML data files live in packages/werkstatt-site/src/domain/ontology/blueprints/*.yaml; this schema validates
+  them in blueprint.validate and during surface.generate expansion.
+</purpose>
+<non-goals>
+  <item>Do not read files (callers supply parsed YAML objects).</item>
+  <item>Do not cross-check datasets/constellations (blueprint.validate does that).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0193: initial schema.</item>
+  <item>RFC-0496: add serviceSchema (BlueprintServiceConfig) to BlueprintLevel; add linkingParentSchema to linking.</item>
+  <item>RFC-0497: add intersectionSchema (BlueprintIntersectionConfig) to BlueprintLevel.</item>
+  <item>RFC-0500: add hubSchema (BlueprintHubConfig) to BlueprintLevel; add statusGateSchema (BlueprintStatusGate) to policy.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+import type { Blueprint } from "./blueprint.ts";
+
+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),
+});
+
+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(),
+});
+
+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 as Blueprint, errors: [] };
+  }
+  return {
+    ok: false,
+    errors: result.error.issues.map(
+      (issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`,
+    ),
+  };
+}