@holoscript/core 8.0.8 → 8.0.10

package/dist/parser/HoloCompositionTypes.d.ts

@@ -0,0 +1,2013 @@
+/**
+ * .holo Composition AST Types
+ *
+ * Type definitions for the declarative .holo format.
+ * This is a scene-centric language designed for AI agents and visual tools.
+ *
+ * @version 1.0.0
+ */
+import type { ProvenanceContext } from '../compiler/traits/ProvenanceSemiring';
+export interface SourceLocation {
+    line: number;
+    column: number;
+    offset?: number;
+}
+export interface SourceRange {
+    start: SourceLocation;
+    end: SourceLocation;
+}
+/**
+ * Platform constraint parsed from `@platform(...)` decorators.
+ *
+ * Syntax forms:
+ * ```holoscript
+ * @platform(quest3)                 → include: ['quest3'], exclude: []
+ * @platform(phone, desktop)         → include: ['phone', 'desktop'], exclude: []
+ * @platform(not: car, wearable)     → include: [], exclude: ['car', 'wearable']
+ * ```
+ */
+export interface PlatformConstraint {
+    /** Target platforms this block applies to (empty = all) */
+    include: string[];
+    /** Platforms to exclude */
+    exclude: string[];
+}
+export interface HoloNode {
+    type: string;
+    loc?: SourceRange;
+    provenance?: {
+        author: string;
+        timestamp: number;
+        provenanceHash: string;
+        context?: ProvenanceContext;
+    };
+}
+export type HoloValue = string | number | boolean | null | HoloValue[] | HoloObject | HoloBindValue;
+export interface HoloBindValue {
+    __bind: true;
+    source: string;
+    transform?: string;
+}
+export interface HoloObject {
+    [key: string]: HoloValue;
+}
+export interface HoloPosition {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface HoloComposition extends HoloNode {
+    type: 'Composition';
+    name: string;
+    theme?: HoloTheme;
+    environment?: HoloEnvironment;
+    scenes?: HoloScene[];
+    state?: HoloState;
+    templates: HoloTemplate[];
+    objects: HoloObjectDecl[];
+    spatialGroups: HoloSpatialGroup[];
+    lights: HoloLight[];
+    effects?: HoloEffects;
+    camera?: HoloCamera;
+    logic?: HoloLogic;
+    imports: HoloImport[];
+    timelines: HoloTimeline[];
+    audio: HoloAudio[];
+    zones: HoloZone[];
+    /** Declarative world blocks (environment / physics container). */
+    worlds?: HoloWorld[];
+    ui?: HoloUI;
+    transitions: HoloTransition[];
+    conditionals: HoloConditionalBlock[];
+    iterators: HoloForEachBlock[];
+    npcs: HoloNPC[];
+    quests: HoloQuest[];
+    spawnPoints?: HoloSpawnPoint[];
+    triggers?: HoloGameTrigger[];
+    lootTables?: HoloLootTable[];
+    worldChunks?: HoloWorldChunk[];
+    /** World-layer phasing: same coords, different content gated by a quest predicate (P2.4) */
+    worldLayers?: HoloWorldLayer[];
+    /** Instanced dungeon/raid content spun up per party with receipt-sealed completion (P2.6) */
+    dungeonInstances?: HoloDungeonInstance[];
+    /** World sharding: AABB partitions of a single world across rooms, receipt-sealed handoff (P2.5) */
+    worldShards?: HoloWorldShard[];
+    /** Named locomotion routes (patrol/path/orbit) declared at scene level */
+    movementPaths?: HoloMovementPath[];
+    /** Scene-level declarative reaction triggers (on_<trigger> -> action wiring) */
+    reactionTriggers?: HoloReactionTrigger[];
+    abilities: HoloAbility[];
+    dialogues: HoloDialogue[];
+    stateMachines: HoloStateMachine[];
+    achievements: HoloAchievement[];
+    talentTrees: HoloTalentTree[];
+    shapes: HoloShape[];
+    /** User-defined trait definitions (trait Name [extends Base] { ... }) */
+    traitDefinitions?: HoloTraitDefinition[];
+    /** Root-level trait attachments (e.g. @page, @metadata) */
+    traits?: HoloObjectTrait[];
+    /** Event handlers attached at the composition level (e.g. on(Target, "event") {}) */
+    eventHandlers?: HoloEventHandler[];
+    /** Actions available at the composition level */
+    actions?: HoloAction[];
+    /** Raw metadata key-value properties */
+    metadata?: Record<string, HoloValue>;
+    /** Named regulatory bundles that gate deploy/compile evidence. */
+    policyPacks?: HoloPolicyPackBlock[];
+    spawnGroups?: HoloSpawnGroup[];
+    waypointSets?: HoloWaypoints[];
+    constraints?: HoloConstraintBlock[];
+    terrains?: HoloTerrainBlock[];
+    domainBlocks?: HoloDomainBlock[];
+    norms?: HoloNormBlock[];
+    metanorms?: HoloMetanorm[];
+    /** SimulationContract block (v6.3) — preconditions → invariants → receipt */
+    contract?: HoloContract;
+    /** Named pub/sub topic declarations (v6.4) */
+    topics?: HoloTopic[];
+    /** Typed directional channels between nodes (v6.4) */
+    channels?: HoloChannel[];
+    /** Declarative natural-language graph connections (v6.4) */
+    connections?: HoloConnection[];
+}
+export interface HoloTheme extends HoloNode {
+    type: 'Theme';
+    properties: HoloThemeProperty[];
+}
+export interface HoloThemeProperty extends HoloNode {
+    type: 'ThemeProperty';
+    key: string;
+    value: HoloValue;
+}
+export interface HoloEnvironment extends HoloNode {
+    type: 'Environment';
+    properties: HoloEnvironmentProperty[];
+}
+export interface HoloScene extends HoloNode {
+    type: 'Scene';
+    name: string;
+    environment?: HoloEnvironment;
+    objects: HoloObjectDecl[];
+}
+export interface HoloEnvironmentProperty extends HoloNode {
+    type: 'EnvironmentProperty';
+    key: string;
+    value: HoloValue | HoloParticleSystem | HoloLighting;
+}
+export interface HoloParticleSystem extends HoloNode {
+    type: 'ParticleSystem';
+    name: string;
+    properties: Record<string, HoloValue>;
+}
+export interface HoloLighting extends HoloNode {
+    type: 'Lighting';
+    properties: Record<string, HoloValue>;
+}
+export interface HoloLight extends HoloNode {
+    type: 'Light';
+    id?: string;
+    name: string;
+    lightType: 'directional' | 'point' | 'spot' | 'hemisphere' | 'ambient' | 'area';
+    properties: HoloLightProperty[];
+    /** @platform() conditional compilation constraint */
+    platformConstraint?: PlatformConstraint;
+}
+export interface HoloLightProperty extends HoloNode {
+    type: 'LightProperty';
+    key: string;
+    value: HoloValue;
+}
+export interface HoloEffects extends HoloNode {
+    type: 'Effects';
+    effects: HoloEffect[];
+}
+export interface HoloEffect extends HoloNode {
+    type: 'Effect';
+    effectType: string;
+    properties: Record<string, HoloValue>;
+}
+export interface HoloCamera extends HoloNode {
+    type: 'Camera';
+    cameraType: 'perspective' | 'orthographic' | 'cinematic';
+    position?: HoloPosition;
+    target?: HoloPosition;
+    fov?: number;
+    near?: number;
+    far?: number;
+    properties: HoloCameraProperty[];
+}
+export interface HoloCameraProperty extends HoloNode {
+    type: 'CameraProperty';
+    key: string;
+    value: HoloValue;
+}
+export interface HoloTimeline extends HoloNode {
+    type: 'Timeline';
+    name: string;
+    autoplay?: boolean;
+    loop?: boolean;
+    entries: HoloTimelineEntry[];
+}
+export interface HoloTimelineEntry extends HoloNode {
+    type: 'TimelineEntry';
+    time: number;
+    action: HoloTimelineAction;
+}
+export type HoloTimelineAction = {
+    kind: 'animate';
+    target: string;
+    properties: Record<string, HoloValue>;
+} | {
+    kind: 'emit';
+    event: string;
+    data?: HoloValue;
+} | {
+    kind: 'call';
+    method: string;
+    args?: HoloValue[];
+};
+export interface HoloAudio extends HoloNode {
+    type: 'Audio';
+    name: string;
+    properties: HoloAudioProperty[];
+}
+export interface HoloAudioProperty extends HoloNode {
+    type: 'AudioProperty';
+    key: string;
+    value: HoloValue;
+}
+export interface HoloZone extends HoloNode {
+    type: 'Zone';
+    name: string;
+    properties: HoloZoneProperty[];
+    handlers: HoloEventHandler[];
+}
+export interface HoloZoneProperty extends HoloNode {
+    type: 'ZoneProperty';
+    key: string;
+    value: HoloValue;
+}
+/**
+ * Spawn point for players or NPCs with optional faction filtering.
+ *
+ * Grammar:
+ * ```holoscript
+ * spawn_point village_entry {
+ *   faction: "neutral"
+ *   max_count: 10
+ *   respawn_radius: 5
+ *   position: (10, 0, 10)
+ * }
+ * ```
+ */
+export interface HoloSpawnPoint extends HoloNode {
+    type: 'SpawnPoint';
+    name: string;
+    /** faction tag (e.g. 'horde', 'alliance', 'neutral', custom string) */
+    faction?: string;
+    /** Maximum concurrent entities at this spawn point */
+    maxCount?: number;
+    /** Radius (metres) within which respawn positions are randomised */
+    respawnRadius?: number;
+    position?: HoloPosition;
+    /** Raw key-value properties not mapped to typed fields */
+    properties: Record<string, HoloValue>;
+}
+/**
+ * Game trigger volume — fires enter/exit actions for nearby entities.
+ *
+ * Grammar:
+ * ```holoscript
+ * trigger dungeon_entrance {
+ *   radius: 3
+ *   faction_filter: ["alliance", "neutral"]
+ *   on_enter { emit("dungeon_enter") }
+ *   on_exit  { emit("dungeon_exit")  }
+ * }
+ * ```
+ */
+export interface HoloGameTrigger extends HoloNode {
+    type: 'GameTrigger';
+    name: string;
+    /** Detection sphere radius in metres */
+    radius: number;
+    /** Only fire for entities belonging to these factions (empty = all) */
+    factionFilter?: string[];
+    onEnter?: HoloEventHandler[];
+    onExit?: HoloEventHandler[];
+    position?: HoloPosition;
+    /** Raw key-value properties not mapped to typed fields */
+    properties: Record<string, HoloValue>;
+}
+/**
+ * Named movement path — a scene-level locomotion route for patrol/path/orbit.
+ *
+ * Grammar:
+ * ```holoscript
+ * movement_path patrol_route {
+ *   mode: "patrol"          // patrol | follow | path | orbit
+ *   loop: true
+ *   speed: 2.5
+ *   waypoints: [[0,0,0], [10,0,0], [10,0,10], [0,0,10]]
+ *   easing: "linear"
+ * }
+ * ```
+ *
+ * The IR node is the scene-level declaration; the imperative `.hs` `move`
+ * statement (MovementStatementNode, types/base.ts) references it by name and the
+ * runtime LocomotionTrait drives it. Locomotion logic is NOT duplicated here.
+ */
+export interface HoloMovementPath extends HoloNode {
+    type: 'MovementPath';
+    name: string;
+    /** Locomotion mode: patrol | follow | path | orbit | snap */
+    mode?: string;
+    /** Whether the path loops when the end is reached */
+    loop?: boolean;
+    /** Movement speed in metres/second */
+    speed?: number;
+    /** Waypoint array — each element is [x, y, z] */
+    waypoints?: HoloValue;
+    /** Easing function name (linear | ease_in | ease_out | ease_in_out | spring) */
+    easing?: string;
+    /** Raw key-value properties for extensibility */
+    properties: Record<string, HoloValue>;
+}
+/**
+ * Scene-level reaction trigger — declarative on_<trigger> -> action wiring.
+ *
+ * Grammar:
+ * ```holoscript
+ * reaction_trigger on_player_enter {
+ *   target: "player"
+ *   condition: "player.level >= 5"
+ *   on_activate { emit("zone_entered") }
+ *   on_deactivate { emit("zone_exited") }
+ *   cooldown: 2.0
+ * }
+ * ```
+ *
+ * The handler bodies are `HoloEventHandler`s (same shape used by GameTrigger's
+ * onEnter/onExit). Cognitive verbs inside a body (llm_call/recall/…) are resolved
+ * at compile time by BehaviorTreeTrait via CognitiveActions.ts — not re-parsed
+ * here. Maps to GameEventBlockNode.category (types/base.ts) for routing.
+ */
+export interface HoloReactionTrigger extends HoloNode {
+    type: 'ReactionTrigger';
+    /** Trigger event name, e.g. "on_player_enter", "on_collision", "on_proximity" */
+    name: string;
+    /** Entity type or id to react to (e.g. "player", "enemy", "@npc_guard") */
+    target?: string;
+    /** Optional guard expression — trigger only fires when truthy */
+    condition?: string;
+    /** Cooldown in seconds before this trigger can fire again */
+    cooldown?: number;
+    /** Handlers fired when the trigger activates */
+    onActivate?: HoloEventHandler[];
+    /** Handlers fired when the trigger deactivates (e.g. entity leaves radius) */
+    onDeactivate?: HoloEventHandler[];
+    /** Raw key-value properties for extensibility */
+    properties: Record<string, HoloValue>;
+}
+/**
+ * Named loot table with weighted entries.
+ *
+ * Grammar:
+ * ```holoscript
+ * loot_table goblin_drops {
+ *   entry common_coin   { item: "gold_coin"     qty: "1..5"  weight: 60 }
+ *   entry iron_shard    { item: "iron_shard"    qty: "1..2"  weight: 25  rarity: "uncommon" }
+ *   entry rare_amulet   { item: "shadow_amulet" qty: "1"     weight: 5   rarity: "rare"     condition: "player_level >= 10" }
+ *   entry nothing       { weight: 10 }
+ *   guaranteed { item: "goblin_ear" qty: 1 }
+ *   multiplier_on_faction_hostile: "ironveil * 1.5"
+ * }
+ * ```
+ */
+export interface HoloLootEntry extends HoloNode {
+    type: 'LootEntry';
+    /** Entry identifier (bare name after 'entry') */
+    id: string;
+    /** Item reference id */
+    itemId?: string;
+    /** Relative drop weight (higher = more common) */
+    weight: number;
+    /** Quantity range, e.g. "1..5" or a number */
+    qty?: string | number;
+    /** Rarity tier */
+    rarity?: 'common' | 'uncommon' | 'rare' | 'epic' | 'legendary';
+    /** Optional condition expression string */
+    condition?: string;
+    /** Raw key-value properties for extensibility */
+    properties: Record<string, HoloValue>;
+}
+export interface HoloLootTable extends HoloNode {
+    type: 'LootTable';
+    name: string;
+    entries: HoloLootEntry[];
+    /** Items guaranteed to drop regardless of roll */
+    guaranteed?: Record<string, HoloValue>;
+    /** Raw key-value properties (multipliers, global modifiers) */
+    properties: Record<string, HoloValue>;
+}
+/**
+ * World chunk for large open-world streaming.
+ *
+ * Grammar:
+ * ```holoscript
+ * world_chunk dockside {
+ *   bounds: ((-200, 0, -200), (200, 100, 200))
+ *   priority: "high"
+ *   lod_distances: [50, 150, 400]
+ *   biome: "coastal_urban"
+ *   npc_roster: ["merchant_alva", "harbor_guard_01"]
+ *   streaming {
+ *     load_radius: 300
+ *     unload_radius: 500
+ *     budget_kb: 32768
+ *   }
+ * }
+ * ```
+ */
+export interface HoloWorldChunk extends HoloNode {
+    type: 'WorldChunk';
+    name: string;
+    /** Streaming priority hint ('high' | 'medium' | 'low' | number) */
+    priority?: string | number;
+    /** Biome identifier string */
+    biome?: string;
+    /** LOD switch distances in metres */
+    lodDistances?: number[];
+    /** Asset paths declared in the chunk manifest */
+    assetManifest?: string[];
+    /** NPC names present in this chunk (references to npc declarations) */
+    npcRoster?: string[];
+    /** Spawn point positions */
+    spawnPoints?: HoloPosition[];
+    /** Streaming sub-block properties */
+    streaming?: Record<string, HoloValue>;
+    /** Raw key-value properties for extensibility */
+    properties: Record<string, HoloValue>;
+}
+/**
+ * A typed phasing predicate: a player is "in" the layer iff their completion of
+ * `questId` matches `mustBeCompleted`. The questId is compile-validated against
+ * the composition's declared quests — an unknown quest is a compile error, not a
+ * runtime surprise (the "phasing as a typed verifiable predicate" claim).
+ */
+export interface HoloPhasePredicate {
+    type: 'PhasePredicate';
+    kind: 'quest_flag';
+    questId: string;
+    /** true = visible AFTER the quest is completed; false = visible BEFORE. */
+    mustBeCompleted: boolean;
+}
+/**
+ * A world_layer block: content (NPCs/objects, referenced by name) that exists in
+ * the same world coordinates but is gated to players whose phase predicate holds.
+ *
+ * Syntax:
+ *   world_layer post_awakening {
+ *     requires_quest: "main_chapter_1"     // forbids_quest for the inverse
+ *     npcs: ["restored_keeper", "vigilant_guard"]
+ *     objects: ["healed_shrine"]
+ *   }
+ */
+export interface HoloWorldLayer extends HoloNode {
+    type: 'WorldLayer';
+    name: string;
+    predicate: HoloPhasePredicate;
+    /** NPC names gated to this layer (references to npc declarations). */
+    npcs: string[];
+    /** Object names gated to this layer. */
+    objects: string[];
+    /** Raw key-value properties for extensibility. */
+    properties: Record<string, HoloValue>;
+}
+/**
+ * A dungeon_instance block: instanced content (a dungeon/raid) spun up on demand,
+ * one live instance per party, capped at `maxInstances`. Completion emits a
+ * receipt sealed against the party + instance, and (optionally) sets a quest flag.
+ *
+ * Syntax:
+ *   dungeon_instance shadowfen_keep {
+ *     max_instances: 10
+ *     party_size: 5
+ *     reset_timer: 3600              // seconds an empty instance lingers before release
+ *     completion_quest: "shadowfen_cleared"   // compile-validated against declared quests
+ *     npcs: ["dungeon_boss", "shadow_acolyte"]
+ *   }
+ */
+export interface HoloDungeonInstance extends HoloNode {
+    type: 'DungeonInstance';
+    name: string;
+    /** Max concurrent live instances (pool cap). */
+    maxInstances: number;
+    /** Players per instance. */
+    partySize: number;
+    /** Seconds an empty instance lingers before release (0 = release immediately). */
+    resetTimer: number;
+    /** Quest id set on completion (compile-validated). Empty = no quest flag. */
+    completionQuest: string;
+    /** NPC names that populate the instance. */
+    npcs: string[];
+    /** Object names that populate the instance. */
+    objects: string[];
+    /** Raw key-value properties for extensibility. */
+    properties: Record<string, HoloValue>;
+}
+/**
+ * A world_shard block: an axis-aligned partition of a single world, hosted as its
+ * own room. A player crossing into a neighbor shard is handed off; the handoff is
+ * receipt-sealed and validated (the target must be a declared NEIGHBOR and the
+ * position must be inside its bounds — anti-teleport).
+ *
+ * Syntax:
+ *   world_shard north_province {
+ *     min: [-1000, 0, -1000]
+ *     max: [0, 256, 1000]
+ *     neighbors: ["south_province", "east_province"]
+ *     max_players: 200
+ *     handoff: "seamless"          // or "loading"
+ *   }
+ */
+export interface HoloWorldShard extends HoloNode {
+    type: 'WorldShard';
+    name: string;
+    /** AABB minimum corner [x, y, z]. */
+    min: [number, number, number];
+    /** AABB maximum corner [x, y, z]. */
+    max: [number, number, number];
+    /** Names of adjacent shards a player may be handed off to (compile-validated). */
+    neighbors: string[];
+    /** Max players hosted in this shard's room. */
+    maxPlayers: number;
+    /** Handoff style on a border crossing ('seamless' | 'loading'). */
+    handoff: string;
+    /** Raw key-value properties for extensibility. */
+    properties: Record<string, HoloValue>;
+}
+export interface HoloWorld extends HoloNode {
+    type: 'World';
+    id?: string;
+    name?: string;
+    bounds?: HoloObject;
+    properties?: HoloWorldProperty[];
+    children?: HoloObjectDecl[];
+}
+export interface HoloWorldProperty extends HoloNode {
+    type: 'WorldProperty';
+    key: string;
+    value: HoloValue;
+}
+export interface HoloUI extends HoloNode {
+    type: 'UI';
+    elements: HoloUIElement[];
+}
+export interface HoloUIElement extends HoloNode {
+    type: 'UIElement';
+    name: string;
+    properties: HoloUIProperty[];
+}
+export interface HoloUIProperty extends HoloNode {
+    type: 'UIProperty';
+    key: string;
+    value: HoloValue;
+}
+export interface HoloTransition extends HoloNode {
+    type: 'Transition';
+    name: string;
+    properties: HoloTransitionProperty[];
+}
+export interface HoloTransitionProperty extends HoloNode {
+    type: 'TransitionProperty';
+    key: string;
+    value: HoloValue;
+}
+export interface HoloConditionalBlock extends HoloNode {
+    type: 'ConditionalBlock';
+    condition: string;
+    objects: HoloObjectDecl[];
+    spatialGroups?: HoloSpatialGroup[];
+    elseObjects?: HoloObjectDecl[];
+    elseSpatialGroups?: HoloSpatialGroup[];
+}
+export interface HoloForEachBlock extends HoloNode {
+    type: 'ForEachBlock';
+    variable: string;
+    iterable: string;
+    objects: HoloObjectDecl[];
+    spatialGroups?: HoloSpatialGroup[];
+}
+export interface HoloState extends HoloNode {
+    type: 'State';
+    properties: HoloStateProperty[];
+}
+export interface HoloStateProperty extends HoloNode {
+    type: 'StateProperty';
+    key: string;
+    value: HoloValue;
+    reactive?: boolean;
+}
+export interface HoloTemplate extends HoloNode {
+    type: 'Template';
+    name: string;
+    version?: number;
+    migrations?: HoloMigration[];
+    properties: HoloTemplateProperty[];
+    state?: HoloState;
+    actions: HoloAction[];
+    traits: HoloObjectTrait[];
+    directives?: unknown[];
+    /** @platform() conditional compilation constraint */
+    platformConstraint?: PlatformConstraint;
+}
+export interface HoloMigration extends HoloNode {
+    type: 'Migration';
+    fromVersion: number;
+    body: unknown;
+}
+export interface HoloTemplateProperty extends HoloNode {
+    type: 'TemplateProperty';
+    key: string;
+    value: HoloValue;
+}
+/**
+ * Scene object declaration in a `.holo` composition.
+ *
+ * **Asset maturity (draft → mesh → final)** — optional `ObjectProperty` keys
+ * consumed by `R3FCompiler.compileObjectDecl`:
+ * - `maturity`: `"draft"` | `"mesh"` | `"final"` — sets `R3FNode.assetMaturity`
+ * - `promoteUrl` / `promote_url`: string — GLB/URL for draft→mesh promotion (passed to `R3FNode.props`)
+ * - `collisionShape` / `collision_shape`: string — collision proxy hint (passed to `R3FNode.props`)
+ * The `@draft` trait also forces `assetMaturity: 'draft'` and draft rendering props.
+ */
+export interface HoloObjectDecl extends HoloNode {
+    type: 'Object' | 'ObjectDecl';
+    id?: string;
+    name: string;
+    position?: HoloPosition;
+    scale?: HoloPosition;
+    rotation?: HoloPosition;
+    declarationKind?: 'object' | 'instanced_object' | string;
+    instanceMetadata?: HoloInstancedObjectMetadata;
+    __holo_id?: string;
+    template?: string;
+    properties: HoloObjectProperty[];
+    state?: HoloState;
+    traits: HoloObjectTrait[];
+    directives?: unknown[];
+    children?: HoloObjectDecl[];
+    subOrbs?: HoloSubOrb[];
+    /** @platform() conditional compilation constraint */
+    platformConstraint?: PlatformConstraint;
+}
+export interface HoloInstancedObjectMetadata extends HoloNode {
+    type: 'InstancedObjectMetadata';
+    sourceTrait?: string;
+    instanceTraits: string[];
+    count?: number;
+    anchor?: string;
+    seed?: HoloValue;
+    generator?: HoloValue;
+    properties: Record<string, HoloValue>;
+    traits: HoloObjectTrait[];
+}
+export interface HoloSubOrb extends HoloNode {
+    type: 'SubOrb';
+    name: string;
+    source: string;
+    properties: HoloObjectProperty[];
+}
+export interface HoloObjectTrait extends HoloNode {
+    type: 'ObjectTrait';
+    name: string;
+    config: Record<string, HoloValue>;
+    params?: Record<string, HoloValue>;
+    /** Positional arguments for traits (e.g. @trait(arg1, arg2)) */
+    args?: HoloValue[];
+    /** @platform() conditional compilation constraint for trait-level variants */
+    platformConstraint?: PlatformConstraint;
+}
+/**
+ * A user-defined trait declaration in HoloScript.
+ *
+ * Grammar (tree-sitter-holoscript grammar.js line 214-222):
+ * ```
+ * trait Clickable extends Interactable {
+ *   cursor: "pointer"
+ *   highlight: true
+ * }
+ * ```
+ *
+ * When `extends` is present, the trait inherits all properties, event handlers,
+ * and actions from the parent trait. Child properties override parent properties
+ * with the same key.
+ */
+export interface HoloTraitDefinition extends HoloNode {
+    type: 'TraitDefinition';
+    /** Name of the trait being defined */
+    name: string;
+    /** Parent trait name (from `extends` clause), or undefined if no inheritance */
+    base?: string;
+    /** Properties declared directly in this trait (not including inherited) */
+    properties: HoloTraitProperty[];
+    /** Event handlers declared in this trait */
+    eventHandlers?: HoloEventHandler[];
+    /** Actions declared in this trait */
+    actions?: HoloAction[];
+}
+export interface HoloTraitProperty extends HoloNode {
+    type: 'TraitProperty';
+    key: string;
+    value: HoloValue;
+}
+export interface HoloObjectProperty extends HoloNode {
+    type: 'ObjectProperty';
+    key: string;
+    value: HoloValue;
+}
+export interface HoloShape extends HoloNode {
+    type: 'Shape';
+    name: string;
+    shapeType: string;
+    properties: HoloShapeProperty[];
+}
+export interface HoloShapeProperty extends HoloNode {
+    type: 'ShapeProperty';
+    key: string;
+    value: HoloValue;
+}
+export interface HoloSpatialGroup extends HoloNode {
+    type: 'SpatialGroup';
+    id?: string;
+    name: string;
+    properties: HoloGroupProperty[];
+    objects: HoloObjectDecl[];
+    lights?: HoloLight[];
+    groups?: HoloSpatialGroup[];
+    body?: HoloStatement[];
+    /** @platform() conditional compilation constraint */
+    platformConstraint?: PlatformConstraint;
+}
+export interface HoloGroupProperty extends HoloNode {
+    type: 'GroupProperty';
+    key: string;
+    value: HoloValue;
+}
+export interface HoloLogic extends HoloNode {
+    type: 'Logic';
+    handlers: HoloEventHandler[];
+    actions: HoloAction[];
+}
+export interface HoloEventHandler extends HoloNode {
+    type: 'EventHandler';
+    event: string;
+    parameters: HoloParameter[];
+    body: HoloStatement[];
+}
+export interface HoloAction extends HoloNode {
+    type: 'Action';
+    name: string;
+    parameters: HoloParameter[];
+    body: HoloStatement[];
+    async?: boolean;
+}
+export interface HoloParameter extends HoloNode {
+    type: 'Parameter';
+    name: string;
+    paramType?: string;
+    defaultValue?: HoloValue;
+}
+export type HoloStatement = HoloAssignment | HoloMethodCall | HoloIfStatement | HoloForStatement | HoloWhileStatement | HoloClassicForStatement | HoloVariableDeclaration | HoloAwaitStatement | HoloReturnStatement | HoloEmitStatement | HoloAnimateStatement | HoloOnErrorStatement | HoloExpressionStatement;
+export interface HoloWhileStatement extends HoloNode {
+    type: 'WhileStatement';
+    condition: HoloExpression;
+    body: HoloStatement[];
+}
+export interface HoloOnErrorStatement extends HoloNode {
+    type: 'OnErrorStatement';
+    body: HoloStatement[];
+}
+export interface HoloAssignment extends HoloNode {
+    type: 'Assignment';
+    target: string;
+    operator: '=' | '+=' | '-=' | '*=' | '/=';
+    value: HoloExpression;
+}
+export interface HoloMethodCall extends HoloNode {
+    type: 'MethodCall';
+    object?: string;
+    method: string;
+    arguments: HoloExpression[];
+}
+export interface HoloIfStatement extends HoloNode {
+    type: 'IfStatement';
+    condition: HoloExpression;
+    consequent: HoloStatement[];
+    alternate?: HoloStatement[];
+}
+export interface HoloClassicForStatement extends HoloNode {
+    type: 'ClassicForStatement';
+    init?: HoloStatement;
+    test?: HoloExpression;
+    update?: HoloStatement;
+    body: HoloStatement[];
+}
+export interface HoloVariableDeclaration extends HoloNode {
+    type: 'VariableDeclaration';
+    kind: 'let' | 'var' | 'const';
+    name: string;
+    value?: HoloExpression;
+}
+export interface HoloForStatement extends HoloNode {
+    type: 'ForStatement';
+    variable: string;
+    iterable: HoloExpression;
+    body: HoloStatement[];
+}
+export interface HoloAwaitStatement extends HoloNode {
+    type: 'AwaitStatement';
+    expression: HoloExpression;
+}
+export interface HoloReturnStatement extends HoloNode {
+    type: 'ReturnStatement';
+    value?: HoloExpression;
+}
+export interface HoloEmitStatement extends HoloNode {
+    type: 'EmitStatement';
+    event: string;
+    data?: HoloExpression;
+}
+export interface HoloAnimateStatement extends HoloNode {
+    type: 'AnimateStatement';
+    target: string;
+    properties: Record<string, HoloValue>;
+}
+export interface HoloExpressionStatement extends HoloNode {
+    type: 'ExpressionStatement';
+    expression: HoloExpression;
+}
+export type HoloExpression = HoloLiteral | HoloIdentifier | HoloBinaryExpression | HoloUnaryExpression | HoloMemberExpression | HoloCallExpression | HoloArrayExpression | HoloObjectExpression | HoloConditionalExpression | HoloUpdateExpression | HoloBindExpression;
+export interface HoloLiteral extends HoloNode {
+    type: 'Literal';
+    value: string | number | boolean | null;
+}
+export interface HoloIdentifier extends HoloNode {
+    type: 'Identifier';
+    name: string;
+}
+export interface HoloBinaryExpression extends HoloNode {
+    type: 'BinaryExpression';
+    operator: string;
+    left: HoloExpression;
+    right: HoloExpression;
+}
+export interface HoloUnaryExpression extends HoloNode {
+    type: 'UnaryExpression';
+    operator: '!' | '-';
+    argument: HoloExpression;
+}
+export interface HoloMemberExpression extends HoloNode {
+    type: 'MemberExpression';
+    object: HoloExpression;
+    property: string;
+    computed: boolean;
+}
+export interface HoloCallExpression extends HoloNode {
+    type: 'CallExpression';
+    callee: HoloExpression;
+    arguments: HoloExpression[];
+}
+export interface HoloArrayExpression extends HoloNode {
+    type: 'ArrayExpression';
+    elements: HoloExpression[];
+}
+export interface HoloObjectExpression extends HoloNode {
+    type: 'ObjectExpression';
+    properties: {
+        key: string;
+        value: HoloExpression;
+    }[];
+}
+export interface HoloConditionalExpression extends HoloNode {
+    type: 'ConditionalExpression';
+    test: HoloExpression;
+    consequent: HoloExpression;
+    alternate: HoloExpression;
+}
+export interface HoloUpdateExpression extends HoloNode {
+    type: 'UpdateExpression';
+    operator: '++' | '--';
+    argument: HoloExpression;
+    prefix: boolean;
+}
+export interface HoloBindExpression extends HoloNode {
+    type: 'BindExpression';
+    source: string;
+    transform?: string;
+}
+/** Legacy import node type used by HoloCompositionParser */
+export interface HoloImport extends HoloNode {
+    type: 'Import';
+    specifiers: HoloImportSpecifier[];
+    source: string;
+}
+export interface HoloImportSpecifier extends HoloNode {
+    type: 'ImportSpecifier';
+    imported: string;
+    local?: string;
+}
+/**
+ * AST node for @import directives produced by HoloScriptPlusParser.
+ *
+ * Supported syntax forms:
+ *   @import "./path.hs"
+ *   @import "./path.hs" as Alias
+ *   @import { A, B } from "./path.hs"
+ *   @import * as NS from "./path.hs"
+ */
+export interface ImportDirective extends HoloNode {
+    type: 'import';
+    /** Raw import path string as written in source */
+    path: string;
+    /** Derived or explicit alias (filename stem if not specified) */
+    alias: string;
+    /** Named exports to import. Undefined means "all under alias namespace". */
+    namedImports?: string[];
+    /** True for `@import * as NS from "./f.hs"` form */
+    isWildcard?: boolean;
+}
+/**
+ * AST node for @export directives produced by HoloScriptPlusParser.
+ *
+ * Supported syntax forms:
+ *   @export template "MyTemplate"
+ *   @export object "MyObject"
+ *   @export "NamedThing"
+ *   @export  (anonymous — exports the next node)
+ */
+export interface ExportDirective extends HoloNode {
+    type: 'export';
+    /** The kind of thing being exported: 'template' | 'object' | 'composition' | 'trait' | 'any' */
+    exportKind: 'template' | 'object' | 'composition' | 'trait' | 'group' | 'scene' | 'any';
+    /** The exported name, if specified explicitly */
+    exportName?: string;
+}
+export interface HoloParseResult {
+    success: boolean;
+    ast?: HoloComposition;
+    errors: HoloParseError[];
+    warnings: HoloParseWarning[];
+}
+export interface HoloParseError {
+    message: string;
+    loc?: SourceLocation;
+    code?: string;
+    suggestion?: string;
+    severity?: 'error' | 'warning';
+}
+export interface HoloParseWarning {
+    message: string;
+    loc?: SourceLocation;
+    code?: string;
+}
+/**
+ * Typed AI-agency attachment for a scene object (currently NPCs).
+ *
+ * Makes "this object has AI agency" a first-class IR node a compiler/analyzer
+ * can reason about WITHOUT running the trait runtime — brain kind, autonomy
+ * envelope, tool permissions, and model binding are all statically inspectable.
+ */
+export interface AgentBrainAttachment extends HoloNode {
+    type: 'AgentBrainAttachment';
+    /** Kind of agent brain driving this object. */
+    brainType: 'llm' | 'behavior-tree' | 'state-machine' | 'scripted' | 'hybrid' | 'remote';
+    /** How much independent action the agent is permitted. */
+    autonomy?: 'reactive' | 'deliberative' | 'autonomous' | 'supervised';
+    /** Reference to a brain/skill definition by id (e.g. a .hsplus brain skill). */
+    brainRef?: string;
+    /** Names of tools/abilities this brain is permitted to invoke. */
+    toolPermissions?: string[];
+    /** Model binding for llm/hybrid brains. Provider aligns with ModelProvider. */
+    model?: {
+        provider?: 'anthropic' | 'openai' | 'local' | 'ollama' | 'custom';
+        name?: string;
+        temperature?: number;
+        maxTokens?: number;
+    };
+    /** Raw additional brain config not captured by typed fields. */
+    config?: Record<string, HoloValue>;
+}
+export interface HoloNPC extends HoloNode {
+    type: 'NPC';
+    name: string;
+    npcType?: string;
+    model?: string;
+    /** Spatial anchor for the agent (same canonical position type as objects). */
+    position?: HoloPosition;
+    /** First-class AI-agency attachment — replaces the opaque config bag for agency reasoning. */
+    brain?: AgentBrainAttachment;
+    properties: HoloNPCProperty[];
+    behaviors: HoloBehavior[];
+    state?: HoloState;
+    dialogueTree?: string;
+    /** @decorator { config } trait blocks attached to the NPC body (e.g. @verbalFingerprint, @reputationLedger). */
+    traits?: HoloObjectTrait[];
+    /** action name(...) { ... } and on eventName(...) { ... } members declared in the NPC body. */
+    directives?: Array<Record<string, unknown>>;
+}
+export interface HoloNPCProperty extends HoloNode {
+    type: 'NPCProperty';
+    key: string;
+    value: HoloValue;
+}
+export interface HoloBehavior extends HoloNode {
+    type: 'Behavior';
+    name: string;
+    trigger: string;
+    condition?: HoloExpression;
+    actions: HoloBehaviorAction[];
+    timeout?: number;
+    priority?: number;
+}
+export interface HoloBehaviorAction extends HoloNode {
+    type: 'BehaviorAction';
+    actionType: 'move' | 'animate' | 'face' | 'damage' | 'heal' | 'spawn' | 'emit' | 'wait' | 'call';
+    config: Record<string, HoloValue>;
+}
+export interface HoloQuest extends HoloNode {
+    type: 'Quest';
+    name: string;
+    giver?: string;
+    level?: number;
+    questType?: 'fetch' | 'defeat' | 'discover' | 'escort' | 'deliver' | 'custom';
+    objectives: HoloQuestObjective[];
+    rewards: HoloQuestRewards;
+    branches?: HoloQuestBranch[];
+    prerequisites?: string[];
+}
+export interface HoloQuestObjective extends HoloNode {
+    type: 'QuestObjective';
+    id: string;
+    description: string;
+    objectiveType: 'discover' | 'defeat' | 'collect' | 'deliver' | 'interact' | 'survive';
+    target: string | HoloExpression;
+    count?: number;
+    optional?: boolean;
+}
+export interface HoloQuestRewards extends HoloNode {
+    type: 'QuestRewards';
+    experience?: number;
+    gold?: number;
+    items?: HoloQuestRewardItem[];
+    reputation?: Record<string, number>;
+    unlocks?: string[];
+}
+export interface HoloQuestRewardItem extends HoloNode {
+    type: 'QuestRewardItem';
+    id: string;
+    count?: number;
+    rarity?: 'common' | 'uncommon' | 'rare' | 'epic' | 'legendary';
+}
+export interface HoloQuestBranch extends HoloNode {
+    type: 'QuestBranch';
+    condition: HoloExpression;
+    text?: string;
+    rewardMultiplier?: number;
+    nextQuest?: string;
+}
+export interface HoloAbility extends HoloNode {
+    type: 'Ability';
+    name: string;
+    abilityType: 'spell' | 'skill' | 'passive' | 'ultimate';
+    class?: string;
+    level?: number;
+    stats: HoloAbilityStats;
+    scaling?: HoloAbilityScaling;
+    effects: HoloAbilityEffects;
+    projectile?: HoloAbilityProjectile;
+}
+export interface HoloAbilityStats extends HoloNode {
+    type: 'AbilityStats';
+    manaCost?: number;
+    staminaCost?: number;
+    cooldown?: number;
+    castTime?: number;
+    range?: number;
+    radius?: number;
+    duration?: number;
+}
+export interface HoloAbilityScaling extends HoloNode {
+    type: 'AbilityScaling';
+    baseDamage?: number;
+    spellPower?: number;
+    attackPower?: number;
+    levelScale?: number;
+}
+export interface HoloAbilityEffects extends HoloNode {
+    type: 'AbilityEffects';
+    impact?: HoloAbilityImpact;
+    damage?: HoloAbilityDamage;
+    buff?: HoloAbilityBuff;
+    debuff?: HoloAbilityDebuff;
+}
+export interface HoloAbilityImpact extends HoloNode {
+    type: 'AbilityImpact';
+    animation?: string;
+    particle?: string;
+    sound?: string;
+    shake?: {
+        intensity: number;
+        duration: number;
+    };
+}
+export interface HoloAbilityDamage extends HoloNode {
+    type: 'AbilityDamage';
+    damageType: 'physical' | 'fire' | 'ice' | 'lightning' | 'arcane' | 'holy' | 'shadow';
+    canCrit?: boolean;
+    critMultiplier?: number;
+}
+export interface HoloAbilityBuff extends HoloNode {
+    type: 'AbilityBuff';
+    stat: string;
+    amount: number;
+    duration: number;
+    stacks?: number;
+}
+export interface HoloAbilityDebuff extends HoloNode {
+    type: 'AbilityDebuff';
+    effect: 'slow' | 'stun' | 'silence' | 'root' | 'burn' | 'freeze' | 'poison';
+    duration: number;
+    magnitude?: number;
+}
+export interface HoloAbilityProjectile extends HoloNode {
+    type: 'AbilityProjectile';
+    model?: string;
+    speed?: number;
+    lifetime?: number;
+    trail?: string;
+    homing?: boolean;
+}
+export interface HoloDialogue extends HoloNode {
+    type: 'Dialogue';
+    id: string;
+    character?: string;
+    emotion?: 'friendly' | 'angry' | 'sad' | 'neutral' | 'excited' | 'mysterious';
+    content: string | HoloLocalizedText;
+    options: HoloDialogueOption[];
+    condition?: HoloExpression;
+    nextDialogue?: string;
+}
+export interface HoloDialogueOption extends HoloNode {
+    type: 'DialogueOption';
+    text: string | HoloLocalizedText;
+    action?: HoloStatement[];
+    unlocked?: HoloExpression;
+    emotion?: string;
+    next?: string;
+}
+export interface HoloLocalizedText extends HoloNode {
+    type: 'LocalizedText';
+    id: string;
+    translations: Record<string, string>;
+    fallback?: string;
+}
+export interface HoloStateMachine extends HoloNode {
+    type: 'StateMachine';
+    name: string;
+    initialState: string;
+    inputs?: HoloAnimationInput[];
+    listeners?: HoloAnimationListener[];
+    states: Record<string, HoloState_Machine>;
+    transitions?: HoloStateTransition[];
+}
+export interface HoloState_Machine extends HoloNode {
+    type: 'State_Machine';
+    name: string;
+    clip?: string;
+    clips?: string[];
+    parameter?: string;
+    parameters?: string[];
+    thresholds?: number[];
+    blendType?: '1d' | 'direct';
+    blendMode?: 'override' | 'additive';
+    mask?: string[];
+    baseline?: Record<string, number>;
+    entry?: HoloStatement[];
+    exit?: HoloStatement[];
+    actions: HoloBehaviorAction[];
+    transitions: HoloStateTransition[];
+    onDamage?: HoloStatement[];
+    timeout?: number;
+    onTimeout?: HoloStatement[];
+}
+export interface HoloStateTransition extends HoloNode {
+    type: 'StateTransition';
+    from?: string | 'any';
+    target: string;
+    condition?: HoloExpression;
+    conditions?: HoloAnimationTransitionCondition[];
+    event?: string;
+    duration?: number;
+    easing?: string;
+    exitTime?: number;
+    hasExitTime?: boolean;
+    pauseWhenExiting?: boolean;
+    priority?: number;
+    canTransitionToSelf?: boolean;
+}
+export type HoloAnimationInputType = 'bool' | 'float' | 'int' | 'trigger';
+export interface HoloAnimationInput extends HoloNode {
+    type: 'AnimationInput';
+    name: string;
+    inputType: HoloAnimationInputType;
+    rawType?: string;
+    default?: number | boolean;
+}
+export type HoloAnimationListenerAction = 'set' | 'fire' | 'reset';
+export interface HoloAnimationListener extends HoloNode {
+    type: 'AnimationListener';
+    event: string;
+    parameter: string;
+    action: HoloAnimationListenerAction;
+    value?: number | boolean | string;
+    source?: string;
+}
+export interface HoloAnimationTransitionCondition extends HoloNode {
+    type: 'AnimationTransitionCondition';
+    parameter: string;
+    operator: '==' | '!=' | '>' | '<' | '>=' | '<=';
+    value: number | boolean | string;
+    chain?: 'and' | 'or';
+}
+export interface HoloAchievement extends HoloNode {
+    type: 'Achievement';
+    name: string;
+    description: string;
+    points?: number;
+    condition: HoloExpression;
+    reward?: HoloAchievementReward;
+    progress?: HoloExpression;
+    hidden?: boolean;
+}
+export interface HoloAchievementReward extends HoloNode {
+    type: 'AchievementReward';
+    title?: string;
+    badge?: string;
+    bonus?: Record<string, number>;
+    unlocks?: string[];
+}
+export interface HoloTalentTree extends HoloNode {
+    type: 'TalentTree';
+    name: string;
+    class?: string;
+    rows: HoloTalentRow[];
+}
+export interface HoloTalentRow extends HoloNode {
+    type: 'TalentRow';
+    tier: number;
+    nodes: HoloTalentNode[];
+}
+export interface HoloTalentNode extends HoloNode {
+    type: 'TalentNode';
+    id: string;
+    name: string;
+    description?: string;
+    points: number;
+    maxPoints?: number;
+    requires?: string[];
+    effect: HoloTalentEffect;
+    icon?: string;
+}
+export interface HoloTalentEffect extends HoloNode {
+    type: 'TalentEffect';
+    effectType: 'spell' | 'upgrade' | 'passive' | 'unlock';
+    target?: string;
+    bonus?: Record<string, number>;
+}
+export interface HoloParserOptions {
+    /** Include source locations in AST nodes */
+    locations?: boolean;
+    /** Collect errors instead of throwing */
+    tolerant?: boolean;
+    /** Enable strict mode (stricter validation) */
+    strict?: boolean;
+    /** Source filename for error messages */
+    filename?: string;
+    /**
+     * Injectable union of known trait names used to suppress false-positive
+     * unknown-trait warnings.
+     *
+     * When provided, `ErrorRecovery` uses this set (instead of the built-in
+     * `VR_TRAITS`-derived fallback) as the trait dictionary for unknown-trait
+     * suggestions. Build it with `buildKnownTraitSet()` from
+     * `traits/knownTraitSet` so the parser, LSP, and linter share one SSOT.
+     *
+     * Optional and non-breaking: when absent, behavior is exactly the current
+     * `VR_TRAITS`-based behavior.
+     */
+    knownTraits?: ReadonlySet<string>;
+}
+/**
+ * Compact import record stored in `ASTProgram.imports`.
+ * Mirrors `ImportDirective` but is serialization-lightweight (no loc).
+ */
+export interface HSPlusImport {
+    path: string;
+    alias: string;
+    namedImports?: string[];
+    isWildcard?: boolean;
+}
+/**
+ * Async file-reader function injected by the host environment.
+ *
+ * - **Node.js**: `(p) => fs.promises.readFile(p, 'utf-8')`
+ * - **Browser / XR**: `(p) => fetch(p).then(r => r.text())`
+ * - **Tests**: in-memory `Map<string, string>` lookup
+ *
+ * The function receives the **canonical** (resolved absolute) path.
+ */
+export type ReadFileFn = (absolutePath: string) => Promise<string>;
+export interface HoloSpawnGroup extends HoloNode {
+    type: 'SpawnGroup';
+    name: string;
+    properties: Record<string, HoloValue>;
+}
+export interface HoloWaypoints extends HoloNode {
+    type: 'Waypoints';
+    name: string;
+    points: HoloValue;
+}
+export interface HoloConstraintBlock extends HoloNode {
+    type: 'Constraint';
+    name: string;
+    properties: Record<string, HoloValue>;
+}
+export interface HoloTerrainBlock extends HoloNode {
+    type: 'Terrain';
+    name: string;
+    properties: Record<string, HoloValue>;
+}
+export type HoloDomainType = 'iot' | 'robotics' | 'dataviz' | 'education' | 'healthcare' | 'music' | 'architecture' | 'web3' | 'material' | 'material_graph' | 'light_field' | 'nav_field' | 'physics_contract' | 'physics' | 'vfx' | 'particle_field' | 'postfx' | 'audio' | 'weather' | 'procedural' | 'rendering' | 'navigation' | 'input' | 'codebase' | 'narrative' | 'payment' | 'norms' | 'service' | 'contract' | 'data' | 'network' | 'pipeline' | 'metric' | 'container' | 'resilience' | 'simulation' | 'mcp_servers' | 'custom';
+export interface HoloDomainBlock extends HoloNode {
+    type: 'DomainBlock';
+    /** Domain category */
+    domain: HoloDomainType;
+    /** The specific keyword used (e.g. 'sensor', 'joint', 'recipe') */
+    keyword: string;
+    /** Block name (the string after the keyword) */
+    name: string;
+    /** Trait decorators on the block (e.g. @networked @safety_rated) */
+    traits: string[];
+    /**
+     * Optional plugin-exported domain tags.
+     *
+     * Populated by domain plugins / schema mappers so compilers can avoid
+     * hardcoded domain vocabulary in core.
+     */
+    domainTags?: string[];
+    /** Properties declared inside the block */
+    properties: Record<string, HoloValue>;
+    /** Nested objects inside the block */
+    children?: HoloObjectDecl[];
+    /** Event handlers inside the block */
+    eventHandlers?: HoloEventHandler[];
+    /** Structured pipeline AST (populated when domain === 'pipeline' and keyword === 'pipeline') */
+    pipelineAST?: import('./PipelineParser').Pipeline;
+}
+export interface CompiledCutsceneAction {
+    type: 'camera_move' | 'character_action' | 'wait' | 'effect' | 'audio';
+    target?: string;
+    params: Record<string, any>;
+    duration?: number;
+}
+export interface CompiledChoice {
+    text: string;
+    condition?: string;
+    nextChapter?: string;
+    action?: string;
+}
+export interface CompiledDialogueLine {
+    speaker?: string;
+    text: string;
+    emotion?: string;
+    duration?: number;
+    voiceClip?: string;
+}
+export interface CompiledChapter {
+    name: string;
+    trigger?: string;
+    dialogueLines?: CompiledDialogueLine[];
+    choices?: CompiledChoice[];
+    onComplete?: string;
+    cutsceneActions?: CompiledCutsceneAction[];
+}
+export interface CompiledNarrative {
+    name: string;
+    type: 'linear' | 'branching' | 'open_world';
+    chapters: CompiledChapter[];
+    variables?: Record<string, HoloValue>;
+    startChapter?: string;
+}
+export interface CompiledPaywall {
+    name: string;
+    price: number;
+    asset: 'USDC' | 'ETH' | 'SOL';
+    network: 'base' | 'ethereum' | 'solana';
+    recipient: string;
+    description?: string;
+    type: 'one_time' | 'subscription' | 'tip' | 'per_use';
+    gatedContent?: string[];
+    revenueSplit?: {
+        creator: number;
+        platform: number;
+        agent: number;
+    };
+}
+export interface CompiledHealthcare {
+    name: string;
+    keyword: string;
+    /** Medical modality: xray, mri, ct, ultrasound, ecg */
+    modality?: string;
+    /** Body system targeted: cardiovascular, nervous, skeletal, etc. */
+    bodySystem?: string;
+    /** DICOM window/level for imaging */
+    dicomWindow?: {
+        center: number;
+        width: number;
+    };
+    /** Vital signs to monitor */
+    vitalSigns?: string[];
+    /** Alert thresholds for vital monitoring */
+    alertThresholds?: Record<string, {
+        min: number;
+        max: number;
+    }>;
+    /** Procedure steps */
+    procedureSteps?: string[];
+    /** Patient data display fields */
+    displayFields?: string[];
+    /** Traits applied */
+    traits: string[];
+    /** Extra properties */
+    properties: Record<string, unknown>;
+}
+export interface CompiledRobotics {
+    name: string;
+    keyword: string;
+    /** Joint type: revolute, prismatic, continuous, fixed, floating, planar */
+    jointType?: string;
+    /** Joint limits (radians for revolute, meters for prismatic) */
+    jointLimits?: {
+        lower: number;
+        upper: number;
+        effort: number;
+        velocity: number;
+    };
+    /** Drive/controller type: position, velocity, effort */
+    driveType?: string;
+    /** Controller algorithm: pid, mpc, lqr, impedance */
+    controllerType?: string;
+    /** End effector type: parallel_gripper, suction_gripper, welding_torch, etc. */
+    effectorType?: string;
+    /** Sensor type: camera, imu, lidar, force_torque, contact */
+    sensorType?: string;
+    /** ROS 2 compatibility flags */
+    ros2?: {
+        packageName?: string;
+        nodeType?: string;
+        topicName?: string;
+    };
+    /** Safety rating (ISO 10218, TS 15066) */
+    safetyRating?: string;
+    /** Traits applied */
+    traits: string[];
+    /** Extra properties */
+    properties: Record<string, unknown>;
+}
+export interface CompiledIoT {
+    name: string;
+    keyword: string;
+    /** Device type: sensor, actuator, gateway, controller */
+    deviceType?: string;
+    /** Communication protocol: mqtt, coap, http, websocket, zigbee, ble */
+    protocol?: string;
+    /** Telemetry fields to stream */
+    telemetryFields?: string[];
+    /** Update interval in milliseconds */
+    updateInterval?: number;
+    /** Digital twin model reference */
+    twinModel?: string;
+    /** Data bindings (property -> source) */
+    bindings?: Record<string, string>;
+    traits: string[];
+    properties: Record<string, unknown>;
+}
+export interface CompiledDataViz {
+    name: string;
+    keyword: string;
+    /** Chart type: bar, line, scatter, pie, heatmap, treemap, network */
+    chartType?: string;
+    /** Data source reference or inline data */
+    dataSource?: string;
+    /** Axes configuration */
+    axes?: [string, string, string];
+    /** Metric aggregation: sum, avg, min, max, count */
+    aggregation?: string;
+    /** Refresh interval in ms */
+    refreshInterval?: number;
+    /** Widget dimensions */
+    dimensions?: {
+        width: number;
+        height: number;
+    };
+    traits: string[];
+    properties: Record<string, unknown>;
+}
+export interface CompiledEducation {
+    name: string;
+    keyword: string;
+    /** Content type: lesson, quiz, curriculum, exercise */
+    contentType?: string;
+    /** Difficulty level: beginner, intermediate, advanced */
+    difficulty?: string;
+    /** Learning objectives */
+    objectives?: string[];
+    /** Quiz questions (for quiz keyword) */
+    questions?: Array<{
+        question: string;
+        options?: string[];
+        answer?: string;
+    }>;
+    /** Prerequisites (lesson/module names) */
+    prerequisites?: string[];
+    /** Estimated duration in minutes */
+    duration?: number;
+    traits: string[];
+    properties: Record<string, unknown>;
+}
+export interface CompiledMusic {
+    name: string;
+    keyword: string;
+    /** Instrument type: synth, sampler, drum_machine, effect */
+    instrumentType?: string;
+    /** Tempo in BPM */
+    bpm?: number;
+    /** Time signature: [numerator, denominator] */
+    timeSignature?: [number, number];
+    /** Key signature: C, Am, F#m, etc. */
+    key?: string;
+    /** Audio effect chain names */
+    effects?: string[];
+    /** Sequence pattern (note data) */
+    pattern?: string;
+    /** Number of bars/measures */
+    bars?: number;
+    traits: string[];
+    properties: Record<string, unknown>;
+}
+export interface CompiledArchitecture {
+    name: string;
+    keyword: string;
+    /** Structure type: room, floor, building, zone */
+    structureType?: string;
+    /** Floor area in square meters */
+    area?: number;
+    /** Height in meters */
+    height?: number;
+    /** Wall material */
+    wallMaterial?: string;
+    /** Floor material */
+    floorMaterial?: string;
+    /** HVAC zone temperature setpoint (Celsius) */
+    temperatureSetpoint?: number;
+    /** Occupancy capacity */
+    capacity?: number;
+    /** Building code reference */
+    buildingCode?: string;
+    traits: string[];
+    properties: Record<string, unknown>;
+}
+export interface CompiledWeb3 {
+    name: string;
+    keyword: string;
+    /** Contract/token standard: ERC20, ERC721, ERC1155, custom */
+    standard?: string;
+    /** Blockchain network: ethereum, polygon, base, solana, arbitrum */
+    network?: string;
+    /** Contract address */
+    contractAddress?: string;
+    /** ABI function signatures */
+    functions?: string[];
+    /** Token supply (for token keyword) */
+    supply?: number;
+    /** Governance voting threshold */
+    votingThreshold?: number;
+    traits: string[];
+    properties: Record<string, unknown>;
+}
+export interface CompiledProcedural {
+    name: string;
+    keyword: string;
+    /** Generation type: terrain, scatter, distribute, L-system, noise */
+    genType?: string;
+    /** Random seed */
+    seed?: number;
+    /** Density for scatter/distribute */
+    density?: number;
+    /** Scale range [min, max] */
+    scaleRange?: [number, number];
+    /** Noise parameters */
+    noise?: {
+        type: string;
+        octaves: number;
+        frequency: number;
+        amplitude: number;
+    };
+    /** Source mesh/prefab to scatter */
+    sourceMesh?: string;
+    traits: string[];
+    properties: Record<string, unknown>;
+}
+export interface CompiledRendering {
+    name: string;
+    keyword: string;
+    /** LOD levels with distance thresholds */
+    lodLevels?: Array<{
+        distance: number;
+        mesh?: string;
+        detail?: number;
+    }>;
+    /** Render layer/queue */
+    renderLayer?: string;
+    /** Shadow mode: none, cast, receive, both */
+    shadowMode?: string;
+    /** Culling mode: none, frustum, occlusion */
+    cullingMode?: string;
+    /** Draw order priority */
+    sortOrder?: number;
+    traits: string[];
+    properties: Record<string, unknown>;
+}
+export interface CompiledNavigation {
+    name: string;
+    keyword: string;
+    /** Agent radius for navmesh generation */
+    agentRadius?: number;
+    /** Agent height */
+    agentHeight?: number;
+    /** Max slope angle in degrees */
+    maxSlope?: number;
+    /** Step height */
+    stepHeight?: number;
+    /** Agent speed */
+    speed?: number;
+    /** Avoidance priority */
+    avoidancePriority?: number;
+    /** Behavior tree root node type */
+    behaviorRoot?: string;
+    traits: string[];
+    properties: Record<string, unknown>;
+}
+export interface CompiledInput {
+    name: string;
+    keyword: string;
+    /** Input type: button, axis, gesture, gaze, hand_tracking */
+    inputType?: string;
+    /** Platform binding: keyboard, gamepad, vr_controller, touch */
+    platform?: string;
+    /** Key/button binding */
+    binding?: string;
+    /** Action name mapped to this input */
+    action?: string;
+    /** Gesture recognition threshold */
+    threshold?: number;
+    /** Interaction distance (for spatial inputs) */
+    interactionDistance?: number;
+    traits: string[];
+    properties: Record<string, unknown>;
+}
+/**
+ * Norm lifecycle phase identifiers (CRSEC model).
+ *
+ * - creation:   How the norm is proposed and authored
+ * - representation: Formal encoding of the norm's rules and constraints
+ * - spreading:  How the norm propagates through agent communication/observation
+ * - evaluation: Sanity checks and acceptance criteria for norm adoption
+ * - compliance: Enforcement, violation detection, and sanction application
+ */
+export type NormLifecyclePhase = 'creation' | 'representation' | 'spreading' | 'evaluation' | 'compliance';
+/**
+ * Status of a norm within its lifecycle
+ */
+export type NormStatus = 'draft' | 'proposed' | 'voting' | 'adopted' | 'suspended' | 'deprecated' | 'revoked' | 'contested';
+/**
+ * Voting mechanism for norm proposals
+ */
+export type NormVotingMechanism = 'majority' | 'supermajority' | 'consensus' | 'weighted' | 'liquid_democracy' | 'quadratic' | 'ranked_choice' | 'lazy_consensus';
+/**
+ * Norm violation severity level
+ */
+export type NormViolationSeverity = 'info' | 'warning' | 'minor' | 'moderate' | 'major' | 'critical';
+/**
+ * Sanction type applied for norm violations
+ */
+export type NormSanctionType = 'warn' | 'restrict' | 'penalize' | 'suspend' | 'ban' | 'quarantine' | 'escalate' | 'custom';
+/**
+ * How a norm spreads through the agent population
+ */
+export type NormSpreadingMechanism = 'broadcast' | 'observation' | 'communication' | 'imitation' | 'enforcement' | 'passive';
+/**
+ * A first-class norm declaration in a HoloScript composition.
+ *
+ * Grammar:
+ * ```holoscript
+ * norm "NoSpamming" {
+ *   description: "Agents must not send unsolicited messages"
+ *   category: "communication"
+ *   priority: 8
+ *
+ *   creation {
+ *     author: "system"
+ *     rationale: "Prevent message flooding in shared spaces"
+ *     initial_status: "proposed"
+ *   }
+ *
+ *   representation {
+ *     condition: "message_count_per_minute < 10"
+ *     scope: "all_agents"
+ *     exceptions: ["system_announcements", "emergency_alerts"]
+ *   }
+ *
+ *   spreading {
+ *     mechanism: "broadcast"
+ *     visibility: "public"
+ *     adoption_incentive: 5
+ *   }
+ *
+ *   evaluation {
+ *     voting: "majority"
+ *     quorum: 0.6
+ *     approval_threshold: 0.5
+ *     review_period: 86400
+ *     auto_adopt: false
+ *   }
+ *
+ *   compliance {
+ *     monitoring: "continuous"
+ *     violation_threshold: 3
+ *     severity: "moderate"
+ *     sanctions: ["warn", "restrict", "suspend"]
+ *     appeal_allowed: true
+ *     grace_period: 3600
+ *   }
+ * }
+ * ```
+ */
+export interface HoloNormBlock extends HoloNode {
+    type: 'NormBlock';
+    /** Name of the norm */
+    name: string;
+    /** Trait decorators on the norm (e.g. @enforceable @community_driven) */
+    traits: string[];
+    /** Top-level norm properties (description, category, priority, etc.) */
+    properties: Record<string, HoloValue>;
+    /** Creation phase: how the norm is proposed and authored */
+    creation?: HoloNormCreation;
+    /** Representation phase: formal rule encoding */
+    representation?: HoloNormRepresentation;
+    /** Spreading phase: propagation through the agent population */
+    spreading?: HoloNormSpreading;
+    /** Evaluation phase: acceptance criteria and voting rules */
+    evaluation?: HoloNormEvaluation;
+    /** Compliance phase: enforcement, violation, and sanctions */
+    compliance?: HoloNormCompliance;
+    /** Event handlers for norm lifecycle events */
+    eventHandlers?: HoloEventHandler[];
+    /** @platform() conditional compilation constraint */
+    platformConstraint?: PlatformConstraint;
+}
+/**
+ * Creation phase — how the norm originates.
+ */
+export interface HoloNormCreation extends HoloNode {
+    type: 'NormCreation';
+    properties: Record<string, HoloValue>;
+}
+/**
+ * Representation phase — formal encoding of the norm's constraints.
+ */
+export interface HoloNormRepresentation extends HoloNode {
+    type: 'NormRepresentation';
+    properties: Record<string, HoloValue>;
+}
+/**
+ * Spreading phase — how the norm propagates through the population.
+ */
+export interface HoloNormSpreading extends HoloNode {
+    type: 'NormSpreading';
+    properties: Record<string, HoloValue>;
+}
+/**
+ * Evaluation phase — sanity checks, voting, and acceptance criteria.
+ */
+export interface HoloNormEvaluation extends HoloNode {
+    type: 'NormEvaluation';
+    properties: Record<string, HoloValue>;
+}
+/**
+ * Compliance phase — enforcement, violation detection, and sanctions.
+ */
+export interface HoloNormCompliance extends HoloNode {
+    type: 'NormCompliance';
+    properties: Record<string, HoloValue>;
+}
+/**
+ * A metanorm declaration: governance rules about the norm system itself.
+ *
+ * Grammar:
+ * ```holoscript
+ * metanorm "NormAmendmentProcess" {
+ *   description: "Rules for proposing changes to existing norms"
+ *   applies_to: "all_norms"
+ *
+ *   rules {
+ *     amendment_quorum: 0.75
+ *     amendment_voting: "supermajority"
+ *     cooldown_period: 604800
+ *     max_amendments_per_cycle: 3
+ *     retroactive_allowed: false
+ *   }
+ *
+ *   escalation {
+ *     authority: "governance_council"
+ *     override_threshold: 0.9
+ *     appeal_levels: 2
+ *   }
+ *
+ *   on norm_conflict(normA, normB) {
+ *     emit("norm_conflict_detected", { a: normA, b: normB })
+ *   }
+ * }
+ * ```
+ */
+export interface HoloMetanorm extends HoloNode {
+    type: 'Metanorm';
+    /** Name of the metanorm */
+    name: string;
+    /** Trait decorators */
+    traits: string[];
+    /** Top-level metanorm properties */
+    properties: Record<string, HoloValue>;
+    /** Governance rules sub-block */
+    rules?: HoloMetanormRules;
+    /** Escalation sub-block */
+    escalation?: HoloMetanormEscalation;
+    /** Event handlers for metanorm events */
+    eventHandlers?: HoloEventHandler[];
+}
+/**
+ * Metanorm governance rules sub-block.
+ */
+export interface HoloMetanormRules extends HoloNode {
+    type: 'MetanormRules';
+    properties: Record<string, HoloValue>;
+}
+/**
+ * Metanorm escalation sub-block.
+ */
+export interface HoloMetanormEscalation extends HoloNode {
+    type: 'MetanormEscalation';
+    properties: Record<string, HoloValue>;
+}
+/**
+ * A single named clause in a contract block.
+ *
+ * Used for both preconditions (entry checks) and invariants (continuous checks).
+ */
+export interface HoloContractClause {
+    /** Unique clause name, e.g. "gravity_set" */
+    name: string;
+    /** Raw expression string — evaluated by the SimulationContract verifier. */
+    expr: string;
+    /** Optional human-readable description of what this clause checks. */
+    description?: string;
+}
+/**
+ * Declarative contract block for a `.holo` composition.
+ *
+ * Authors write preconditions (entry checks), invariants (continuous checks),
+ * and a receipt shape (what a successful execution produces). These feed the
+ * SimulationContract CPU verifier gate in DispatchPolicy.
+ *
+ * Syntax:
+ * ```
+ * sim_contract {
+ *   precondition "gravity_set" { gravity != null }
+ *   precondition "arena_bounded" "arena radius must be positive" { arena.radius > 0 }
+ *   invariant "energy_conserved" { total_energy <= initial_energy + 0.001 }
+ *   receipt { winner: string, final_score: number, elapsed_ms: number }
+ * }
+ * ```
+ */
+export interface HoloContract extends HoloNode {
+    type: 'contract';
+    /** Named entry conditions that must hold before the composition runs. */
+    preconditions: HoloContractClause[];
+    /** Named properties that must hold throughout execution. */
+    invariants: HoloContractClause[];
+    /**
+     * Shape of the receipt produced upon successful completion.
+     * Keys are field names; values are type annotations (string).
+     */
+    receipt: Record<string, string>;
+}
+/**
+ * Named regulatory bundle for regulated AI deployments.
+ *
+ * Syntax:
+ * ```holoscript
+ * policy_pack fair_lending_v1 {
+ *   version: "2026.06"
+ *   framework_id: CFPB_FAIR_LENDING
+ *   required_tests: [
+ *     { id: "four_fifths", protected_attribute: "race", adverse_impact_ratio_min: 0.8 }
+ *   ]
+ *   required_compile_targets: ["model_card", "impact_assessment"]
+ *   audit_retention { min_days: 2555 storage: "immutable_ledger" }
+ *   monitoring { interval: "quarterly" drift_sweep_required: true }
+ * }
+ * ```
+ */
+export interface HoloPolicyPackBlock extends HoloNode {
+    type: 'PolicyPack';
+    name: string;
+    version: string;
+    frameworkId: string;
+    requiredTests: HoloValue[];
+    requiredCompileTargets: string[];
+    auditRetention: Record<string, HoloValue>;
+    monitoringCadence: Record<string, HoloValue>;
+    properties: Record<string, HoloValue>;
+}
+/**
+ * Named pub/sub topic declaration.
+ *
+ * ```holoscript
+ * topic InventoryUpdate {
+ *   type: "InventoryDelta"
+ *   broadcast: true
+ * }
+ * ```
+ */
+export interface HoloTopic extends HoloNode {
+    type: 'Topic';
+    name: string;
+    /** Payload type annotation (string label, not validated by parser). */
+    dataType?: string;
+    /** When true, all subscribers receive every message (fan-out). */
+    broadcast?: boolean;
+    /** Additional key-value metadata. */
+    metadata?: Record<string, HoloValue>;
+}
+/**
+ * Typed directional channel connecting two named nodes.
+ *
+ * ```holoscript
+ * channel PlayerUpdates {
+ *   from: PlayerState
+ *   to: HUD
+ *   capacity: 64
+ * }
+ * ```
+ */
+export interface HoloChannel extends HoloNode {
+    type: 'Channel';
+    name: string;
+    /** Source node name. */
+    from?: string;
+    /** Destination node name. */
+    to?: string;
+    /** Maximum buffered messages (0 = unbounded). */
+    capacity?: number;
+    /** Additional key-value metadata. */
+    metadata?: Record<string, HoloValue>;
+}
+/**
+ * Declarative natural-language graph connection.
+ *
+ * ```holoscript
+ * connect PlayerState to HUD
+ * connect PlayerState to HUD as "updates"
+ * ```
+ */
+export interface HoloConnection extends HoloNode {
+    type: 'Connection';
+    /** Source node identifier. */
+    from: string;
+    /** Destination node identifier. */
+    to: string;
+    /** Optional edge-type label (the string after `as`). */
+    edgeType?: string;
+}