footprintjs 0.1.0

package/dist/esm/types/lib/memory/SharedMemory.d.ts

@@ -0,0 +1,34 @@
+/**
+ * SharedMemory — The shared state container for all flowchart execution
+ *
+ * Like a runtime heap with namespace isolation:
+ * - Each run gets its own namespace (runs/{id}/)
+ * - Default values can be initialised and preserved
+ * - Accepts commit bundles from TransactionBuffer
+ */
+import type { MemoryPatch } from './types';
+export declare class SharedMemory {
+    private context;
+    private _defaultValues?;
+    constructor(defaultValues?: unknown, initialContext?: unknown);
+    /** Gets a clone of the default values. */
+    getDefaultValues(): {} | undefined;
+    /** Gets all run namespaces. */
+    getRuns(): any;
+    /** Updates a value using merge semantics. */
+    updateValue(runId: string, path: string[], key: string, value: unknown): void;
+    /** Sets a value using overwrite semantics. */
+    setValue(runId: string, path: string[], key: string, value: unknown): void;
+    /**
+     * Reads a value from the store.
+     * Looks up in run namespace first, falls back to global.
+     */
+    getValue(runId?: string, path?: string[], key?: string): any;
+    /** Gets the entire state as a JSON object. */
+    getState(): Record<string, unknown>;
+    /** Applies a commit bundle from TransactionBuffer. */
+    applyPatch(overwrite: MemoryPatch, updates: MemoryPatch, trace: {
+        path: string;
+        verb: 'set' | 'merge';
+    }[]): void;
+}

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

@@ -0,0 +1,74 @@
+/**
+ * StageContext — Execution context for a single stage in a flowchart run
+ *
+ * Like a stack frame in a compiler/runtime:
+ * - Reference to SharedMemory (accessing heap memory)
+ * - TransactionBuffer for staging mutations (transaction buffer)
+ * - Links to parent/child/next contexts (call stack frames)
+ * - DiagnosticCollector for logs, errors, metrics
+ */
+import { DiagnosticCollector } from './DiagnosticCollector';
+import { EventLog } from './EventLog';
+import { SharedMemory } from './SharedMemory';
+import { TransactionBuffer } from './TransactionBuffer';
+import type { FlowControlType, StageSnapshot } from './types';
+export declare class StageContext {
+    private sharedMemory;
+    private buffer?;
+    private eventLog?;
+    stageName: string;
+    runId: string;
+    branchId?: string;
+    isDecider: boolean;
+    isFork: boolean;
+    parent?: StageContext;
+    next?: StageContext;
+    children?: StageContext[];
+    debug: DiagnosticCollector;
+    constructor(runId: string, name: string, sharedMemory: SharedMemory, branchId?: string, eventLog?: EventLog, isDecider?: boolean);
+    /** Returns the SharedMemory instance (needed by scope layer). */
+    getSharedMemory(): SharedMemory;
+    /** Lazily creates the transaction buffer (pay clone cost only if stage writes). */
+    getTransactionBuffer(): TransactionBuffer;
+    /** Builds an absolute path inside the shared memory (run namespace). */
+    private withNamespace;
+    patch(path: string[], key: string, value: unknown, shouldRedact?: boolean): void;
+    set(path: string[], key: string, value: unknown): void;
+    merge(path: string[], key: string, value: unknown): void;
+    setObject(path: string[], key: string, value: unknown, shouldRedact?: boolean, description?: string): void;
+    updateObject(path: string[], key: string, value: unknown, description?: string): void;
+    setRoot(key: string, value: unknown): void;
+    setGlobal(key: string, value: unknown, description?: string): void;
+    updateGlobalContext(key: string, value: unknown): void;
+    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;
+    createNext(path: string, stageName: string, isDecider?: boolean): StageContext;
+    createChild(runId: string, branchId: string, stageName: string, isDecider?: boolean): StageContext;
+    createDecider(path: string, stageName: string): StageContext;
+    setAsDecider(): StageContext;
+    setAsFork(): StageContext;
+    addLog(key: string, value: unknown, path?: string[]): void;
+    setLog(key: string, value: unknown, path?: string[]): void;
+    addMetric(key: string, value: unknown, path?: string[]): void;
+    setMetric(key: string, value: unknown, path?: string[]): void;
+    addEval(key: string, value: unknown, path?: string[]): void;
+    setEval(key: string, value: unknown, path?: string[]): void;
+    addError(key: string, value: unknown, path?: string[]): void;
+    addFlowDebugMessage(type: FlowControlType, description: string, options?: {
+        targetStage?: string | string[];
+        rationale?: string;
+        count?: number;
+        iteration?: number;
+    }): void;
+    getStageId(): string;
+    getSnapshot(): StageSnapshot;
+}

