@decantr/essence-spec 1.0.8 → 2.0.0

package/README.md

@@ -15,9 +15,9 @@ npm install @decantr/essence-spec
 
 - `validateEssence()` for schema validation
 - `evaluateGuard()` for contract/guard checks
-- `normalizeEssence()` for version normalization
-- `migrateV2ToV3()` and `migrateV30ToV31()` for structured migrations
-- Decantr essence TypeScript types
+- `normalizeEssence()` for active Essence v4 normalization
+- `migrateToV4()` for the explicit legacy migration path
+- Decantr Essence v4 TypeScript types
 
 ## Example
 
@@ -34,12 +34,12 @@ const violations = evaluateGuard(essence, {});
 
 ## Schema Exports
 
-- `@decantr/essence-spec/schema/essence.v2.json`
-- `@decantr/essence-spec/schema/essence.v3.json`
+- `@decantr/essence-spec/schema/essence.v4.json`
+- `@decantr/essence-spec/schema/essence.v2.json` and `essence.v3.json` remain archived references for migration tooling only
 
 ## Compatibility
 
-`@decantr/essence-spec` now defines a stable public contract for Decantr essence validation and migration in the `1.x` line.
+`@decantr/essence-spec` defines the active Essence v4 public contract for Decantr V2. Runtime validation accepts v4 only; older Essence v2/v3 files are supported through `decantr migrate --to v4`.
 
 - additive schema fields may be introduced in compatible minor releases
 - breaking schema or migration behavior changes require a major version

package/dist/index.d.ts

@@ -1,11 +1,9 @@
 /**
- * Essence v2 schema types — normalized terminology.
+ * Essence v4 active contract types.
  *
- * Terminology mapping (v1 wine terms → v2 normalized):
- *   terroir → archetype, vintage → theme, tannins → features,
- *   carafe → shell, cork → guard, blend → layout, clarity → density,
- *   vessel → platform, character → personality,
- *   decantation process → essence pipeline
+ * Decantr V2 treats Essence v4 as the only active runtime contract. Older
+ * Essence v2/v3 document shapes remain modeled only so `decantr migrate --to v4`
+ * can upgrade existing projects.
  */
 type ThemeStyle = 'auradecantism' | 'clean' | 'glassmorphism' | 'retro' | 'bioluminescent' | 'launchpad' | 'dopamine' | 'editorial' | 'liquid-glass' | 'prismatic';
 type ThemeMode = 'light' | 'dark' | 'auto';
@@ -121,7 +119,7 @@ interface Essence {
     accessibility?: Accessibility;
     _impression?: Impression;
 }
