footprintjs 3.0.21 → 4.0.0

package/dist/types/lib/engine/handlers/RuntimeStructureManager.d.ts

@@ -13,7 +13,7 @@ import type { SerializedPipelineStructure } from '../types.js';
  * Compute the node type from node properties.
  * Shared by RuntimeStructureManager (serialization) and ExtractorRunner (metadata).
  */
-export declare function computeNodeType(node: StageNode): 'stage' | 'decider' | 'fork' | 'streaming';
+export declare function computeNodeType(node: StageNode): 'stage' | 'decider' | 'selector' | 'fork' | 'streaming' | 'subflow';
 export declare class RuntimeStructureManager {
     private runtimePipelineStructure?;
     private structureNodeMap;
@@ -21,6 +21,7 @@ export declare class RuntimeStructureManager {
     init(buildTimeStructure?: SerializedPipelineStructure): void;
     /** Returns the current runtime structure (mutated during execution). */
     getStructure(): SerializedPipelineStructure | undefined;
+    private static readonly MAX_NODE_MAP_DEPTH;
     /** Recursively registers all nodes in the O(1) lookup map. */
     private buildNodeMap;
     /** Convert a runtime StageNode into a SerializedPipelineStructure node. */

package/dist/types/lib/engine/index.d.ts

@@ -10,7 +10,6 @@ export { isStageNodeReturn } from './graph/StageNode.js';
 export * from './types.js';
 export * from './handlers/index.js';
 export type { CombinedNarrativeEntry, CombinedNarrativeOptions } from './narrative/CombinedNarrativeBuilder.js';
-export { ControlFlowNarrativeGenerator } from './narrative/ControlFlowNarrativeGenerator.js';
 export { NullControlFlowNarrativeGenerator } from './narrative/NullControlFlowNarrativeGenerator.js';
 export type { IControlFlowNarrative } from './narrative/types.js';
 export { FlowRecorderDispatcher } from './narrative/FlowRecorderDispatcher.js';

package/dist/types/lib/engine/narrative/CombinedNarrativeBuilder.d.ts

@@ -5,7 +5,7 @@
  * Use CombinedNarrativeRecorder (auto-attached by setEnableNarrative()) instead.
  */
 export interface CombinedNarrativeEntry {
-    type: 'stage' | 'step' | 'condition' | 'fork' | 'subflow' | 'loop' | 'break' | 'error';
+    type: 'stage' | 'step' | 'condition' | 'fork' | 'selector' | 'subflow' | 'loop' | 'break' | 'error';
     text: string;
     depth: number;
     stageName?: string;

package/dist/types/lib/engine/narrative/FlowRecorderDispatcher.d.ts

@@ -33,8 +33,9 @@ export declare class FlowRecorderDispatcher implements IControlFlowNarrative {
     onBreak(stageName: string, traversalContext?: TraversalContext): void;
     onError(stageName: string, errorMessage: string, error: unknown, traversalContext?: TraversalContext): void;
     /**
-     * Returns sentences from the first attached recorder that provides them.
-     * By convention, NarrativeFlowRecorder exposes getSentences().
+     * Returns sentences from an attached NarrativeFlowRecorder (looked up by ID).
+     * Callers that need sentences should attach a NarrativeFlowRecorder with id 'narrative'
+     * and retrieve it directly via getRecorderById() if they need typed access.
      */
     getSentences(): string[];
 }

package/dist/types/lib/engine/narrative/NarrativeFlowRecorder.d.ts

@@ -14,7 +14,6 @@ export declare class NarrativeFlowRecorder implements FlowRecorder {
     private sentences;
     /** Parallel array: the actual stage name that produced each sentence. */
     private stageNames;
-    private isFirstStage;
     constructor(id?: string);
     onStageExecuted(event: FlowStageEvent): void;
     onNext(event: FlowNextEvent): void;

package/dist/types/lib/engine/narrative/index.d.ts

@@ -1,7 +1,6 @@
 export type { CombinedNarrativeEntry, CombinedNarrativeOptions } from './CombinedNarrativeBuilder.js';
 export type { CombinedNarrativeRecorderOptions } from './CombinedNarrativeRecorder.js';
 export { CombinedNarrativeRecorder } from './CombinedNarrativeRecorder.js';
-export { ControlFlowNarrativeGenerator } from './ControlFlowNarrativeGenerator.js';
 export { NullControlFlowNarrativeGenerator } from './NullControlFlowNarrativeGenerator.js';
 export type { IControlFlowNarrative } from './types.js';
 export { FlowRecorderDispatcher } from './FlowRecorderDispatcher.js';

package/dist/types/lib/engine/traversal/FlowchartTraverser.d.ts

@@ -45,6 +45,11 @@ export interface TraverserOptions<TOut = any, TScope = any> {
     signal?: AbortSignal;
     /** Pre-configured FlowRecorders to attach when narrative is enabled. */
     flowRecorders?: FlowRecorder[];
+    /**
+     * Maximum recursive executeNode depth. Defaults to FlowchartTraverser.MAX_EXECUTE_DEPTH (500).
+     * Override in tests or unusually deep pipelines.
+     */
+    maxDepth?: number;
 }
 export declare class FlowchartTraverser<TOut = any, TScope = any> {
     private readonly root;
@@ -65,6 +70,42 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
     private readonly narrativeGenerator;
     private readonly flowRecorderDispatcher;
     private subflowResults;
+    /**
+     * Per-traverser set of lazy subflow IDs that have been resolved by THIS run.
+     * Used instead of writing `node.subflowResolver = undefined` back to the shared
+     * StageNode graph — avoids a race where a concurrent traverser clears the shared
+     * resolver before another traverser has finished using it.
+     */
+    private readonly resolvedLazySubflows;
+    /**
+     * Recursion depth counter for executeNode.
+     * Each recursive executeNode call increments this; decrements on exit (try/finally).
+     * Prevents call-stack overflow on infinite loops or excessively deep stage chains.
+     */
+    private _executeDepth;
+    /**
+     * Per-instance maximum depth (set from TraverserOptions.maxDepth or the class default).
+     */
+    private readonly _maxDepth;
+    /**
+     * Default maximum recursive executeNode depth before an error is thrown.
+     * 500 comfortably covers any realistic pipeline depth (including deeply nested
+     * subflows) while preventing call-stack overflow (~10 000 frames in V8).
+     *
+     * **Note on counting:** the counter increments once per `executeNode` call, not once per
+     * logical user stage. Subflow root entry and subflow continuation after return each cost
+     * one tick. For pipelines with many nested subflows, budget roughly 2 × (avg stages per
+     * subflow) of headroom when computing a custom `maxDepth` via `RunOptions.maxDepth`.
+     *
+     * **Note on loops:** for `loopTo()` pipelines, this depth guard and `ContinuationResolver`'s
+     * iteration limit are independent — the lower one fires first. The default depth guard (500)
+     * fires before the default iteration limit (1000) for loop-heavy pipelines.
+     *
+     * @remarks Not safe for concurrent `.execute()` calls on the same instance — concurrent
+     * executions race on `_executeDepth`. Use a separate `FlowchartTraverser` per concurrent
+     * execution. `FlowChartExecutor.run()` always creates a fresh traverser per call.
+     */
+    static readonly MAX_EXECUTE_DEPTH = 500;
     constructor(opts: TraverserOptions<TOut, TScope>);
     private createDeps;
     execute(): Promise<TraversalResult>;
@@ -76,6 +117,12 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
         subflowResults?: Record<string, unknown> | undefined;
         recorders?: {
             id: string;
+            /**
+             * Per-traverser set of lazy subflow IDs that have been resolved by THIS run.
+             * Used instead of writing `node.subflowResolver = undefined` back to the shared
+             * StageNode graph — avoids a race where a concurrent traverser clears the shared
+             * resolver before another traverser has finished using it.
+             */
             name: string;
             data: unknown;
         }[] | undefined;
@@ -90,6 +137,12 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
     getNarrative(): string[];
     /** Returns the FlowRecorderDispatcher, or undefined if narrative is disabled. */
     getFlowRecorderDispatcher(): FlowRecorderDispatcher | undefined;
+    /**
+     * Build an O(1) ID→node map from the root graph.
+     * Used by NodeResolver to avoid repeated DFS on every loopTo() call.
+     * Depth-guarded at MAX_EXECUTE_DEPTH to prevent infinite recursion on cyclic graphs.
+     */
+    private buildNodeIdMap;
     private getStageFn;
     private executeStage;
     /**

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

@@ -112,7 +112,7 @@ export interface HandlerDeps<TOut = any, TScope = any> {
     stageMap: Map<string, StageFunction<TOut, TScope>>;
     root: StageNode<TOut, TScope>;
     executionRuntime: IExecutionRuntime;
-    ScopeFactory: ScopeFactory<TScope>;
+    scopeFactory: ScopeFactory<TScope>;
     subflows?: Record<string, {
         root: StageNode<TOut, TScope>;
     }>;
@@ -144,10 +144,17 @@ export interface RunOptions {
      * Accessible via `scope.getEnv()`. Inherited by subflows automatically.
      */
     env?: ExecutionEnv;
+    /**
+     * Override the maximum recursive `executeNode` depth for this run.
+     * Defaults to `FlowchartTraverser.MAX_EXECUTE_DEPTH` (500).
+     * Useful when deeply nested subflows or long chains need more headroom.
+     * Must be >= 1.
+     */
+    maxDepth?: number;
 }
 export type { FlowControlType, FlowMessage };
 export interface RuntimeStructureMetadata {
-    type: 'stage' | 'decider' | 'fork' | 'streaming';
+    type: 'stage' | 'decider' | 'selector' | 'fork' | 'streaming' | 'subflow';
     subflowId?: string;
     isSubflowRoot?: boolean;
     subflowName?: string;
@@ -200,7 +207,7 @@ export type TraversalResult = BranchResults | string | Error;
 export interface SerializedPipelineNode {
     name: string;
     id?: string;
-    type?: 'stage' | 'decider' | 'fork' | 'streaming' | 'loop' | 'user' | 'tool' | 'function' | 'sequence';
+    type?: 'stage' | 'decider' | 'selector' | 'fork' | 'streaming' | 'subflow' | 'loop' | 'user' | 'tool' | 'function' | 'sequence';
     description?: string;
     children?: SerializedPipelineNode[];
     next?: SerializedPipelineNode;

package/dist/types/lib/memory/StageContext.d.ts

@@ -53,11 +53,8 @@ export declare class StageContext {
     appendToArray(path: string[], key: string, items: unknown[], description?: string): void;
     mergeObject(path: string[], key: string, obj: Record<string, unknown>, description?: string): void;
     getValue(path: string[], key?: string, description?: string): any;
-    get(path: string[], key?: string): any;
     getRoot(key: string): any;
     getGlobal(key: string): any;
-    getFromRoot(key: string): any;
-    getFromGlobalContext(key: string): any;
     getScope(): Record<string, unknown>;
     getRunId(): string;
     commit(): void;

package/dist/types/lib/memory/pathOps.d.ts

@@ -1,10 +1,34 @@
 /**
  * pathOps.ts — Native nested-path helpers (replaces lodash.get/set/has/mergewith)
  *
- * All functions guard against prototype-pollution attacks.
+ * Security contract: all functions guard against prototype-pollution and
+ * prototype-chain-read attacks. The DENIED set blocks the three canonical
+ * pollution vectors (__proto__, constructor, prototype) on every function.
+ *
+ * Intentional asymmetry:
+ *   - nativeSet  — DENIED check only at each segment. No hasOwnProperty
+ *     check is needed because writing always creates an OWN property on `curr`,
+ *     which cannot pollute the prototype chain.
+ *   - nativeGet / nativeHas — DENIED check + hasOwnProperty at every step.
+ *     Reads follow the prototype chain by default (bracket notation), so the
+ *     hasOwnProperty guard is required to prevent leaking inherited values
+ *     (e.g. Object.prototype, Object constructor, toString).
+ *   - mergeContextWins — DENIED check only; Object.keys() is own-enumerable-only
+ *     by spec so prototype keys never appear in the iteration.
+ *
+ * Do NOT "fix" the nativeSet asymmetry by adding hasOwnProperty — it is
+ * intentional and would break path creation for new intermediate nodes.
+ *
  * Paths may be dot-notation strings or pre-split (string|number)[] arrays.
  */
-/** Get the value at `path` in `obj`, returning `defaultValue` if absent. */
+/**
+ * Get the value at `path` in `obj`, returning `defaultValue` if absent.
+ *
+ * Security: each path segment is checked against the DENIED list and requires
+ * an own property at every step, preventing prototype-chain reads.
+ * e.g. nativeGet({}, '__proto__') and nativeGet({}, 'constructor') both return
+ * `defaultValue` instead of leaking Object.prototype / the Object constructor.
+ */
 export declare function nativeGet(obj: any, path: string | (string | number)[], defaultValue?: any): any;
 /** Mutate `obj`, setting `value` at `path` (creates intermediate objects). Returns `obj`. */
 export declare function nativeSet(obj: any, path: string | (string | number)[], value: any): any;

package/dist/types/lib/memory/utils.d.ts

@@ -31,9 +31,18 @@ export declare function setNestedValue<T>(obj: NestedObject, runId: string, _pat
 export declare function updateNestedValue<T>(obj: any, runId: string | undefined, _path: (string | number)[], field: string | number, value: T, defaultValues?: unknown): any;
 /**
  * In-place value update with merge semantics.
- * - Arrays: concatenate
- * - Objects: shallow merge (spread)
+ * - Arrays (non-empty): concatenate onto existing
+ * - Arrays (empty):     direct replace — writing `[]` clears the field
+ * - Objects (non-empty): shallow merge (spread)
+ * - Objects (empty):    direct replace — writing `{}` clears the field
  * - Primitives: direct assignment
+ *
+ * Note on empty arrays: both `value && Array.isArray(value)` and
+ * `Array.isArray(value)` evaluate the same for arrays — `[]` is truthy in
+ * JavaScript, so the `&&` guard was never the issue. The actual bug was the
+ * concat path: `[...cur, ...[]]` silently returned `cur` unchanged when `value`
+ * was `[]`, making `updateValue(obj, 'tags', [])` a no-op instead of a clear.
+ * The fix is the explicit `value.length === 0` early-return branch.
  */
 export declare function updateValue(object: any, key: string | number, value: any): void;
 /**
@@ -50,7 +59,11 @@ export declare function redactPatch(patch: MemoryPatch, redactedSet: Set<string>
 export declare function normalisePath(path: (string | number)[]): string;
 /**
  * Deep union merge helper.
- * - Arrays: union without duplicates (encounter order preserved)
+ * - Arrays (non-empty): union without duplicates (encounter order preserved)
+ * - Arrays (empty):     replace — src `[]` clears the destination array.
+ *   Rationale: writing `scope.tags = []` means "clear tags", not "append nothing".
+ *   Without this rule, an empty-array write silently becomes a no-op which is
+ *   impossible to distinguish from a bug.
  * - Objects: recursive merge
  * - Primitives: source wins
  */

package/dist/types/lib/runner/FlowChartExecutor.d.ts

@@ -1,11 +1,20 @@
 /**
  * FlowChartExecutor — Public API for executing a compiled FlowChart.
  *
- * Wraps FlowchartTraverser. Pairs with FlowChartBuilder:
+ * Wraps FlowchartTraverser. Build a chart with flowChart() and pass the result here:
+ *
  *   const chart = flowChart('entry', entryFn).addFunction('process', processFn).build();
- *   const executor = new FlowChartExecutor(chart);          // uses default ScopeFacade
- *   const executor = new FlowChartExecutor(chart, myFactory); // custom scope factory
- *   const result = await executor.run();
+ *
+ *   // No-options form (uses auto-detected TypedScope factory from the chart):
+ *   const executor = new FlowChartExecutor(chart);
+ *
+ *   // Options-object form (preferred when you need to customize behavior):
+ *   const executor = new FlowChartExecutor(chart, { scopeFactory: myFactory, enrichSnapshots: true });
+ *
+ *   // 2-param form (accepts a ScopeFactory directly, for backward compatibility):
+ *   const executor = new FlowChartExecutor(chart, myFactory);
+ *
+ *   const result = await executor.run({ input: data, env: { traceId: 'req-123' } });
  */
 import type { CombinedNarrativeEntry } from '../engine/narrative/CombinedNarrativeBuilder.js';
 import type { ManifestEntry } from '../engine/narrative/recorders/ManifestFlowRecorder.js';
@@ -14,6 +23,54 @@ import { type ExtractorError, type FlowChart, type RunOptions, type ScopeFactory
 import type { ScopeProtectionMode } from '../scope/protection/types.js';
 import type { Recorder, RedactionPolicy, RedactionReport } from '../scope/types.js';
 import { type RuntimeSnapshot } from './ExecutionRuntime.js';
+/**
+ * Options object for `FlowChartExecutor` — preferred over positional params.
+ *
+ * ```typescript
+ * const ex = new FlowChartExecutor(chart, {
+ *   scopeFactory: myFactory,
+ *   enrichSnapshots: true,
+ * });
+ * ```
+ *
+ * **Sync note for maintainers:** Every field added here must also appear in the
+ * `flowChartArgs` private field type and in the constructor's options-resolution
+ * block (the `else if` branch that reads from `opts`). Missing any one of the
+ * three causes silent omission — the option is accepted but never applied.
+ *
+ * **TScope inference note:** When using the options-object form with a custom scope,
+ * TypeScript cannot infer `TScope` through the options object. Pass the type
+ * explicitly: `new FlowChartExecutor<TOut, MyScope>(chart, { scopeFactory })`.
+ */
+export interface FlowChartExecutorOptions<TScope = any> {
+    /** Custom scope factory. Defaults to TypedScope or ScopeFacade auto-detection. */
+    scopeFactory?: ScopeFactory<TScope>;
+    /** Whether to enrich snapshots with scope state (enables `getSnapshot()`). */
+    enrichSnapshots?: boolean;
+    /**
+     * Default values pre-populated into the shared context before **each** stage
+     * (re-applied every stage, acting as baseline defaults).
+     */
+    defaultValuesForContext?: unknown;
+    /**
+     * Initial context values merged into the shared context **once** at startup
+     * (applied before the first stage, not repeated on subsequent stages).
+     * Distinct from `defaultValuesForContext`, which is re-applied every stage.
+     */
+    initialContext?: unknown;
+    /** Read-only input accessible via `scope.getArgs()` — never tracked or written. */
+    readOnlyContext?: unknown;
+    /**
+     * Custom error classifier for throttling detection. Return `true` if the
+     * error represents a rate-limit or backpressure condition (the executor will
+     * treat it differently from hard failures). Defaults to no throttling classification.
+     */
+    throttlingErrorChecker?: (error: unknown) => boolean;
+    /** Handlers for streaming stage lifecycle events (see `addStreamingFunction`). */
+    streamHandlers?: StreamHandlers;
+    /** Scope protection mode for TypedScope direct-assignment detection. */
+    scopeProtectionMode?: ScopeProtectionMode;
+}
 export declare class FlowChartExecutor<TOut = any, TScope = any> {
     private traverser;
     private narrativeEnabled;
@@ -24,7 +81,23 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
     private sharedRedactedKeys;
     private sharedRedactedFieldsByKey;
     private readonly flowChartArgs;
-    constructor(flowChart: FlowChart<TOut, TScope>, scopeFactory?: ScopeFactory<TScope>, defaultValuesForContext?: unknown, initialContext?: unknown, readOnlyContext?: unknown, throttlingErrorChecker?: (error: unknown) => boolean, streamHandlers?: StreamHandlers, scopeProtectionMode?: ScopeProtectionMode, enrichSnapshots?: boolean);
+    /**
+     * Create a FlowChartExecutor.
+     *
+     * **Options object form** (preferred):
+     * ```typescript
+     * new FlowChartExecutor(chart, { scopeFactory, enrichSnapshots: true })
+     * ```
+     *
+     * **2-param form** (also supported):
+     * ```typescript
+     * new FlowChartExecutor(chart, scopeFactory)
+     * ```
+     *
+     * @param flowChart - The compiled FlowChart returned by `flowChart(...).build()`
+     * @param factoryOrOptions - A `ScopeFactory<TScope>` OR a `FlowChartExecutorOptions<TScope>` options object.
+     */
+    constructor(flowChart: FlowChart<TOut, TScope>, factoryOrOptions?: ScopeFactory<TScope> | FlowChartExecutorOptions<TScope>);
     private createTraverser;
     enableNarrative(): void;
     /**
@@ -100,8 +173,6 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
     /** @internal */
     getExtractedResults<TResult = unknown>(): Map<string, TResult>;
     /** @internal */
-    getEnrichedResults<TResult = unknown>(): Map<string, TResult>;
-    /** @internal */
     getExtractorErrors(): ExtractorError[];
     /**
      * Returns the subflow manifest from an attached ManifestFlowRecorder.

package/dist/types/lib/runner/RunnableChart.d.ts

@@ -47,6 +47,8 @@ export interface RunnableFlowChart<TOut = any, TScope = any> extends FlowChart<T
     toOpenAPI(options?: ChartOpenAPIOptions): object;
     /** Generate MCP tool description from chart metadata. Cached. */
     toMCPTool(): MCPToolDescription;
+    /** Generate a Mermaid flowchart diagram string from the chart's node graph. */
+    toMermaid(): string;
 }
 /**
  * Enrich a FlowChart with run + describe methods.

package/dist/types/lib/runner/index.d.ts

@@ -1,6 +1,7 @@
 export type { ComposableRunner } from './ComposableRunner.js';
 export type { NarrativeEntry, RecorderSnapshot, RuntimeSnapshot } from './ExecutionRuntime.js';
 export { ExecutionRuntime } from './ExecutionRuntime.js';
+export type { FlowChartExecutorOptions } from './FlowChartExecutor.js';
 export { FlowChartExecutor } from './FlowChartExecutor.js';
 export type { SubtreeSnapshot } from './getSubtreeSnapshot.js';
 export { getSubtreeSnapshot, listSubflowPaths } from './getSubtreeSnapshot.js';

package/dist/types/lib/scope/ScopeFacade.d.ts

@@ -111,8 +111,25 @@ export declare class ScopeFacade {
     getPipelineId(): string;
     /** Checks if a key is redacted (explicit _redactedKeys set). */
     private _isKeyRedacted;
-    /** Checks if a key should be auto-redacted by the policy (exact keys + patterns). */
+    /**
+     * Checks if a key should be auto-redacted by the policy (exact keys + patterns).
+     *
+     * ReDoS guard: pattern testing is capped at MAX_PATTERN_KEY_LEN characters.
+     * Scope state keys are always short identifiers; any key exceeding the cap
+     * is almost certainly not a legitimate scope key, so skipping pattern matching
+     * for it does not risk leaking PII. Exact-key matching (Array.includes) is
+     * still applied regardless of length and is not vulnerable to ReDoS.
+     */
     private _isPolicyRedacted;
+    /**
+     * Maximum key length (characters) that will be tested against regex redaction
+     * patterns. Keys longer than this are skipped for pattern matching to prevent
+     * ReDoS: a pathological regex tested against an unboundedly long key string
+     * can cause catastrophic backtracking.
+     *
+     * 256 characters comfortably exceeds any realistic scope-state key name.
+     */
+    private static readonly _MAX_PATTERN_KEY_LEN;
     /**
      * Returns a deep-cloned copy with specified fields replaced by '[REDACTED]'.
      * Supports dot-notation paths (e.g. 'address.zip') for nested objects.

package/dist/types/lib/scope/index.d.ts

@@ -10,7 +10,6 @@ export type { DebugEntry, DebugRecorderOptions, DebugVerbosity } from './recorde
 export { DebugRecorder } from './recorders/DebugRecorder.js';
 export type { AggregatedMetrics, StageMetrics } from './recorders/MetricRecorder.js';
 export { MetricRecorder } from './recorders/MetricRecorder.js';
-export type { NarrativeDetail, NarrativeOperation, NarrativeRecorderOptions, StageNarrativeData, } from './recorders/NarrativeRecorder.js';
 export type { ScopeProtectionMode, ScopeProtectionOptions } from './protection/index.js';
 export { createErrorMessage, createProtectedScope } from './protection/index.js';
 export type { ProviderResolver, ResolveOptions, ScopeFactory, ScopeProvider, StageContextLike, StrictMode, } from './providers/index.js';

package/dist/types/lib/scope/providers/types.d.ts

@@ -11,7 +11,7 @@ export interface StageContextLike {
     updateObject(path: string[], key: string, value: unknown, description?: string): void;
     addLog?(key: string, val: unknown): void;
     addError?(key: string, val: unknown): void;
-    getFromGlobalContext?(key: string): unknown;
+    getGlobal?(key: string): unknown;
     setRoot?(key: string, value: unknown): void;
     setGlobal?(key: string, value: unknown, description?: string): void;
     pipelineId?: string;

package/dist/types/lib/scope/recorders/index.d.ts

@@ -3,4 +3,3 @@ export type { DebugEntry, DebugRecorderOptions, DebugVerbosity } from './DebugRe
 export { DebugRecorder } from './DebugRecorder.js';
 export type { AggregatedMetrics, StageMetrics } from './MetricRecorder.js';
 export { MetricRecorder } from './MetricRecorder.js';
-export type { NarrativeDetail, NarrativeOperation, NarrativeRecorderOptions, StageNarrativeData, } from './NarrativeRecorder.js';

package/dist/types/lib/scope/types.d.ts

@@ -47,7 +47,13 @@ export interface StageEvent extends RecorderContext {
 export interface RedactionPolicy {
     /** Exact key names to always redact (e.g. ['ssn', 'creditCard']). */
     keys?: string[];
-    /** Regex patterns — any key matching a pattern is auto-redacted. */
+    /**
+     * Regex patterns — any key matching a pattern is auto-redacted.
+     *
+     * Pattern matching is skipped for keys that exceed an internal length cap
+     * (designed to prevent ReDoS on pathological patterns). For very long key
+     * names, use `keys` (exact match) instead of patterns.
+     */
     patterns?: RegExp[];
     /** Field-level redaction within objects — key → array of fields to scrub.
      *  Supports dot-notation for nested paths (e.g. 'address.zip'). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "3.0.21",
+  "version": "4.0.0",
   "description": "Explainable backend flows — automatic causal traces, decision evidence, and MCP tool generation for AI agents",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",

package/dist/esm/lib/engine/narrative/ControlFlowNarrativeGenerator.js

@@ -1,110 +0,0 @@
-/**
- * ControlFlowNarrativeGenerator — Active implementation of IControlFlowNarrative.
- *
- * Converts traversal events into plain-English sentences at traversal time.
- * Produces a human-readable story as a first-class output, enabling any consumer
- * (cheaper LLM, follow-up agent, logging system) to understand what happened
- * without parsing technical structures.
- *
- * This is the FLOW narrative — it captures control flow decisions.
- * The DATA narrative comes from scope/recorders/NarrativeRecorder.
- * CombinedNarrativeBuilder merges both into one story.
- */
-export class ControlFlowNarrativeGenerator {
-    constructor() {
-        this.sentences = [];
-        this.isFirstStage = true;
-    }
-    onStageExecuted(stageName, description) {
-        if (this.isFirstStage) {
-            if (description) {
-                this.sentences.push(`The process began: ${description}.`);
-            }
-            else {
-                this.sentences.push(`The process began with ${stageName}.`);
-            }
-            this.isFirstStage = false;
-        }
-    }
-    onNext(fromStage, toStage, description) {
-        if (description) {
-            this.sentences.push(`Next step: ${description}.`);
-        }
-        else {
-            this.sentences.push(`Next, it moved on to ${toStage}.`);
-        }
-    }
-    onDecision(deciderName, chosenBranch, rationale, deciderDescription, _traversalContext, evidence) {
-        const branchName = chosenBranch;
-        if (evidence) {
-            const matchedRule = evidence.rules.find((r) => r.matched);
-            if (matchedRule) {
-                const label = matchedRule.label ? ` "${matchedRule.label}"` : '';
-                if (matchedRule.type === 'filter') {
-                    const parts = matchedRule.conditions.map((c) => `${c.key} ${c.actualSummary} ${c.op} ${JSON.stringify(c.threshold)} ${c.result ? '\u2713' : '\u2717'}`);
-                    this.sentences.push(`It evaluated${label}: ${parts.join(', ')}, and chose ${branchName}.`);
-                }
-                else {
-                    const parts = matchedRule.inputs.map((i) => `${i.key}=${i.valueSummary}`);
-                    this.sentences.push(`It examined${label}: ${parts.join(', ')}, and chose ${branchName}.`);
-                }
-            }
-            else {
-                this.sentences.push(`No rules matched, fell back to default: ${branchName}.`);
-            }
-        }
-        else if (deciderDescription && rationale) {
-            this.sentences.push(`It ${deciderDescription}: ${rationale}, so it chose ${branchName}.`);
-        }
-        else if (deciderDescription) {
-            this.sentences.push(`It ${deciderDescription} and chose ${branchName}.`);
-        }
-        else if (rationale) {
-            this.sentences.push(`A decision was made: ${rationale}, so the path taken was ${branchName}.`);
-        }
-        else {
-            this.sentences.push(`A decision was made, and the path taken was ${branchName}.`);
-        }
-    }
-    onFork(parentStage, childNames) {
-        const names = childNames.join(', ');
-        this.sentences.push(`Forking into ${childNames.length} parallel paths: ${names}.`);
-    }
-    onSelected(parentStage, selectedNames, totalCount) {
-        const names = selectedNames.join(', ');
-        this.sentences.push(`${selectedNames.length} of ${totalCount} paths were selected: ${names}.`);
-    }
-    onSubflowEntry(subflowName, _subflowId, description) {
-        if (description) {
-            this.sentences.push(`Entering the ${subflowName} subflow: ${description}.`);
-        }
-        else {
-            this.sentences.push(`Entering the ${subflowName} subflow.`);
-        }
-    }
-    onSubflowExit(subflowName, _subflowId) {
-        this.sentences.push(`Exiting the ${subflowName} subflow.`);
-    }
-    onSubflowRegistered(_subflowId, _name, _description, _specStructure) {
-        // No narrative output for registration events
-    }
-    onLoop(targetStage, iteration, description) {
-        if (description) {
-            this.sentences.push(`On pass ${iteration}: ${description} again.`);
-        }
-        else {
-            this.sentences.push(`On pass ${iteration} through ${targetStage}.`);
-        }
-    }
-    onBreak(stageName) {
-        this.sentences.push(`Execution stopped at ${stageName}.`);
-    }
-    onError(stageName, errorMessage, _error) {
-        this.sentences.push(`An error occurred at ${stageName}: ${errorMessage}.`);
-    }
-    /** Returns a defensive copy of accumulated sentences. */
-    getSentences() {
-        return [...this.sentences];
-    }
-}
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiQ29udHJvbEZsb3dOYXJyYXRpdmVHZW5lcmF0b3IuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi8uLi9zcmMvbGliL2VuZ2luZS9uYXJyYXRpdmUvQ29udHJvbEZsb3dOYXJyYXRpdmVHZW5lcmF0b3IudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7Ozs7O0dBV0c7QUFLSCxNQUFNLE9BQU8sNkJBQTZCO0lBQTFDO1FBQ1UsY0FBUyxHQUFhLEVBQUUsQ0FBQztRQUN6QixpQkFBWSxHQUFHLElBQUksQ0FBQztJQXdHOUIsQ0FBQztJQXRHQyxlQUFlLENBQUMsU0FBaUIsRUFBRSxXQUFvQjtRQUNyRCxJQUFJLElBQUksQ0FBQyxZQUFZLEVBQUUsQ0FBQztZQUN0QixJQUFJLFdBQVcsRUFBRSxDQUFDO2dCQUNoQixJQUFJLENBQUMsU0FBUyxDQUFDLElBQUksQ0FBQyxzQkFBc0IsV0FBVyxHQUFHLENBQUMsQ0FBQztZQUM1RCxDQUFDO2lCQUFNLENBQUM7Z0JBQ04sSUFBSSxDQUFDLFNBQVMsQ0FBQyxJQUFJLENBQUMsMEJBQTBCLFNBQVMsR0FBRyxDQUFDLENBQUM7WUFDOUQsQ0FBQztZQUNELElBQUksQ0FBQyxZQUFZLEdBQUcsS0FBSyxDQUFDO1FBQzVCLENBQUM7SUFDSCxDQUFDO0lBRUQsTUFBTSxDQUFDLFNBQWlCLEVBQUUsT0FBZSxFQUFFLFdBQW9CO1FBQzdELElBQUksV0FBVyxFQUFFLENBQUM7WUFDaEIsSUFBSSxDQUFDLFNBQVMsQ0FBQyxJQUFJLENBQUMsY0FBYyxXQUFXLEdBQUcsQ0FBQyxDQUFDO1FBQ3BELENBQUM7YUFBTSxDQUFDO1lBQ04sSUFBSSxDQUFDLFNBQVMsQ0FBQyxJQUFJLENBQUMsd0JBQXdCLE9BQU8sR0FBRyxDQUFDLENBQUM7UUFDMUQsQ0FBQztJQUNILENBQUM7SUFFRCxVQUFVLENBQ1IsV0FBbUIsRUFDbkIsWUFBb0IsRUFDcEIsU0FBa0IsRUFDbEIsa0JBQTJCLEVBQzNC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LENBQUM7SUFFRCxPQUFPLENBQUMsU0FBaUIsRUFBRSxZQUFvQixFQUFFLE1BQWU7UUFDOUQsSUFBSSxDQUFDLFNBQVMsQ0FBQyxJQUFJLENBQUMsd0JBQXdCLFNBQVMsS0FBSyxZQUFZLEdBQUcsQ0FBQyxDQUFDO0lBQzdFLENBQUM7SUFFRCx5REFBeUQ7SUFDekQsWUFBWTtRQUNWLE9BQU8sQ0FBQyxHQUFHLElBQUksQ0FBQyxTQUFTLENBQUMsQ0FBQztJQUM3QixDQUFDO0NBQ0YiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIENvbnRyb2xGbG93TmFycmF0aXZlR2VuZXJhdG9yIOKAlCBBY3RpdmUgaW1wbGVtZW50YXRpb24gb2YgSUNvbnRyb2xGbG93TmFycmF0aXZlLlxuICpcbiAqIENvbnZlcnRzIHRyYXZlcnNhbCBldmVudHMgaW50byBwbGFpbi1FbmdsaXNoIHNlbnRlbmNlcyBhdCB0cmF2ZXJzYWwgdGltZS5cbiAqIFByb2R1Y2VzIGEgaHVtYW4tcmVhZGFibGUgc3RvcnkgYXMgYSBmaXJzdC1jbGFzcyBvdXRwdXQsIGVuYWJsaW5nIGFueSBjb25zdW1lclxuICogKGNoZWFwZXIgTExNLCBmb2xsb3ctdXAgYWdlbnQsIGxvZ2dpbmcgc3lzdGVtKSB0byB1bmRlcnN0YW5kIHdoYXQgaGFwcGVuZWRcbiAqIHdpdGhvdXQgcGFyc2luZyB0ZWNobmljYWwgc3RydWN0dXJlcy5cbiAqXG4gKiBUaGlzIGlzIHRoZSBGTE9XIG5hcnJhdGl2ZSDigJQgaXQgY2FwdHVyZXMgY29udHJvbCBmbG93IGRlY2lzaW9ucy5cbiAqIFRoZSBEQVRBIG5hcnJhdGl2ZSBjb21lcyBmcm9tIHNjb3BlL3JlY29yZGVycy9OYXJyYXRpdmVSZWNvcmRlci5cbiAqIENvbWJpbmVkTmFycmF0aXZlQnVpbGRlciBtZXJnZXMgYm90aCBpbnRvIG9uZSBzdG9yeS5cbiAqL1xuXG5pbXBvcnQgdHlwZSB7IERlY2lzaW9uRXZpZGVuY2UgfSBmcm9tICcuLi8uLi9kZWNpZGUvdHlwZXMuanMnO1xuaW1wb3J0IHR5cGUgeyBJQ29udHJvbEZsb3dOYXJyYXRpdmUgfSBmcm9tICcuL3R5cGVzLmpzJztcblxuZXhwb3J0IGNsYXNzIENvbnRyb2xGbG93TmFycmF0aXZlR2VuZXJhdG9yIGltcGxlbWVudHMgSUNvbnRyb2xGbG93TmFycmF0aXZlIHtcbiAgcHJpdmF0ZSBzZW50ZW5jZXM6IHN0cmluZ1tdID0gW107XG4gIHByaXZhdGUgaXNGaXJzdFN0YWdlID0gdHJ1ZTtcblxuICBvblN0YWdlRXhlY3V0ZWQoc3RhZ2VOYW1lOiBzdHJpbmcsIGRlc2NyaXB0aW9uPzogc3RyaW5nKTogdm9pZCB7XG4gICAgaWYgKHRoaXMuaXNGaXJzdFN0YWdlKSB7XG4gICAgICBpZiAoZGVzY3JpcHRpb24pIHtcbiAgICAgICAgdGhpcy5zZW50ZW5jZXMucHVzaChgVGhlIHByb2Nlc3MgYmVnYW46ICR7ZGVzY3JpcHRpb259LmApO1xuICAgICAgfSBlbHNlIHtcbiAgICAgICAgdGhpcy5zZW50ZW5jZXMucHVzaChgVGhlIHByb2Nlc3MgYmVnYW4gd2l0aCAke3N0YWdlTmFtZX0uYCk7XG4gICAgICB9XG4gICAgICB0aGlzLmlzRmlyc3RTdGFnZSA9IGZhbHNlO1xuICAgIH1cbiAgfVxuXG4gIG9uTmV4dChmcm9tU3RhZ2U6IHN0cmluZywgdG9TdGFnZTogc3RyaW5nLCBkZXNjcmlwdGlvbj86IHN0cmluZyk6IHZvaWQge1xuICAgIGlmIChkZXNjcmlwdGlvbikge1xuICAgICAgdGhpcy5zZW50ZW5jZXMucHVzaChgTmV4dCBzdGVwOiAke2Rlc2NyaXB0aW9ufS5gKTtcbiAgICB9IGVsc2Uge1xuICAgICAgdGhpcy5zZW50ZW5jZXMucHVzaChgTmV4dCwgaXQgbW92ZWQgb24gdG8gJHt0b1N0YWdlfS5gKTtcbiAgICB9XG4gIH1cblxuICBvbkRlY2lzaW9uKFxuICAgIGRlY2lkZXJOYW1lOiBzdHJpbmcsXG4gICAgY2hvc2VuQnJhbmNoOiBzdHJpbmcsXG4gICAgcmF0aW9uYWxlPzogc3RyaW5nLFxuICAgIGRlY2lkZXJEZXNjcmlwdGlvbj86IHN0cmluZyxcbiAgICBfdHJhdmVyc2FsQ29udGV4dD86IHVua25vd24sXG4gICAgZXZpZGVuY2U/OiBEZWNpc2lvbkV2aWRlbmNlLFxuICApOiB2b2lkIHtcbiAgICBjb25zdCBicmFuY2hOYW1lID0gY2hvc2VuQnJhbmNoO1xuICAgIGlmIChldmlkZW5jZSkge1xuICAgICAgY29uc3QgbWF0Y2hlZFJ1bGUgPSBldmlkZW5jZS5ydWxlcy5maW5kKChyKSA9PiByLm1hdGNoZWQpO1xuICAgICAgaWYgKG1hdGNoZWRSdWxlKSB7XG4gICAgICAgIGNvbnN0IGxhYmVsID0gbWF0Y2hlZFJ1bGUubGFiZWwgPyBgIFwiJHttYXRjaGVkUnVsZS5sYWJlbH1cImAgOiAnJztcbiAgICAgICAgaWYgKG1hdGNoZWRSdWxlLnR5cGUgPT09ICdmaWx0ZXInKSB7XG4gICAgICAgICAgY29uc3QgcGFydHMgPSBtYXRjaGVkUnVsZS5jb25kaXRpb25zLm1hcChcbiAgICAgICAgICAgIChjKSA9PlxuICAgICAgICAgICAgICBgJHtjLmtleX0gJHtjLmFjdHVhbFN1bW1hcnl9ICR7Yy5vcH0gJHtKU09OLnN0cmluZ2lmeShjLnRocmVzaG9sZCl9ICR7Yy5yZXN1bHQgPyAnXFx1MjcxMycgOiAnXFx1MjcxNyd9YCxcbiAgICAgICAgICApO1xuICAgICAgICAgIHRoaXMuc2VudGVuY2VzLnB1c2goYEl0IGV2YWx1YXRlZCR7bGFiZWx9OiAke3BhcnRzLmpvaW4oJywgJyl9LCBhbmQgY2hvc2UgJHticmFuY2hOYW1lfS5gKTtcbiAgICAgICAgfSBlbHNlIHtcbiAgICAgICAgICBjb25zdCBwYXJ0cyA9IG1hdGNoZWRSdWxlLmlucHV0cy5tYXAoKGkpID0+IGAke2kua2V5fT0ke2kudmFsdWVTdW1tYXJ5fWApO1xuICAgICAgICAgIHRoaXMuc2VudGVuY2VzLnB1c2goYEl0IGV4YW1pbmVkJHtsYWJlbH06ICR7cGFydHMuam9pbignLCAnKX0sIGFuZCBjaG9zZSAke2JyYW5jaE5hbWV9LmApO1xuICAgICAgICB9XG4gICAgICB9IGVsc2Uge1xuICAgICAgICB0aGlzLnNlbnRlbmNlcy5wdXNoKGBObyBydWxlcyBtYXRjaGVkLCBmZWxsIGJhY2sgdG8gZGVmYXVsdDogJHticmFuY2hOYW1lfS5gKTtcbiAgICAgIH1cbiAgICB9IGVsc2UgaWYgKGRlY2lkZXJEZXNjcmlwdGlvbiAmJiByYXRpb25hbGUpIHtcbiAgICAgIHRoaXMuc2VudGVuY2VzLnB1c2goYEl0ICR7ZGVjaWRlckRlc2NyaXB0aW9ufTogJHtyYXRpb25hbGV9LCBzbyBpdCBjaG9zZSAke2JyYW5jaE5hbWV9LmApO1xuICAgIH0gZWxzZSBpZiAoZGVjaWRlckRlc2NyaXB0aW9uKSB7XG4gICAgICB0aGlzLnNlbnRlbmNlcy5wdXNoKGBJdCAke2RlY2lkZXJEZXNjcmlwdGlvbn0gYW5kIGNob3NlICR7YnJhbmNoTmFtZX0uYCk7XG4gICAgfSBlbHNlIGlmIChyYXRpb25hbGUpIHtcbiAgICAgIHRoaXMuc2VudGVuY2VzLnB1c2goYEEgZGVjaXNpb24gd2FzIG1hZGU6ICR7cmF0aW9uYWxlfSwgc28gdGhlIHBhdGggdGFrZW4gd2FzICR7YnJhbmNoTmFtZX0uYCk7XG4gICAgfSBlbHNlIHtcbiAgICAgIHRoaXMuc2VudGVuY2VzLnB1c2goYEEgZGVjaXNpb24gd2FzIG1hZGUsIGFuZCB0aGUgcGF0aCB0YWtlbiB3YXMgJHticmFuY2hOYW1lfS5gKTtcbiAgICB9XG4gIH1cblxuICBvbkZvcmsocGFyZW50U3RhZ2U6IHN0cmluZywgY2hpbGROYW1lczogc3RyaW5nW10pOiB2b2lkIHtcbiAgICBjb25zdCBuYW1lcyA9IGNoaWxkTmFtZXMuam9pbignLCAnKTtcbiAgICB0aGlzLnNlbnRlbmNlcy5wdXNoKGBGb3JraW5nIGludG8gJHtjaGlsZE5hbWVzLmxlbmd0aH0gcGFyYWxsZWwgcGF0aHM6ICR7bmFtZXN9LmApO1xuICB9XG5cbiAgb25TZWxlY3RlZChwYXJlbnRTdGFnZTogc3RyaW5nLCBzZWxlY3RlZE5hbWVzOiBzdHJpbmdbXSwgdG90YWxDb3VudDogbnVtYmVyKTogdm9pZCB7XG4gICAgY29uc3QgbmFtZXMgPSBzZWxlY3RlZE5hbWVzLmpvaW4oJywgJyk7XG4gICAgdGhpcy5zZW50ZW5jZXMucHVzaChgJHtzZWxlY3RlZE5hbWVzLmxlbmd0aH0gb2YgJHt0b3RhbENvdW50fSBwYXRocyB3ZXJlIHNlbGVjdGVkOiAke25hbWVzfS5gKTtcbiAgfVxuXG4gIG9uU3ViZmxvd0VudHJ5KHN1YmZsb3dOYW1lOiBzdHJpbmcsIF9zdWJmbG93SWQ/OiBzdHJpbmcsIGRlc2NyaXB0aW9uPzogc3RyaW5nKTogdm9pZCB7XG4gICAgaWYgKGRlc2NyaXB0aW9uKSB7XG4gICAgICB0aGlzLnNlbnRlbmNlcy5wdXNoKGBFbnRlcmluZyB0aGUgJHtzdWJmbG93TmFtZX0gc3ViZmxvdzogJHtkZXNjcmlwdGlvbn0uYCk7XG4gICAgfSBlbHNlIHtcbiAgICAgIHRoaXMuc2VudGVuY2VzLnB1c2goYEVudGVyaW5nIHRoZSAke3N1YmZsb3dOYW1lfSBzdWJmbG93LmApO1xuICAgIH1cbiAgfVxuXG4gIG9uU3ViZmxvd0V4aXQoc3ViZmxvd05hbWU6IHN0cmluZywgX3N1YmZsb3dJZD86IHN0cmluZyk6IHZvaWQge1xuICAgIHRoaXMuc2VudGVuY2VzLnB1c2goYEV4aXRpbmcgdGhlICR7c3ViZmxvd05hbWV9IHN1YmZsb3cuYCk7XG4gIH1cblxuICBvblN1YmZsb3dSZWdpc3RlcmVkKF9zdWJmbG93SWQ6IHN0cmluZywgX25hbWU6IHN0cmluZywgX2Rlc2NyaXB0aW9uPzogc3RyaW5nLCBfc3BlY1N0cnVjdHVyZT86IHVua25vd24pOiB2b2lkIHtcbiAgICAvLyBObyBuYXJyYXRpdmUgb3V0cHV0IGZvciByZWdpc3RyYXRpb24gZXZlbnRzXG4gIH1cblxuICBvbkxvb3AodGFyZ2V0U3RhZ2U6IHN0cmluZywgaXRlcmF0aW9uOiBudW1iZXIsIGRlc2NyaXB0aW9uPzogc3RyaW5nKTogdm9pZCB7XG4gICAgaWYgKGRlc2NyaXB0aW9uKSB7XG4gICAgICB0aGlzLnNlbnRlbmNlcy5wdXNoKGBPbiBwYXNzICR7aXRlcmF0aW9ufTogJHtkZXNjcmlwdGlvbn0gYWdhaW4uYCk7XG4gICAgfSBlbHNlIHtcbiAgICAgIHRoaXMuc2VudGVuY2VzLnB1c2goYE9uIHBhc3MgJHtpdGVyYXRpb259IHRocm91Z2ggJHt0YXJnZXRTdGFnZX0uYCk7XG4gICAgfVxuICB9XG5cbiAgb25CcmVhayhzdGFnZU5hbWU6IHN0cmluZyk6IHZvaWQge1xuICAgIHRoaXMuc2VudGVuY2VzLnB1c2goYEV4ZWN1dGlvbiBzdG9wcGVkIGF0ICR7c3RhZ2VOYW1lfS5gKTtcbiAgfVxuXG4gIG9uRXJyb3Ioc3RhZ2VOYW1lOiBzdHJpbmcsIGVycm9yTWVzc2FnZTogc3RyaW5nLCBfZXJyb3I6IHVua25vd24pOiB2b2lkIHtcbiAgICB0aGlzLnNlbnRlbmNlcy5wdXNoKGBBbiBlcnJvciBvY2N1cnJlZCBhdCAke3N0YWdlTmFtZX06ICR7ZXJyb3JNZXNzYWdlfS5gKTtcbiAgfVxuXG4gIC8qKiBSZXR1cm5zIGEgZGVmZW5zaXZlIGNvcHkgb2YgYWNjdW11bGF0ZWQgc2VudGVuY2VzLiAqL1xuICBnZXRTZW50ZW5jZXMoKTogc3RyaW5nW10ge1xuICAgIHJldHVybiBbLi4udGhpcy5zZW50ZW5jZXNdO1xuICB9XG59XG4iXX0=