package/dist/esm/types/lib/memory/TransactionBuffer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * TransactionBuffer — Transactional write buffer for stage mutations
+ *
+ * Collects writes during execution and commits them atomically.
+ * Like a database transaction buffer:
+ * - Changes staged here before being committed to SharedMemory
+ * - Enables read-after-write consistency within a stage
+ * - Records operation trace for deterministic replay
+ */
+import type { MemoryPatch } from './types';
+export declare class TransactionBuffer {
+    private readonly baseSnapshot;
+    private workingCopy;
+    private overwritePatch;
+    private updatePatch;
+    private opTrace;
+    private redactedPaths;
+    constructor(base: any);
+    /** Hard overwrite at the specified path. */
+    set(path: (string | number)[], value: any, shouldRedact?: boolean): void;
+    /** Deep union merge at the specified path. */
+    merge(path: (string | number)[], value: any, shouldRedact?: boolean): void;
+    /** Read current value at path (includes uncommitted changes). */
+    get(path: (string | number)[], defaultValue?: any): any;
+    /**
+     * Flush all staged mutations and return the commit bundle.
+     * Resets the buffer to empty state after commit.
+     */
+    commit(): {
+        overwrite: MemoryPatch;
+        updates: MemoryPatch;
+        redactedPaths: Set<string>;
+        trace: {
+            path: string;
+            verb: 'set' | 'merge';
+        }[];
+    };
+}

package/dist/esm/types/lib/memory/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * memory/ — Foundation library (zero external deps beyond lodash)
+ *
+ * Transactional state management with namespace isolation,
+ * atomic commits, and event-sourced time-travel.
+ */
+export { DiagnosticCollector } from './DiagnosticCollector';
+export { EventLog } from './EventLog';
+export { SharedMemory } from './SharedMemory';
+export { StageContext } from './StageContext';
+export { TransactionBuffer } from './TransactionBuffer';
+export type { CommitBundle, FlowControlType, FlowMessage, MemoryPatch, ScopeFactory, StageSnapshot, TraceEntry, } from './types';
+export { applySmartMerge, deepSmartMerge, DELIM, getNestedValue, getRunAndGlobalPaths, normalisePath, redactPatch, setNestedValue, updateNestedValue, updateValue, } from './utils';

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