-interface EssenceSection {
+interface LegacyEssenceSection {
     id: string;
     path: string;
     archetype: string;
@@ -134,7 +132,7 @@ interface SectionedEssence {
     version: string;
     platform: Platform;
     personality: string[];
-    sections: EssenceSection[];
+    sections: LegacyEssenceSection[];
     shared_features?: string[];
     density: Density;
     guard: Guard;
@@ -220,7 +218,7 @@ interface SectionNavigationItem {
     active_match?: string;
     badge?: string;
 }
-interface EssenceV31Section {
+interface EssenceSection {
     id: string;
     role: ArchetypeRole;
     shell: ShellType | string;
@@ -243,20 +241,21 @@ interface RouteEntry {
 }
 interface EssenceBlueprint {
     shell?: ShellType | string;
-    sections?: EssenceV31Section[];
+    sections: EssenceSection[];
+    /** Migration-only compatibility. Active v4 documents are sectioned-only. */
     pages?: BlueprintPage[];
     features: string[];
     routes?: Record<string, RouteEntry>;
     icon_style?: string;
     avatar_style?: string;
 }
-interface EssenceV3Guard {
+interface EssenceV4Guard {
     mode: GuardMode;
     dna_enforcement: 'error' | 'warn' | 'off';
     blueprint_enforcement: 'warn' | 'off';
     /**
-     * v2.1 C5. Severity for the experiential interactions guard rule (8th
-     * rule). When patterns declare `interactions: [...]` but the source
+     * Severity for the experiential interactions guard rule. When patterns
+     * declare `interactions: [...]` but the source
      * tree is missing the canonical implementations, this controls whether
      * the violation is an error, warning, or ignored.
      *
@@ -269,7 +268,7 @@ interface EssenceMeta {
     archetype: string;
     target: GeneratorTarget;
     platform: Platform;
-    guard: EssenceV3Guard;
+    guard: EssenceV4Guard;
     seo?: {
         schema_org?: string[];
         meta_priorities?: string[];
@@ -315,26 +314,31 @@ interface HotkeySemantics {
     /** If true: hotkey matching is case-sensitive. Default false — uppercase implies Shift. */
     match_case?: boolean;
     /**
-     * v2.1 C3. If true (default): render the .d-hotkey-indicator corner badge
-     * when a chord hotkey prefix is armed. If false: silent chord tracking
-     * (no visual feedback). Recommended true for discoverability.
+     * If true (default): render the .d-hotkey-indicator corner badge when a chord
+     * hotkey prefix is armed. If false: silent chord tracking (no visual feedback).
+     * Recommended true for discoverability.
      */
     show_chord_indicator?: boolean;
 }
-interface EssenceV3 {
+interface EssenceV4 {
     $schema?: string;
-    version: '3.0.0' | '3.1.0';
+    version: '4.0.0';
     dna: EssenceDNA;
     blueprint: EssenceBlueprint;
     meta: EssenceMeta;
     _impression?: Impression;
 }
-type EssenceFile = Essence | SectionedEssence | EssenceV3;
-declare function isV3(essence: EssenceFile): essence is EssenceV3;
+type LegacyEssenceV3 = Omit<EssenceV4, 'version'> & {
+    version: '3.0.0' | '3.1.0';
+};
+type EssenceFile = EssenceV4;
+type LegacyEssenceFile = Essence | SectionedEssence | LegacyEssenceV3 | EssenceV4;
+declare function isV4(essence: unknown): essence is EssenceV4;
+declare function isLegacyV3(essence: unknown): essence is LegacyEssenceV3;
 /** Flatten sections into a flat page list (for guards and backward compat). */
 declare function flattenPages(blueprint: EssenceBlueprint): BlueprintPage[];
-declare function isSectioned(essence: EssenceFile): essence is SectionedEssence;
-declare function isSimple(essence: EssenceFile): essence is Essence;
+declare function isSectioned(essence: unknown): essence is SectionedEssence;
+declare function isSimple(essence: unknown): essence is Essence;
 
 interface SpatialHints {
     density_bias?: number;
@@ -350,7 +354,7 @@ interface AutoFix {
 interface GuardViolation {
     rule: 'theme' | 'structure' | 'layout' | 'density' | 'theme-mode' | 'pattern-exists' | 'accessibility'
     /**
-     * v2.1 C5. Experiential interactions guard rule. Fires when patterns
+     * V4 C5. Experiential interactions guard rule. Fires when patterns
      * declare `interactions: [...]` but the source tree is missing the
      * canonical implementations. Severity controlled by
      * `meta.guard.interactions_enforcement` (defaults: creative=off,
@@ -377,7 +381,7 @@ interface GuardContext {
     patternRegistry?: Map<string, unknown>;
     a11y_issues?: string[];
     /**
-     * v2.1 C5. Pre-computed list of declared interactions whose canonical
+     * V4 C5. Pre-computed list of declared interactions whose canonical
      * implementations are missing from the source tree. Produced by
      * `verifyInteractionsInSource` from @decantr/verifier; passed in here
      * so the guard rule can emit violations without owning the source-scan
@@ -391,15 +395,10 @@ interface GuardContext {
 declare function evaluateGuard(essence: EssenceFile, context?: GuardContext): GuardViolation[];
 
 /**
- * Migrate a v2 EssenceFile to v3 format (DNA/Blueprint/Meta split).
- * If already v3, returns unchanged. SectionedEssence uses first section's theme.
- */
-declare function migrateV2ToV3(essence: EssenceFile): EssenceV3;
-/**
- * Migrate a v3.0 flat-page EssenceV3 to v3.1 sectioned format.
- * If already v3.1 or has blueprint.sections, returns unchanged.
+ * Explicit legacy-to-v4 migration path used by `decantr migrate --to v4`.
+ * Active Decantr V2 commands do not call this implicitly.
  */
-declare function migrateV30ToV31(essence: EssenceV3): EssenceV3;
+declare function migrateToV4(input: unknown): EssenceV4;
 
 declare function normalizeEssence(input: Record<string, unknown>): EssenceFile;
 
@@ -408,5 +407,6 @@ interface ValidationResult {
     errors: string[];
 }
 declare function validateEssence(data: unknown): ValidationResult;
+declare function validateLegacyEssenceForMigration(data: unknown): ValidationResult;
 
-export { type Accessibility, type ArchetypeRole, type AutoFix, type BlueprintPage, type ColumnLayout, type CvdPreference, type DNAOverrides, type Density, type DensityLevel, type Essence, type EssenceBlueprint, type EssenceDNA, type EssenceFile, type EssenceMeta, type EssenceSection, type EssenceV3, type EssenceV31Section, type EssenceV3Guard, type GeneratorTarget, type Guard, type GuardContext, type GuardMode, type GuardViolation, type Impression, type LayoutItem, type PatternRef, type Platform, type PlatformType, type RouteEntry, type RoutingStrategy, type SectionedEssence, type ShellGuidance, type ShellType, type SpatialTokenHints, type SpatialTokens, type StructurePage, type Theme, type ThemeMode, type ThemeShape, type ThemeStyle, type ValidationResult, type WcagLevel, computeDensity, computeSpatialTokens, evaluateGuard, flattenPages, getColumnAlias, getColumnId, getColumnPreset, isSectioned, isSimple, isV3, migrateV2ToV3, migrateV30ToV31, normalizeEssence, validateEssence };
+export { type Accessibility, type ArchetypeRole, type AutoFix, type BlueprintPage, type ColumnLayout, type CvdPreference, type DNAOverrides, type Density, type DensityLevel, type Essence, type EssenceBlueprint, type EssenceDNA, type EssenceFile, type EssenceMeta, type EssenceSection, type EssenceV4, type EssenceV4Guard, type GeneratorTarget, type Guard, type GuardContext, type GuardMode, type GuardViolation, type Impression, type LayoutItem, type LegacyEssenceFile, type LegacyEssenceV3, type PatternRef, type Platform, type PlatformType, type RouteEntry, type RoutingStrategy, type SectionedEssence, type ShellGuidance, type ShellType, type SpatialTokenHints, type SpatialTokens, type StructurePage, type Theme, type ThemeMode, type ThemeShape, type ThemeStyle, type ValidationResult, type WcagLevel, computeDensity, computeSpatialTokens, evaluateGuard, flattenPages, getColumnAlias, getColumnId, getColumnPreset, isLegacyV3, isSectioned, isSimple, isV4, migrateToV4, normalizeEssence, validateEssence, validateLegacyEssenceForMigration };