qnce-engine 1.2.0 → 1.2.2

package/dist/engine/types.d.ts

@@ -0,0 +1,445 @@
+import { QNCEState, FlowEvent } from './core';
+/**
+ * Metadata about the serialization process and compatibility
+ */
+export interface SerializationMetadata {
+    /** Engine version that created this serialized state */
+    engineVersion: string;
+    /** Timestamp when the state was serialized (ISO string) */
+    timestamp: string;
+    /** Story identifier/hash for compatibility checking */
+    storyId?: string;
+    /** Custom metadata for application-specific use */
+    customMetadata?: Record<string, unknown>;
+    /** Compression level used (if any) */
+    compression?: 'none' | 'gzip' | 'lz4';
+    /** Checksum for integrity verification */
+    checksum?: string;
+}
+/**
+ * Complete serialized state that can be saved/restored
+ * Includes all necessary data to fully reconstruct engine state
+ */
+export interface SerializedState {
+    /** Core narrative state (current node, flags, history) */
+    state: QNCEState;
+    /** Active flow events for performance tracking */
+    flowEvents: FlowEvent[];
+    /** Performance and pool statistics snapshot */
+    poolStats?: Record<string, unknown>;
+    /** Branching context and branch state */
+    branchingContext?: {
+        activeBranches: string[];
+        branchStates: Record<string, unknown>;
+        convergencePoints: string[];
+    };
+    /** Validation state and rule overrides */
+    validationState?: {
+        disabledRules: string[];
+        customRules: Record<string, unknown>;
+        validationErrors: string[];
+    };
+    /** Thread pool and background operation state */
+    performanceState?: {
+        performanceMode: boolean;
+        enableProfiling: boolean;
+        backgroundTasks: string[];
+        telemetryData: Record<string, unknown>[];
+    };
+    /** Serialization metadata */
+    metadata: SerializationMetadata;
+}
+/**
+ * Lightweight checkpoint for quick save/restore operations
+ * Contains minimal data for fast state snapshots
+ */
+export interface Checkpoint {
+    /** Unique checkpoint identifier */
+    id: string;
+    /** Human-readable checkpoint name/label */
+    name?: string;
+    /** Core state snapshot (deep copied) */
+    state: QNCEState;
+    /** Checkpoint creation timestamp */
+    timestamp: string;
+    /** Optional description or context */
+    description?: string;
+    /** Tags for checkpoint organization */
+    tags?: string[];
+    /** Lightweight metadata */
+    metadata?: {
+        nodeTitle?: string;
+        choiceCount?: number;
+        flagCount?: number;
+        historyLength?: number;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Options for state serialization
+ */
+export interface SerializationOptions {
+    /** Include performance data in serialization */
+    includePerformanceData?: boolean;
+    /** Include flow events in serialization */
+    includeFlowEvents?: boolean;
+    /** Include branching context */
+    includeBranchingContext?: boolean;
+    /** Include validation state */
+    includeValidationState?: boolean;
+    /** Compression to apply */
+    compression?: 'none' | 'gzip' | 'lz4';
+    /** Generate integrity checksum */
+    generateChecksum?: boolean;
+    /** Custom metadata to include */
+    customMetadata?: Record<string, unknown>;
+    /** Pretty print JSON (increases size but improves readability) */
+    prettyPrint?: boolean;
+}
+/**
+ * Options for state loading/deserialization
+ */
+export interface LoadOptions {
+    /** Verify checksum integrity before loading */
+    verifyChecksum?: boolean;
+    /** Skip compatibility checks (dangerous) */
+    skipCompatibilityCheck?: boolean;
+    /** Restore performance state */
+    restorePerformanceState?: boolean;
+    /** Restore flow events */
+    restoreFlowEvents?: boolean;
+    /** Restore branching context */
+    restoreBranchingContext?: boolean;
+    /** Restore validation state */
+    restoreValidationState?: boolean;
+    /** Migration function for version compatibility */
+    migrationFunction?: (serializedState: SerializedState) => SerializedState;
+}
+/**
+ * Checkpoint management options
+ */
+export interface CheckpointOptions {
+    /** Maximum number of checkpoints to keep */
+    maxCheckpoints?: number;
+    /** Auto-cleanup strategy */
+    cleanupStrategy?: 'lru' | 'fifo' | 'timestamp' | 'manual';
+    /** Include metadata in checkpoint */
+    includeMetadata?: boolean;
+    /** Tags to automatically apply */
+    autoTags?: string[];
+}
+/**
+ * State persistence result with success/error information
+ */
+export interface PersistenceResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Error message if operation failed */
+    error?: string;
+    /** Operation-specific data */
+    data?: {
+        /** Serialized state size in bytes */
+        size?: number;
+        /** Compression ratio achieved */
+        compressionRatio?: number;
+        /** Checksum of saved data */
+        checksum?: string;
+        /** Time taken for operation (ms) */
+        duration?: number;
+    };
+    /** Warnings or informational messages */
+    warnings?: string[];
+}
+/**
+ * Event emitted during state persistence operations
+ */
+export interface PersistenceEvent {
+    /** Event type */
+    type: 'save-start' | 'save-complete' | 'load-start' | 'load-complete' | 'checkpoint-created' | 'checkpoint-restored' | 'cleanup' | 'error';
+    /** Timestamp of event */
+    timestamp: string;
+    /** Associated checkpoint ID (if applicable) */
+    checkpointId?: string;
+    /** Event data */
+    data?: Record<string, unknown>;
+    /** Error information (for error events) */
+    error?: {
+        message: string;
+        code?: string;
+        stack?: string;
+    };
+}
+/**
+ * State validation result for loaded states
+ */
+export interface StateValidationResult {
+    /** Whether the state is valid */
+    isValid: boolean;
+    /** Validation errors */
+    errors: string[];
+    /** Validation warnings */
+    warnings: string[];
+    /** Suggested fixes or migrations */
+    suggestions?: string[];
+    /** Whether the state can be safely loaded */
+    canLoad: boolean;
+}
+/**
+ * Checkpoint manager interface for persistence operations
+ */
+export interface CheckpointManager {
+    /** Create a new checkpoint */
+    createCheckpoint(name?: string, options?: CheckpointOptions): Promise<Checkpoint>;
+    /** List all available checkpoints */
+    listCheckpoints(): Promise<Checkpoint[]>;
+    /** Get a specific checkpoint by ID */
+    getCheckpoint(id: string): Promise<Checkpoint | null>;
+    /** Delete a checkpoint */
+    deleteCheckpoint(id: string): Promise<boolean>;
+    /** Restore from a checkpoint */
+    restoreFromCheckpoint(id: string): Promise<PersistenceResult>;
+    /** Clean up old checkpoints */
+    cleanup(options?: CheckpointOptions): Promise<number>;
+    /** Export checkpoint to external format */
+    exportCheckpoint(id: string, format?: 'json' | 'binary'): Promise<string | Buffer>;
+    /** Import checkpoint from external format */
+    importCheckpoint(data: string | Buffer, format?: 'json' | 'binary'): Promise<Checkpoint>;
+}
+/**
+ * Storage adapter interface for different persistence backends
+ */
+export interface StorageAdapter {
+    /** Save serialized state */
+    save(key: string, data: SerializedState, options?: SerializationOptions): Promise<PersistenceResult>;
+    /** Load serialized state */
+    load(key: string, options?: LoadOptions): Promise<SerializedState | null>;
+    /** Delete stored state */
+    delete(key: string): Promise<boolean>;
+    /** List all stored keys */
+    list(): Promise<string[]>;
+    /** Check if key exists */
+    exists(key: string): Promise<boolean>;
+    /** Get storage statistics */
+    getStats(): Promise<{
+        totalSize: number;
+        keyCount: number;
+        [key: string]: unknown;
+    }>;
+    /** Clear all stored data */
+    clear(): Promise<boolean>;
+}
+/**
+ * Built-in storage adapter types
+ */
+export type StorageAdapterType = 'localStorage' | 'sessionStorage' | 'indexedDB' | 'memory' | 'file';
+/**
+ * Configuration for different storage adapters
+ */
+export interface StorageConfig {
+    /** Storage adapter type */
+    type: StorageAdapterType;
+    /** Adapter-specific options */
+    options?: {
+        /** For file storage: directory path */
+        directory?: string;
+        /** For IndexedDB: database name */
+        databaseName?: string;
+        /** For memory storage: size limit */
+        sizeLimit?: number;
+        /** Auto-compression for storage */
+        autoCompress?: boolean;
+        /** Encryption options */
+        encryption?: {
+            algorithm: string;
+            key: string;
+        };
+    };
+}
+/**
+ * Type guard functions for runtime type checking
+ */
+export interface TypeGuards {
+    isSerializedState: (obj: unknown) => obj is SerializedState;
+    isCheckpoint: (obj: unknown) => obj is Checkpoint;
+    isValidationResult: (obj: unknown) => obj is StateValidationResult;
+    isPersistenceResult: (obj: unknown) => obj is PersistenceResult;
+}
+export type CheckpointId = string;
+export type StorageKey = string;
+export type Timestamp = string;
+/**
+ * History entry for undo/redo functionality
+ */
+export interface HistoryEntry {
+    /** Unique identifier for this history entry */
+    id: string;
+    /** State snapshot at this point */
+    state: QNCEState;
+    /** Timestamp when this entry was created */
+    timestamp: string;
+    /** Optional description of the action that created this entry */
+    action?: string;
+    /** Optional metadata about the change */
+    metadata?: {
+        nodeId?: string;
+        choiceText?: string;
+        flagsChanged?: string[];
+        [key: string]: unknown;
+    };
+}
+/**
+ * Configuration for autosave functionality
+ */
+export interface AutosaveConfig {
+    /** Whether autosave is enabled */
+    enabled: boolean;
+    /** Triggers that should cause an autosave */
+    triggers: ('choice' | 'flag-change' | 'state-load' | 'branch-exit' | 'custom')[];
+    /** Maximum number of autosave entries to keep */
+    maxEntries: number;
+    /** Minimum time between autosaves (ms) to prevent spam */
+    throttleMs: number;
+    /** Whether to include metadata in autosave entries */
+    includeMetadata: boolean;
+    /** Custom autosave naming pattern */
+    namePattern?: string;
+}
+/**
+ * Configuration for undo/redo history
+ */
+export interface UndoRedoConfig {
+    /** Whether undo/redo is enabled */
+    enabled: boolean;
+    /** Maximum number of undo entries to keep */
+    maxUndoEntries: number;
+    /** Maximum number of redo entries to keep */
+    maxRedoEntries: number;
+    /** Whether to track flag changes for undo metadata */
+    trackFlagChanges: boolean;
+    /** Whether to track choice text for undo metadata */
+    trackChoiceText: boolean;
+    /** Actions that should create undo entries */
+    trackActions: ('choice' | 'flag-change' | 'state-load' | 'reset' | 'custom')[];
+}
+/**
+ * Result of undo/redo operations
+ */
+export interface UndoRedoResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Error message if operation failed */
+    error?: string;
+    /** The state that was restored */
+    restoredState?: QNCEState;
+    /** Information about the restored entry */
+    entry?: {
+        id: string;
+        timestamp: string;
+        action?: string;
+        nodeId?: string;
+    };
+    /** Current undo/redo stack sizes after operation */
+    stackSizes?: {
+        undoCount: number;
+        redoCount: number;
+    };
+}
+/**
+ * Autosave operation result
+ */
+export interface AutosaveResult {
+    /** Whether the autosave succeeded */
+    success: boolean;
+    /** Error message if autosave failed */
+    error?: string;
+    /** The checkpoint ID created by autosave */
+    checkpointId?: string;
+    /** Trigger that caused this autosave */
+    trigger?: string;
+    /** Time taken for autosave operation (ms) */
+    duration?: number;
+    /** Size of the autosaved data */
+    size?: number;
+}
+/**
+ * History manager interface for undo/redo operations
+ */
+export interface HistoryManager {
+    /** Push a new state to the undo stack */
+    pushState(state: QNCEState, action?: string, metadata?: Record<string, unknown>): void;
+    /** Undo the last operation */
+    undo(): UndoRedoResult;
+    /** Redo the last undone operation */
+    redo(): UndoRedoResult;
+    /** Clear all history */
+    clear(): void;
+    /** Get the current undo stack size */
+    getUndoCount(): number;
+    /** Get the current redo stack size */
+    getRedoCount(): number;
+    /** Check if undo is available */
+    canUndo(): boolean;
+    /** Check if redo is available */
+    canRedo(): boolean;
+    /** Get history summary for debugging */
+    getHistorySummary(): {
+        undoEntries: {
+            id: string;
+            timestamp: string;
+            action?: string;
+        }[];
+        redoEntries: {
+            id: string;
+            timestamp: string;
+            action?: string;
+        }[];
+    };
+}
+/**
+ * Event emitted during autosave operations
+ */
+export interface AutosaveEvent {
+    /** Event type */
+    type: 'autosave-triggered' | 'autosave-complete' | 'autosave-failed' | 'autosave-throttled';
+    /** Timestamp of event */
+    timestamp: string;
+    /** Trigger that caused the autosave */
+    trigger?: string;
+    /** Event data */
+    data?: {
+        checkpointId?: string;
+        duration?: number;
+        size?: number;
+        throttleRemainingMs?: number;
+    };
+    /** Error information (for failed events) */
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+/**
+ * Event emitted during undo/redo operations
+ */
+export interface UndoRedoEvent {
+    /** Event type */
+    type: 'undo' | 'redo' | 'history-push' | 'history-clear' | 'undo-failed' | 'redo-failed';
+    /** Timestamp of event */
+    timestamp: string;
+    /** Event data */
+    data?: {
+        entryId?: string;
+        action?: string;
+        nodeId?: string;
+        undoCount?: number;
+        redoCount?: number;
+    };
+    /** Error information (for failed events) */
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+export declare const PERSISTENCE_VERSION = "1.0.0";
+export declare const SUPPORTED_VERSIONS: string[];
+//# sourceMappingURL=types.d.ts.map

package/dist/engine/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/engine/types.ts"],"names":[],"mappings":"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"}

package/dist/engine/types.js

@@ -0,0 +1,9 @@
+"use strict";
+// QNCE Engine Types - Sprint 3.3: State Persistence & Checkpoints
+// Comprehensive type definitions for serialization and checkpoint features
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_VERSIONS = exports.PERSISTENCE_VERSION = void 0;
+// Version constants
+exports.PERSISTENCE_VERSION = '1.0.0';
+exports.SUPPORTED_VERSIONS = ['1.0.0'];
+//# sourceMappingURL=types.js.map

package/dist/engine/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/engine/types.ts"],"names":[],"mappings":";AAAA,kEAAkE;AAClE,2EAA2E;;;AA8iB3E,oBAAoB;AACP,QAAA,mBAAmB,GAAG,OAAO,CAAC;AAC9B,QAAA,kBAAkB,GAAG,CAAC,OAAO,CAAC,CAAC"}

package/dist/engine/validation.d.ts

@@ -0,0 +1,110 @@
+import { Choice, NarrativeNode, QNCEState } from './core';
+/**
+ * Validation context containing all state needed for choice validation
+ */
+export interface ValidationContext {
+    currentNode: NarrativeNode;
+    state: QNCEState;
+    availableChoices: Choice[];
+    timestamp?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of choice validation with detailed information
+ */
+export interface ValidationResult {
+    isValid: boolean;
+    reason?: string;
+    failedConditions?: string[];
+    suggestedChoices?: Choice[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Choice validation rule interface for extensible validation logic
+ */
+export interface ValidationRule {
+    name: string;
+    priority: number;
+    validate(choice: Choice, context: ValidationContext): ValidationResult;
+}
+/**
+ * Core ChoiceValidator interface
+ * Provides validation logic for choice execution and availability filtering
+ */
+export interface ChoiceValidator {
+    /**
+     * Validate a specific choice against current state
+     * @param choice - The choice to validate
+     * @param context - Current validation context
+     * @returns Validation result with details
+     */
+    validate(choice: Choice, context: ValidationContext): ValidationResult;
+    /**
+     * Get all currently available/valid choices
+     * @param context - Current validation context
+     * @returns Array of valid choices
+     */
+    getAvailableChoices(context: ValidationContext): Choice[];
+    /**
+     * Add a validation rule to the validator
+     * @param rule - Validation rule to add
+     */
+    addRule(rule: ValidationRule): void;
+    /**
+     * Remove a validation rule by name
+     * @param ruleName - Name of the rule to remove
+     */
+    removeRule(ruleName: string): void;
+    /**
+     * Get all registered validation rules
+     * @returns Array of validation rules sorted by priority
+     */
+    getRules(): ValidationRule[];
+}
+/**
+ * Built-in validation rules for common scenarios
+ */
+export declare class StandardValidationRules {
+    /**
+     * Validates that choice exists in the current node's choices
+     */
+    static readonly CHOICE_EXISTS: ValidationRule;
+    /**
+     * Validates flag-based conditions for choice availability
+     */
+    static readonly FLAG_CONDITIONS: ValidationRule;
+    /**
+     * Validates choice is not disabled or marked as unavailable
+     */
+    static readonly CHOICE_ENABLED: ValidationRule;
+    /**
+     * Validates time-based requirements for choice availability
+     */
+    static readonly TIME_CONDITIONS: ValidationRule;
+    /**
+     * Validates inventory-based requirements for choice availability
+     */
+    static readonly INVENTORY_CONDITIONS: ValidationRule;
+}
+/**
+ * Default implementation of ChoiceValidator
+ * Uses a rule-based system for extensible validation logic
+ */
+export declare class DefaultChoiceValidator implements ChoiceValidator {
+    private rules;
+    constructor();
+    validate(choice: Choice, context: ValidationContext): ValidationResult;
+    getAvailableChoices(context: ValidationContext): Choice[];
+    addRule(rule: ValidationRule): void;
+    removeRule(ruleName: string): void;
+    getRules(): ValidationRule[];
+}
+/**
+ * Factory function to create a choice validator with default rules
+ */
+export declare function createChoiceValidator(): ChoiceValidator;
+/**
+ * Utility function to create validation context from engine state
+ */
+export declare function createValidationContext(currentNode: NarrativeNode, state: QNCEState, availableChoices: Choice[], metadata?: Record<string, unknown>): ValidationContext;
+//# sourceMappingURL=validation.d.ts.map

package/dist/engine/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/engine/validation.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,aAAa,CAAC;IAC3B,KAAK,EAAE,SAAS,CAAC;IACjB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAAC;CACxE;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAAC;IAEvE;;;;OAIG;IACH,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,EAAE,CAAC;IAE1D;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAEpC;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC;;;OAGG;IACH,QAAQ,IAAI,cAAc,EAAE,CAAC;CAC9B;AAED;;GAEG;AACH,qBAAa,uBAAuB;IAClC;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,aAAa,EAAE,cAAc,CAc3C;IAEF;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,eAAe,EAAE,cAAc,CAgD7C;IAEF;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAiB5C;IAEF;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,eAAe,EAAE,cAAc,CAiD7C;IAEF;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,oBAAoB,EAAE,cAAc,CAiClD;CACH;AAED;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,eAAe;IAC5D,OAAO,CAAC,KAAK,CAAwB;;IAWrC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,gBAAgB;IA8BtE,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,EAAE;IASzD,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAWnC,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIlC,QAAQ,IAAI,cAAc,EAAE;CAG7B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,eAAe,CAEvD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,aAAa,EAC1B,KAAK,EAAE,SAAS,EAChB,gBAAgB,EAAE,MAAM,EAAE,EAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,iBAAiB,CAQnB"}