@warpgogol/werkstatt-shared 0.2.0

package/src/share/legal/translation-policy.ts

@@ -0,0 +1,133 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  [RFC-0174] Binding-language policy resolver for legal documents.
+  Pure functions that turn a page's authored `translation` frontmatter block into
+  a render-time decision: is this the binding-language version, what is the locale's
+  translation status, must the mandatory language notice + "unofficial translation"
+  indicator be shown, and where does the binding document live.
+</purpose>
+<non-goals>
+  <item>Do not read content or the route registry — the binding URL is injected by the caller.</item>
+  <item>Do not render markup — that is @warpgogol/werkstatt-site/ui's translation-notice component.</item>
+  <item>Do not translate copy — the notice component owns localized microcopy.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0174: initial binding-language policy resolver.</item>
+</CHANGE_SUMMARY>
+*/
+
+/** Per-locale translation status for a legal document. */
+export type TranslationStatus = "official" | "unofficial" | "disabled";
+
+export const TRANSLATION_STATUSES: readonly TranslationStatus[] = [
+  "official",
+  "unofficial",
+  "disabled",
+] as const;
+
+/**
+ * Authored `translation` block, declared once in the binding-language page file
+ * (e.g. `pages/de/datenschutz.md`). Lives in the client-editable `pages` surface
+ * (DNA-22) so the client toggles it without engineering.
+ */
+export interface PageTranslationPolicy {
+  /** Legally binding language code for this page (e.g. "de"). */
+  binding: string;
+  /** pageId of the binding document; defaults to the declaring page's id. */
+  bindingPageId?: string;
+  /** Localized display name of the binding document, e.g. "Datenschutzerklärung". */
+  bindingDocLabel?: string;
+  /**
+   * Mandatory language notice. Default true. The validator forbids `false` while
+   * any non-binding locale is `unofficial`.
+   */
+  notice?: boolean;
+  /** Persistent "unofficial translation" indicator. Default true. */
+  indicator?: boolean;
+  /**
+   * Per-locale status. A locale absent here that has a translation file is treated
+   * as "unofficial". The binding language itself is always treated as official.
+   */
+  locales?: Record<string, TranslationStatus>;
+}
+
+/** Render-time decision for the current (lang, pageId). */
+export interface ResolvedTranslationContext {
+  /** Is the current render the binding-language version? */
+  isBinding: boolean;
+  /** Effective status of the current locale. */
+  status: TranslationStatus;
+  /** Binding language code (for dual-language notice copy). */
+  bindingLang: string;
+  /** Localized name of the binding document for the notice link text. */
+  bindingDocLabel?: string;
+  /** Absolute or localized URL of the binding document (notice link + redirect target). */
+  bindingUrl: string;
+  /** Inject the mandatory language-notice banner. */
+  showNotice: boolean;
+  /** Render the persistent "unofficial translation" indicator. */
+  showIndicator: boolean;
+  /**
+   * When set, this locale is `disabled` and the route should redirect to the
+   * binding-language document instead of serving the untrusted translation.
+   */
+  redirectTo?: string;
+}
+
+function normalizeStatus(value: unknown): TranslationStatus | undefined {
+  return TRANSLATION_STATUSES.includes(value as TranslationStatus)
+    ? (value as TranslationStatus)
+    : undefined;
+}
+
+/**
+ * Resolve the binding-language decision for one render.
+ *
+ * Returns `null` when the page declares no `translation.binding` (i.e. it is not a
+ * legal page under policy) — callers then render normally with no notice.
+ *
+ * @param resolveBindingUrl Callback that maps (bindingPageId, bindingLang) to the
+ *        binding document's URL. Injected so this module stays free of the route
+ *        registry / content dependencies.
+ */
+export function resolveTranslationContext(args: {
+  lang: string;
+  pageId: string;
+  policy: PageTranslationPolicy | undefined | null;
+  resolveBindingUrl: (bindingPageId: string, bindingLang: string) => string | null;
+}): ResolvedTranslationContext | null {
+  const { lang, pageId, policy, resolveBindingUrl } = args;
+  if (!policy || typeof policy.binding !== "string" || policy.binding.length === 0) {
+    return null;
+  }
+
+  const bindingLang = policy.binding;
+  const bindingPageId = policy.bindingPageId ?? pageId;
+  const isBinding = lang === bindingLang;
+
+  // The binding-language render is the authoritative text — never gets a notice.
+  const status: TranslationStatus = isBinding
+    ? "official"
+    : (normalizeStatus(policy.locales?.[lang]) ?? "unofficial");
+
+  const bindingUrl = resolveBindingUrl(bindingPageId, bindingLang) ?? "";
+  const noticeEnabled = policy.notice !== false;
+  const indicatorEnabled = policy.indicator !== false;
+
+  const showNotice = !isBinding && status === "unofficial" && noticeEnabled;
+  const showIndicator = !isBinding && status === "unofficial" && indicatorEnabled;
+  const redirectTo = !isBinding && status === "disabled" ? bindingUrl : undefined;
+
+  return {
+    isBinding,
+    status,
+    bindingLang,
+    bindingDocLabel: policy.bindingDocLabel,
+    bindingUrl,
+    showNotice,
+    showIndicator,
+    ...(redirectTo ? { redirectTo } : {}),
+  };
+}

