qnce-engine 1.3.1 → 1.4.1

package/dist/utils/logger.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatLog = formatLog;
+exports.createLogger = createLogger;
+exports.deriveLogLevel = deriveLogLevel;
+const LEVEL_ORDER = {
+    silent: 100, // suppress all
+    error: 50,
+    warn: 40,
+    info: 30,
+    success: 30, // treat success same visibility as info
+    debug: 10
+};
+class ConsoleSink {
+    useColor;
+    constructor(useColor) {
+        this.useColor = useColor;
+    }
+    write(entry) {
+        const { level, message } = entry;
+        const color = this.colorFor(level);
+        const prefix = this.prefixFor(level);
+        // Use process.stdout / stderr directly to avoid triggering no-console
+        const out = (level === 'error' ? process.stderr : process.stdout);
+        out.write(`${color}${prefix}${message}${this.useColor ? '\u001b[0m' : ''}\n`);
+    }
+    colorFor(level) {
+        if (!this.useColor)
+            return '';
+        switch (level) {
+            case 'error': return '\u001b[31m'; // red
+            case 'warn': return '\u001b[33m'; // yellow
+            case 'success': return '\u001b[32m'; // green
+            case 'debug': return '\u001b[90m'; // gray
+            default: return '\u001b[36m'; // cyan/info
+        }
+    }
+    prefixFor(level) {
+        switch (level) {
+            case 'error': return '❌ ';
+            case 'warn': return '⚠️  ';
+            case 'success': return '✅ ';
+            case 'debug': return '🔍 ';
+            default: return '';
+        }
+    }
+}
+/** Serialize arbitrary values safely for log messages (avoids generic [object Object]). */
+function formatLog(value, depth = 0, seen = new WeakSet()) {
+    if (typeof value === 'string')
+        return value;
+    if (value instanceof Error)
+        return value.stack || value.message;
+    const t = typeof value;
+    if (value == null || t === 'number' || t === 'boolean')
+        return String(value);
+    if (t === 'function')
+        return `[Function ${value.name || 'anonymous'}]`;
+    if (t === 'symbol')
+        return value.toString();
+    if (Array.isArray(value)) {
+        if (depth > 2)
+            return `[Array(${value.length})]`;
+        return '[' + value.map(v => formatLog(v, depth + 1, seen)).join(', ') + ']';
+    }
+    if (t === 'object') {
+        if (seen.has(value))
+            return '[Circular]';
+        seen.add(value);
+        if (depth > 2)
+            return '{…}';
+        const entries = Object.entries(value)
+            .slice(0, 25)
+            .map(([k, v]) => `${k}: ${formatLog(v, depth + 1, seen)}`);
+        const truncated = Object.keys(value).length > 25 ? ' …' : '';
+        return '{ ' + entries.join(', ') + truncated + ' }';
+    }
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function createLogger(opts = {}) {
+    const sink = opts.sink || new ConsoleSink(opts.useColor ?? process.stdout.isTTY);
+    let level = opts.level || 'info';
+    const basePrefix = '';
+    function emit(l, msg) {
+        // lower numeric = more verbose; allow if candidate order >= current level order
+        if (LEVEL_ORDER[l] < LEVEL_ORDER[level])
+            return; // require candidate >= threshold
+        sink.write({ level: l, message: basePrefix + formatLog(msg), ts: Date.now() });
+    }
+    const logger = {
+        get level() { return level; },
+        setLevel(lvl) { level = lvl; },
+        error(msg) { emit('error', msg); },
+        warn(msg) { emit('warn', msg); },
+        info(msg) { emit('info', msg); },
+        success(msg) { emit('success', msg); },
+        debug(msg) { emit('debug', msg); },
+        child() { return createLogger({ level, sink, useColor: (opts.useColor ?? process.stdout.isTTY) }); }
+    };
+    return logger;
+}
+/** Helper to derive level from flags */
+function deriveLogLevel(flags) {
+    if (flags.quiet)
+        return 'warn';
+    if (flags.verbose)
+        return 'debug';
+    return 'info';
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

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

package/docs/PERFORMANCE.md

@@ -3,6 +3,8 @@
 **Version:** 1.2.0-sprint2  
 **Sprint #2:** Core Performance Refactor Complete  
 
+> Documentation Consolidation: This file now consolidates all performance content. The previous `PERFORMANCE_GUIDE.md` has been merged and will be removed to prevent drift. All future edits should target this canonical document.
+
 ## 🚀 Overview
 
 The QNCE engine now includes comprehensive performance optimization infrastructure delivering:
@@ -124,6 +126,18 @@ const spanId = perf.flowStart('my-flow', { context: 'gameplay' });
 perf.flowComplete(spanId, 'target-node', { result: 'success' });
 ```
 
+### 5. Performance Events (Unified Reference)
+
+Events captured by the performance subsystem (names kept stable for dashboard & telemetry correlations):
+
+- `flow-start` / `flow-complete` – Narrative flow spans
+- `cache-hit` / `cache-miss` – Node retrieval / caching
+- `hot-reload-start` / `hot-reload-end` – Live story delta application
+- `state-transition` – Engine internal state changes
+- `custom` – User defined events via `perf.record()`
+
+These events funnel into the PerfReporter buffers and are aggregated for summary snapshots and flush heuristics (adaptive batching / backoff).
+
 ## 🖥️ CLI Performance Dashboard
 
 Real-time monitoring and performance analysis via `qnce-perf` command.
@@ -179,6 +193,12 @@ qnce-perf live 1000  # Update every 1000ms
 qnce-perf export > performance-report.json
 ```
 
+#### NDJSON Streaming
+```bash
+# One JSON object per line with { summary, flush, thread }
+qnce-perf stream 1000 | jq '.'
+```
+
 #### Reset Counters
 ```bash
 qnce-perf reset
@@ -350,6 +370,316 @@ if (summary.cacheHitRate < 0.8) {
 }
 ```
 
+### 6. Adaptive Flush & Dynamic Batch Sizing (R2/R6 - Beta)
+
+The performance pipeline includes adaptive heuristics for telemetry/perf flush operations.
+
+| Feature | Purpose | Heuristic (Initial) | Status |
+|---------|---------|---------------------|--------|
+| Exponential Backoff (R2) | Avoid tight retry loops after dispatch rejections | Base 20ms * 2^streak (cap 500ms) | Stable |
+| Dynamic Batch Sizing (R6) | Scale throughput under healthy latency; shrink under pressure | Upscale on backlog (>2×/4× base) with p95 <25ms / <50ms; shrink on streak ≥2 | Beta |
+| Rejection Rate | Health signal for downstream pressure | rejected / (accepted + rejected) | Beta |
+| Effective Batch Size Export | Observability of sizing decisions | `lastEffectiveBatchSize` | Beta |
+| Disable Adaptive Batch Flag | Force fixed batch size (diagnostics/baseline) | `disableAdaptiveBatch` config or env `QNCE_DISABLE_ADAPTIVE_BATCH=1` | Beta |
+| Adaptive Enabled Snapshot Flag | Observability: whether dynamic sizing active | `adaptiveEnabled` boolean in flush metrics snapshot | Beta |
+
+Metric Extensions:
+```ts
+interface PerfFlushMetrics {
+  rejectionRate: number;          // 0..1 ratio
+  lastEffectiveBatchSize: number; // adaptive batch size used
+  adaptiveEnabled: boolean;       // true when dynamic sizing heuristics active
+}
+```
+
+Simplified Sizing Logic:
+```ts
+if (consecutiveRejects >= 2) shrink();
+else if (backlog > base*4 && p95 < 50) upscale(≈4x cap);
+else if (backlog > base*2 && p95 < 25) upscale(≈3x cap);
+```
+
+Usage:
+```ts
+import { getPerfReporter } from 'qnce-engine/performance';
+const reporter = getPerfReporter();
+const m = reporter.getFlushMetrics();
+console.log(m.rejectionRate, m.lastEffectiveBatchSize);
+// Determine if adaptive sizing was active for this snapshot
+console.log('Adaptive active:', m.adaptiveEnabled);
+// Force fixed batch sizing for a deterministic baseline
+// const fixed = getPerfReporter({ batchSize: 100, disableAdaptiveBatch: true });
+// m.adaptiveEnabled will be false when forced fixed sizing is in effect.
+```
+
+Suppress warning noise in CI:
+```bash
+export QNCE_SUPPRESS_PERF_WARN=1
+```
+
+Internal debug (subject to change):
+```ts
+// @ts-expect-error internal
+console.log(reporter.__getInternalPerfDebug());
+```
+
+Beta Caveats:
+- Thresholds & scaling factors may evolve
+- Single-sample p95 (no smoothing yet)
+- Provide feedback with backlog, latency, rejection patterns
+
+## 🧪 Performance Modes
+
+Three operational modes patterns frequently referenced during tuning and benchmarking:
+
+### Standard Mode (Default)
+```ts
+const engine = createQNCEEngine(storyData);
+// Suitable for most dev scenarios; minimal overhead.
+```
+
+### Performance Mode
+```ts
+const engine = createQNCEEngine(storyData, {}, true);
+// Enables: object pooling, ThreadPool, perf events.
+```
+
+### Performance Mode + Custom ThreadPool
+```ts
+const engine = createQNCEEngine(storyData, {}, true, {
+  maxWorkers: 4,
+  queueLimit: 200,
+  enableProfiling: true
+});
+// Fine‑tuned background execution & profiling.
+```
+
+## 🎯 Performance Targets & Benchmarks
+
+Current sprint targets alongside representative observations (non-binding; provide directional validation):
+
+| Metric | Target | Current | Status |
+|--------|--------|---------|--------|
+| Object Pool Hit Rate | >95% | 100% | ✅ |
+| Memory Allocation Reduction | >90% | >90% | ✅ |
+| Hot-Reload Frame Stall | <2ms | 3.35ms | 🔄 68% improvement |
+| State Transition Time | <5ms | <1ms | ✅ |
+| Cache Hit Rate | >95% | >92% | ✅ |
+| ThreadPool Processing | Non-blocking | ✅ | ✅ |
+
+### Benchmark Snapshots
+
+Object Pooling:
+```
+Standard Mode:     ~1000 allocations / 100 transitions
+Performance Mode:  ~100 allocations / 100 transitions (≈90% reduction)
+GC Pressure:       Eliminated for pooled classes
+```
+
+Hot-Reload (Story ~50 nodes):
+```
+Comparison: 0.14ms
+Patch:      3.35ms
+Total:      3.49ms (target <2ms still under optimization)
+```
+
+ThreadPool:
+```
+Throughput:     1000+ jobs/sec (synthetic)
+Scheduling:     Priority aware
+Environment:    Browser + Node compatible
+```
+
+## 🚀 Production Deployment Quick Start
+
+### Installation
+```bash
+npm install qnce-engine
+npm install -g qnce-engine   # Optional CLI dashboard
+```
+
+### Example Production Init
+```ts
+const engine = createQNCEEngine(storyData, {}, true, {
+  maxWorkers: 4,
+  queueLimit: 500,
+  enableProfiling: true
+});
+
+// Periodic metrics export (example)
+setInterval(() => {
+  const summary = perf.summary();
+  monitoringService.sendMetrics({
+    cacheHitRate: summary.cacheHitRate,
+    hotReloadAvg: summary.hotReloadPerformance.avgTime,
+    workerUtilization: engine.getThreadPoolStats().workerUtilization
+  });
+}, 30000);
+```
+
+## 🔧 Performance Tuning Recipes
+
+High Throughput:
+```ts
+createQNCEEngine(storyData, {}, true, { maxWorkers: 8, queueLimit: 1000, enableProfiling: false });
+```
+
+Development / Diagnostics:
+```ts
+createQNCEEngine(storyData, {}, true, { maxWorkers: 2, queueLimit: 50, enableProfiling: true });
+// Use: qnce-perf live 500
+```
+
+## 🩺 Troubleshooting (Extended)
+
+Memory Pressure:
+1. Inspect pool stats: `engine.getPoolStats()`
+2. Confirm perf mode enabled
+3. Audit custom handlers for retained references
+
+Slow Hot-Reload:
+1. `qnce-perf dashboard` → check hot-reload section
+2. Split very large story diffs into batches
+3. Validate minimal unrelated node churn
+
+Queue Overflows:
+1. Inspect `engine.getThreadPoolStats().queuedJobs`
+2. Increase `maxWorkers` / `queueLimit`
+3. Reduce low-priority background submissions
+
+## 🔀 Migration Guide (v0.1.0 → v1.2.0-sprint2)
+
+No breaking API changes. Enable performance mode explicitly to opt into advanced systems:
+```ts
+// Before
+const engine = createQNCEEngine(storyData);
+// After
+const engine = createQNCEEngine(storyData, {}, true);
+```
+
+CLI Adoption:
+```bash
+npm install -g qnce-engine@1.2.0-sprint2
+qnce-perf live
+```
+
+## ✅ Sprint Summary
+
+Sprint #2 Deliverables Achieved:
+- 90%+ allocation reduction via pooling
+- Background ThreadPool processing
+- Hot-reload improvement (~68%)
+- Comprehensive profiling & adaptive flush pipeline (beta heuristics)
+- CLI dashboard for real-time insights
+
+The engine is production-ready with evolving adaptive heuristics (provide feedback on backlog/latency/rejection traces for tuning).
+
+
+## 🔄 Phase 2 (Wave 1) Additions (@beta)
+
+Version: 1.4.0-beta.0 introduces incremental reliability & observability upgrades to the flush pipeline.
+
+### 1. Retry-Once Dispatch
+On the first rejected batch dispatch the reporter attempts exactly one immediate retry when:
+* `consecutiveRejects === 1`
+* `p95DispatchLatencyMs < 200`
+
+This reduces transient loss without causing uncontrolled retry storms (subsequent failures rely solely on exponential backoff).
+
+### 2. Smoothed p95 (EMA)
+Metric: `smoothedP95DispatchLatencyMs` provides an exponential moving average (alpha=0.2) of raw p95 latency, reducing volatility for future adaptive controls.
+
+Properties:
+* Always trends toward raw p95
+* Resets to 0 with no samples
+* Lightweight (constant space, O(1) update)
+
+### 3. Extended Flush Metrics
+`PerfFlushMetrics` now exposes:
+```ts
+interface PerfFlushMetrics {
+  backoffActive?: boolean;      // true if inside current backoff window
+  consecutiveRejects?: number;  // current rejection streak count
+  smoothedP95DispatchLatencyMs?: number; // EMA-smoothed p95 latency
+  backoffDelayMs?: number;      // current backoff duration (ms)
+  rejectedFlushesSinceLastSuccess?: number; // rolling failures since last success
+}
+```
+
+Example:
+```ts
+const m = getPerfReporter().getFlushMetrics();
+console.log({
+  p95: m.p95DispatchLatencyMs,
+  smoothed: m.smoothedP95DispatchLatencyMs,
+  backoffActive: m.backoffActive,
+  consecutiveRejects: m.consecutiveRejects,
+  rejectionRate: m.rejectionRate
+});
+```
+
+### 4. Adaptive Sampling Scaffold
+Disabled by default. Enable with:
+```bash
+export QNCE_ADAPTIVE_SAMPLING=1
+```
+Current prototype uses an EMA of events/sec to interpolate a sample rate between configured low/high watermarks. All events recorded when disabled.
+
+### 5. Thread Pool Override (Test Only)
+For deterministic retry testing (non-public, unstable):
+```ts
+// @ts-expect-error internal
+PerfReporter.__setThreadPoolOverride({ writeTelemetry: () => Promise.resolve() });
+```
+Never rely on this in production; it may be removed without notice.
+
+### 6. Persistence Micro-Latency Threshold Update
+Save/load/checkpoint tests now assert <10ms (previous <2ms proved brittle after added instrumentation). Still enforces a tight micro-budget while avoiding CI flakiness.
+
+### 7. Environment Flags Summary
+| Flag | Purpose | Default |
+|------|---------|---------|
+| `QNCE_SUPPRESS_PERF_WARN` | Suppress console warnings for rejected flushes | Off |
+| `QNCE_DISABLE_ADAPTIVE_BATCH` | Force fixed batch size (disable dynamic sizing) | Off |
+| `QNCE_ADAPTIVE_SAMPLING` | Enable beta sampling scaffold | Off |
+
+Config controls (code):
+```ts
+// Adjust smoothing strength for smoothed p95 (0.01..1.0)
+getPerfReporter({ smoothingAlpha: 0.3 });
+```
+
+### 8. Planned Follow-Ups
+* Configurable smoothing alpha & decay windows
+* Structured retry outcome telemetry (success vs loss metrics)
+* Critical event class exemption list for sampling
+* Percentile window rotation + reservoir sampling
+
+Please include `p95DispatchLatencyMs`, `smoothedP95DispatchLatencyMs`, `rejectionRate`, and `consecutiveRejects` snapshots when filing performance issues.
+
+
 ---
 
 **Ready for Production:** QNCE v1.2.0-sprint2 delivers comprehensive performance optimization with real-time monitoring capabilities. All systems tested and production-ready! 🚀
+
+<!-- PROFILING-SNAPSHOT:START -->
+
+
+### Profiling Snapshot (Automated)
+
+Generated: 2025-09-10T18:17:48.505Z
+
+Condition evaluation benchmark cold vs warm cache latency (milliseconds). Targets: keep warm p50 < 0.002 ms for simple expressions.
+
+
+| Expr | Cold p50 | Cold p95 | Warm p50 | Warm p95 |
+|------|---------:|---------:|---------:|---------:|
+
+
+| flags.score > 10 && flags.lives >= 2 | 0.0018 | 0.0022 | 0.0011 | 0.0012 |
+| flags.mode === "hard" || flags.debug | 0.0012 | 0.0018 | 0.0006 | 0.0006 |
+| flags.a && flags.b && flags.c && flags.d | 0.0011 | 0.0013 | 0.0005 | 0.0005 |
+| flags.combo > 5 && (flags.streak >= 3… | 0.0012 | 0.0013 | 0.0004 | 0.0005 |
+
+
+<!-- PROFILING-SNAPSHOT:END -->

package/examples/fluent-builder-prototype.ts

@@ -0,0 +1,71 @@
+// Prototype: Fluent narrative builder to explore ergonomics
+// Not part of the public API; for design validation only.
+
+type Predicate<T> = (ctx: T) => boolean;
+
+interface BuilderContext {
+  flags: Record<string, unknown>;
+  nodeId?: string;
+}
+
+class Phase {
+  constructor(public readonly name: string, public when?: Predicate<BuilderContext>) {}
+}
+
+class Entangler<TKeys extends string = string> {
+  private bindings: Array<{ from: TKeys; to: TKeys; transform?: (v: any) => any }>= [];
+  bind(from: TKeys, to: TKeys, transform?: (v: any) => any) {
+    this.bindings.push({ from, to, transform });
+    return this;
+  }
+  apply(flags: Record<string, unknown>) {
+    for (const b of this.bindings) {
+      const v = flags[b.from];
+      flags[b.to] = b.transform ? b.transform(v) : v;
+    }
+  }
+}
+
+class NarrativeBuilder {
+  private phases: Phase[] = [];
+  private entangler = new Entangler<string>();
+
+  phase(name: string, when?: Predicate<BuilderContext>) {
+    this.phases.push(new Phase(name, when));
+    return this;
+  }
+
+  entangle(from: string, to: string, transform?: (v: any) => any) {
+    this.entangler.bind(from, to, transform);
+    return this;
+  }
+
+  measure(cb: (ctx: BuilderContext) => void) {
+    // noop placeholder for prototype
+    return this;
+  }
+
+  run(initial: BuilderContext) {
+    const ctx: BuilderContext = { flags: { ...initial.flags }, nodeId: initial.nodeId };
+    // apply entanglement first
+    this.entangler.apply(ctx.flags);
+    // evaluate phases
+    const active = this.phases.filter(p => !p.when || p.when(ctx)).map(p => p.name);
+    return { ctx, activePhases: active };
+  }
+}
+
+// Tiny smoke test for the prototype
+if (require.main === module) {
+  const builder = new NarrativeBuilder()
+    .phase('dreaming', ({ flags }) => !!flags["asleep"]) // superposition-like conditional phase
+    .phase('awake', ({ flags }) => !flags["asleep"])      // mutually exclusive for demo
+    .entangle('mood', 'narrationTone', v => (v === 'calm' ? 'soft' : 'tense'))
+    .measure(() => {});
+
+  const result = builder.run({ flags: { asleep: true, mood: 'calm' } });
+  console.log('Active phases:', result.activePhases);
+  console.log('Flags:', result.ctx.flags);
+}
+
+export { NarrativeBuilder, Entangler, Phase };

package/examples/quantum-integration-demo.ts

@@ -0,0 +1,51 @@
+// Example: Opt-in quantum helpers (FeatureFlags + attachQuantumFeatures)
+// This demo is safe to run in Node or a browser bundler.
+
+import { createQNCEEngine, type StoryData } from '../src/engine/core';
+import { FeatureFlags } from '../src/quantum/flags';
+import { Phase } from '../src/quantum/phase';
+import { attachQuantumFeatures } from '../src/quantum/integration';
+
+// Minimal story
+const story: StoryData = {
+  initialNodeId: 'start',
+  nodes: [
+    {
+      id: 'start',
+      text: 'You stand at a fork in the road.',
+      choices: [
+        { text: 'Take the left path', nextNodeId: 'left', flagEffects: { courage: 1 } },
+        { text: 'Take the right path', nextNodeId: 'right', flagEffects: { wisdom: 1 } }
+      ]
+    },
+    { id: 'left', text: 'The left path is quiet and calm.', choices: [] },
+    { id: 'right', text: 'The right path is lively and bright.', choices: [] }
+  ]
+};
+
+const engine = createQNCEEngine(story);
+
+// Start with phases enabled, entanglement disabled
+const flags = new FeatureFlags({ 'quantum.phases': true, 'quantum.entanglement': false });
+const q = attachQuantumFeatures(engine, flags);
+
+// Define a phase that activates when a flag is present
+const bravePhase = new Phase('brave', ({ flags }) => Boolean(flags.courage));
+
+console.log('Phase active before choice?', q.isPhaseActive(bravePhase)); // false
+
+// Make a choice that sets courage
+engine.makeChoice(0); // left path sets courage: 1
+
+console.log('Phase active after choice?', q.isPhaseActive(bravePhase)); // true when quantum.phases enabled
+
+// Toggle entanglement on and bind flags
+q.flags.enable('quantum.entanglement');
+q.entangle((e) => e.bind('courage', 'bravery'));
+
+// After entanglement, downstream systems could read `bravery` too
+const allFlags = engine.getFlags();
+console.log('All flags (post-entangle):', allFlags);
+
+// Detach when done (optional cleanup)
+q.detach();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qnce-engine",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "description": "Core QNCE (Quantum Narrative Convergence Engine) - Framework agnostic narrative engine with performance optimization",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,18 +13,31 @@
   },
   "scripts": {
     "build": "tsc",
+    "typecheck": "tsc --noEmit",
     "build:watch": "tsc --watch",
     "build:examples": "tsc --outDir dist/examples --target ES2022 --module CommonJS --moduleResolution Node --strict --esModuleInterop --skipLibCheck --declaration false examples/persistence-demo.ts examples/autosave-undo-demo.ts",
     "lint": "eslint .",
-    "test": "./node_modules/.bin/jest",
-    "test:watch": "./node_modules/.bin/jest --watch",
-    "test:coverage": "./node_modules/.bin/jest --coverage",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
     "test:performance": "node scripts/performance-tests.js",
     "demo:performance": "npm run build && node scripts/performance-demo.js",
     "demo:quickstart": "npm run build && node examples/quickstart-demo.js",
     "demo:persistence": "npm run build:examples && node dist/examples/examples/persistence-demo.js",
     "demo:autosave": "npm run build:examples && node dist/examples/examples/autosave-undo-demo.js",
-    "prepublishOnly": "npm run build && npm run test"
+    "demo:fluent": "npx -y ts-node --compiler-options '{\"module\":\"commonjs\"}' examples/fluent-builder-prototype.ts",
+    "perf:micro": "ts-node scripts/perf-micro.ts",
+    "perf:init-load": "ts-node scripts/benchmark-init-load.ts",
+    "perf:conditions": "ts-node scripts/perf-conditions.ts",
+    "dx:api-report": "npm run build && api-extractor run --local --verbose",
+    "dx:api-warnings": "npm run build && api-extractor run --local --verbose | grep -i 'ae-' || true",
+    "docs:typedoc": "typedoc",
+    "prepublishOnly": "npm run build && npm run test",
+    "dx:api-inventory": "node scripts/api-inventory.mjs",
+    "docs:sync": "ts-node scripts/sync-docs.ts",
+    "docs:perf-snapshot": "ts-node scripts/update-performance-doc.ts",
+    "check:sensitive": "node scripts/check-sensitive-files.mjs",
+    "audit:licenses": "node scripts/license-audit.mjs"
   },
   "keywords": [
     "narrative",
@@ -38,13 +51,14 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ByteSower/qnce-engine.git"
+    "url": "git+https://github.com/ByteSower/qnce-engine.git"
   },
   "homepage": "https://github.com/ByteSower/qnce-engine#readme",
   "bugs": {
     "url": "https://github.com/ByteSower/qnce-engine/issues"
   },
   "devDependencies": {
+    "@microsoft/api-extractor": "^7.47.0",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^15.0.7",
@@ -52,8 +66,8 @@
     "@types/jest": "^29.5.14",
     "@types/node": "^20.0.0",
     "@types/react": "^18.0.0",
-    "@typescript-eslint/eslint-plugin": "^6.21.0",
-    "@typescript-eslint/parser": "^6.21.0",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
     "eslint": "^8.57.1",
     "eslint-plugin-react": "^7.33.0",
     "eslint-plugin-react-hooks": "^4.6.0",
@@ -62,7 +76,9 @@
     "react": "^18.0.0",
     "react-dom": "^18.3.1",
     "ts-jest": "^29.4.0",
-    "typescript": "~5.8.3"
+    "ts-node": "^10.9.2",
+    "typedoc": "^0.26.10",
+    "typescript": "~5.6.0"
   },
   "dependencies": {
     "ajv": "^8.12.0"