@warpgogol/werkstatt-shared 0.2.0

package/src/share/page.ts

@@ -0,0 +1,351 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Build resolved page models from entry data, executing the block composition
+pipeline for each block defined in a page's content.
+</purpose>
+<non-goals>
+  <item>Do not own content loading or route file dispatch.</item>
+  <item>Do not handle growth, passport, or other cross-cutting concerns
+    (those are wired in the route or layout).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Wave 1 (RFC-0026): Initial creation — ResolvedPage/ResolvedBlock types and buildPage pipeline.</item>
+  <item>Moved SectionProps into shared package for cross-app consumption.</item>
+  <item>RFC-0091: PLANET_IMPORT_PATHS and BLOCK_TYPE_TO_COSMIC_NAME now derived from registry; import from @warpgogol/werkstatt-shared/ontology/archetypes instead of literal constants.</item>
+  <item>RFC-0262: add the optional BuildPageOptions.validateProps dev-time fail-fast hook, called once per resolved shell and content block.</item>
+  <item>RFC-0263: hideSectionNumber injection now keyed off registry-derived roleByCosmicName[planetName] === "hero" instead of the hardcoded UNNUMBERED_HERO_PLANETS literal set (deleted).</item>
+  <item>RFC-0264: relocated SectionProps/SectionPageOverride here from the @warpgogol/werkstatt-shared/share root barrel (its natural domain owner); consumers now import from @warpgogol/werkstatt-shared/share/page.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { RuntimeContext } from "./runtime-context.ts";
+import { evalVisibility, type ResolvedFeatureGraph, EMPTY_FEATURE_GRAPH } from "./visibility.ts";
+import {
+  planetImportPaths as registryPlanetImportPaths,
+  blockTypeToCosmicName as registryBlockTypeToCosmicName,
+  moonImportPaths as registryMoonImportPaths,
+  roleByCosmicName as registryRoleByCosmicName,
+} from "@warpgogol/werkstatt-shared/ontology/archetypes";
+
+// @ai-invariant: PageEntry and BlockEntry shapes MUST stay structurally
+// compatible with @warpgogol/werkstatt-shared/ontology/schemas PageEntrySchema / BlockEntrySchema.
+// Any field change here requires a matching change there and in every
+// system.md pages[] block that references the changed field.
+
+export interface PageEntry {
+  kind: "page";
+  cosmicStar: string;
+  title: string;
+  description: string;
+  lang: string;
+  blocks: BlockEntry[];
+}
+
+export interface BlockEntry {
+  id?: string;
+  type?: string; // CMS-facing archetype slug — validated by page.block.validate
+  use?: string; // PlanetName or MoonName — normalized from type for internal resolution
+  props: Record<string, unknown>;
+  visibility?: import("./visibility.ts").VisibilityExpr;
+  /** Block layer — shell blocks render before content blocks (RFC-0036). */
+  layer?: "shell" | "section";
+}
+
+// ---------------------------------------------------------------------------
+// Shell block types (RFC-0036)
+// ---------------------------------------------------------------------------
+
+export interface ShellBlockConfig {
+  enabled?: boolean;
+  cosmicMoon: string; // MoonName from MoonCatalog
+  pin: string;
+  props?: Record<string, unknown>;
+}
+
+export interface ShellConfig {
+  background?: ShellBlockConfig;
+  header?: ShellBlockConfig;
+  footer?: ShellBlockConfig;
+}
+
+/**
+ * A single block after visibility evaluation and prop validation.
+ * All blocks in ResolvedPage.blocks passed visibility — invisible blocks are dropped.
+ */
+export interface ResolvedBlock {
+  /** Stable kebab-case block id from the content entry (null if not declared). */
+  readonly id: string | null;
+  /** The PlanetName or MoonName identifying this block's archetype. */
+  readonly planetName: string;
+  /**
+   * Stable import path into packages/ui for the component.
+   * Used by the page route to dynamically load the component:
+   *   const sections = import.meta.glob("@warpgogol/werkstatt-site/ui/sections/*")
+   *   const Component = sections[block.componentImportPath]
+   */
+  readonly componentImportPath: string;
+  /** Props already evaluated and ready to spread into the component. */
+  readonly props: Record<string, unknown>;
+  /** The raw visibility expression (retained for attribution / debugging). null if absent. */
+  readonly visibility: import("./visibility.ts").VisibilityExpr | null;
+  /** Block layer — shell blocks are prepended and render before content blocks (RFC-0036). */
+  readonly layer?: "shell" | "section";
+}
+
+/**
+ * A fully resolved page: title/description from the entry, filtered block list,
+ * and the RuntimeContext used during resolution.
+ */
+export interface ResolvedPage {
+  /** The IAU star name identifying this page in the cosmic overlay. */
+  readonly star: string;
+  readonly title: string;
+  readonly description: string;
+  readonly lang: string;
+  /** Blocks that passed visibility evaluation, in document order. */
+  readonly blocks: readonly ResolvedBlock[];
+  /** The RuntimeContext used during resolution — retained for attribution. */
+  readonly ctx: RuntimeContext;
+}
+
+// RFC-0035: Universal Section Props Contract — every resolved content block's
+// props extend this shape. RFC-0264: relocated from the @warpgogol/werkstatt-shared/share root
+// barrel to page.ts (its natural domain owner); re-exported from the `./page`
+// subpath.
+export interface SectionProps {
+  /** Active locale for i18n rendering */
+  lang: string;
+  /** App default locale for RFC-0008 site/content fallback */
+  defaultLanguageCode: string;
+  /** Zero-padded section index (01, 02, ...) for anchors and styling */
+  sectionNumber: string;
+  /** Optional link registry for CTA/link resolution */
+  linkRegistry?: Record<string, string | null>;
+  /** Complete block.props as declared in page frontmatter */
+  pageOverride: Record<string, unknown>;
+  /** RFC-0048: Stable pageId for localized anchor resolution */
+  pageId?: string;
+}
+
+/** Type helper for sections to declare their specific pageOverride shape */
+export type SectionPageOverride<T extends Record<string, unknown>> = SectionProps & {
+  pageOverride: T;
+};
+
+// @ai-invariant: PLANET_IMPORT_PATHS and MOON_IMPORT_PATHS are the single
+// source of truth for cosmicName → import path resolution. Every name added
+// to a manifest MUST also appear in one of these maps (via the archetype
+// registry), and vice versa. Silent mismatches cause
+// "[buildPage] No component import path registered for ..." at runtime.
+// Three-way alignment: manifest.yaml cosmicName ↔ import-paths map ↔ system.md pin.
+
+// Default PlanetName → import path table
+// Derived from the archetype registry via @warpgogol/werkstatt-shared/ontology/archetypes
+// (RFC-0091). The archetype.registry.build command regenerates
+// packages/werkstatt-site/src/domain/ontology/archetypes/index.yaml from manifests.
+// ---------------------------------------------------------------------------
+
+/**
+ * RFC-0091 fallback: entries that cannot be derived from manifests but must
+ * remain registered. Empty since RFC-0175 — Amalthea (formerly a reserved
+ * placeholder mapped to hero) is now claimed by the chat-widget section, so the
+ * registry-derived mapping is authoritative. The registry is spread LAST so a
+ * real manifest mapping always wins over any future placeholder fallback.
+ */
+const PLANET_IMPORT_PATHS_FALLBACK: Record<string, string> = {};
+
+/** @internal */
+export const PLANET_IMPORT_PATHS: Record<string, string> = {
+  ...PLANET_IMPORT_PATHS_FALLBACK,
+  ...registryPlanetImportPaths,
+};
+
+// ---------------------------------------------------------------------------
+// MoonCatalog → import path table (RFC-0036)
+// Components that can be used as shell-level blocks.
+// RFC-0097: derived from the archetype registry just like PLANET_IMPORT_PATHS.
+// `packages/werkstatt-site/src/domain/ontology/archetypes/index.yaml` is regenerated by
+// `archetype.registry.build` from every shell.* manifest under
+// `packages/werkstatt-site/src/domain/ui/components/shell/`. The previous
+// MOON_IMPORT_PATHS_FALLBACK (Hermippe → site-background) was retired by
+// RFC-0108 Proposal D once the registry began discovering the shell archetype
+// directly; the registry is now the single source of truth.
+// ---------------------------------------------------------------------------
+
+/** @internal */
+export const MOON_IMPORT_PATHS: Record<string, string> = {
+  ...registryMoonImportPaths,
+};
+
+/** @internal */
+export const BLOCK_TYPE_TO_COSMIC_NAME: Record<string, string> = registryBlockTypeToCosmicName;
+
+export function normalizeBlockType(block: BlockEntry): string {
+  const selector = block.type ?? block.use;
+  if (!selector) {
+    throw new Error("[buildPage] Block is missing required author-facing `type`.");
+  }
+  return BLOCK_TYPE_TO_COSMIC_NAME[selector] ?? selector;
+}
+
+/**
+ * Resolves a PlanetName to the stable import path of its section component.
+ * Returns null if no mapping is registered.
+ */
+export function resolveComponentPath(planetName: string): string | null {
+  return PLANET_IMPORT_PATHS[planetName] ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// BuildPageOptions
+// ---------------------------------------------------------------------------
+
+export interface BuildPageOptions {
+  /**
+   * Override the default PlanetName → import path resolver.
+   * Useful when the caller can resolve paths from the live uni.registry.yaml.
+   */
+  resolveImportPath?: (planetName: string) => string | null;
+  /**
+   * Provide a resolved feature graph for visibility evaluation.
+   * Defaults to EMPTY_FEATURE_GRAPH (all features enabled) when omitted.
+   */
+  featureGraph?: ResolvedFeatureGraph;
+  /**
+   * Shell-level blocks from system.yaml prepended to content blocks (RFC-0036).
+   * These bypass visibility evaluation and are always included if enabled.
+   */
+  shellBlocks?: ShellBlockConfig[];
+  /**
+   * RFC-0262: dev-only fail-fast prop validation. When supplied, buildPage
+   * calls this once per resolved block (shell and content) with the block's
+   * PlanetName/MoonName, its evaluated props, and its stable block id (null
+   * for shell blocks). A violation should throw — buildPage does not catch
+   * it, matching its existing "never silently drop a block" contract.
+   * page.block.validate (build.check) remains the deploy-time gate; this
+   * hook exists purely so an agent iterating in `astro dev` sees the same
+   * violation immediately instead of only at the next build:check run.
+   */
+  validateProps?: (
+    planetName: string,
+    props: Record<string, unknown>,
+    blockId: string | null,
+  ) => void | Promise<void>;
+}
+
+// @ai-invariant: buildPage is the SINGLE page pipeline (DNA-25). Every page
+// route MUST call it once per locale; no route may hand-assemble block
+// composition. Routes that bypass buildPage fail page.pipeline.contract.
+// buildPage throws on missing import paths — it never silently drops blocks.
+
+/**
+ * The single build-time page pipeline (DNA-25, RFC-0026).
+ *
+ * Call this once per page route, once per locale:
+ * ```ts
+ * const ctx = EMPTY_RUNTIME_CONTEXT(lang);
+ * const page = await buildPage(entry.data, ctx);
+ * ```
+ *
+ * buildPage guarantees:
+ *   - All blocks with `visibility` evaluating false are dropped from ResolvedPage.blocks.
+ *   - All remaining blocks have a non-null componentImportPath.
+ *   - No block is skipped silently due to an error — errors throw.
+ *
+ * Cross-reference checks (star/route coherence, system.yaml pin list,
+ * propsSchema strict validation) run in page.block.validate (build.check),
+ * not inside buildPage. buildPage is intentionally lenient at render time
+ * so that validators provide precise error messages.
+ *
+ * @throws {Error} if a block's `use` has no registered component import path.
+ */
+/**
+ * Combined resolver that checks both PlanetCatalog and MoonCatalog (RFC-0036).
+ * MoonCatalog is checked first for shell-level components.
+ */
+export function resolveComponentPathUnified(name: string): string | null {
+  return MOON_IMPORT_PATHS[name] ?? PLANET_IMPORT_PATHS[name] ?? null;
+}
+
+export async function buildPage(
+  entry: PageEntry,
+  ctx: RuntimeContext,
+  options?: BuildPageOptions,
+): Promise<ResolvedPage> {
+  const resolver = options?.resolveImportPath ?? resolveComponentPathUnified;
+  const featureGraph: ResolvedFeatureGraph = options?.featureGraph ?? EMPTY_FEATURE_GRAPH;
+  const shellBlocks = options?.shellBlocks ?? [];
+
+  const resolvedBlocks: ResolvedBlock[] = [];
+
+  // Process shell blocks first (RFC-0036) — these bypass visibility
+  for (const shellBlock of shellBlocks) {
+    if (shellBlock.enabled === false) continue;
+
+    const componentImportPath = resolver(shellBlock.cosmicMoon);
+    if (componentImportPath === null) {
+      throw new Error(
+        `[buildPage] No component import path registered for moon "${shellBlock.cosmicMoon}". ` +
+          `Register it in MOON_IMPORT_PATHS or supply a custom resolveImportPath option.`,
+      );
+    }
+
+    const shellProps = shellBlock.props ?? {};
+    if (options?.validateProps)
+      await options.validateProps(shellBlock.cosmicMoon, shellProps, null);
+
+    resolvedBlocks.push({
+      id: null,
+      planetName: shellBlock.cosmicMoon,
+      componentImportPath,
+      props: shellProps,
+      visibility: null,
+      layer: "shell",
+    });
+  }
+
+  // Process content blocks with visibility evaluation
+  for (const block of entry.blocks) {
+    // Evaluate visibility — drop blocks that evaluate false
+    const visible = evalVisibility(block.visibility ?? null, ctx, featureGraph);
+    if (!visible) continue;
+
+    // Resolve the component import path
+    const planetName = normalizeBlockType(block);
+    const componentImportPath = resolver(planetName);
+    if (componentImportPath === null) {
+      throw new Error(
+        `[buildPage] No component import path registered for block "${planetName}". ` +
+          `Register it in PLANET_IMPORT_PATHS or supply a custom resolveImportPath option.`,
+      );
+    }
+
+    const contentProps =
+      registryRoleByCosmicName[planetName] === "hero"
+        ? { ...block.props, hideSectionNumber: true }
+        : block.props;
+    if (options?.validateProps) {
+      await options.validateProps(planetName, contentProps, block.id ?? null);
+    }
+
+    resolvedBlocks.push({
+      id: block.id ?? null,
+      planetName,
+      componentImportPath,
+      props: contentProps,
+      visibility: block.visibility ?? null,
+      layer: block.layer ?? "section",
+    });
+  }
+
+  return {
+    star: entry.cosmicStar,
+    title: entry.title,
+    description: entry.description,
+    lang: entry.lang,
+    blocks: resolvedBlocks,
+    ctx,
+  };
+}

package/src/share/redirects.test.ts

@@ -0,0 +1,62 @@
+/*
+<MODULE_CONTRACT>
+  <purpose>RFC-0595: unit tests for extractRedirectTarget helper.</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0595: initial extractRedirectTarget tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect } from "vitest";
+import { extractRedirectTarget, parseRedirectRules } from "./redirects.ts";
+
+test("extractRedirectTarget: extracts url from standard meta-refresh tag", () => {
+  const html = `<html><head><meta http-equiv="refresh" content="0;url=/de/agb"></head><body></body></html>`;
+  expect(extractRedirectTarget(html)).toBe("/de/agb");
+});
+
+test("extractRedirectTarget: extracts url with single quotes", () => {
+  const html = `<html><head><meta http-equiv='refresh' content='0;url=/en/page'></head></html>`;
+  expect(extractRedirectTarget(html)).toBe("/en/page");
+});
+
+test("extractRedirectTarget: extracts absolute URL", () => {
+  const html = `<meta http-equiv="refresh" content="0;url=https://example.com/target">`;
+  expect(extractRedirectTarget(html)).toBe("https://example.com/target");
+});
+
+test("extractRedirectTarget: handles delay before url", () => {
+  const html = `<meta http-equiv="refresh" content="5;url=/delayed">`;
+  expect(extractRedirectTarget(html)).toBe("/delayed");
+});
+
+test("extractRedirectTarget: returns null when no meta-refresh tag", () => {
+  const html = `<html><head><title>Normal page</title></head><body>content</body></html>`;
+  expect(extractRedirectTarget(html)).toBeNull();
+});
+
+test("extractRedirectTarget: returns null for malformed content attribute", () => {
+  const html = `<meta http-equiv="refresh" content="just text no url">`;
+  expect(extractRedirectTarget(html)).toBeNull();
+});
+
+test("extractRedirectTarget: returns null for empty html", () => {
+  expect(extractRedirectTarget("")).toBeNull();
+});
+
+test("parseRedirectRules: still works correctly alongside extractRedirectTarget", () => {
+  const rules = parseRedirectRules("/old /new 301\n/de/* / 308");
+  expect(rules).toHaveLength(2);
+  expect(rules[0].from).toBe("/old");
+  expect(rules[1].from).toBe("/de/*");
+});
+
+test("extractRedirectTarget: returns first hop only (multi-hop scenario)", () => {
+  const html = `<meta http-equiv="refresh" content="0;url=/intermediate">`;
+  expect(extractRedirectTarget(html)).toBe("/intermediate");
+});
+
+test("extractRedirectTarget: handles reversed attribute order (content before http-equiv)", () => {
+  const html = `<meta content="0;url=/target" http-equiv="refresh">`;
+  expect(extractRedirectTarget(html)).toBe("/target");
+});

package/src/share/redirects.ts

@@ -0,0 +1,54 @@
+/*
+<MODULE_CONTRACT>
+<purpose>App-agnostic _redirects file parsing for reuse across site-kernel-checks and site-kernel-handoff (RFC-0588).</purpose>
+<non-goals>
+  <item>Do not handle advanced Cloudflare Pages syntax (query parameters, placeholders) — only whitespace-delimited `from to status` lines.</item>
+  <item>Do not perform glob-to-regex conversion — that is the consumer's responsibility.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0588: extracted parseRedirectRules and RedirectRule from site-kernel-checks/managed-public.ts into @warpgogol/werkstatt-shared/share/redirects subpath.</item>
+  <item>RFC-0595: add extractRedirectTarget helper for parsing url= from meta-refresh tags.</item>
+</CHANGE_SUMMARY>
+*/
+
+export type RedirectRule = {
+  from: string;
+  to: string | undefined;
+  status: number;
+  line: string;
+};
+
+export function parseRedirectRules(body: string): RedirectRule[] {
+  return body
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith("#"))
+    .map((line) => {
+      const [from, to, statusRaw] = line.split(/\s+/);
+      return {
+        from: from ?? "",
+        to,
+        status: Number(statusRaw ?? 301),
+        line,
+      };
+    })
+    .filter((rule) => rule.from.length > 0);
+}
+
+/**
+ * Extract the redirect target URL from a `<meta http-equiv="refresh" content="0;url=...">` tag.
+ * Returns the immediate target only (first hop). Returns null if the tag is
+ * absent or the url= value cannot be parsed.
+ */
+export function extractRedirectTarget(html: string): string | null {
+  const m = html.match(
+    /<meta[^>]+http-equiv=["']refresh["'][^>]*content=["']\s*\d+\s*;\s*url=([^"']+)['"][^>]*>/i,
+  );
+  if (m?.[1]) return m[1].trim();
+  const m2 = html.match(
+    /<meta[^>]+content=["']\s*\d+\s*;\s*url=([^"']+)['"][^>]*http-equiv=["']refresh["'][^>]*>/i,
+  );
+  if (m2?.[1]) return m2[1].trim();
+  return null;
+}

package/src/share/rfc0042-utils.ts

@@ -0,0 +1,95 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0042 shared utilities for section components — NEED_THIS_* markers and type casting.</purpose>
+<non-goals>
+  <item>Do not implement content fetching — RFC-0042 removed stub-based loading.</item>
+  <item>Do not handle i18n logic — lang is passed separately via SectionProps.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0042: Created shared utilities to centralize NEED_THIS_* pattern and type casting.</item>
+</CHANGE_SUMMARY>
+*/
+
+/**
+ * [RFC-0042] Helper for NEED_THIS_* markers — shows explicit placeholder when field is missing.
+ * Use this in section components to indicate required fields that were not provided in blocks[].props.
+ *
+ * @param fieldName - The name of the field (will be uppercased in the marker)
+ * @param value - The value from pageOverride.props
+ * @returns The value if present and non-empty, otherwise `NEED_THIS_${fieldName.toUpperCase()}`
+ *
+ * @example
+ * ```typescript
+ * const content = {
+ *   heading: need("heading", props.heading),
+ *   description: need("description", props.description),
+ * };
+ * ```
+ */
+export function need<T>(fieldName: string, value: T | undefined | null): T | string {
+  if (value === undefined || value === null) {
+    return `NEED_THIS_${fieldName.toUpperCase()}`;
+  }
+  if (typeof value === "string") {
+    return value.trim() !== "" ? value : `NEED_THIS_${fieldName.toUpperCase()}`;
+  }
+  if (Array.isArray(value)) {
+    return value.length > 0 ? value : (`NEED_THIS_${fieldName.toUpperCase()}` as unknown as T);
+  }
+  if (typeof value === "object") {
+    return Object.keys(value as object).length > 0
+      ? value
+      : (`NEED_THIS_${fieldName.toUpperCase()}` as unknown as T);
+  }
+  return value;
+}
+
+/**
+ * [RFC-0042] Type-safe casting function for pageOverride to section content types.
+ * Use this instead of `as unknown as T` to make type casting explicit and searchable.
+ *
+ * @ai-invariant Use this function when casting pageOverride to a specific section content type.
+ *
+ * @param pageOverride - The pageOverride from SectionProps (blocks[].props)
+ * @returns The same object cast to type T
+ *
+ * @example
+ * ```typescript
+ * const props = cast<TeamSectionContent>(pageOverride);
+ * ```
+ */
+export function cast<T extends Record<string, unknown>>(pageOverride: Record<string, unknown>): T {
+  return pageOverride as unknown as T;
+}
+
+/**
+ * [RFC-0042] Default value helper with NEED_THIS_* marker fallback.
+ * Returns the value if present, otherwise returns the provided default or a NEED_THIS marker.
+ *
+ * @param value - The value from pageOverride.props
+ * @param defaultValue - Default value to use if value is missing
+ * @param fieldName - Field name for NEED_THIS marker (only used if defaultValue is not provided)
+ * @returns The value, defaultValue, or NEED_THIS marker
+ *
+ * @example
+ * ```typescript
+ * const content = {
+ *   texture: withDefault(props.texture, false),
+ *   heading: withDefault(props.heading, null, "heading"), // becomes NEED_THIS_HEADING if missing
+ * };
+ * ```
+ */
+export function withDefault<T>(
+  value: T | undefined,
+  defaultValue: T | null,
+  fieldName?: string,
+): T | string {
+  if (value !== undefined && value !== null) {
+    return value;
+  }
+  if (defaultValue !== null) {
+    return defaultValue;
+  }
+  return fieldName ? `NEED_THIS_${fieldName.toUpperCase()}` : "NEED_THIS_VALUE";
+}

package/src/share/runtime-context.ts

@@ -0,0 +1,70 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Defines RuntimeContext — the single context object threaded through the buildPage
+pipeline and every block-level rendering decision (DNA-26, RFC-0026).
+At MVP exactly three fields are present; segment and flags are reserved no-ops that
+become active when RFC-0027 activates the Growth Layer.
+</purpose>
+<non-goals>
+  <item>Do not add new fields without a superseding RFC (RFC-0026 nonGoal).</item>
+  <item>Do not allow non-null segment or non-empty flags at MVP — runtime.context.shape enforces this.</item>
+  <item>Do not add rendering logic here.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Wave 1 (RFC-0026): Initial creation — RuntimeContext shape and EMPTY_RUNTIME_CONTEXT factory.</item>
+</CHANGE_SUMMARY>
+*/
+
+/**
+ * The single context object threaded through the buildPage pipeline.
+ *
+ * At MVP (RFC-0026):
+ *   - `locale`  — the active BCP-47 language code; evaluated by block visibility expressions.
+ *   - `segment` — RESERVED. Always null at MVP. RFC-0027 will populate this from edge-runtime
+ *                 persona detection. Content authors may write `visibility: { segment: "..." }`
+ *                 today; the expression evaluates false until RFC-0027 activates it.
+ *   - `flags`   — RESERVED. Always {} at MVP. RFC-0027 will populate this from feature-flag
+ *                 edge evaluation. Content authors may write `visibility: { flag: "..." }` today;
+ *                 the expression evaluates false until RFC-0027 activates it.
+ *
+ * `runtime.context.shape` verifies that no workspace code constructs a RuntimeContext
+ * with non-null segment or non-empty flags before RFC-0027 supersedes this file.
+ */
+export interface RuntimeContext {
+  /** Active BCP-47 locale (e.g. "de", "en"). Evaluated by { locale: "de" } expressions. */
+  readonly locale: string;
+
+  /**
+   * RESERVED — always null at MVP.
+   * Do NOT construct a RuntimeContext with a non-null segment (violation caught by runtime.context.shape).
+   * RFC-0027 will fill this from an edge-runtime persona-detection result.
+   */
+  readonly segment: string | null;
+
+  /**
+   * RESERVED — always {} at MVP.
+   * Do NOT construct a RuntimeContext with non-empty flags (violation caught by runtime.context.shape).
+   * RFC-0027 will fill this from an edge-runtime feature-flag evaluation result.
+   */
+  readonly flags: Readonly<Record<string, boolean>>;
+}
+
+/**
+ * The only legal way to construct a RuntimeContext at MVP.
+ *
+ * Usage in page routes:
+ * ```ts
+ * import { EMPTY_RUNTIME_CONTEXT } from "@warpgogol/werkstatt-shared/share";
+ * const ctx = EMPTY_RUNTIME_CONTEXT(lang);
+ * const page = await buildPage(entry, ctx);
+ * ```
+ *
+ * @param locale — the active BCP-47 language code from the route params.
+ */
+export const EMPTY_RUNTIME_CONTEXT = (locale: string): RuntimeContext => ({
+  locale,
+  segment: null,
+  flags: Object.freeze({}) as Readonly<Record<string, boolean>>,
+});