qnce-engine 1.3.1 → 1.4.1

package/dist/engine/core.js

@@ -1,6 +1,29 @@
 "use strict";
 // QNCE Core Engine - Framework Agnostic
 // Quantum Narrative Convergence Engine
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QNCEEngine = exports.ChoiceValidationError = exports.QNCENavigationError = void 0;
 exports.createQNCEEngine = createQNCEEngine;
@@ -19,8 +42,13 @@ Object.defineProperty(exports, "QNCENavigationError", { enumerable: true, get: f
 Object.defineProperty(exports, "ChoiceValidationError", { enumerable: true, get: function () { return errors_2.ChoiceValidationError; } });
 // State persistence imports - Sprint 3.3
 const types_1 = require("./types");
+const logger_1 = require("../utils/logger");
 // Conditional choice evaluator - Sprint 3.4
 const condition_1 = require("./condition");
+const error_factory_1 = require("./error-factory");
+const debug_logger_1 = require("../utils/debug-logger");
+const hot_profiler_1 = require("../utils/hot-profiler");
+const intern_1 = require("../utils/intern");
 // Demo narrative data moved to demo-story.ts
 function findNode(nodes, id) {
     const node = nodes.find(n => n.id === id);
@@ -32,18 +60,45 @@ function findNode(nodes, id) {
  * QNCE Engine - Core narrative state management
  * Framework agnostic implementation with object pooling integration
  */
+/**
+ * Main engine class.
+ * @public
+ */
 class QNCEEngine {
     state;
     storyData; // Made public for hot-reload compatibility
     activeFlowEvents = [];
     performanceMode = false;
     enableProfiling = false;
+    debugMode = false;
     branchingEngine;
     choiceValidator; // Sprint 3.2: Choice validation
     // Sprint 3.3: State persistence and checkpoints
     checkpoints = new Map();
     maxCheckpoints = 50;
     autoCheckpointEnabled = false;
+    // Flag pooling to reduce duplicate string allocations
+    flagKeyPool = new Map();
+    flagValuePool = new Map();
+    internFlagKey(raw) {
+        let pooled = this.flagKeyPool.get(raw);
+        if (!pooled) {
+            this.flagKeyPool.set(raw, raw);
+            pooled = raw;
+        }
+        return pooled;
+    }
+    internFlagValue(val) {
+        if (typeof val === 'string' && val.length <= 64) { // limit to modest strings
+            let pooled = this.flagValuePool.get(val);
+            if (!pooled) {
+                this.flagValuePool.set(val, val);
+                pooled = val;
+            }
+            return pooled;
+        }
+        return val;
+    }
     // Sprint 3.3: State persistence properties
     checkpointManager;
     // Sprint 3.5: Autosave and Undo/Redo properties
@@ -67,12 +122,32 @@ class QNCEEngine {
     lastAutosaveTime = 0;
     isUndoRedoOperation = false;
     storageAdapter;
+    // Storage retry policy (initial simple implementation)
+    storageRetryPolicy = {
+        maxAttempts: 3,
+        baseDelayMs: 5,
+        factor: 2,
+        maxDelayMs: 100,
+        jitter: true
+    };
+    // Sprint 4.1: Telemetry support
+    telemetry;
+    defaultTelemetryCtx;
+    // Hooks
+    preChoiceHooks = [];
+    postChoiceHooks = [];
+    hookCounter = 0;
+    logger = (0, logger_1.createLogger)({ level: 'warn' });
+    engineOptions;
+    minimalTelemetry = false;
     get flags() {
         return this.state.flags;
     }
     get history() {
         return this.state.history;
     }
+    /** Access the engine logger (public read-only) */
+    getLogger() { return this.logger; }
     get isComplete() {
         try {
             return this.getCurrentNode().choices.length === 0;
@@ -81,10 +156,16 @@ class QNCEEngine {
             return true; // If current node not found, consider it complete
         }
     }
-    constructor(storyData, initialState, performanceMode = false, threadPoolConfig) {
+    constructor(storyData, initialState, performanceMode = false, threadPoolConfig, options) {
         this.storyData = storyData;
         this.performanceMode = performanceMode;
         this.enableProfiling = performanceMode; // Enable profiling with performance mode
+        if (this.performanceMode) {
+            try {
+                condition_1.conditionEvaluator.enablePooling(true);
+            }
+            catch { }
+        }
         // Initialize choice validator (Sprint 3.2)
         this.choiceValidator = (0, validation_1.createChoiceValidator)();
         // Initialize ThreadPool if in performance mode
@@ -96,39 +177,138 @@ class QNCEEngine {
             flags: initialState?.flags || {},
             history: initialState?.history || [storyData.initialNodeId],
         };
+        // Telemetry wiring
+        this.telemetry = options?.telemetry;
+        if (options?.logger)
+            this.logger = options.logger;
+        this.engineOptions = options;
+        this.minimalTelemetry = options?.minimalTelemetry ?? false;
+        if (this.telemetry) {
+            const sessionId = options?.sessionId || `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+            this.defaultTelemetryCtx = {
+                sessionId,
+                storyId: undefined,
+                appVersion: options?.appVersion,
+                engineVersion: types_1.PERSISTENCE_VERSION,
+                env: options?.env
+            };
+            try {
+                this.telemetry.emit({ type: 'session.start', payload: { initialNodeId: this.state.currentNodeId }, ts: Date.now(), ctx: this.defaultTelemetryCtx });
+            }
+            catch { }
+        }
+    }
+    /**
+     * Dispose engine resources (telemetry, performance reporter, background thread pool in perf mode)
+     * @public
+     */
+    async dispose() {
+        try {
+            if (this.telemetry)
+                await this.telemetry.dispose();
+        }
+        catch { }
+        try {
+            (0, PerfReporter_1.getPerfReporter)().dispose?.();
+        }
+        catch { }
+        if (this.performanceMode) {
+            try {
+                const { shutdownThreadPool } = await Promise.resolve().then(() => __importStar(require('../performance/ThreadPool')));
+                await shutdownThreadPool();
+            }
+            catch { }
+        }
     }
     // Lane B: StorageAdapter integration
     /** Attach a storage adapter for persistence */
     attachStorageAdapter(adapter) {
         this.storageAdapter = adapter;
     }
+    /**
+     * Configure storage retry policy for transient save failures.
+     * @param policy - Partial policy overriding defaults. Set maxAttempts to 1 to disable retries.
+     * @beta
+     */
+    setStorageRetryPolicy(policy) {
+        this.storageRetryPolicy = { ...this.storageRetryPolicy, ...policy };
+    }
+    async sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
+    computeBackoff(attempt) {
+        const { baseDelayMs, factor, maxDelayMs, jitter } = this.storageRetryPolicy;
+        const raw = Math.min(baseDelayMs * Math.pow(factor, attempt - 1), maxDelayMs);
+        if (!jitter)
+            return raw;
+        const spread = raw * 0.5;
+        return Math.max(0, raw - spread + Math.random() * spread);
+    }
     /** Save current state through the attached storage adapter */
     async saveToStorage(key, options = {}) {
         if (!this.storageAdapter)
             return { success: false, error: 'No storage adapter attached' };
+        const t0 = Date.now();
         const serialized = await this.saveState(options);
-        return this.storageAdapter.save(key, serialized, options);
+        const policy = this.storageRetryPolicy;
+        let attempt = 0;
+        let lastResult;
+        while (true) {
+            attempt++;
+            try {
+                lastResult = await this.storageAdapter.save(key, serialized, options);
+            }
+            catch (err) {
+                lastResult = { success: false, error: err?.message || 'unknown-error' };
+            }
+            if (lastResult.success || attempt >= policy.maxAttempts || policy.maxAttempts <= 1)
+                break;
+            // Only retry if explicitly failed (success === false)
+            const delay = this.computeBackoff(attempt);
+            await this.sleep(delay);
+        }
+        try {
+            this.telemetry?.emit({ type: 'storage.op', payload: { op: 'save', key, ms: Date.now() - t0, ok: !!lastResult?.success, attempts: attempt, maxAttempts: policy.maxAttempts }, ts: Date.now(), ctx: this.defaultTelemetryCtx });
+        }
+        catch { }
+        return lastResult || { success: false, error: 'unknown' };
     }
     /** Load state from the attached storage adapter */
     async loadFromStorage(key, options = {}) {
         if (!this.storageAdapter)
             return { success: false, error: 'No storage adapter attached' };
+        const t0 = Date.now();
         const serialized = await this.storageAdapter.load(key, options);
         if (!serialized)
             return { success: false, error: `No data for key: ${key}` };
-        return this.loadState(serialized, options);
+        const res = await this.loadState(serialized, options);
+        try {
+            this.telemetry?.emit({ type: 'storage.op', payload: { op: 'load', key, ms: Date.now() - t0, ok: !!res?.success }, ts: Date.now(), ctx: this.defaultTelemetryCtx });
+        }
+        catch { }
+        return res;
     }
     /** Delete a stored state via the adapter */
     async deleteFromStorage(key) {
         if (!this.storageAdapter)
             return false;
-        return this.storageAdapter.delete(key);
+        const t0 = Date.now();
+        const ok = await this.storageAdapter.delete(key);
+        try {
+            this.telemetry?.emit({ type: 'storage.op', payload: { op: 'delete', key, ms: Date.now() - t0, ok }, ts: Date.now(), ctx: this.defaultTelemetryCtx });
+        }
+        catch { }
+        return ok;
     }
     /** List keys from the adapter */
     async listStorageKeys() {
         if (!this.storageAdapter)
             return [];
-        return this.storageAdapter.list();
+        const t0 = Date.now();
+        const keys = await this.storageAdapter.list();
+        try {
+            this.telemetry?.emit({ type: 'storage.op', payload: { op: 'list', count: keys.length, ms: Date.now() - t0, ok: true }, ts: Date.now(), ctx: this.defaultTelemetryCtx });
+        }
+        catch { }
+        return keys;
     }
     /** Check if a key exists via the adapter */
     async storageExists(key) {
@@ -140,7 +320,13 @@ class QNCEEngine {
     async clearStorage() {
         if (!this.storageAdapter)
             return false;
-        return this.storageAdapter.clear();
+        const t0 = Date.now();
+        const ok = await this.storageAdapter.clear();
+        try {
+            this.telemetry?.emit({ type: 'storage.op', payload: { op: 'clear', ms: Date.now() - t0, ok }, ts: Date.now(), ctx: this.defaultTelemetryCtx });
+        }
+        catch { }
+        return ok;
     }
     /** Get storage statistics from the adapter */
     async getStorageStats() {
@@ -152,7 +338,7 @@ class QNCEEngine {
     /**
      * Navigate directly to a specific node by ID
      * @param nodeId - The ID of the node to navigate to
-     * @throws {QNCENavigationError} When nodeId is invalid or not found
+    * @throws \{QNCENavigationError\} When nodeId is invalid or not found
      */
     goToNodeById(nodeId) {
         // Validate node exists
@@ -210,7 +396,12 @@ class QNCEEngine {
                 choices: pooledNode.choices
             };
         }
-        return findNode(this.storyData.nodes, this.state.currentNodeId);
+        const node = findNode(this.storyData.nodes, this.state.currentNodeId);
+        try {
+            this.telemetry?.emit({ type: 'node.enter', payload: this.minimalTelemetry ? node.id : { nodeId: node.id }, ts: Date.now(), ctx: this.defaultTelemetryCtx });
+        }
+        catch { }
+        return node;
     }
     /**
      * Get available choices from the current node with validation and conditional filtering
@@ -223,6 +414,22 @@ class QNCEEngine {
             timestamp: Date.now(),
             customData: {}
         };
+        // Performance-mode choice array pooling: reuse a scratch array to avoid per-call allocations
+        let scratch;
+        if (this.performanceMode) {
+            // Lazily allocate a shared scratch array on first use and clear in-place
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore - attach hidden field for pooling (internal only)
+            if (!this.__choiceScratch) { /* eslint-disable-line */
+                // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                // @ts-ignore
+                this.__choiceScratch = []; /* eslint-disable-line */
+            }
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore
+            scratch = this.__choiceScratch; /* eslint-disable-line */
+            scratch.length = 0;
+        }
         // First apply conditional filtering (Sprint 3.4)
         const conditionallyAvailable = currentNode.choices.filter((choice) => {
             // If no condition is specified, choice is always available
@@ -231,19 +438,58 @@ class QNCEEngine {
             }
             try {
                 // Evaluate the condition using the condition evaluator
-                return condition_1.conditionEvaluator.evaluate(choice.condition, context);
+                const t0 = Date.now();
+                const res = hot_profiler_1.globalHotProfiler.wrap('condition.evaluate', () => condition_1.conditionEvaluator.evaluate(choice.condition, context));
+                try {
+                    this.telemetry?.emit({ type: 'expression.evaluate', payload: this.minimalTelemetry ? 1 : { ok: true, ms: Date.now() - t0 }, ts: Date.now(), ctx: this.defaultTelemetryCtx });
+                }
+                catch { }
+                if (this.debugMode)
+                    debug_logger_1.globalDebugLogger.log('condition.ok', { nodeId: this.state.currentNodeId, choiceText: choice.text, expr: choice.condition });
+                return res;
             }
             catch (error) {
                 // Log condition evaluation errors but don't block other choices
                 if (error instanceof condition_1.ConditionEvaluationError) {
-                    console.warn(`[QNCE] Choice condition evaluation failed: ${error.message}`, {
+                    const struct = error_factory_1.ErrorFactory.condition('Choice condition evaluation failed', {
                         choiceText: choice.text,
-                        condition: choice.condition,
-                        nodeId: this.state.currentNodeId
+                        conditionExpression: choice.condition,
+                        nodeId: this.state.currentNodeId,
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        storyId: this.storyData?.id,
+                        cause: error
                     });
+                    // eslint-disable-next-line no-console
+                    this.logger.warn('[QNCE] ' + (0, error_factory_1.serializeStructuredError)(struct));
+                    try {
+                        this.telemetry?.emit({ type: 'engine.structuredError', payload: (0, error_factory_1.serializeStructuredError)(struct), ts: Date.now(), ctx: this.defaultTelemetryCtx });
+                    }
+                    catch { }
+                    try {
+                        this.telemetry?.emit({ type: 'expression.evaluate', payload: this.minimalTelemetry ? 0 : { ok: false, error: 'ConditionEvaluationError' }, ts: Date.now(), ctx: this.defaultTelemetryCtx });
+                    }
+                    catch { }
                 }
                 else {
-                    console.warn(`[QNCE] Unexpected error evaluating choice condition:`, error);
+                    const struct = error_factory_1.ErrorFactory.condition('Unexpected error evaluating choice condition', {
+                        choiceText: choice.text,
+                        conditionExpression: choice.condition,
+                        nodeId: this.state.currentNodeId,
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        storyId: this.storyData?.id,
+                        cause: error
+                    });
+                    // eslint-disable-next-line no-console
+                    this.logger.warn('[QNCE] ' + (0, error_factory_1.serializeStructuredError)(struct));
+                    try {
+                        this.telemetry?.emit({ type: 'engine.structuredError', payload: (0, error_factory_1.serializeStructuredError)(struct), ts: Date.now(), ctx: this.defaultTelemetryCtx });
+                    }
+                    catch { }
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    try {
+                        this.telemetry?.emit({ type: 'engine.error', payload: { where: 'getAvailableChoices', error: error?.message || String(error) }, ts: Date.now(), ctx: this.defaultTelemetryCtx });
+                    }
+                    catch { }
                 }
                 // Return false for invalid conditions (choice won't be shown)
                 return false;
@@ -252,7 +498,14 @@ class QNCEEngine {
         // Then apply choice validation (Sprint 3.2)
         const validationContext = (0, validation_1.createValidationContext)(currentNode, this.state, conditionallyAvailable // Pass the conditionally filtered choices
         );
-        return this.choiceValidator.getAvailableChoices(validationContext);
+        const validated = this.choiceValidator.getAvailableChoices(validationContext);
+        if (!this.performanceMode || !scratch)
+            return validated;
+        // Copy into scratch to present a stable pooled array (avoid leaking validator's array if it allocates)
+        for (let i = 0; i < validated.length; i++)
+            scratch[i] = validated[i];
+        scratch.length = validated.length;
+        return scratch;
     }
     makeChoice(choiceIndex) {
         const choices = this.getAvailableChoices();
@@ -277,9 +530,13 @@ class QNCEEngine {
         return { ...this.state.flags };
     }
     setFlag(key, value) {
+        if (this.debugMode)
+            debug_logger_1.globalDebugLogger.log('flag.set', { key, value });
         // Sprint 3.5: Save state for undo before making changes
         const preChangeState = this.deepCopy(this.state);
-        this.state.flags[key] = value;
+        const pooledKey = this.internFlagKey(key);
+        const pooledValue = this.internFlagValue(value);
+        this.state.flags[pooledKey] = pooledValue;
         // Sprint 3.5: Track state change for undo/redo
         if (this.undoRedoConfig.enabled && !this.isUndoRedoOperation &&
             this.undoRedoConfig.trackActions.includes('flag-change')) {
@@ -294,7 +551,20 @@ class QNCEEngine {
                 flagKey: key,
                 flagValue: value
             }).catch((error) => {
-                console.warn('[QNCE] Autosave failed:', error.message);
+                const struct = error_factory_1.ErrorFactory.persistence('Autosave failed', {
+                    operation: 'autosave',
+                    flagKey: key,
+                    flagValue: value,
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    storyId: this.storyData?.id,
+                    cause: error
+                });
+                // eslint-disable-next-line no-console
+                this.logger.warn('[QNCE] ' + (0, error_factory_1.serializeStructuredError)(struct));
+                try {
+                    this.telemetry?.emit({ type: 'engine.structuredError', payload: (0, error_factory_1.serializeStructuredError)(struct), ts: Date.now(), ctx: this.defaultTelemetryCtx });
+                }
+                catch { }
             });
         }
     }
@@ -302,6 +572,35 @@ class QNCEEngine {
         return [...this.state.history];
     }
     selectChoice(choice) {
+        if (this.debugMode)
+            debug_logger_1.globalDebugLogger.log('choice.select.start', { from: this.state.currentNodeId, to: choice.nextNodeId, choiceText: choice.text });
+        // Pre-choice hooks (ordered by priority desc then registration order)
+        if (this.preChoiceHooks.length) {
+            const currentNodeForHooks = this.getCurrentNode();
+            for (const hook of this.preChoiceHooks) {
+                try {
+                    const res = hook.h({ engine: this, node: currentNodeForHooks, choice });
+                    if (res === false)
+                        return; // cancellation
+                }
+                catch (e) {
+                    const struct = error_factory_1.ErrorFactory.hook('pre-choice hook error', {
+                        hookStage: 'pre-choice',
+                        nodeId: currentNodeForHooks.id,
+                        choiceText: choice.text,
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        storyId: this.storyData?.id,
+                        cause: e
+                    });
+                    // eslint-disable-next-line no-console
+                    this.logger.warn('[QNCE] ' + (0, error_factory_1.serializeStructuredError)(struct));
+                    try {
+                        this.telemetry?.emit({ type: 'engine.structuredError', payload: (0, error_factory_1.serializeStructuredError)(struct), ts: Date.now(), ctx: this.defaultTelemetryCtx });
+                    }
+                    catch { }
+                }
+            }
+        }
         // Sprint 3.5: Save state for undo before making changes
         const preChangeState = this.deepCopy(this.state);
         // S2-T4: Add state transition profiling
@@ -314,6 +613,11 @@ class QNCEEngine {
             : null;
         const fromNodeId = this.state.currentNodeId;
         const toNodeId = choice.nextNodeId;
+        // Telemetry: choice.select
+        try {
+            this.telemetry?.emit({ type: 'choice.select', payload: { fromNodeId, toNodeId, choiceText: choice.text }, ts: Date.now(), ctx: this.defaultTelemetryCtx });
+        }
+        catch { }
         // Create flow event for tracking narrative progression
         if (this.performanceMode) {
             const flowSpanId = this.enableProfiling
@@ -357,9 +661,50 @@ class QNCEEngine {
                 toNodeId,
                 choiceText: choice.text
             }).catch(error => {
-                console.warn('[QNCE] Autosave failed:', error.message);
+                const struct = error_factory_1.ErrorFactory.persistence('Autosave failed', {
+                    operation: 'autosave',
+                    fromNodeId,
+                    toNodeId,
+                    choiceText: choice.text,
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    storyId: this.storyData?.id,
+                    cause: error
+                });
+                // eslint-disable-next-line no-console
+                this.logger.warn('[QNCE] ' + (0, error_factory_1.serializeStructuredError)(struct));
+                try {
+                    this.telemetry?.emit({ type: 'engine.structuredError', payload: (0, error_factory_1.serializeStructuredError)(struct), ts: Date.now(), ctx: this.defaultTelemetryCtx });
+                }
+                catch { }
             });
         }
+        // Post-choice hooks
+        if (this.postChoiceHooks.length) {
+            const nodeAfter = this.getCurrentNode();
+            for (const hook of this.postChoiceHooks) {
+                try {
+                    hook.h({ engine: this, node: nodeAfter, choice });
+                }
+                catch (e) {
+                    const struct = error_factory_1.ErrorFactory.hook('post-choice hook error', {
+                        hookStage: 'post-choice',
+                        nodeId: nodeAfter.id,
+                        choiceText: choice.text,
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        storyId: this.storyData?.id,
+                        cause: e
+                    });
+                    // eslint-disable-next-line no-console
+                    this.logger.warn('[QNCE] ' + (0, error_factory_1.serializeStructuredError)(struct));
+                    try {
+                        this.telemetry?.emit({ type: 'engine.structuredError', payload: (0, error_factory_1.serializeStructuredError)(struct), ts: Date.now(), ctx: this.defaultTelemetryCtx });
+                    }
+                    catch { }
+                }
+            }
+        }
+        if (this.debugMode)
+            debug_logger_1.globalDebugLogger.log('choice.select.end', { to: this.state.currentNodeId });
         // Complete state transition span
         if (transitionSpanId) {
             (0, PerfReporter_1.getPerfReporter)().endSpan(transitionSpanId, {
@@ -371,7 +716,19 @@ class QNCEEngine {
         if (this.performanceMode) {
             // Preload next possible nodes in background
             this.preloadNextNodes().catch(error => {
-                console.warn('[QNCE] Background preload failed:', error.message);
+                const struct = error_factory_1.ErrorFactory.state('Background preload failed', {
+                    operation: 'preloadNextNodes',
+                    nodeId: toNodeId,
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    storyId: this.storyData?.id,
+                    cause: error
+                });
+                // eslint-disable-next-line no-console
+                this.logger.warn('[QNCE] ' + (0, error_factory_1.serializeStructuredError)(struct));
+                try {
+                    this.telemetry?.emit({ type: 'engine.structuredError', payload: (0, error_factory_1.serializeStructuredError)(struct), ts: Date.now(), ctx: this.defaultTelemetryCtx });
+                }
+                catch { }
             });
             // Write telemetry data in background  
             this.backgroundTelemetryWrite({
@@ -380,10 +737,51 @@ class QNCEEngine {
                 toNodeId,
                 choiceText: choice.text.slice(0, 50) // First 50 chars for privacy
             }).catch(error => {
-                console.warn('[QNCE] Background telemetry failed:', error.message);
+                const struct = error_factory_1.ErrorFactory.telemetry('Background telemetry failed', {
+                    operation: 'backgroundTelemetryWrite',
+                    fromNodeId,
+                    toNodeId,
+                    choiceText: choice.text,
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    storyId: this.storyData?.id,
+                    cause: error
+                });
+                // eslint-disable-next-line no-console
+                this.logger.warn('[QNCE] ' + (0, error_factory_1.serializeStructuredError)(struct));
             });
         }
     }
+    // eslint-disable-next-line @typescript-eslint/no-inferrable-types
+    registerHook(type, handler, priority = 0) {
+        const list = type === 'pre-choice' ? this.preChoiceHooks : this.postChoiceHooks;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const entry = { h: handler, p: priority, o: this.hookCounter++ };
+        list.push(entry);
+        list.sort((a, b) => (b.p - a.p) || (a.o - b.o));
+        return () => {
+            const idx = list.indexOf(entry);
+            if (idx >= 0)
+                list.splice(idx, 1);
+        };
+    }
+    /** Clear all hooks (testing / reset) */
+    clearHooks() { this.preChoiceHooks = []; this.postChoiceHooks = []; }
+    /** Enable verbose debug logging (stored in ring buffer) */
+    enableDebug() { this.debugMode = true; debug_logger_1.globalDebugLogger.setEnabled(true); }
+    disableDebug() { this.debugMode = false; if (!this.enableProfiling)
+        debug_logger_1.globalDebugLogger.setEnabled(false); }
+    getDebugLogs() { return debug_logger_1.globalDebugLogger.flush(); }
+    clearDebugLogs() { debug_logger_1.globalDebugLogger.clear(); }
+    /** Enable aggregated hot path profiling */
+    enableHotProfiling() { hot_profiler_1.globalHotProfiler.enable(true); }
+    disableHotProfiling() { hot_profiler_1.globalHotProfiler.enable(false); }
+    getHotProfileSummary() { return hot_profiler_1.globalHotProfiler.summary(); }
+    resetHotProfile() { hot_profiler_1.globalHotProfiler.reset(); }
+    /** Flush telemetry (useful before process exit) */
+    async flushTelemetry() { try {
+        await this.telemetry?.flush();
+    }
+    catch { } }
     resetNarrative() {
         // Sprint 3.5: Save state for undo before reset
         const preChangeState = this.deepCopy(this.state);
@@ -422,7 +820,8 @@ class QNCEEngine {
             this.triggerAutosave('state-load', {
                 nodeId: state.currentNodeId
             }).catch((error) => {
-                console.warn('[QNCE] Autosave failed:', error.message);
+                // eslint-disable-next-line no-console
+                this.logger.warn('[QNCE] Autosave failed: ' + error.message);
             });
         }
     }
@@ -480,6 +879,7 @@ class QNCEEngine {
             // Generate checksum if requested
             if (options.generateChecksum) {
                 const stateToHash = { ...serializedState };
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 delete stateToHash.metadata.checksum; // Exclude checksum from hash
                 const stateString = JSON.stringify(stateToHash);
                 metadata.checksum = await this.generateChecksum(stateString);
@@ -748,7 +1148,11 @@ class QNCEEngine {
      */
     createFlowEvent(fromNodeId, toNodeId, metadata) {
         const flow = ObjectPool_1.poolManager.borrowFlow();
-        flow.initialize(fromNodeId, metadata);
+        // In minimal telemetry mode, avoid attaching heavy metadata
+        const meta = this.minimalTelemetry ? undefined : (0, intern_1.internShallowRecord)(metadata || {});
+        // Intern node id to reduce duplicate string allocations across events
+        const fromId = (0, intern_1.internString)(fromNodeId);
+        flow.initialize(fromId, meta);
         flow.addTransition(fromNodeId, toNodeId);
         return flow;
     }
@@ -756,16 +1160,19 @@ class QNCEEngine {
      * Record and manage flow events
      */
     recordFlowEvent(flow) {
+        const toId = flow.transitions[flow.transitions.length - 1]?.split('->')[1] || '';
         const flowEvent = {
             id: `${flow.nodeId}-${Date.now()}`,
             fromNodeId: flow.nodeId,
-            toNodeId: flow.transitions[flow.transitions.length - 1]?.split('->')[1] || '',
+            toNodeId: (0, intern_1.internString)(toId),
             timestamp: flow.timestamp,
-            metadata: flow.metadata
+            // In minimal mode, drop metadata entirely
+            metadata: this.minimalTelemetry ? undefined : flow.metadata
         };
         this.activeFlowEvents.push(flowEvent);
         // Clean up old flow events (basic LRU-style cleanup)
-        if (this.activeFlowEvents.length > 10) {
+        const cap = this.minimalTelemetry ? 5 : 10;
+        if (this.activeFlowEvents.length > cap) {
             this.activeFlowEvents.shift(); // Remove oldest
         }
     }
@@ -829,7 +1236,9 @@ class QNCEEngine {
             }
         };
         threadPool.submitJob('telemetry-write', telemetryData, 'low').catch(error => {
-            console.warn('[QNCE] Telemetry write failed:', error.message);
+            if (this.engineOptions?.suppressTelemetryWarnings && error?.message === 'Job queue limit exceeded')
+                return;
+            this.logger.warn('[QNCE] Telemetry write failed: ' + error.message);
         });
     }
     // ================================
@@ -841,7 +1250,8 @@ class QNCEEngine {
      */
     enableBranching(story) {
         if (this.branchingEngine) {
-            console.warn('[QNCE] Branching already enabled for this engine instance');
+            // eslint-disable-next-line no-console
+            this.logger.warn('[QNCE] Branching already enabled for this engine instance');
             return this.branchingEngine;
         }
         // Create branching engine with current state
@@ -1003,6 +1413,7 @@ class QNCEEngine {
         if (!receivedChecksum)
             return false;
         const stateToHash = { ...serializedState };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         delete stateToHash.metadata.checksum;
         const stateString = JSON.stringify(stateToHash);
         const expectedChecksum = await this.generateChecksum(stateString);
@@ -1194,12 +1605,19 @@ class QNCEEngine {
      */
     pushToUndoStack(state, action, metadata) {
         const startTime = performance.now();
+        // Memory optimization (lightweight history): we store a shallow snapshot of flags + currentNodeId
+        // instead of deep copying full engine state. We embed it in metadata under a reserved key and keep
+        // a minimal placeholder state reference to satisfy existing types.
+        const LIGHT_STATE_KEY = '__lightState';
+        const prevHist = state?.history;
+        const lightState = { currentNodeId: state.currentNodeId, flags: { ...state.flags }, history: [...(Array.isArray(prevHist) ? prevHist : this.state.history)] };
         const entry = {
             id: this.generateHistoryId(),
-            state: this.deepCopy(state),
+            // Keep original deep copy for compatibility OFF for now -> minimal placeholder with current fields.
+            state: this.deepCopy({ currentNodeId: state.currentNodeId, flags: { ...state.flags }, history: [...(Array.isArray(prevHist) ? prevHist : this.state.history)] }),
             timestamp: new Date().toISOString(),
             action,
-            metadata
+            metadata: { ...(metadata || {}), [LIGHT_STATE_KEY]: lightState }
         };
         this.undoStack.push(entry);
         // Clear redo stack when new change is made
@@ -1239,9 +1657,10 @@ class QNCEEngine {
             // Save current state to redo stack
             const currentEntry = {
                 id: this.generateHistoryId(),
-                state: this.deepCopy(this.state),
+                state: this.deepCopy({ currentNodeId: this.state.currentNodeId, flags: { ...this.state.flags }, history: [...this.state.history] }),
                 timestamp: new Date().toISOString(),
-                action: 'redo-point'
+                action: 'redo-point',
+                metadata: { __lightState: { currentNodeId: this.state.currentNodeId, flags: { ...this.state.flags }, history: [...this.state.history] } }
             };
             this.redoStack.push(currentEntry);
             // Enforce max redo entries
@@ -1252,7 +1671,17 @@ class QNCEEngine {
             const entryToRestore = this.undoStack.pop();
             // Set flag to prevent triggering undo/redo tracking during restore
             this.isUndoRedoOperation = true;
-            this.state = this.deepCopy(entryToRestore.state);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- metadata may carry lightweight snapshot
+            const light = entryToRestore.metadata?.__lightState;
+            if (light) {
+                this.state.currentNodeId = light.currentNodeId;
+                this.state.flags = { ...light.flags };
+                if (Array.isArray(light.history))
+                    this.state.history = [...light.history];
+            }
+            else {
+                this.state = this.deepCopy(entryToRestore.state);
+            }
             this.isUndoRedoOperation = false;
             const duration = performance.now() - startTime;
             // Performance tracking
@@ -1312,9 +1741,10 @@ class QNCEEngine {
             // Save current state to undo stack
             const currentEntry = {
                 id: this.generateHistoryId(),
-                state: this.deepCopy(this.state),
+                state: this.deepCopy({ currentNodeId: this.state.currentNodeId, flags: { ...this.state.flags }, history: [...this.state.history] }),
                 timestamp: new Date().toISOString(),
-                action: 'undo-point'
+                action: 'undo-point',
+                metadata: { __lightState: { currentNodeId: this.state.currentNodeId, flags: { ...this.state.flags }, history: [...this.state.history] } }
             };
             this.undoStack.push(currentEntry);
             // Enforce max undo entries
@@ -1325,7 +1755,17 @@ class QNCEEngine {
             const entryToRestore = this.redoStack.pop();
             // Set flag to prevent triggering undo/redo tracking during restore
             this.isUndoRedoOperation = true;
-            this.state = this.deepCopy(entryToRestore.state);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- metadata may carry lightweight snapshot
+            const light = entryToRestore.metadata?.__lightState;
+            if (light) {
+                this.state.currentNodeId = light.currentNodeId;
+                this.state.flags = { ...light.flags };
+                if (Array.isArray(light.history))
+                    this.state.history = [...light.history];
+            }
+            else {
+                this.state = this.deepCopy(entryToRestore.state);
+            }
             this.isUndoRedoOperation = false;
             const duration = performance.now() - startTime;
             // Performance tracking
@@ -1429,6 +1869,8 @@ class QNCEEngine {
      * @param metadata - Optional metadata about the trigger
      * @returns Promise resolving to autosave result
      */
+    // metadata currently unused (reserved for future extended autosave telemetry)
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     async triggerAutosave(trigger, metadata) {
         const startTime = performance.now();
         // Check if autosave is enabled
@@ -1540,12 +1982,20 @@ exports.QNCEEngine = QNCEEngine;
 /**
  * Factory function to create a QNCE engine instance
  */
-function createQNCEEngine(storyData, initialState, performanceMode = false) {
-    return new QNCEEngine(storyData, initialState, performanceMode);
+/**
+ * Factory to create a QNCE engine instance.
+ * @public
+ */
+function createQNCEEngine(storyData, initialState, performanceMode = false, threadPoolConfig, options) {
+    return new QNCEEngine(storyData, initialState, performanceMode, threadPoolConfig, options);
 }
 /**
  * Load story data from JSON
  */
+/**
+ * Load and validate StoryData from JSON-like input.
+ * @public
+ */
 function loadStoryData(jsonData) {
     // Add validation here in the future
     return jsonData;