@@ -0,0 +1,60 @@
+/**
+ * types.ts — Core type definitions for the memory library
+ *
+ * Zero dependencies on old code or other libraries in this package.
+ */
+/** A flat key-value bag representing a state patch (overwrite or merge). */
+export interface MemoryPatch {
+    [key: string]: any;
+}
+/** A single entry in the chronological operation trace. */
+export interface TraceEntry {
+    /** Canonical path string (segments joined by DELIM). */
+    path: string;
+    /** 'set' = hard overwrite, 'merge' = deep union merge. */
+    verb: 'set' | 'merge';
+}
+/** The atomic bundle produced by TransactionBuffer.commit(). */
+export interface CommitBundle {
+    /** Auto-assigned step index (set by EventLog.record). */
+    idx?: number;
+    /** Human-readable stage name. */
+    stage: string;
+    /** Chronological write log for deterministic replay. */
+    trace: TraceEntry[];
+    /** Paths that should be redacted in UI (sensitive data). */
+    redactedPaths: string[];
+    /** Hard overwrite patches. */
+    overwrite: MemoryPatch;
+    /** Deep merge patches. */
+    updates: MemoryPatch;
+}
+/** Types of control flow decisions captured by the execution engine. */
+export type FlowControlType = 'next' | 'branch' | 'children' | 'selected' | 'subflow' | 'loop';
+/** A single flow control narrative entry. */
+export interface FlowMessage {
+    type: FlowControlType;
+    description: string;
+    targetStage?: string | string[];
+    rationale?: string;
+    count?: number;
+    iteration?: number;
+    timestamp?: number;
+}
+/** Serialisable representation of a stage's state (for debugging / visualisation). */
+export type StageSnapshot = {
+    id: string;
+    name?: string;
+    isDecider?: boolean;
+    isFork?: boolean;
+    logs: Record<string, unknown>;
+    errors: Record<string, unknown>;
+    metrics: Record<string, unknown>;
+    evals: Record<string, unknown>;
+    flowMessages?: FlowMessage[];
+    next?: StageSnapshot;
+    children?: StageSnapshot[];
+};
+/** Forward-declared so StageContext can accept it without importing scope/. */
+export type ScopeFactory<TScope> = (core: StageContext, stageName: string, readOnlyContext?: unknown) => TScope;
+import type { StageContext } from './StageContext';

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

@@ -0,0 +1,67 @@
+/**
+ * utils.ts — Helper functions for nested object manipulation
+ *
+ * Provides consistent path traversal and value manipulation for the memory system.
+ * Zero external dependencies beyond lodash helpers.
+ */
+import type { MemoryPatch } from './types';
+/** ASCII Unit-Separator — cannot appear in JS identifiers, invisible in logs. */
+export declare const DELIM = "\u001F";
+type NestedObject = {
+    [key: string]: any;
+};
+/**
+ * Resolves run-namespaced and global paths.
+ * Each flowchart execution (run) stores data under `runs/{id}/` to prevent collisions.
+ */
+export declare function getRunAndGlobalPaths(runId?: string, path?: (string | number)[]): {
+    runPath: (string | number)[] | undefined;
+    globalPath: (string | number)[];
+};
+/**
+ * Sets a value at a nested path, creating intermediate objects as needed.
+ */
+export declare function setNestedValue<T>(obj: NestedObject, runId: string, _path: string[], field: string, value: T, defaultValues?: unknown): NestedObject;
+/**
+ * Deep-merges a value into the object at the specified path.
+ * - Arrays: concatenate
+ * - Objects: shallow merge at each level
+ * - Primitives: replace
+ */
+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)
+ * - Primitives: direct assignment
+ */
+export declare function updateValue(object: any, key: string | number, value: any): void;
+/**
+ * Gets a value at a nested path with prototype-pollution protection.
+ */
+export declare function getNestedValue(root: any, path: (string | number)[], field?: string | number): any;
+/**
+ * Redacts sensitive values in a patch for logging/debugging.
+ */
+export declare function redactPatch(patch: MemoryPatch, redactedSet: Set<string>): MemoryPatch;
+/**
+ * Normalises an array path into a stable string key using DELIM.
+ */
+export declare function normalisePath(path: (string | number)[]): string;
+/**
+ * Deep union merge helper.
+ * - Arrays: union without duplicates (encounter order preserved)
+ * - Objects: recursive merge
+ * - Primitives: source wins
+ */
+export declare function deepSmartMerge(dst: any, src: any): any;
+/**
+ * Applies a commit bundle to a base state by replaying operations in order.
+ * Two-phase: UPDATE (union-merge) then OVERWRITE (direct set).
+ * Guarantees "last writer wins" semantics.
+ */
+export declare function applySmartMerge(base: any, updates: MemoryPatch, overwrite: MemoryPatch, trace: {
+    path: string;
+    verb: 'set' | 'merge';
+}[]): any;
+export {};

