@decantr/core 1.0.5 → 2.0.0

package/README.md

@@ -15,7 +15,7 @@ npm install @decantr/core
 
 ## Stability
 
-`@decantr/core` is published for advanced package consumers that need low-level execution-pack primitives. It is stable in the `1.x` line for the documented exports in this package, but it is still not the recommended first integration surface for most Decantr adopters.
+`@decantr/core` is published for advanced package consumers that need low-level execution-pack primitives. It is stable in the `2.x` line for the documented exports in this package, but it is still not the recommended first integration surface for most Decantr adopters.
 
 ## What It Exports
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { StructurePage, EssenceFile, EssenceV3 } from '@decantr/essence-spec';
+import { StructurePage, EssenceFile, EssenceV4 } from '@decantr/essence-spec';
 import { Pattern, ResolvedPreset, Theme, ContentResolver } from '@decantr/registry';
 
 type IRNodeType = 'app' | 'shell' | 'page' | 'pattern' | 'grid' | 'nav' | 'store';
@@ -42,7 +42,7 @@ interface IRPatternMeta {
      */
     presetDescription?: string;
     /**
-     * v2.1 Tier C1. Declared runtime interactions from the pattern JSON.
+     * Declared runtime interactions from the pattern JSON.
      * Page-pack renderer surfaces these as a checkbox checklist.
      */
     interactions?: string[];
@@ -92,7 +92,7 @@ interface IRRoute {
     shell: string;
     sectionId?: string;
 }
-/** Which v3 essence layer sourced this node */
+/** Which Essence v4 layer sourced this node */
 type IRLayer = 'dna' | 'blueprint' | 'meta';
 interface IRNode {
     type: IRNodeType;
@@ -100,7 +100,7 @@ interface IRNode {
     children: IRNode[];
     spatial?: IRSpatial;
     meta?: Record<string, unknown>;
-    /** When built from a v3 essence, indicates the originating layer */
+    /** When built from an Essence v4 document, indicates the originating layer */
     layer?: IRLayer;
 }
 interface IRAppNode extends IRNode {
@@ -407,7 +407,7 @@ interface PagePackPattern {
      */
     presetDescription?: string;
     /**
-     * v2.1 Tier C1. Declared interactions from the pattern JSON. Rendered
+     * Declared interactions from the pattern JSON. Rendered
      * as a checkbox checklist so cold LLMs in generation mode see a
      * hard-edged list they can't categorize as "philosophy". Enforced by
      * decantr check --strict (C5 guard rule).
@@ -544,8 +544,8 @@ interface CompileExecutionPackBundleOptions {
 }
 declare function renderExecutionPackMarkdown(pack: ExecutionPackBase<unknown>): string;
 declare function resolvePackAdapter(target: string | undefined, platformType: string | undefined): string;
-declare function listPackSections(essence: EssenceV3): SectionPackInput[];
-declare function listPackPages(essence: EssenceV3): PagePackInput[];
+declare function listPackSections(essence: EssenceV4): SectionPackInput[];
+declare function listPackPages(essence: EssenceV4): PagePackInput[];
 declare function buildScaffoldPack(appNode: IRAppNode, options?: ScaffoldPackBuilderOptions): ScaffoldExecutionPack;
 declare function buildSectionPack(appNode: IRAppNode, input: SectionPackInput, options?: SectionPackBuilderOptions): SectionExecutionPack;
 declare function buildPagePack(appNode: IRAppNode, input: PagePackInput, options?: PagePackBuilderOptions): PageExecutionPack;
@@ -585,6 +585,44 @@ interface PipelineResult {
  */
 declare function runPipeline(essence: EssenceFile, options: PipelineOptions): Promise<PipelineResult>;
 
+type RealizationAdapter = 'react-vite' | 'next-app' | 'generic-web' | string;
+interface RealizationRoute {
+    path: string;
+    sectionId: string;
+    sectionRole: string;
+    pageId: string;
+    shell: string;
+    patterns: string[];
+    states: Array<'empty' | 'loading' | 'error'>;
+}
+interface RealizationMockDataSeed {
+    id: string;
+    source: 'feature' | 'route';
+    shape: Record<string, unknown>;
+}
+interface RealizationInteractionPlaceholder {
+    id: string;
+    kind: 'command-palette' | 'hotkey' | 'auth-mock' | 'route-action';
+    route?: string;
+    label: string;
+}
+interface RealizationPlan {
+    version: '1.0.0';
+    sourceEssenceVersion: '4.0.0';
+    adapter: RealizationAdapter;
+    canRealizeFrameworkCode: boolean;
+    routes: RealizationRoute[];
+    shell: {
+        id: string;
+        theme: string;
+        mode: string;
+    };
+    mockData: RealizationMockDataSeed[];
+    interactions: RealizationInteractionPlaceholder[];
+    unsupportedReason?: string;
+}
+declare function compileRealizationPlan(essence: EssenceV4): RealizationPlan;
+
 interface ResolvedPage {
     page: ResolvedStructurePage;
     patterns: Map<string, {
@@ -609,8 +647,8 @@ interface ResolvedEssence {
     shell: IRShellConfig;
     routes: IRRoute[];
     features: string[];
-    /** True when the source essence was v3 (DNA/Blueprint/Meta) */
-    isV3Source: boolean;
+    /** True when the source essence uses the active DNA/Blueprint/Meta contract. */
+    isBlueprintSource: boolean;
 }
 declare function resolveVisualEffects(theme: Theme, pattern: Pattern, _slot?: string): IRVisualEffect | null;
 /** Resolve all external references in an Essence file */
@@ -619,4 +657,4 @@ declare function resolveEssence(essence: EssenceFile, resolver: ContentResolver)
 /** Convert a kebab-case or snake_case string to PascalCase */
 declare function pascalCase(str: string): string;
 
-export { type CompileExecutionPackBundleOptions, EXECUTION_PACK_BUNDLE_SCHEMA_URL, EXECUTION_PACK_SCHEMA_URLS, type ExecutionPackAntiPattern, type ExecutionPackBase, type ExecutionPackBundle, type ExecutionPackExample, type ExecutionPackManifest, type ExecutionPackScope, type ExecutionPackSelector, type ExecutionPackSuccessCheck, type ExecutionPackTarget, type ExecutionPackTokenBudget, type ExecutionPackType, type IRAppNode, type IRBreakpointEntry, type IRCardWrapping, type IRGridNode, type IRHookType, type IRLayer, type IRNavItem, type IRNode, type IRNodeType, type IRPageNode, type IRPatternMeta, type IRPatternNode, type IRRoute, type IRShellConfig, type IRShellNode, type IRSpatial, type IRStoreNode, type IRTheme, type IRThemeDecoration, type IRVisualEffect, type IRWiring, type IRWiringSignal, type MutationExecutionPack, type MutationPackBuilderOptions, type MutationPackData, type MutationPackKind, PACK_MANIFEST_SCHEMA_URL, type PackManifestEntry, type PackManifestMutationEntry, type PackManifestPageEntry, type PackManifestSectionEntry, type PageExecutionPack, type PagePackBuilderOptions, type PagePackData, type PagePackInput, type PagePackPattern, type PipelineOptions, type PipelineResult, type ResolvedEssence, type ResolvedPage, type ReviewExecutionPack, type ReviewPackBuilderOptions, type ReviewPackData, type ReviewPackKind, SELECTED_EXECUTION_PACK_SCHEMA_URL, type ScaffoldExecutionPack, type ScaffoldPackBuilderOptions, type ScaffoldPackData, type ScaffoldPackRoute, type SectionExecutionPack, type SectionPackBuilderOptions, type SectionPackData, type SectionPackInput, type SectionPackRoute, type SelectedExecutionPack, type SelectedExecutionPackResponse, buildMutationPack, buildPageIR, buildPagePack, buildReviewPack, buildScaffoldPack, buildSectionPack, compileExecutionPackBundle, compileSelectedExecutionPack, countPatterns, findNodes, listPackPages, listPackSections, pascalCase, renderExecutionPackMarkdown, resolveEssence, resolvePackAdapter, resolveVisualEffects, runPipeline, selectExecutionPackFromBundle, validateIR, walkIR };
+export { type CompileExecutionPackBundleOptions, EXECUTION_PACK_BUNDLE_SCHEMA_URL, EXECUTION_PACK_SCHEMA_URLS, type ExecutionPackAntiPattern, type ExecutionPackBase, type ExecutionPackBundle, type ExecutionPackExample, type ExecutionPackManifest, type ExecutionPackScope, type ExecutionPackSelector, type ExecutionPackSuccessCheck, type ExecutionPackTarget, type ExecutionPackTokenBudget, type ExecutionPackType, type IRAppNode, type IRBreakpointEntry, type IRCardWrapping, type IRGridNode, type IRHookType, type IRLayer, type IRNavItem, type IRNode, type IRNodeType, type IRPageNode, type IRPatternMeta, type IRPatternNode, type IRRoute, type IRShellConfig, type IRShellNode, type IRSpatial, type IRStoreNode, type IRTheme, type IRThemeDecoration, type IRVisualEffect, type IRWiring, type IRWiringSignal, type MutationExecutionPack, type MutationPackBuilderOptions, type MutationPackData, type MutationPackKind, PACK_MANIFEST_SCHEMA_URL, type PackManifestEntry, type PackManifestMutationEntry, type PackManifestPageEntry, type PackManifestSectionEntry, type PageExecutionPack, type PagePackBuilderOptions, type PagePackData, type PagePackInput, type PagePackPattern, type PipelineOptions, type PipelineResult, type RealizationAdapter, type RealizationInteractionPlaceholder, type RealizationMockDataSeed, type RealizationPlan, type RealizationRoute, type ResolvedEssence, type ResolvedPage, type ReviewExecutionPack, type ReviewPackBuilderOptions, type ReviewPackData, type ReviewPackKind, SELECTED_EXECUTION_PACK_SCHEMA_URL, type ScaffoldExecutionPack, type ScaffoldPackBuilderOptions, type ScaffoldPackData, type ScaffoldPackRoute, type SectionExecutionPack, type SectionPackBuilderOptions, type SectionPackData, type SectionPackInput, type SectionPackRoute, type SelectedExecutionPack, type SelectedExecutionPackResponse, buildMutationPack, buildPageIR, buildPagePack, buildReviewPack, buildScaffoldPack, buildSectionPack, compileExecutionPackBundle, compileRealizationPlan, compileSelectedExecutionPack, countPatterns, findNodes, listPackPages, listPackSections, pascalCase, renderExecutionPackMarkdown, resolveEssence, resolvePackAdapter, resolveVisualEffects, runPipeline, selectExecutionPackFromBundle, validateIR, walkIR };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/resolve.ts
-import { computeDensity, isSectioned, isSimple, isV3 } from "@decantr/essence-spec";
+import { computeDensity, isV4 } from "@decantr/essence-spec";
 import { detectWirings, resolvePatternPreset } from "@decantr/registry";
 
 // src/utils.ts
@@ -115,15 +115,7 @@ function buildThemeDecoration(theme) {
     dimensions: shell.dimensions || null
   };
 }
-function buildTheme(essence, isAddon) {
-  return {
-    id: essence.theme.id,
-    mode: essence.theme.mode,
-    shape: essence.theme.shape || null,
-    isAddon
-  };
-}
-function buildThemeFromV3(essence, isAddon) {
+function buildThemeFromV4(essence, isAddon) {
   const dna = essence.dna;
   return {
     id: dna.theme.id,
@@ -145,7 +137,7 @@ function blueprintPageToStructurePage(page, defaultShell, sectionId) {
 function routeIdentity(pageId, sectionId) {
   return sectionId ? `${sectionId}:${pageId}` : pageId;
 }
-function buildV3Routes(essence, structurePages) {
+function buildV4Routes(essence, structurePages) {
   const explicitRoutes = /* @__PURE__ */ new Map();
   for (const [path, entry] of Object.entries(essence.blueprint.routes ?? {})) {
     if (!entry?.page) continue;
@@ -230,81 +222,14 @@ function resolveVisualEffects(theme, pattern, _slot) {
   };
 }
 async function resolveEssence(essence, resolver) {
-  if (isV3(essence)) {
-    return resolveV3Essence(essence, resolver);
-  }
-  let simpleEssence;
-  if (isSimple(essence)) {
-    simpleEssence = essence;
-  } else if (isSectioned(essence)) {
-    const sectioned = essence;
-    if (sectioned.sections.length > 1) {
-      throw new Error(
-        `Sectioned essences with ${sectioned.sections.length} sections are not yet supported. Only single-section sectioned essences can be processed. Consider migrating to v3 format using migrateV2ToV3().`
-      );
-    }
-    const firstSection = sectioned.sections[0];
-    simpleEssence = {
-      version: sectioned.version,
-      archetype: firstSection.archetype,
-      theme: firstSection.theme,
-      personality: sectioned.personality,
-      platform: sectioned.platform,
-      structure: firstSection.structure,
-      features: firstSection.features || [],
-      density: sectioned.density,
-      guard: sectioned.guard,
-      target: sectioned.target
-    };
-  } else {
-    throw new Error("Invalid essence format");
-  }
-  let registryTheme = null;
-  const themeResult = await resolver.resolve("theme", simpleEssence.theme.id);
-  if (themeResult) {
-    registryTheme = themeResult.item;
+  if (!isV4(essence)) {
+    throw new Error(
+      "Active Decantr V2 workflows require Essence v4.0.0. Run `decantr migrate --to v4` for older essence files."
+    );
   }
-  const themeSpatial = registryTheme?.spatial;
-  const density = computeDensity(
-    simpleEssence.personality,
-    themeSpatial ? {
-      density_bias: themeSpatial.density_bias,
-      content_gap_shift: themeSpatial.content_gap_shift
-    } : void 0
-  );
-  const themeId = simpleEssence.theme.id;
-  const isAddon = themeId.startsWith("custom:") || !CORE_STYLES.has(themeId);
-  const theme = buildTheme(simpleEssence, isAddon);
-  const resolvedPages = await resolvePages(simpleEssence.structure, resolver, registryTheme);
-  const shellType = simpleEssence.structure[0]?.shell || "sidebar-main";
-  const brand = pascalCase(simpleEssence.archetype);
-  const nav = buildNavItems(simpleEssence.structure);
-  const decoration = registryTheme ? buildThemeDecoration(registryTheme) : null;
-  const shell = {
-    type: shellType,
-    brand,
-    nav,
-    inset: false,
-    decoration
-  };
-  const routes = simpleEssence.structure.map((page, i) => ({
-    path: routePath(page.id, i),
-    pageId: page.id,
-    shell: page.shell
-  }));
-  return {
-    essence,
-    pages: resolvedPages,
-    registryTheme,
-    density: { gap: density.content_gap, level: density.level },
-    theme,
-    shell,
-    routes,
-    features: simpleEssence.features ?? [],
-    isV3Source: false
-  };
+  return resolveV4Essence(essence, resolver);
 }
-async function resolveV3Essence(essence, resolver) {
+async function resolveV4Essence(essence, resolver) {
   const { dna, blueprint, meta } = essence;
   let registryTheme = null;
   const themeResult = await resolver.resolve("theme", dna.theme.id);
@@ -325,22 +250,17 @@ async function resolveV3Essence(essence, resolver) {
   };
   const themeId = dna.theme.id;
   const isAddon = themeId.startsWith("custom:") || !CORE_STYLES.has(themeId);
-  const theme = buildThemeFromV3(essence, isAddon);
-  const defaultShell = blueprint.shell ?? blueprint.sections?.[0]?.shell ?? "sidebar-main";
-  const structurePages = blueprint.pages ? blueprint.pages.map((page) => blueprintPageToStructurePage(page, defaultShell)) : blueprint.sections ? blueprint.sections.flatMap(
+  const theme = buildThemeFromV4(essence, isAddon);
+  const defaultShell = blueprint.shell ?? blueprint.sections[0]?.shell ?? "sidebar-main";
+  const structurePages = blueprint.sections.flatMap(
     (section) => section.pages.map(
       (page) => blueprintPageToStructurePage(page, section.shell ?? defaultShell, section.id)
     )
-  ) : [
-    blueprintPageToStructurePage(
-      { id: "home", layout: ["hero"] },
-      defaultShell
-    )
-  ];
+  );
   const resolvedPages = await resolvePages(structurePages, resolver, registryTheme);
   const shellType = defaultShell;
   const brand = pascalCase(meta.archetype);
-  const routes = buildV3Routes(essence, structurePages);
+  const routes = buildV4Routes(essence, structurePages);
   const nav = buildNavItems(structurePages, routes);
   const decoration = registryTheme ? buildThemeDecoration(registryTheme) : null;
   const shell = {
@@ -359,7 +279,7 @@ async function resolveV3Essence(essence, resolver) {
     shell,
     routes,
     features: blueprint.features ?? [],
-    isV3Source: true
+    isBlueprintSource: true
   };
 }
 async function resolvePages(pages, resolver, registryTheme) {
@@ -558,23 +478,19 @@ function validateIR(root) {
 }
 
 // src/packs.ts
-import { isV3 as isV33, migrateV2ToV3 as migrateV2ToV32 } from "@decantr/essence-spec";
+import { isV4 as isV42 } from "@decantr/essence-spec";
 
 // src/pipeline.ts
-import { isV3 as isV32, migrateV2ToV3, validateEssence } from "@decantr/essence-spec";
+import { validateEssence } from "@decantr/essence-spec";
 import { createResolver } from "@decantr/registry";
 function extractRouting(essence) {
-  if (isV32(essence)) {
-    return essence.meta.platform.routing || "history";
-  }
-  return essence.platform?.routing || "history";
+  return essence.meta.platform.routing || "history";
 }
 async function runPipeline(essence, options) {
   const validation = validateEssence(essence);
   if (!validation.valid) {
     throw new Error(`Invalid essence: ${validation.errors.join(", ")}`);
   }
-  const effectiveEssence = isV32(essence) ? essence : migrateV2ToV3(essence);
   const resolver = options.resolver ?? (() => {
     if (!options.contentRoot) {
       throw new Error("Pipeline options must include either a contentRoot or a resolver.");
@@ -584,8 +500,8 @@ async function runPipeline(essence, options) {
       overridePaths: options.overridePaths
     });
   })();
-  const resolved = await resolveEssence(effectiveEssence, resolver);
-  const layer = resolved.isV3Source ? "blueprint" : void 0;
+  const resolved = await resolveEssence(essence, resolver);
+  const layer = "blueprint";
   const pageNodes = [];
   for (const rp of resolved.pages) {
     const pageIR = buildPageIR(
@@ -779,13 +695,13 @@ var DEFAULT_REVIEW_ANTI_PATTERNS = [
   }
 ];
 function collectPatternIds(page) {
-  const patternIds = [];
+  const patternIds2 = [];
   walkIR(page, (node) => {
     if (node.type !== "pattern") return;
     const patternNode = node;
-    patternIds.push(patternNode.pattern.patternId);
+    patternIds2.push(patternNode.pattern.patternId);
   });
-  return [...new Set(patternIds)];
+  return [...new Set(patternIds2)];
 }
 function pageIdentity(pageId, sectionId) {
   return sectionId ? `${sectionId}/${pageId}` : pageId;
@@ -882,6 +798,16 @@ function routingImplementationHint(routing) {
 }
 function renderExecutionPackMarkdown(pack) {
   const lines = [];
+  const escapeMarkdownCell = (value) => {
+    let escaped = "";
+    for (const char of value) {
+      if (char === "\\") escaped += "\\\\";
+      else if (char === "|") escaped += "\\|";
+      else if (char === "\n" || char === "\r") escaped += "<br>";
+      else escaped += char;
+    }
+    return escaped;
+  };
   lines.push(`# ${pack.packType.charAt(0).toUpperCase()}${pack.packType.slice(1)} Pack`);
   lines.push("");
   lines.push(`**Objective:** ${pack.objective}`);
@@ -960,7 +886,6 @@ function renderExecutionPackMarkdown(pack) {
     }
     lines.push("");
     if (scaffoldPack.data.themeDecorators && scaffoldPack.data.themeDecorators.length > 0) {
-      const escScaffoldCell = (s) => s.replace(/\|/g, "\\|");
       lines.push(`## Required Theme Decorators (${scaffoldPack.data.theme.id})`);
       lines.push("");
       lines.push(
@@ -971,7 +896,7 @@ function renderExecutionPackMarkdown(pack) {
       lines.push("|-------|--------|----------|");
       for (const entry of scaffoldPack.data.themeDecorators) {
         lines.push(
-          `| \`.${entry.class}\` | ${escScaffoldCell(entry.intent)} | ${escScaffoldCell(entry.applyTo)} |`
+          `| \`.${entry.class}\` | ${escapeMarkdownCell(entry.intent)} | ${escapeMarkdownCell(entry.applyTo)} |`
         );
       }
       lines.push("");
@@ -1029,7 +954,6 @@ function renderExecutionPackMarkdown(pack) {
       lines.push("");
     }
     if (sectionPack.data.themeDecorators && sectionPack.data.themeDecorators.length > 0) {
-      const escCell = (s) => s.replace(/\|/g, "\\|");
       lines.push(`## Required Theme Decorators (${sectionPack.data.theme.id})`);
       lines.push("");
       lines.push(
@@ -1040,7 +964,7 @@ function renderExecutionPackMarkdown(pack) {
       lines.push("|-------|--------|----------|");
       for (const entry of sectionPack.data.themeDecorators) {
         lines.push(
-          `| \`.${entry.class}\` | ${escCell(entry.intent)} | ${escCell(entry.applyTo)} |`
+          `| \`.${entry.class}\` | ${escapeMarkdownCell(entry.intent)} | ${escapeMarkdownCell(entry.applyTo)} |`
         );
       }
       lines.push("");
@@ -1080,7 +1004,9 @@ function renderExecutionPackMarkdown(pack) {
         lines.push(`  > ${pattern.presetDescription}`);
       }
       if (pattern.interactions && pattern.interactions.length > 0) {
-        lines.push(`  **Interactions (MUST implement each \u2014 see DECANTR.md "Interaction Requirements"):**`);
+        lines.push(
+          `  **Interactions (MUST implement each \u2014 see DECANTR.md "Interaction Requirements"):**`
+        );
         for (const interaction of pattern.interactions) {
           lines.push(`  - [ ] ${interaction}`);
         }
@@ -1225,70 +1151,42 @@ function resolvePackAdapter(target, platformType) {
 }
 function listPackSections(essence) {
   const declaredSections = essence.blueprint.sections;
-  if (declaredSections && declaredSections.length > 0) {
-    const routedSectionPages = new Set(
-      Object.values(essence.blueprint.routes ?? {}).map(
-        (entry) => `${entry.section}:${entry.page}`
-      )
-    );
-    return declaredSections.map((section) => {
-      const pageIds = section.pages.filter(
-        (page) => routedSectionPages.size === 0 || routedSectionPages.has(`${section.id}:${page.id}`)
-      ).map((page) => page.id);
-      return {
-        id: section.id,
-        role: section.role,
-        shell: section.shell,
-        description: section.description,
-        features: section.features,
-        pageIds,
-        ...Array.isArray(section.navigation_items) && section.navigation_items.length > 0 ? { navigationItems: section.navigation_items } : {},
-        ...Array.isArray(section.directives) && section.directives.length > 0 ? { directives: section.directives } : {}
-      };
-    }).filter((section) => section.pageIds.length > 0);
-  }
-  const pages = essence.blueprint.pages ?? [{ id: "home", layout: ["hero"] }];
-  return [
-    {
-      id: essence.meta.archetype || "default",
-      role: "primary",
-      shell: essence.blueprint.shell ?? "sidebar-main",
-      description: `${essence.meta.archetype || "Application"} section`,
-      features: essence.blueprint.features || [],
-      pageIds: pages.map((page) => page.id)
-    }
-  ];
+  const routedSectionPages = new Set(
+    Object.values(essence.blueprint.routes ?? {}).map((entry) => `${entry.section}:${entry.page}`)
+  );
+  return declaredSections.map((section) => {
+    const pageIds = section.pages.filter(
+      (page) => routedSectionPages.size === 0 || routedSectionPages.has(`${section.id}:${page.id}`)
+    ).map((page) => page.id);
+    return {
+      id: section.id,
+      role: section.role,
+      shell: section.shell,
+      description: section.description,
+      features: section.features,
+      pageIds,
+      ...Array.isArray(section.navigation_items) && section.navigation_items.length > 0 ? { navigationItems: section.navigation_items } : {},
+      ...Array.isArray(section.directives) && section.directives.length > 0 ? { directives: section.directives } : {}
+    };
+  }).filter((section) => section.pageIds.length > 0);
 }
 function listPackPages(essence) {
   const declaredSections = essence.blueprint.sections;
-  if (declaredSections && declaredSections.length > 0) {
-    const routedSectionPages = new Set(
-      Object.values(essence.blueprint.routes ?? {}).map(
-        (entry) => `${entry.section}:${entry.page}`
-      )
-    );
-    return declaredSections.flatMap(
-      (section) => section.pages.map((page) => ({
-        pageId: page.id,
-        shell: page.shell_override ?? section.shell,
-        sectionId: section.id,
-        sectionRole: section.role,
-        features: section.features,
-        ...Array.isArray(page.directives) && page.directives.length > 0 ? { directives: page.directives } : {}
-      })).filter(
-        (page) => routedSectionPages.size === 0 || routedSectionPages.has(`${page.sectionId}:${page.pageId}`)
-      )
-    );
-  }
-  const pages = essence.blueprint.pages ?? [{ id: "home", layout: ["hero"] }];
-  const defaultShell = essence.blueprint.shell ?? "sidebar-main";
-  return pages.map((page) => ({
-    pageId: page.id,
-    shell: page.shell_override ?? defaultShell,
-    sectionId: essence.meta.archetype || "default",
-    sectionRole: "primary",
-    features: essence.blueprint.features || []
-  }));
+  const routedSectionPages = new Set(
+    Object.values(essence.blueprint.routes ?? {}).map((entry) => `${entry.section}:${entry.page}`)
+  );
+  return declaredSections.flatMap(
+    (section) => section.pages.map((page) => ({
+      pageId: page.id,
+      shell: page.shell_override ?? section.shell,
+      sectionId: section.id,
+      sectionRole: section.role,
+      features: section.features,
+      ...Array.isArray(page.directives) && page.directives.length > 0 ? { directives: page.directives } : {}
+    })).filter(
+      (page) => routedSectionPages.size === 0 || routedSectionPages.has(`${page.sectionId}:${page.pageId}`)
+    )
+  );
 }
 function buildPageManifestEntries(pages) {
   const counts = /* @__PURE__ */ new Map();
@@ -1618,19 +1516,23 @@ function buildReviewPack(appNode, options = {}) {
   return pack;
 }
 async function compileExecutionPackBundle(essence, options = {}) {
-  const effectiveEssence = isV33(essence) ? essence : migrateV2ToV32(essence);
+  if (!isV42(essence)) {
+    throw new Error(
+      "Active Decantr V2 workflows require Essence v4.0.0. Run `decantr migrate --to v4` for older essence files."
+    );
+  }
   const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
   const sharedTarget = {
-    framework: effectiveEssence.meta.target || null,
-    runtime: effectiveEssence.meta.platform.type || null,
-    adapter: resolvePackAdapter(effectiveEssence.meta.target, effectiveEssence.meta.platform.type)
+    framework: essence.meta.target || null,
+    runtime: essence.meta.platform.type || null,
+    adapter: resolvePackAdapter(essence.meta.target, essence.meta.platform.type)
   };
   const pipeline = await runPipeline(essence, {
     contentRoot: options.contentRoot,
     overridePaths: options.overridePaths,
     resolver: options.resolver
   });
-  const navMeta = effectiveEssence.meta.navigation;
+  const navMeta = essence.meta.navigation;
   const commandPaletteValue = typeof navMeta?.command_palette === "object" && navMeta.command_palette !== null ? navMeta.command_palette : Boolean(navMeta?.command_palette);
   const themeDecorators = (() => {
     const defs = pipeline.registryTheme?.decorator_definitions;
@@ -1665,8 +1567,8 @@ async function compileExecutionPackBundle(essence, options = {}) {
   const review = buildReviewPack(pipeline.ir, {
     target: sharedTarget
   });
-  const sectionInputs = listPackSections(effectiveEssence);
-  const pageInputs = listPackPages(effectiveEssence);
+  const sectionInputs = listPackSections(essence);
+  const pageInputs = listPackPages(essence);
   const sections = sectionInputs.map(
     (section) => buildSectionPack(pipeline.ir, section, {
       target: sharedTarget
@@ -1773,6 +1675,106 @@ async function compileSelectedExecutionPack(essence, selector, options = {}) {
   const bundle = await compileExecutionPackBundle(essence, options);
   return selectExecutionPackFromBundle(bundle, selector);
 }
+
+// src/realization.ts
+import { isV4 as isV43 } from "@decantr/essence-spec";
+var CERTIFIED_REALIZATION_ADAPTERS = /* @__PURE__ */ new Set(["react-vite", "next-app"]);
+function routePath2(page, fallbackIndex) {
+  if (page.route) return page.route;
+  if (page.id === "home" || fallbackIndex === 0) return "/";
+  return `/${page.id}`;
+}
+function patternIds(layout) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const item of layout) {
+    if (typeof item === "string") {
+      ids.add(item);
+    } else if ("pattern" in item) {
+      ids.add(item.pattern);
+    } else if ("cols" in item) {
+      for (const col of item.cols) {
+        ids.add(typeof col === "string" ? col : col.pattern);
+      }
+    }
+  }
+  return [...ids];
+}
+function compileRealizationPlan(essence) {
+  if (!isV43(essence)) {
+    throw new Error(
+      "Active Decantr V2 workflows require Essence v4.0.0. Run `decantr migrate --to v4` for older essence files."
+    );
+  }
+  const packAdapter = resolvePackAdapter(essence.meta.target, essence.meta.platform.type);
+  const adapter = essence.meta.target === "nextjs" ? "next-app" : packAdapter;
+  const canRealizeFrameworkCode = CERTIFIED_REALIZATION_ADAPTERS.has(adapter);
+  const routes = [];
+  for (const section of essence.blueprint.sections) {
+    section.pages.forEach((page, pageIndex) => {
+      routes.push({
+        path: routePath2(page, routes.length + pageIndex),
+        sectionId: section.id,
+        sectionRole: section.role,
+        pageId: page.id,
+        shell: page.shell_override ?? section.shell,
+        patterns: patternIds(page.layout),
+        states: ["empty", "loading", "error"]
+      });
+    });
+  }
+  const mockData = [
+    ...essence.blueprint.features.map((feature) => ({
+      id: feature,
+      source: "feature",
+      shape: { enabled: true, status: "mocked" }
+    })),
+    ...routes.map((route) => ({
+      id: route.pageId,
+      source: "route",
+      shape: { title: route.pageId, items: [] }
+    }))
+  ];
+  const navigation = essence.meta.navigation;
+  const interactions = [
+    {
+      id: "auth-mock",
+      kind: "auth-mock",
+      label: "Authenticated user/session placeholder"
+    }
+  ];
+  if (navigation?.command_palette) {
+    interactions.push({
+      id: "command-palette",
+      kind: "command-palette",
+      label: "Command palette placeholder"
+    });
+  }
+  for (const hotkey of navigation?.hotkeys ?? []) {
+    interactions.push({
+      id: `hotkey-${hotkey.key}`,
+      kind: "hotkey",
+      route: hotkey.route,
+      label: hotkey.label
+    });
+  }
+  return {
+    version: "1.0.0",
+    sourceEssenceVersion: "4.0.0",
+    adapter,
+    canRealizeFrameworkCode,
+    routes,
+    shell: {
+      id: essence.blueprint.shell ?? essence.blueprint.sections[0]?.shell ?? "sidebar-main",
+      theme: essence.dna.theme.id,
+      mode: essence.dna.theme.mode
+    },
+    mockData,
+    interactions,
+    ...canRealizeFrameworkCode ? {} : {
+      unsupportedReason: "No certified realization adapter is available for this target yet. Use the V4 contract, execution packs, prompts, and Project Health without generated framework code."
+    }
+  };
+}
 export {
   EXECUTION_PACK_BUNDLE_SCHEMA_URL,
   EXECUTION_PACK_SCHEMA_URLS,
@@ -1785,6 +1787,7 @@ export {
   buildScaffoldPack,
   buildSectionPack,
   compileExecutionPackBundle,
+  compileRealizationPlan,
   compileSelectedExecutionPack,
   countPatterns,
   findNodes,