package/src/share/material-credits.ts

@@ -0,0 +1,181 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  RFC-0220 Material Credits helpers shared by UI and Site OS commands. Parses sidecar
+  YAML records, resolves localized/default-language fallback, and builds simple
+  schema.org CreativeWork-style payloads from the same structured source.
+</purpose>
+<non-goals>
+  <item>Do not scan the filesystem; callers supply raw sidecar maps.</item>
+  <item>Do not render UI; @warpgogol/werkstatt-site/ui owns presentation.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0220: initial helper surface for material credit sidecars.</item>
+  <item>RFC-0227: buildMaterialCreditJsonLd emits @id for page-graph linking.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { parse as parseYaml } from "yaml";
+import {
+  type MaterialCredit,
+  type MaterialCreditLabels,
+  type MaterialKind,
+  type MaterialTarget,
+  materialCreditSchema,
+  materialTargetKey,
+  formatMaterialCreditLine,
+} from "./schemas/material-credit.ts";
+
+// RFC-0488: re-export label mapping helpers for @warpgogol/werkstatt-shared/share/material-credits consumers.
+export {
+  labelForSourceType,
+  labelForStatus,
+  labelForUsageBasis,
+} from "./schemas/material-credit.ts";
+export type {
+  MaterialSourceType,
+  MaterialCreditStatus,
+  UsageBasisType,
+} from "./schemas/material-credit.ts";
+
+export interface MaterialCreditRecord {
+  file: string;
+  lang?: string;
+  credit: MaterialCredit;
+}
+
+export type RawMaterialCreditMap = Record<string, string | { default?: string }>;
+
+function rawToString(raw: string | { default?: string }): string {
+  return typeof raw === "string" ? raw : (raw.default ?? "");
+}
+
+export function langFromCreditPath(path: string): string | undefined {
+  const match = path.match(/\/src\/content\/[^/]+\/([^/]+)\//);
+  if (!match) return undefined;
+  const segment = match[1];
+  // RFC-0220: language-agnostic asset folders (surface/assets/, shared/assets/)
+  // carry no lang segment; the sidecar itself is the canonical record.
+  return segment === "assets" || segment === "media" ? undefined : segment;
+}
+
+export function parseMaterialCreditMap(rawMap: RawMaterialCreditMap): MaterialCreditRecord[] {
+  const records: MaterialCreditRecord[] = [];
+  for (const [file, raw] of Object.entries(rawMap)) {
+    const parsed = parseYaml(rawToString(raw));
+    const credit = materialCreditSchema.parse(parsed);
+    records.push({ file, lang: langFromCreditPath(file), credit });
+  }
+  return records;
+}
+
+export function findMaterialCredit(
+  records: MaterialCreditRecord[],
+  target: MaterialTarget,
+  lang: string,
+  defaultLang: string,
+): MaterialCredit | null {
+  const candidates = lang === defaultLang ? [lang, undefined] : [lang, defaultLang, undefined];
+  for (const candidateLang of candidates) {
+    const key = materialTargetKey(target, candidateLang);
+    const record = records.find((item) => {
+      const recordLang = item.credit.target.lang ?? item.lang;
+      return materialTargetKey(item.credit.target, recordLang) === key;
+    });
+    if (record) return record.credit;
+  }
+  return null;
+}
+
+export function creditByTarget(
+  rawMap: RawMaterialCreditMap,
+  target: MaterialTarget,
+  lang: string,
+  defaultLang: string,
+): MaterialCredit | null {
+  return findMaterialCredit(parseMaterialCreditMap(rawMap), target, lang, defaultLang);
+}
+
+export function schemaTypeForMaterial(
+  kind: MaterialKind,
+): "ImageObject" | "VideoObject" | "CreativeWork" {
+  if (kind === "image") return "ImageObject";
+  if (kind === "video") return "VideoObject";
+  return "CreativeWork";
+}
+
+/**
+ * RFC-0227: stable @id for a material credit node, derived from the content URL.
+ * Used by both the disclosure <script> and any page-graph associatedMedia reference.
+ */
+export function materialCreditAtId(contentUrl?: string, targetId?: string): string | undefined {
+  const base = contentUrl ?? (targetId ? `urn:material:${targetId}` : undefined);
+  return base ? `${base}#material` : undefined;
+}
+
+export function buildMaterialCreditJsonLd(
+  credit: MaterialCredit,
+  contentUrl?: string,
+  labels?: MaterialCreditLabels,
+): Record<string, unknown> {
+  const creators = credit.parties.filter(
+    (party) => party.role === "creator" || party.role === "coCreator",
+  );
+  const creator =
+    creators.length === 1
+      ? {
+          "@type": creators[0].kind === "Organization" ? "Organization" : "Person",
+          name: creators[0].name,
+          url: creators[0].url,
+        }
+      : creators.map((party) => ({
+          "@type": party.kind === "Organization" ? "Organization" : "Person",
+          name: party.name,
+          ...(party.url ? { url: party.url } : {}),
+        }));
+
+  const copyrightHolder = resolveCopyrightHolder(credit);
+  const copyrightYear =
+    credit.license.copyrightYear ?? copyrightYearFromNotice(credit.license.copyrightNotice);
+  // RFC-0227: stable @id for page-graph linking.
+  const atId = materialCreditAtId(contentUrl, credit.target.id);
+
+  return {
+    "@type": schemaTypeForMaterial(credit.target.kind),
+    ...(atId ? { "@id": atId } : {}),
+    ...(contentUrl ? { contentUrl } : {}),
+    name: credit.title ?? credit.target.id,
+    ...(labels ? { creditText: formatMaterialCreditLine(credit, labels) } : {}),
+    creator,
+    ...(copyrightHolder ? { copyrightHolder } : {}),
+    ...(copyrightYear ? { copyrightYear } : {}),
+    ...(credit.license.copyrightNotice ? { copyrightNotice: credit.license.copyrightNotice } : {}),
+    // RFC-0223: only emit a URL as schema.org license; the human label stays in creditText.
+    ...(credit.license.url ? { license: credit.license.url } : {}),
+    ...(credit.license.acquireLicensePage
+      ? { acquireLicensePage: credit.license.acquireLicensePage }
+      : {}),
+    ...(credit.createdAt ? { dateCreated: credit.createdAt } : {}),
+  };
+}
+
+function copyrightYearFromNotice(notice?: string): number | undefined {
+  const match = notice?.match(/\b(\d{4})\b/);
+  return match ? Number(match[1]) : undefined;
+}
+
+function resolveCopyrightHolder(credit: MaterialCredit): Record<string, unknown> | undefined {
+  const holder = credit.parties.find((party) => party.role === "rightsHolder");
+  if (holder) {
+    return {
+      "@type": holder.kind === "Person" ? "Person" : "Organization",
+      name: holder.name,
+      ...(holder.url ? { url: holder.url } : {}),
+    };
+  }
+  const fromNotice = credit.license.copyrightNotice
+    ?.match(/©\s*\d{0,4}\s*([^.]+?)\.?\s*(?:All rights|$)/i)?.[1]
+    ?.trim();
+  return fromNotice ? { "@type": "Organization", name: fromNotice } : undefined;
+}

package/src/share/middleware/language-redirect.ts

@@ -0,0 +1,49 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/share/src/middleware/language-redirect.ts as an authored share middleware module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+<!-- @ai-invariant Generated factory output (RFC-0055) flows through system.md i18n config; do not hand-edit app copies. -->
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { defineMiddleware } from "astro:middleware";
+
+/**
+ * Factory for language routing middleware.
+ *
+ * [RFC-0160] The default language is served WITHOUT a URL prefix (`/`,
+ * `/<slug>`), and only non-default languages are prefixed (`/<lang>/…`).
+ * Therefore unprefixed paths ARE default-language content and MUST NOT be
+ * rewritten to `/<defaultLang>/…`. Client-side language detection for the
+ * default audience happens exclusively at `/` (see the root entry page's
+ * soft redirect, RFC-0159).
+ *
+ * This middleware also issues a 308 redirect when the default language is
+ * accessed with its old prefixed URL (`/<defaultLang>/…`), so bookmarks and
+ * search results do not 404. In static-output production this is handled by
+ * the `_redirects` file; the middleware covers dev mode and SSR routes.
+ */
+export function createLanguageRedirectMiddleware(options: {
+  supportedLangs: readonly string[];
+  defaultLang: string;
+}) {
+  return defineMiddleware((ctx: any, next: any) => {
+    const url = new URL(ctx.request.url);
+    const segments = url.pathname.split("/").filter(Boolean);
+    const firstSegment = segments[0];
+
+    // Redirect /<defaultLang>/<rest> → /<rest> with a 308 Permanent Redirect.
+    if (firstSegment === options.defaultLang) {
+      const rest = segments.slice(1).join("/");
+      const target = "/" + (rest ? rest + url.search : url.search);
+      return ctx.redirect(target, 308);
+    }
+
+    return next();
+  });
+}

package/src/share/offer-capacity.ts

@@ -0,0 +1,149 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Pure Offer Capacity Wave calculations for structured offer availability policy.</purpose>
+<non-goals>
+  <item>Do not fetch CRM, browser, or private operational data.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0322: add structured offer capacity wave helper.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface OfferCapacityPolicy {
+  timezone: string;
+  startsAt: string;
+  cadence: "monthly" | "fixed-days";
+  cadenceDays?: number;
+  slotRange: { min: number; max: number };
+  maxSlotsPerWave: number;
+}
+
+export interface OfferCapacityReservation {
+  waveId: string;
+  slots: number;
+  source: "bordbuch" | "manual";
+  asOf: string;
+}
+
+export interface OfferCapacityState {
+  waveId: string;
+  waveIndex: number;
+  startsAt: string;
+  endsAt: string;
+  daysRemaining: number;
+  progress: number;
+  slotRange: { min: number; max: number };
+  maxSlots: number;
+  reservedSlots?: number;
+  openSlots?: number;
+  availabilityStatus: "known" | "unknown" | "full";
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function parseDateOnly(value: string): Date {
+  const match = value.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (!match) throw new Error(`Invalid date-only value: ${value}`);
+  const [, year, month, day] = match;
+  return new Date(Date.UTC(Number(year), Number(month) - 1, Number(day)));
+}
+
+function dateOnly(date: Date, timezone: string): string {
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(date);
+  const get = (type: string) => parts.find((part) => part.type === type)?.value ?? "";
+  return `${get("year")}-${get("month")}-${get("day")}`;
+}
+
+function daysInMonth(year: number, monthIndex: number): number {
+  return new Date(Date.UTC(year, monthIndex + 1, 0)).getUTCDate();
+}
+
+function addMonthsClamped(start: Date, months: number): Date {
+  const year = start.getUTCFullYear();
+  const month = start.getUTCMonth() + months;
+  const targetYear = year + Math.floor(month / 12);
+  const targetMonth = ((month % 12) + 12) % 12;
+  const day = Math.min(start.getUTCDate(), daysInMonth(targetYear, targetMonth));
+  return new Date(Date.UTC(targetYear, targetMonth, day));
+}
+
+function addDays(date: Date, days: number): Date {
+  return new Date(date.getTime() + days * DAY_MS);
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+function monthDistance(from: Date, to: Date): number {
+  return (
+    (to.getUTCFullYear() - from.getUTCFullYear()) * 12 + (to.getUTCMonth() - from.getUTCMonth())
+  );
+}
+
+export function calculateOfferCapacityState(
+  policy: OfferCapacityPolicy,
+  reservations: readonly OfferCapacityReservation[] = [],
+  now: Date = new Date(),
+): OfferCapacityState {
+  const start = parseDateOnly(policy.startsAt);
+  const today = parseDateOnly(dateOnly(now, policy.timezone));
+  let waveIndex = 0;
+  let waveStart = start;
+  let waveEnd: Date;
+
+  if (policy.cadence === "monthly") {
+    waveIndex = Math.max(0, monthDistance(start, today));
+    waveStart = addMonthsClamped(start, waveIndex);
+    if (waveStart > today && waveIndex > 0) {
+      waveIndex -= 1;
+      waveStart = addMonthsClamped(start, waveIndex);
+    }
+    waveEnd = addMonthsClamped(start, waveIndex + 1);
+  } else {
+    const cadenceDays = policy.cadenceDays ?? 0;
+    if (cadenceDays <= 0) throw new Error("fixed-days cadence requires cadenceDays > 0");
+    waveIndex = Math.max(
+      0,
+      Math.floor((today.getTime() - start.getTime()) / (cadenceDays * DAY_MS)),
+    );
+    waveStart = addDays(start, waveIndex * cadenceDays);
+    waveEnd = addDays(waveStart, cadenceDays);
+  }
+
+  const waveId =
+    policy.cadence === "monthly"
+      ? `${waveStart.getUTCFullYear()}-${String(waveStart.getUTCMonth() + 1).padStart(2, "0")}`
+      : `${policy.startsAt}+${waveIndex}`;
+  const duration = Math.max(1, waveEnd.getTime() - waveStart.getTime());
+  const elapsed = clamp(today.getTime() - waveStart.getTime(), 0, duration);
+  const activeReservations = reservations.filter((reservation) => reservation.waveId === waveId);
+  const reservedSlots =
+    activeReservations.length > 0
+      ? activeReservations.reduce((sum, reservation) => sum + reservation.slots, 0)
+      : undefined;
+  const openSlots =
+    reservedSlots === undefined
+      ? undefined
+      : clamp(policy.maxSlotsPerWave - reservedSlots, 0, policy.maxSlotsPerWave);
+
+  return {
+    waveId,
+    waveIndex,
+    startsAt: dateOnly(waveStart, "UTC"),
+    endsAt: dateOnly(waveEnd, "UTC"),
+    daysRemaining: Math.max(0, Math.ceil((waveEnd.getTime() - today.getTime()) / DAY_MS)),
+    progress: Math.round((elapsed / duration) * 100),
+    slotRange: policy.slotRange,
+    maxSlots: policy.maxSlotsPerWave,
+    ...(reservedSlots === undefined ? {} : { reservedSlots }),
+    ...(openSlots === undefined ? {} : { openSlots }),
+    availabilityStatus: openSlots === undefined ? "unknown" : openSlots <= 0 ? "full" : "known",
+  };
+}

package/src/share/onboarding-yaml/index.ts

@@ -0,0 +1,162 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0082 shared parser for RFC-0076-headed onboarding artifacts.
+
+Owns the rule "first YAML document is the RFC-0076 metadata header; last YAML
+document is the artifact payload" so phase validation, audit validators, and
+content-discipline parsers all see the same answer.
+</purpose>
+<non-goals>
+  <item>Do not introduce a generic YAML schema framework — scoped to onboarding RFC-0076 metadata only.</item>
+  <item>Do not read files from disk.</item>
+  <item>Do not own the metadata key set beyond the four declared by RFC-0076.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0082: Introduce shared multi-document YAML helper for onboarding artifacts.</item>
+</CHANGE_SUMMARY>
+*/
+
+import YAML from "yaml";
+import type { ZodType } from "zod";
+
+/**
+ * The four top-level keys that belong to the RFC-0076 metadata header.
+ * Anything else at the top level is part of the artifact payload.
+ */
+export const RFC_METADATA_KEYS = [
+  "phase",
+  "derivedFromInputHash",
+  "generatedAt",
+  "generator",
+] as const;
+
+export type RfcMetadataKey = (typeof RFC_METADATA_KEYS)[number];
+
+/**
+ * The RFC-0076 metadata header that every machine-readable file under
+ * onboarding/.output/<phase>/ MUST carry.
+ *
+ * - `phase` — the onboarding phase that produced the artifact (e.g. "04-author").
+ * - `derivedFromInputHash` — sha256 of the input manifest the artifact was derived from.
+ * - `generatedAt` — ISO 8601 timestamp.
+ * - `generator` — author name, typically "agent" or a command name.
+ */
+export interface RfcMetadataHeader {
+  phase: string;
+  derivedFromInputHash: string;
+  generatedAt: string;
+  generator: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asString(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+function buildHeader(raw: Record<string, unknown>): RfcMetadataHeader | null {
+  const phase = asString(raw["phase"]);
+  const hash = asString(raw["derivedFromInputHash"]);
+  if (phase === null || hash === null) {
+    return null;
+  }
+  return {
+    phase,
+    derivedFromInputHash: hash,
+    generatedAt: asString(raw["generatedAt"]) ?? "",
+    generator: asString(raw["generator"]) ?? "",
+  };
+}
+
+/**
+ * Read the RFC-0076 metadata header from an onboarding YAML artifact.
+ *
+ * Accepts both file shapes:
+ * - **Two-doc file**: first doc is the header, second doc is the payload.
+ * - **Single-doc file**: header keys and payload keys are merged at top level.
+ *
+ * Returns `null` when the source does not contain at minimum `phase` and
+ * `derivedFromInputHash` — callers can treat that as "no RFC-0076 header
+ * present" without inspecting the YAML themselves.
+ */
+export function parseOnboardingArtifactHeader(source: string): RfcMetadataHeader | null {
+  const docs = YAML.parseAllDocuments(source);
+  if (docs.length === 0) return null;
+  const first = docs[0].toJSON();
+  if (!isRecord(first)) return null;
+  return buildHeader(first);
+}
+
+/**
+ * Read the artifact payload from an onboarding YAML artifact and validate
+ * it against the caller-supplied Zod schema.
+ *
+ * Selection rule:
+ * - **Two-doc file** → the LAST document is the payload, returned unchanged
+ *   (schemas can keep `.strict()` because the header lives in a separate doc).
+ * - **Single-doc file** → the document is the payload merged with the header;
+ *   the four RFC_METADATA_KEYS are stripped before validation so `.strict()`
+ *   schemas can still accept the file.
+ *
+ * Throws the Zod validation error on schema mismatch and a plain Error when
+ * the source contains zero documents or more than two documents (the second
+ * case enforces the "exactly header + payload" contract).
+ */
+export function parseOnboardingArtifactPayload<T>(source: string, schema: ZodType<T>): T {
+  const docs = YAML.parseAllDocuments(source);
+  if (docs.length === 0) {
+    throw new Error("parseOnboardingArtifactPayload: source contains no YAML documents.");
+  }
+  if (docs.length > 2) {
+    throw new Error(
+      `parseOnboardingArtifactPayload: expected exactly 1 or 2 YAML documents (RFC-0076 header + payload), found ${docs.length}.`,
+    );
+  }
+
+  let payload: unknown;
+  if (docs.length === 2) {
+    payload = docs[1].toJSON();
+  } else {
+    const merged = docs[0].toJSON();
+    if (isRecord(merged)) {
+      // Strip RFC-0076 metadata keys from the merged single-doc payload, BUT
+      // preserve any key the schema itself declares as a payload field. This
+      // matters most for `generatedAt`, which RFC-0076 carries in the header
+      // and several content-discipline schemas (e.g. contentAtomsFileSchema)
+      // also declare as a strict payload field. Without this carve-out the
+      // strip would erase a legitimate payload value and schema parse would
+      // fail with a confusing "expected string, received undefined" error.
+      const schemaKeys = getSchemaTopLevelKeys(schema);
+      const stripped: Record<string, unknown> = { ...merged };
+      for (const key of RFC_METADATA_KEYS) {
+        if (!schemaKeys.has(key)) {
+          delete stripped[key];
+        }
+      }
+      payload = stripped;
+    } else {
+      payload = merged;
+    }
+  }
+
+  return schema.parse(payload);
+}
+
+/**
+ * Best-effort top-level-key extraction from a Zod schema. Used to decide which
+ * RFC-0076 metadata keys to preserve when stripping a merged single-doc
+ * payload. Returns an empty set when the schema does not expose a `.shape` —
+ * permissive schemas like z.unknown() / z.any() then accept the stripped
+ * payload as-is.
+ */
+function getSchemaTopLevelKeys(schema: ZodType<unknown>): Set<string> {
+  const candidate = schema as unknown as { shape?: Record<string, unknown> };
+  if (candidate.shape && typeof candidate.shape === "object") {
+    return new Set(Object.keys(candidate.shape));
+  }
+  return new Set();
+}