package/dist/esm/types/lib/runner/ExecutionRuntime.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ExecutionRuntime — The runtime environment for one flowchart execution.
+ *
+ * Wires up the three memory primitives into a single container:
+ *   - SharedMemory (the heap — shared state across all stages)
+ *   - StageContext  (the call stack — per-stage execution tree)
+ *   - EventLog      (the transaction log — commit history for replay)
+ *
+ * The engine (FlowchartTraverser) receives this as its runtime parameter.
+ * After execution, consumers query it for the full execution state.
+ */
+import { EventLog } from '../memory/EventLog';
+import { SharedMemory } from '../memory/SharedMemory';
+import { StageContext } from '../memory/StageContext';
+import type { CommitBundle, FlowMessage, StageSnapshot } from '../memory/types';
+export interface NarrativeEntry {
+    stageId: string;
+    stageName: string;
+    displayName?: string;
+    stageMessages: string[];
+    flowMessage?: FlowMessage;
+    timeIndex: number;
+}
+export type RuntimeSnapshot = {
+    sharedState: Record<string, unknown>;
+    executionTree: StageSnapshot;
+    commitLog: CommitBundle[];
+};
+export declare class ExecutionRuntime {
+    globalStore: SharedMemory;
+    rootStageContext: StageContext;
+    executionHistory: EventLog;
+    constructor(rootName: string, defaultValues?: unknown, initialState?: unknown);
+    getPipelines(): string[];
+    setRootObject(path: string[], key: string, value: unknown): void;
+    getSnapshot(): RuntimeSnapshot;
+    getFullNarrative(): NarrativeEntry[];
+    private walkContextTree;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * FlowChartExecutor — Public API for executing a compiled FlowChart.
+ *
+ * Wraps FlowchartTraverser. Pairs with FlowChartBuilder:
+ *   const chart = flowChart('entry', entryFn).addFunction('process', processFn).build();
+ *   const executor = new FlowChartExecutor(chart, scopeFactory);
+ *   const result = await executor.run();
+ */
+import { type ExtractorError, type FlowChart, type RunOptions, type ScopeFactory, type SerializedPipelineStructure, type StageNode, type StreamHandlers, type SubflowResult, type TraversalResult } from '../engine/types';
+import type { ScopeProtectionMode } from '../scope/protection/types';
+export declare class FlowChartExecutor<TOut = any, TScope = any> {
+    private traverser;
+    private narrativeEnabled;
+    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);
+    private createTraverser;
+    enableNarrative(): void;
+    getNarrative(): string[];
+    run(options?: RunOptions): Promise<TraversalResult>;
+    getSnapshot(): {
+        sharedState: Record<string, unknown>;
+        executionTree: unknown;
+        commitLog: unknown[];
+    };
+    getRuntime(): import("../engine/types").IExecutionRuntime;
+    setRootObject(path: string[], key: string, value: unknown): void;
+    getBranchIds(): string[];
+    getRuntimeRoot(): StageNode;
+    getRuntimeStructure(): SerializedPipelineStructure | undefined;
+    getSubflowResults(): Map<string, SubflowResult>;
+    getExtractedResults<TResult = unknown>(): Map<string, TResult>;
+    getEnrichedResults<TResult = unknown>(): Map<string, TResult>;
+    getExtractorErrors(): ExtractorError[];
+}

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

@@ -0,0 +1,3 @@
+export type { NarrativeEntry, RuntimeSnapshot } from './ExecutionRuntime';
+export { ExecutionRuntime } from './ExecutionRuntime';
+export { FlowChartExecutor } from './FlowChartExecutor';

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

@@ -0,0 +1,47 @@
+/**
+ * ScopeFacade — Base class that library consumers extend to create custom scope classes
+ *
+ * Wraps StageContext (from memory/) to provide a consumer-friendly API for
+ * state access, debug logging, metrics, and recorder hooks.
+ *
+ * Consumers extend this class to add domain-specific properties:
+ *
+ * ```typescript
+ * class MyScope extends ScopeFacade {
+ *   get userName(): string { return this.getValue('name') as string; }
+ *   set userName(value: string) { this.setValue('name', value); }
+ * }
+ * ```
+ */
+import { StageContext } from '../memory/StageContext';
+import type { CommitEvent, Recorder } from './types';
+export declare class ScopeFacade {
+    static readonly BRAND: unique symbol;
+    protected _stageContext: StageContext;
+    protected _stageName: string;
+    protected readonly _readOnlyValues?: unknown;
+    private _recorders;
+    constructor(context: StageContext, stageName: string, readOnlyValues?: unknown);
+    attachRecorder(recorder: Recorder): void;
+    detachRecorder(recorderId: string): void;
+    getRecorders(): Recorder[];
+    notifyStageStart(): void;
+    notifyStageEnd(duration?: number): void;
+    notifyCommit(mutations: CommitEvent['mutations']): void;
+    addDebugInfo(key: string, value: unknown): void;
+    addDebugMessage(value: unknown): void;
+    addErrorInfo(key: string, value: unknown): void;
+    addMetric(metricName: string, value: unknown): void;
+    addEval(metricName: string, value: unknown): void;
+    getInitialValueFor(key: string): any;
+    getValue(key?: string): any;
+    setValue(key: string, value: unknown, shouldRedact?: boolean, description?: string): void;
+    updateValue(key: string, value: unknown, description?: string): void;
+    deleteValue(key: string, description?: string): void;
+    setGlobal(key: string, value: unknown, description?: string): void;
+    getGlobal(key: string): any;
+    setObjectInRoot(key: string, value: unknown): void;
+    getReadOnlyValues(): unknown;
+    getPipelineId(): string;
+    private _invokeHook;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * scope/ — Scope management library
+ *
+ * Depends on memory/ (Phase 1). Provides ScopeFacade, recorders,
+ * providers, protection, and Zod-based scope definitions.
+ */
+export { ScopeFacade } from './ScopeFacade';
+export type { CommitEvent, ErrorEvent, ReadEvent, Recorder, RecorderContext, StageEvent, WriteEvent } from './types';
+export type { DebugEntry, DebugRecorderOptions, DebugVerbosity } from './recorders/DebugRecorder';
+export { DebugRecorder } from './recorders/DebugRecorder';
+export type { AggregatedMetrics, StageMetrics } from './recorders/MetricRecorder';
+export { MetricRecorder } from './recorders/MetricRecorder';
+export type { NarrativeDetail, NarrativeOperation, NarrativeRecorderOptions, StageNarrativeData, } from './recorders/NarrativeRecorder';
+export { NarrativeRecorder } from './recorders/NarrativeRecorder';
+export type { ScopeProtectionMode, ScopeProtectionOptions } from './protection';
+export { createErrorMessage, createProtectedScope } from './protection';
+export type { ProviderResolver, ResolveOptions, ScopeFactory, ScopeProvider, StageContextLike, StrictMode, } from './providers';
+export { __clearScopeResolversForTests, attachBaseStateCompat, attachScopeMethods, isSubclassOfScopeFacade, looksLikeClassCtor, looksLikeFactory, makeClassProvider, makeFactoryProvider, registerScopeResolver, resolveScopeProvider, toScopeFactory, } from './providers';
+export type { DefineScopeOptions } from './state/zod/defineScopeFromZod';
+export { defineScopeFromZod } from './state/zod/defineScopeFromZod';
+export { ZodScopeResolver } from './state/zod/resolver';
+export { defineScopeSchema, isScopeSchema } from './state/zod/schema/builder';
+export { createScopeProxyFromZod } from './state/zod/scopeFactory';

package/dist/esm/types/lib/scope/protection/createProtectedScope.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Scope Protection — Proxy-based protection layer
+ *
+ * Intercepts direct property assignments on scope objects and provides
+ * clear error messages guiding developers to use setValue() instead.
+ */
+import type { ScopeProtectionOptions } from './types';
+export declare function createErrorMessage(propertyName: string, stageName: string): string;
+export declare function createProtectedScope<T extends object>(scope: T, options?: ScopeProtectionOptions): T;

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

@@ -0,0 +1,2 @@
+export { createErrorMessage, createProtectedScope } from './createProtectedScope';
+export type { ScopeProtectionMode, ScopeProtectionOptions } from './types';

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

@@ -0,0 +1,13 @@
+/**
+ * Scope Protection Types
+ *
+ * Types for the Proxy-based protection system that prevents
+ * direct property assignment on scope objects.
+ */
+export type ScopeProtectionMode = 'error' | 'warn' | 'off';
+export interface ScopeProtectionOptions {
+    mode?: ScopeProtectionMode;
+    stageName?: string;
+    logger?: (message: string) => void;
+    allowedInternalProperties?: (string | symbol)[];
+}

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

@@ -0,0 +1,26 @@
+/**
+ * attachScopeMethods — Attach ScopeFacade-compatible methods onto any target object.
+ *
+ * Gives non-class scopes (like Zod-generated proxies) the same convenience
+ * methods as ScopeFacade subclasses: getValue, setValue, addDebugInfo, etc.
+ *
+ * API matches ScopeFacade's simplified signatures (no path arrays).
+ */
+import type { StageContextLike } from './types';
+/** @deprecated Use attachScopeMethods instead. */
+export declare const attachBaseStateCompat: typeof attachScopeMethods;
+/** Attach ScopeFacade-compatible methods onto any target (e.g., a proxy scope). */
+export declare function attachScopeMethods<T extends object>(target: T, ctx: StageContextLike, stageName: string, readOnly?: unknown): T & {
+    addDebugInfo(k: string, v: unknown): void;
+    addDebugMessage(v: unknown): void;
+    addErrorInfo(k: string, v: unknown): void;
+    addMetric(name: string, v: unknown): void;
+    addEval(name: string, v: unknown): void;
+    getInitialValueFor(k: string): unknown;
+    getValue(key?: string): unknown;
+    setValue(key: string, value: unknown, shouldRedact?: boolean, description?: string): void;
+    updateValue(key: string, value: unknown, description?: string): void;
+    setObjectInRoot(key: string, value: unknown): void;
+    getReadOnlyValues(): unknown;
+    getPipelineId(): string | undefined;
+};

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

@@ -0,0 +1,14 @@
+/**
+ * Guards — Heuristic functions for detecting input types
+ *
+ * Used by the registry to determine whether an input is a class constructor,
+ * factory function, or ScopeFacade subclass.
+ */
+type CallableFunction = (...args: unknown[]) => unknown;
+/** Heuristic: class constructor vs. plain function */
+export declare function looksLikeClassCtor(fn: unknown): fn is CallableFunction;
+/** Heuristic: factory function (a function that is NOT a class ctor) */
+export declare function looksLikeFactory(fn: unknown): fn is CallableFunction;
+/** True iff `ctor` is a class that extends ScopeFacade (checks prototype chain) */
+export declare function isSubclassOfScopeFacade(ctor: unknown): boolean;
+export {};

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

@@ -0,0 +1,6 @@
+export { attachBaseStateCompat, attachScopeMethods } from './baseStateCompatible';
+export { isSubclassOfScopeFacade, looksLikeClassCtor, looksLikeFactory } from './guards';
+export { makeClassProvider, makeFactoryProvider } from './providers';
+export { __clearScopeResolversForTests, resolveScopeProvider } from './registry';
+export { registerScopeResolver, toScopeFactory } from './resolve';
+export type { ProviderResolver, ResolveOptions, ScopeFactory, ScopeProvider, StageContextLike, StrictMode, } from './types';

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

@@ -0,0 +1,8 @@
+/**
+ * Provider Factories — Wrap factory functions and class constructors as ScopeProviders
+ */
+import type { ScopeFactory, ScopeProvider, StageContextLike } from './types';
+/** Wrap an existing factory function as a ScopeProvider */
+export declare function makeFactoryProvider<TScope>(factory: ScopeFactory<TScope>): ScopeProvider<TScope>;
+/** Wrap a class constructor as a ScopeProvider */
+export declare function makeClassProvider<TScope>(Ctor: new (ctx: StageContextLike, stageName: string, readOnly?: unknown) => TScope): ScopeProvider<TScope>;

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

@@ -0,0 +1,11 @@
+/**
+ * Registry — Central registry for scope provider resolvers
+ *
+ * Maintains a list of registered resolvers. Resolvers are checked in
+ * registration order (first match wins). Built-in resolvers (class, factory)
+ * are checked last as fallback.
+ */
+import type { ProviderResolver, ResolveOptions, ScopeProvider } from './types';
+export declare function registerScopeResolver(resolver: ProviderResolver): void;
+export declare function __clearScopeResolversForTests(): void;
+export declare function resolveScopeProvider<TScope>(input: unknown, options?: ResolveOptions): ScopeProvider<TScope>;

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

@@ -0,0 +1,8 @@
+/**
+ * resolve.ts — Public API for converting scope inputs to ScopeFactory
+ */
+import type { ResolveOptions, ScopeFactory } from './types';
+/** Normalize a factory/class/schema-like input into a ScopeFactory the pipeline expects */
+export declare function toScopeFactory<TScope>(input: unknown, options?: ResolveOptions): ScopeFactory<TScope>;
+export { registerScopeResolver } from './registry';
+export type { ResolveOptions, ScopeProvider } from './types';

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

@@ -0,0 +1,40 @@
+/**
+ * Provider System Types
+ *
+ * Defines contracts between the registry, resolvers, and providers.
+ * StageContextLike is the minimal surface from StageContext to avoid tight coupling.
+ */
+/** Minimal surface from StageContext (patch-based) */
+export interface StageContextLike {
+    getValue(path: string[], key?: string): unknown;
+    setObject(path: string[], key: string, value: unknown, shouldRedact?: boolean, description?: string): void;
+    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;
+    setRoot?(key: string, value: unknown): void;
+    setGlobal?(key: string, value: unknown, description?: string): void;
+    pipelineId?: string;
+    runId?: string;
+}
+/** Factory type the pipeline expects */
+export type ScopeFactory<TScope> = (ctx: StageContextLike, stageName: string, readOnly?: unknown) => TScope;
+/** Strategy object that creates a scope */
+export interface ScopeProvider<TScope> {
+    readonly kind: string;
+    create(ctx: StageContextLike, stageName: string, readOnly?: unknown): TScope;
+}
+/** Resolver that can turn an arbitrary input into a ScopeProvider */
+export interface ProviderResolver<TScope = any> {
+    name: string;
+    canHandle(input: unknown): boolean;
+    makeProvider(input: unknown, options?: unknown): ScopeProvider<TScope>;
+}
+/** Optional strictness for schema-backed providers */
+export type StrictMode = 'off' | 'warn' | 'deny';
+/** Options bag passed to resolve() */
+export type ResolveOptions = {
+    zod?: {
+        strict?: StrictMode;
+    };
+};

package/dist/esm/types/lib/scope/recorders/DebugRecorder.d.ts

@@ -0,0 +1,35 @@
+/**
+ * DebugRecorder — Development-focused recorder for detailed debugging
+ *
+ * Captures errors (always), mutations and reads (in verbose mode),
+ * and stage lifecycle events for troubleshooting.
+ */
+import type { ErrorEvent, ReadEvent, Recorder, StageEvent, WriteEvent } from '../types';
+export type DebugVerbosity = 'minimal' | 'verbose';
+export interface DebugEntry {
+    type: 'read' | 'write' | 'error' | 'stageStart' | 'stageEnd';
+    stageName: string;
+    timestamp: number;
+    data: unknown;
+}
+export interface DebugRecorderOptions {
+    id?: string;
+    verbosity?: DebugVerbosity;
+}
+export declare class DebugRecorder implements Recorder {
+    readonly id: string;
+    private entries;
+    private verbosity;
+    constructor(options?: DebugRecorderOptions);
+    onRead(event: ReadEvent): void;
+    onWrite(event: WriteEvent): void;
+    onError(event: ErrorEvent): void;
+    onStageStart(event: StageEvent): void;
+    onStageEnd(event: StageEvent): void;
+    getEntries(): DebugEntry[];
+    getErrors(): DebugEntry[];
+    getEntriesForStage(stageName: string): DebugEntry[];
+    setVerbosity(level: DebugVerbosity): void;
+    getVerbosity(): DebugVerbosity;
+    clear(): void;
+}