@sladg/apex-state 3.11.4 → 4.6.0

package/dist/index.d.ts

@@ -334,11 +334,26 @@ interface GenericMeta {
      * Used to track changes triggered by computation logic.
      */
     isComputationChange?: boolean;
+    /**
+     * Indicates if the change originated from an expression evaluation (BoolLogic/ValueLogic).
+     * Used to track changes produced by the expression stage in the pipeline.
+     */
+    isExpressionChange?: boolean;
+    /**
+     * Indicates if the change is a concern output (BoolLogic, ValueLogic, or validator result).
+     * Stamped by WASM from the registration_meta provided at expression/listener registration.
+     */
+    isConcern?: boolean;
     /**
      * Identifies the originator of the change.
-     * Can be a user ID, component name, or any identifier string.
+     * Can be a user ID, component name, listener function name, or any identifier string.
      */
     sender?: string;
+    /**
+     * The pipeline stage that produced this change (e.g., 'sync', 'flip', 'aggregation_write', 'listeners').
+     * Used for debugging to understand the source of a change.
+     */
+    stage?: string;
 }
 
 /**
@@ -669,16 +684,28 @@ type PathsWithSameValueAs<DATA extends object, PATH extends ResolvableDeepKey<DA
 }[ResolvableDeepKey<DATA, Depth>];
 /**
  * A tuple of two paths that must have the same value type.
- * Format: [path1, path2]
+ * Format: [path1, path2] or [path1, path2, { oneWay: '[0]->[1]' | '[1]->[0]' }]
+ *
+ * `oneWay` makes sync unidirectional. The value declares the direction explicitly:
+ * - `'[0]->[1]'` — first path pushes to second path (left → right)
+ * - `'[1]->[0]'` — second path pushes to first path (right → left)
+ *
+ * Without the option, sync is bidirectional.
  *
  * **Scaling note**: This type is O(N²) where N = number of paths. It hits TS2589
  * at ~1,500 paths. For large state types, use the `syncPairs()` helper function
  * or `store.syncPairs()` (pre-warmed from `createGenericStore`) instead —
  * they scale to ~50K–80K paths.
  *
- * @example
+ * @example Bidirectional
  * const pair: SyncPair<State> = ['user.email', 'profile.email']
  *
+ * @example One-way: user.email → profile.email only
+ * const pair: SyncPair<State> = ['user.email', 'profile.email', { oneWay: '[0]->[1]' }]
+ *
+ * @example One-way: profile.email → user.email only (reversed direction)
+ * const pair: SyncPair<State> = ['user.email', 'profile.email', { oneWay: '[1]->[0]' }]
+ *
  * @example Custom depth — propagates to DeepKey and PathsWithSameValueAs
  * ```typescript
  * // Limit path traversal to 10 levels
@@ -686,13 +713,16 @@ type PathsWithSameValueAs<DATA extends object, PATH extends ResolvableDeepKey<DA
  * ```
  */
 type SyncPair<DATA extends object, Depth extends number = DefaultDepth> = {
-    [P1 in ResolvableDeepKey<DATA, Depth>]: [
+    [P1 in ResolvableDeepKey<DATA, Depth>]: [P1, PathsWithSameValueAs<DATA, P1, Depth>] | [
         P1,
-        PathsWithSameValueAs<DATA, P1, Depth>
+        PathsWithSameValueAs<DATA, P1, Depth>,
+        {
+            oneWay: '[0]->[1]' | '[1]->[0]';
+        }
     ];
 }[ResolvableDeepKey<DATA, Depth>];
 /**
- * A tuple of two paths for flip (alias for SyncPair).
+ * A tuple of two paths for flip. Always bidirectional: path1 ↔ path2 (inverted values).
  * Format: [path1, path2]
  *
  * **Scaling note**: O(N²) — hits TS2589 at ~1,500 paths. Use `flipPairs()` helper
@@ -701,7 +731,12 @@ type SyncPair<DATA extends object, Depth extends number = DefaultDepth> = {
  * @example
  * const pair: FlipPair<State> = ['isActive', 'isInactive']
  */
-type FlipPair<DATA extends object, Depth extends number = DefaultDepth> = SyncPair<DATA, Depth>;
+type FlipPair<DATA extends object, Depth extends number = DefaultDepth> = {
+    [P1 in ResolvableDeepKey<DATA, Depth>]: [
+        P1,
+        PathsWithSameValueAs<DATA, P1, Depth>
+    ];
+}[ResolvableDeepKey<DATA, Depth>];
 /**
  * A tuple for aggregation: [target, source] or [target, source, excludeWhen]
  * First element (left) is ALWAYS the target (aggregated) path.
@@ -779,13 +814,24 @@ type CheckPairValueMatch<DATA extends object, P1 extends string, P2 extends stri
     NonNullable<DeepValue<DATA, P1>>
 ] ? [P1, P2] : [P1, never] : [P1, never] : never : never;
 /**
- * Validates an array of [P1, P2] sync/flip pairs lazily — O(K) where K = pairs written.
+ * Validates an array of sync/flip pairs lazily — O(K) where K = pairs written.
+ * Accepts [P1, P2] or [P1, P2, { oneWay: '[0]->[1]' | '[1]->[0]' }].
+ * The optional third element declares direction — does not affect value type validation.
  */
-type CheckSyncPairs<DATA extends object, T extends readonly [string, string][], Depth extends number = DefaultDepth> = {
+type CheckSyncPairs<DATA extends object, T extends readonly ([string, string] | [string, string, {
+    oneWay: '[0]->[1]' | '[1]->[0]';
+}])[], Depth extends number = DefaultDepth> = {
     [I in keyof T]: T[I] extends [
         infer P1 extends string,
-        infer P2 extends string
-    ] ? CheckPairValueMatch<DATA, P1, P2, Depth> : T[I];
+        infer P2 extends string,
+        {
+            oneWay: '[0]->[1]' | '[1]->[0]';
+        }
+    ] ? CheckPairValueMatch<DATA, P1, P2, Depth> extends [P1, P2] ? [P1, P2, {
+        oneWay: '[0]->[1]' | '[1]->[0]';
+    }] : [P1, never, {
+        oneWay: '[0]->[1]' | '[1]->[0]';
+    }] : T[I] extends [infer P1 extends string, infer P2 extends string] ? CheckPairValueMatch<DATA, P1, P2, Depth> : T[I];
 };
 /**
  * Validates that two paths both resolve to number.
@@ -851,10 +897,9 @@ type DeepPartial<T> = T extends (infer U)[] ? DeepPartial<U>[] : T extends reado
 declare const VALIDATED: unique symbol;
 declare const STORE_DATA: unique symbol;
 /** Pre-validated sync pair array. Returned by `syncPairs()`. Branded with DATA to prevent cross-store use. */
-type ValidatedSyncPairs<DATA extends object = object> = [
-    string,
-    string
-][] & {
+type ValidatedSyncPairs<DATA extends object = object> = ([string, string] | [string, string, {
+    oneWay: '[0]->[1]' | '[1]->[0]';
+}])[] & {
     [VALIDATED]: 'sync';
     [STORE_DATA]: DATA;
 };
@@ -885,76 +930,105 @@ type ValidatedListeners<DATA extends object = object, META extends GenericMeta =
     [STORE_DATA]: DATA;
 };
 
-interface BaseConcernProps<STATE, PATH extends string> {
-    state: STATE;
-    path: PATH;
-    value: unknown;
-}
-interface ConcernType<NAME extends string = string, EXTRA_PROPS = Record<string, unknown>, RETURN_TYPE = unknown> {
-    name: NAME;
-    description: string;
-    /** Evaluated inside effect() - all state accesses are tracked */
-    evaluate: (props: BaseConcernProps<Record<string, unknown>, string> & EXTRA_PROPS) => RETURN_TYPE;
-}
-interface ConcernRegistration {
-    id: string;
-    path: string;
-    concernName: string;
-    concern: ConcernType;
-    config: Record<string, unknown>;
-    dispose: () => void;
-}
-
-/**
- * Pipeline Observer — Unified debug logging + Redux DevTools integration.
- *
- * Single interface that dispatches to:
- * - Console logging (controlled by logPipeline / logListeners / logConcerns flags)
- * - Redux DevTools (controlled by devtools flag) with nested tree-shaped state
- *
- * Call sites use one `observer.xyz()` call; the observer fans out internally.
- * Zero runtime cost when all flags are false (returns no-op object).
- */
-
-interface PipelineObserver {
-    pipelineStart: (label: string, input: unknown[]) => void;
-    phase1: (stateChanges: unknown[]) => void;
-    syncExpand: (changes: unknown[]) => void;
-    flipExpand: (changes: unknown[]) => void;
-    listenerDispatch: (subscriberId: number, fnName: string, scope: string, input: unknown[], output: unknown) => void;
-    validatorResult: (outputPath: string, input: unknown, result: unknown) => void;
-    phase2: (stateChanges: unknown[]) => void;
-    pipelineEnd: () => void;
-    concernEval: (path: string, name: string, value: unknown, result: unknown) => void;
-    destroy: () => void;
-}
-interface DevToolsInstance {
-    init: (state: unknown) => void;
-    send: (action: {
-        type: string;
-    }, state: unknown) => void;
-    unsubscribe: () => void;
-}
-interface DevToolsRef {
-    prefix: string;
-    pipeline: DevToolsInstance | null;
-}
-
-/**
- * Debug Timing Utilities
- *
- * Provides timing measurement for concerns and listeners
- * to detect slow operations during development.
- */
-type TimingType = 'concerns' | 'listeners' | 'registration';
-interface TimingMeta {
-    path: string;
+type Stage = "input" | "aggregation_write" | "diff" | "sync" | "flip" | "clear_path" | "aggregation_read" | "computation" | "expression" | "listeners" | "apply";
+type ChangeKind = "real" | "redundant" | "breakdown" | "consumed";
+type ChangeContext = "Initial" | "Mutation";
+type Lineage = "Input" | {
+    "Derived": {
+        parent_id: number;
+        via: Stage;
+        context: ChangeContext;
+    };
+};
+type ChangeAudit = {
+    source_path?: string;
+    logic_id?: number;
+};
+type TraceEntry = {
+    /**
+     * Monotonic counter. Parents numbered pipeline-globally, children within parent.
+     */
+    seq: number;
+    /**
+     * Stage or operation name (e.g. "input", "sync", "sync_pair", "listener", "input:skip").
+     */
+    stage: string;
+    /**
+     * Actual input values as JSON. Per-child: only what that operation matched.
+     */
+    inputs: Array<unknown>;
+    /**
+     * Actual output values as JSON. What this operation produced.
+     */
+    outputs: Array<unknown>;
+    /**
+     * Microseconds. Parent = total stage time. Child = per-operation time. 0 when timing unavailable.
+     */
+    duration_us: number;
+    /**
+     * Extra metadata (registration_id, reason, etc.). Omitted when empty.
+     */
+    meta: Record<string, unknown>;
+    /**
+     * Per-operation breakdown. Omitted when empty. Recursive (same struct).
+     */
+    children: Array<TraceEntry>;
+};
+type PipelineTrace = {
+    entries: Array<TraceEntry>;
+};
+type ListenerError = {
+    subscriber_id: number;
     name: string;
-}
-interface Timing {
-    run: <T>(type: TimingType, fn: () => T, meta: TimingMeta) => T;
-    reportBatch: (type: TimingType) => void;
-}
+    error: string;
+};
+type ClearPathInput = {
+    triggers: Array<string>;
+    targets: Array<string>;
+};
+type SideEffectsRegistration = {
+    registration_id: string;
+    sync_pairs: Array<[string, string]>;
+    directed_sync_pairs: Array<[string, string]>;
+    flip_pairs: Array<[string, string]>;
+    aggregation_pairs: Array<unknown>;
+    clear_paths: Array<ClearPathInput>;
+    computation_pairs: Array<unknown>;
+    listeners: Array<ListenerRegistration$1>;
+    anchor_path: string | null;
+};
+type ListenerRegistration$1 = {
+    subscriber_id: number;
+    topic_paths: Array<string>;
+    scope_path: string;
+    name?: string;
+    /**
+     * Whether to dispatch this subscriber immediately on registration with current shadow state.
+     * Used by validators to produce initial validation results without requiring a state change.
+     */
+    run_on_registration: boolean | null;
+};
+type ConcernsRegistration = {
+    /**
+     * Expression registrations (logic, value, options — WASM auto-detects export type from tree_json).
+     */
+    expressions: Array<ExpressionRegistration>;
+    /**
+     * Subscriber registrations (validators, custom concerns, etc.).
+     * Same format as SideEffectsRegistration.listeners — WASM treats them
+     * identically. TS controls wave_priority at registration time.
+     */
+    listeners: Array<ListenerRegistration$1>;
+};
+type ExpressionRegistration = {
+    output_path: string;
+    tree_json: string;
+    /**
+     * Opaque meta stamped on every change produced by this expression.
+     * TS uses this for concern tagging (e.g. `{ isConcern: true }`).
+     */
+    meta: unknown | null;
+};
 
 /**
  * WASM Bridge — Thin namespace over Rust/WASM exports.
@@ -970,211 +1044,129 @@ interface Timing {
  * @module wasm/bridge
  */
 
-/** A single state change (input or output). */
+/**
+ * JS-facing change — derived from Wasm.Change with `value_json` replaced by
+ * parsed `value: unknown` and `meta` typed as GenericMeta.
+ *
+ * `kind`, `lineage`, and `audit` are optional: they are populated on changes
+ * returned from WASM (output) but absent on changes constructed in JS (input).
+ */
 interface Change {
     path: string;
     value: unknown;
-    origin?: string;
-}
-/** A single dispatch entry with sequential ID and input change references. */
-interface DispatchEntry {
-    dispatch_id: number;
-    subscriber_id: number;
-    scope_path: string;
-    topic_path: string;
-    /** Indexes into ProcessResult.changes array. */
-    input_change_ids: number[];
-}
-/** A group of dispatches to execute sequentially. */
-interface DispatchGroup {
-    dispatches: DispatchEntry[];
-}
-/** A target for propagating produced changes from child to parent dispatch. */
-interface PropagationTarget {
-    target_dispatch_id: number;
-    /** Prefix to prepend to child's relative paths for the target's scope. */
-    remap_prefix: string;
-}
-/** Pre-computed execution plan with propagation map. */
-interface FullExecutionPlan {
-    groups: DispatchGroup[];
-    /** propagation_map[dispatch_id] = targets to forward produced changes to. */
-    propagation_map: PropagationTarget[][];
-}
-/** Validator dispatch info for JS-side execution. */
-interface ValidatorDispatch {
-    validator_id: number;
-    output_path: string;
-    dependency_values: Record<string, string>;
-}
-/**
- * Extends a base tuple with an optional trailing BoolLogic condition (JSON-serialized).
- * Used by aggregation and computation pairs to share the "optional excludeWhen" pattern.
- */
-type WasmPairWithCondition<Base extends [...string[]]> = [...Base] | [...Base, condition: string];
-/** WASM-side aggregation pair: [target, source] with optional excludeWhen condition. */
-type WasmAggregationPair = WasmPairWithCondition<[
-    target: string,
-    source: string
-]>;
-/** WASM-side computation pair: [operation, target, source] with optional excludeWhen condition. */
-type WasmComputationPair = WasmPairWithCondition<[
-    op: string,
-    target: string,
-    source: string
-]>;
-/** WASM-side sync pair: [source, target] — bidirectional sync. */
-type WasmSyncPair = [source: string, target: string];
-/** WASM-side flip pair: [source, target] — inverted boolean sync. */
-type WasmFlipPair = [source: string, target: string];
-/** WASM-side clear path rule: trigger paths → target paths to null. */
-interface WasmClearPathRule {
-    triggers: string[];
-    targets: string[];
-}
-/** WASM-side listener entry for topic-based dispatch. */
-interface WasmListenerEntry {
-    subscriber_id: number;
-    topic_path: string;
-    scope_path: string;
-}
-/** Consolidated registration input for side effects (sync, flip, aggregation, computation, clear, listeners). */
-interface SideEffectsRegistration {
-    registration_id: string;
-    sync_pairs?: WasmSyncPair[];
-    flip_pairs?: WasmFlipPair[];
-    aggregation_pairs?: WasmAggregationPair[];
-    computation_pairs?: WasmComputationPair[];
-    clear_paths?: WasmClearPathRule[];
-    listeners?: WasmListenerEntry[];
-}
-/** Consolidated registration output from side effects registration. */
-interface SideEffectsResult {
-    sync_changes: Change[];
-    aggregation_changes: Change[];
-    computation_changes: Change[];
-    registered_listener_ids: number[];
-}
-/** WASM-side BoolLogic entry for declarative boolean evaluation. */
-interface WasmBoolLogicEntry {
-    output_path: string;
-    tree_json: string;
-}
-/** WASM-side validator entry for validation orchestration. */
-interface WasmValidatorEntry {
-    validator_id: number;
-    output_path: string;
-    dependency_paths: string[];
-    scope: string;
-}
-/** WASM-side ValueLogic entry for declarative value computation. */
-interface WasmValueLogicEntry {
-    output_path: string;
-    tree_json: string;
-}
-/** Consolidated registration input for concerns (BoolLogic, validators, and ValueLogic). */
-interface ConcernsRegistration {
-    registration_id: string;
-    bool_logics?: WasmBoolLogicEntry[];
-    validators?: WasmValidatorEntry[];
-    value_logics?: WasmValueLogicEntry[];
-}
-/** Consolidated registration output from concerns registration. */
-interface ConcernsResult {
-    bool_logic_changes: Change[];
-    registered_logic_ids: number[];
-    registered_validator_ids: number[];
-    value_logic_changes: Change[];
-    registered_value_logic_ids: number[];
-}
-/** Result of processChanges (Phase 1). */
-interface ProcessChangesResult {
-    state_changes: Change[];
-    changes: Change[];
-    validators_to_run: ValidatorDispatch[];
-    execution_plan: FullExecutionPlan | null;
-    has_work: boolean;
+    meta: GenericMeta;
+    kind?: ChangeKind;
+    lineage?: Lineage;
+    audit?: ChangeAudit;
 }
 /**
- * An isolated WASM pipeline instance.
- * Each store gets its own pipeline so multiple Providers don't interfere.
- * All methods are pre-bound to the pipeline's ID — consumers never pass IDs.
+ * Create a new isolated WASM pipeline instance.
+ * Each store should call this once and store the result.
+ * Call pipeline.destroy() on cleanup.
  */
-interface WasmPipeline {
-    readonly id: number;
+declare const createWasmPipeline: (options?: {
+    debug?: boolean;
+}) => {
+    id: number;
+    readonly destroyed: boolean;
     shadowInit: (state: object) => void;
     shadowDump: () => unknown;
-    processChanges: (changes: Change[]) => ProcessChangesResult;
-    pipelineFinalize: (jsChanges: Change[]) => {
-        state_changes: Change[];
+    processChanges: (changes: Change[]) => {
+        changes: Change[];
+        listener_errors: ListenerError[];
+        trace: PipelineTrace | undefined;
+    };
+    registerSideEffects: (reg: Partial<SideEffectsRegistration>, subscriberFns?: Map<number, (...args: unknown[]) => unknown>) => {
+        sync_changes: Change[];
+        aggregation_changes: Change[];
+        computation_changes: Change[];
+        registered_side_effects: Record<string, ListenerRegistration$1[]>;
+    };
+    unregisterSideEffects: (registrationId: string) => {
+        sync_changes: Change[];
+        aggregation_changes: Change[];
+        computation_changes: Change[];
+        registered_side_effects: Record<string, ListenerRegistration$1[]>;
+    };
+    registerConcerns: (reg: Partial<ConcernsRegistration>, subscriberFns?: Map<number, (...args: unknown[]) => unknown>) => {
+        expression_changes: Change[];
+        registered_expression_ids: number[];
+        registered_subscriber_ids: number[];
+        initial_listener_changes: Change[];
     };
-    registerSideEffects: (reg: SideEffectsRegistration) => SideEffectsResult;
-    unregisterSideEffects: (registrationId: string) => void;
-    registerConcerns: (reg: ConcernsRegistration) => ConcernsResult;
     unregisterConcerns: (registrationId: string) => void;
     registerBoolLogic: (outputPath: string, tree: unknown) => number;
     unregisterBoolLogic: (logicId: number) => void;
     pipelineReset: () => void;
     destroy: () => void;
-    /** Per-instance storage for validation schemas (can't cross WASM boundary). */
-    validatorSchemas: Map<number, ValidationSchema>;
-}
+};
+type WasmPipeline = ReturnType<typeof createWasmPipeline>;
 
 /**
- * PathGroups Data Structure
+ * Apex State Logger — Simplified debug logging with colored console output.
  *
- * A custom data structure that provides O(1) connected component lookups
- * instead of O(V+E) recomputation on every change like graphology's connectedComponents.
+ * Two log functions:
+ * 1. logPipeline — called once per processChanges with WASM pipeline trace
+ * 2. logRegistration — called once per register/unregister with graph snapshot
  *
- * When wasmGraphType is set ('sync' | 'flip'), addEdge/removeEdge automatically
- * mirror registrations to WASM bridge for pipeline processing.
+ * Zero runtime cost when log flag is false (returns no-op logger).
  *
- * Operations complexity:
- * - getAllGroups(): O(G) where G is number of groups (typically small)
- * - getGroupPaths(path): O(1) lookup
- * - addEdge(p1, p2): O(n) where n is smaller group size (merge)
- * - removeEdge(p1, p2): O(n) for affected component
- * - hasPath(path): O(1)
- * - hasEdge(p1, p2): O(1)
- */
-/** Graph type for WASM mirroring. When set, addEdge/removeEdge mirror to WASM. */
-type WasmGraphType = 'sync' | 'flip';
-/**
- * PathGroups maintains connected components with O(1) lookups.
+ * Responsible for:
+ *   - Rendering PipelineTrace entries recursively with [NN]/[NN.MM] numbering
+ *   - Color-coding entries by registration_id (deterministic palette) or stage
+ *   - Formatting timing as ms from duration_us
  *
- * Internal structure:
- * - pathToGroup: Maps each path to its group ID
- * - groupToPaths: Maps each group ID to the set of paths in that group
- * - edges: Set of edge keys for edge existence checks and proper removal
- * - adjacency: Maps each path to its direct neighbors (for split detection on removal)
- * - nextGroupId: Counter for generating unique group IDs
+ * Out of scope:
+ *   - Trace collection (handled by Rust pipeline_trace.rs)
+ *   - DevTools integration (handled by store/devtools.ts)
  */
-interface PathGroups {
-    pathToGroup: Map<string, number>;
-    groupToPaths: Map<number, Set<string>>;
-    edges: Set<string>;
-    adjacency: Map<string, Set<string>>;
-    nextGroupId: number;
-    wasmGraphType?: WasmGraphType;
+
+type GraphSnapshot$1 = Record<string, unknown>;
+type SideEffectsResult = ReturnType<WasmPipeline['registerSideEffects']>;
+interface PipelineLogData {
+    initialChanges: Change[];
+    /** WASM pipeline trace (undefined if not traced). */
+    trace: PipelineTrace | undefined;
+    /** Final applied changes: always present (can be empty). */
+    appliedChanges: Change[];
+    /** State snapshot after changes (undefined if not captured). */
+    stateSnapshot: unknown | undefined;
+}
+interface RegistrationLogData {
+    result: SideEffectsResult | undefined;
+    appliedChanges: Change[];
+    stateSnapshot: unknown | undefined;
+    durationMs: number;
+}
+interface RegistrationLogParams {
+    type: 'register' | 'unregister';
+    id: string;
+    snapshot: GraphSnapshot$1;
+    data?: RegistrationLogData;
+}
+interface ApexLogger {
+    logPipeline: (data: PipelineLogData) => void;
+    logRegistration: (params: RegistrationLogParams) => void;
+    destroy: () => void;
 }
 
 /**
- * Graph Type Definitions
+ * Valtio DevTools — Connects state and concerns proxies to Redux DevTools,
+ * and provides a pipeline notifier for sending pipeline/registration events.
  *
- * Type aliases for the PathGroups data structure used in sync and flip operations.
- * These aliases maintain backward compatibility with the previous graphology-based API.
+ * Uses valtio/utils devtools() to expose both proxies as separate DevTools instances:
+ * - '{prefix}:state' — application state proxy
+ * - '{prefix}:concerns' — computed concern values proxy
+ *
+ * Singleton connections per proxy — survives StrictMode remounts and HMR reloads.
  */
 
-/**
- * Sync graph: Paths that must have synchronized values
- * Type alias for PathGroups - maintains backward compatibility
- */
-type SyncGraph = PathGroups;
-/**
- * Flip graph: Paths with inverted boolean values
- * Type alias for PathGroups - maintains backward compatibility
- */
-type FlipGraph = PathGroups;
+type GraphSnapshot = Record<string, unknown>;
+interface DevToolsNotifier {
+    notifyPipeline: (data: PipelineLogData) => void;
+    notifyRegistration: (type: 'register' | 'unregister', id: string, snapshot: GraphSnapshot) => void;
+    destroy: () => void;
+}
 
 /**
  * Core Store Types
@@ -1187,18 +1179,14 @@ type FlipGraph = PathGroups;
  * Debug configuration for development tooling
  */
 interface DebugConfig {
-    /** Enable timing measurement for concerns and listeners */
+    /** Enable console logging for pipeline runs and registrations */
+    log?: boolean;
+    /** Enable timing warnings for slow listeners */
     timing?: boolean;
-    /** Threshold in milliseconds for slow operation warnings (default: 5ms) */
+    /** Threshold in milliseconds for slow listener warnings (default: 5ms) */
     timingThreshold?: number;
     /** Enable tracking of processChanges calls and applied changes for testing/debugging */
     track?: boolean;
-    /** Log pipeline phases, state changes, sync/flip expansions */
-    logPipeline?: boolean;
-    /** Log listener dispatch inputs and outputs */
-    logListeners?: boolean;
-    /** Log concern evaluations and validator runs */
-    logConcerns?: boolean;
     /** Connect to Redux DevTools Extension for state inspection */
     devtools?: boolean;
 }
@@ -1240,8 +1228,6 @@ interface StoreConfig {
     maxIterations?: number;
     /** Debug configuration for development tooling */
     debug?: DebugConfig;
-    /** Use legacy TypeScript implementation instead of WASM (default: false) */
-    useLegacyImplementation?: boolean;
 }
 interface ProviderProps<DATA extends object> {
     initialState: DATA;
@@ -1306,12 +1292,18 @@ type OnStateListener<DATA extends object = object, SUB_STATE = DATA, META extend
  * }
  * ```
  */
-interface ListenerRegistration<DATA extends object = object, META extends GenericMeta = GenericMeta, Depth extends number = DefaultDepth> {
+/**
+ * Single-path listener — watches one path (or all paths when null).
+ * `scope` may be omitted (defaults to `path`).
+ */
+interface SinglePathListener<DATA extends object = object, META extends GenericMeta = GenericMeta, Depth extends number = DefaultDepth> {
     /**
-     * Path to watch - only changes under this path will trigger the listener
-     * null = watch all paths (receives every change)
+     * Path to watch - only changes under this path will trigger the listener.
+     * null = watch all paths (receives every change).
+     * Array = watch multiple paths; listener fires once per run when any match,
+     * receiving all matching changes merged into a single input array.
      */
-    path: DeepKey<DATA, Depth> | null;
+    path: DeepKey<DATA, Depth> | DeepKey<DATA, Depth>[] | null;
     /**
      * Scope for state and changes presentation
      * - If omitted/undefined: defaults to `path` (scoped state matching the watched path)
@@ -1323,52 +1315,70 @@ interface ListenerRegistration<DATA extends object = object, META extends Generi
     scope?: DeepKey<DATA, Depth> | null;
     fn: OnStateListener<DATA, any, META>;
 }
-interface ListenerHandlerRef {
-    scope: string | null;
-    fn: (...args: unknown[]) => unknown;
-}
-interface SideEffectGraphs<DATA extends object = object, META extends GenericMeta = GenericMeta> {
-    sync: SyncGraph;
-    flip: FlipGraph;
-    listeners: Map<string, ListenerRegistration<DATA, META>[]>;
-    sortedListenerPaths: string[];
-    /** O(1) lookup: subscriber_id -> handler ref. Populated by registerListener. */
-    listenerHandlers: Map<number, ListenerHandlerRef>;
+/**
+ * Multi-path listener — watches multiple paths simultaneously.
+ * Handler fires once per pipeline run with all matched changes merged.
+ * `scope` is required (use null for full paths).
+ */
+interface MultiPathListener<DATA extends object = object, META extends GenericMeta = GenericMeta, Depth extends number = DefaultDepth> {
+    /**
+     * Array of paths to watch. Handler fires once with changes from any matched path.
+     */
+    path: DeepKey<DATA, Depth>[];
+    /**
+     * Scope for state and changes presentation (required for multi-path listeners).
+     * - null: state is full DATA, changes use FULL paths
+     * - string: state is value at scope, changes use paths RELATIVE to scope
+     */
+    scope: DeepKey<DATA, Depth> | null;
+    fn: OnStateListener<DATA, any, META>;
 }
+/** Listener registration — single-path or multi-path. */
+type ListenerRegistration<DATA extends object = object, META extends GenericMeta = GenericMeta, Depth extends number = DefaultDepth> = SinglePathListener<DATA, META, Depth> | MultiPathListener<DATA, META, Depth>;
 interface Registrations {
-    concerns: Map<string, ConcernType[]>;
-    effectCleanups: Set<() => void>;
-    sideEffectCleanups: Map<string, () => void>;
-    aggregations: Map<string, Aggregation[]>;
-}
-interface ProcessingState<DATA extends object = object, META extends GenericMeta = GenericMeta> {
-    queue: ArrayOfChanges<DATA, META>;
+    /** Cleanup functions keyed by registration ID. Multiple cleanups may exist per registration. */
+    cleanups: Record<string, (() => void)[]>;
 }
 /** Internal store state (NOT tracked - wrapped in ref()) */
-interface InternalState<DATA extends object = object, META extends GenericMeta = GenericMeta> {
-    graphs: SideEffectGraphs<DATA, META>;
+interface InternalState {
     registrations: Registrations;
-    processing: ProcessingState<DATA, META>;
-    timing: Timing;
-    observer: PipelineObserver;
     config: DeepRequired<StoreConfig>;
-    /** Redux DevTools state — prefix for naming + shared connection instance. */
-    _devtools: DevToolsRef;
-    /** Per-store WASM pipeline instance (null when using legacy implementation). */
+    logger: ApexLogger;
+    /** DevTools — pipeline notifier + proxy inspection. Null when devtools disabled. */
+    devtools: DevToolsNotifier | null;
+    /** Per-store WASM pipeline instance (null after destroy). */
     pipeline: WasmPipeline | null;
-    /** Pending deferred destroy timer — cancelled on StrictMode re-mount. */
-    _destroyTimer?: ReturnType<typeof setTimeout> | undefined;
 }
 type ConcernValues = Record<string, Record<string, unknown>>;
 /** Two-proxy pattern: state and _concerns are independent to prevent infinite loops */
-interface StoreInstance<DATA extends object, META extends GenericMeta = GenericMeta> {
+interface StoreInstance<DATA extends object> {
     state: DATA;
     _concerns: ConcernValues;
-    _internal: InternalState<DATA, META>;
+    _internal: InternalState;
     /** Debug tracking data, only populated when debug.track is enabled */
     _debug: DebugTrack | null;
 }
 
+interface BaseConcernProps<STATE, PATH extends string> {
+    state: STATE;
+    path: PATH;
+    value: unknown;
+}
+interface ConcernType<NAME extends string = string, EXTRA_PROPS = Record<string, unknown>, RETURN_TYPE = unknown> {
+    name: NAME;
+    description: string;
+    /** Evaluated inside effect() - all state accesses are tracked */
+    evaluate: (props: BaseConcernProps<Record<string, unknown>, string> & EXTRA_PROPS) => RETURN_TYPE;
+}
+interface ConcernRegistration {
+    id: string;
+    path: string;
+    concernName: string;
+    concern: ConcernType;
+    config: Record<string, unknown>;
+    dispose: () => void;
+}
+
 interface ValidationError {
     field?: string;
     message: string;
@@ -1701,6 +1711,13 @@ interface SideEffects<DATA extends object, META extends GenericMeta = GenericMet
      * Accepts direct `ListenerRegistration<T>[]` or pre-validated result from `listeners()`.
      */
     listeners?: ListenerRegistration<DATA, META>[];
+    /**
+     * Anchor path - guard for all resources in this registration.
+     * When the anchor path is structurally absent from shadow state, all listeners,
+     * BoolLogics, and validators silently skip execution for that pipeline run
+     * (no unregistration — they resume when the path reappears).
+     */
+    anchorPath?: DeepKey<DATA, Depth>;
 }
 
 /**
@@ -1735,14 +1752,34 @@ interface GenericStoreApi<DATA extends object, META extends GenericMeta = Generi
         } & {
             [K in keyof SELECTION as SELECTION[K] extends true ? K : never]?: K extends keyof EvaluatedConcerns<CONCERNS> ? EvaluatedConcerns<CONCERNS>[K] : never;
         };
+        /** Reactive snapshot of all concerns matching this selection, keyed by path. Re-renders when any concern changes. */
+        useConcernsSnapshot: () => Record<string, {
+            [K in keyof SELECTION as SELECTION[K] extends true ? K : never]?: K extends keyof EvaluatedConcerns<CONCERNS> ? EvaluatedConcerns<CONCERNS>[K] : never;
+        }>;
     };
+    /**
+     * React hook. Fires callback whenever concerns matching the selection change.
+     * Does NOT trigger re-renders — use useConcernsSnapshot() for reactive UI instead.
+     * Callback is stable across renders (no need to memoize).
+     */
+    useWatchConcerns: <SELECTION extends Partial<Record<Extract<CONCERNS[number], {
+        name: string;
+    }>['name'], boolean>>>(selection: SELECTION, callback: (concerns: Record<string, {
+        [K in keyof SELECTION as SELECTION[K] extends true ? K : never]?: K extends keyof EvaluatedConcerns<CONCERNS> ? EvaluatedConcerns<CONCERNS>[K] : never;
+    }>) => void) => void;
     withMeta: (presetMeta: Partial<META>) => {
         useFieldStore: <P extends DeepKey<DATA>>(path: P) => {
             value: DeepValue<DATA, P>;
             setValue: (newValue: DeepValue<DATA, P>, meta?: META) => void;
         };
     };
-    syncPairs: <T extends [ResolvableDeepKey<DATA>, ResolvableDeepKey<DATA>][]>(pairs: CheckSyncPairs<DATA, T>) => ValidatedSyncPairs<DATA>;
+    syncPairs: <T extends ([ResolvableDeepKey<DATA>, ResolvableDeepKey<DATA>] | [
+        ResolvableDeepKey<DATA>,
+        ResolvableDeepKey<DATA>,
+        {
+            oneWay: '[0]->[1]' | '[1]->[0]';
+        }
+    ])[]>(pairs: CheckSyncPairs<DATA, T>) => ValidatedSyncPairs<DATA>;
     flipPairs: <T extends [ResolvableDeepKey<DATA>, ResolvableDeepKey<DATA>][]>(pairs: CheckSyncPairs<DATA, T>) => ValidatedFlipPairs<DATA>;
     aggregationPairs: <T extends ([ResolvableDeepKey<DATA>, ResolvableDeepKey<DATA>] | [ResolvableDeepKey<DATA>, ResolvableDeepKey<DATA>, BoolLogic<DATA>])[]>(pairs: CheckAggregationPairs<DATA, T>) => ValidatedAggregationPairs<DATA>;
     computationPairs: <T extends ([
@@ -1971,20 +2008,14 @@ interface FieldInput<T> {
  */
 declare const useTransformedField: <TStored, TDisplay, TField extends FieldInput<TStored>>(field: TField, config: TransformConfig<TStored, TDisplay>) => Omit<TField, "value" | "setValue"> & FieldInput<TDisplay>;
 
-/** Legacy JS implementation - uses JS graph structure */
-declare const registerFlipPair: <DATA extends object, META extends GenericMeta = GenericMeta>(store: StoreInstance<DATA, META>, path1: string & {}, path2: string & {}) => (() => void);
-
-/** Legacy JS implementation - uses JS listener maps and sorted paths */
-declare const registerListenerLegacy: <DATA extends object, META extends GenericMeta = GenericMeta>(store: StoreInstance<DATA, META>, registration: ListenerRegistration<DATA, META>) => (() => void);
-
 /**
- * Legacy batch version of registerSyncPair. Adds all edges first, then computes
- * initial sync changes across all final groups and calls processChanges once.
- * This avoids cascading effect re-evaluations when registering many pairs.
+ * WASM Implementation - Side Effects Registration
+ *
+ * Consolidates all side effects (sync, flip, aggregation, listeners) into a single
+ * WASM call for efficiency. No legacy fallback logic - assumes WASM is loaded.
  */
-declare const registerSyncPairsBatch: <DATA extends object, META extends GenericMeta = GenericMeta>(store: StoreInstance<DATA, META>, pairs: [string & {}, string & {}][]) => (() => void);
 
-declare const registerSideEffects: <DATA extends object, META extends GenericMeta = GenericMeta>(store: StoreInstance<DATA, META>, id: string, effects: SideEffects<DATA, META>) => (() => void);
+declare const registerSideEffects: <DATA extends object, META extends GenericMeta = GenericMeta>(store: StoreInstance<DATA>, id: string, effects: SideEffects<DATA, META>) => (() => void);
 
 /**
  * Lazy-validated pair helper functions
@@ -2042,7 +2073,9 @@ declare const registerSideEffects: <DATA extends object, META extends GenericMet
  * useSideEffects('my-syncs', { syncPaths: syncs })  // no O(N²) re-check
  * ```
  */
-declare const syncPairs: <DATA extends object, Depth extends number = DefaultDepth>() => <T extends [ResolvableDeepKey<DATA, Depth>, ResolvableDeepKey<DATA, Depth>][]>(pairs: CheckSyncPairs<DATA, T, Depth>) => ValidatedSyncPairs<DATA>;
+declare const syncPairs: <DATA extends object, Depth extends number = DefaultDepth>() => <T extends ([ResolvableDeepKey<DATA, Depth>, ResolvableDeepKey<DATA, Depth>] | [ResolvableDeepKey<DATA, Depth>, ResolvableDeepKey<DATA, Depth>, {
+    oneWay: "[0]->[1]" | "[1]->[0]";
+}])[]>(pairs: CheckSyncPairs<DATA, T, Depth>) => ValidatedSyncPairs<DATA>;
 /**
  * Lazy-validated flip pairs. Curried: `flipPairs<State>()(pairs)`.
  *
@@ -2340,4 +2373,4 @@ declare const applyChangesToObject: <T extends object>(obj: T, changes: AnyChang
  */
 declare const deepClone: <T>(value: T) => T;
 
-export { type Aggregation, type AggregationPair, type ArrayOfChanges, type BaseConcernProps, type BoolLogic, type BufferedField, type CheckAggregationPairs, type CheckComputationPairs, type CheckPairValueMatch, type CheckSyncPairs, type ClearPathRule, type ComputationOp, type ComputationPair, type ConcernRegistration, type ConcernRegistrationMap, type ConcernType, type DebugConfig, type DebugTrack, type DebugTrackEntry, type DeepKey, type DeepKeyFiltered, type DeepPartial, type DeepRequired, type DeepValue, type EvaluatedConcerns, type ExtractEvaluateReturn, type FieldInput$2 as FieldInput, type FlipPair, type GenericMeta, type GenericStoreApi, type HASH_KEY, type KeyboardSelectConfig, type ListenerRegistration, type OnStateListener, type PathsWithSameValueAs, type PipelineObserver, type ProviderProps, STORE_DATA, type SelectOption, type SideEffects, type StoreConfig, type StoreInstance, type SyncPair, type ThrottleConfig, type ThrottleFieldInput, type TransformConfig, VALIDATED, type ValidatedAggregationPairs, type ValidatedComputationPairs, type ValidatedFlipPairs, type ValidatedListeners, type ValidatedSyncPairs, type ValidationError, type ValidationSchema, type ValidationStateConcern, type ValidationStateInput, type ValidationStateResult, _, aggregationPairs, applyChangesToObject, computationPairs, createGenericStore, deepClone, defaultConcerns, dot, evaluateBoolLogic, extractPlaceholders, findConcern, flipPairs, hashKey, interpolateTemplate, is, listeners, index as prebuilts, registerFlipPair, registerListenerLegacy, registerSideEffects, registerSyncPairsBatch, syncPairs, useBufferedField, useKeyboardSelect, useThrottledField, useTransformedField };
+export { type Aggregation, type AggregationPair, type ArrayOfChanges, type BaseConcernProps, type BoolLogic, type BufferedField, type CheckAggregationPairs, type CheckComputationPairs, type CheckPairValueMatch, type CheckSyncPairs, type ClearPathRule, type ComputationOp, type ComputationPair, type ConcernRegistration, type ConcernRegistrationMap, type ConcernType, type DebugConfig, type DebugTrack, type DebugTrackEntry, type DeepKey, type DeepKeyFiltered, type DeepPartial, type DeepRequired, type DeepValue, type EvaluatedConcerns, type ExtractEvaluateReturn, type FieldInput$2 as FieldInput, type FlipPair, type GenericMeta, type GenericStoreApi, type HASH_KEY, type KeyboardSelectConfig, type ListenerRegistration, type OnStateListener, type PathsWithSameValueAs, type ProviderProps, STORE_DATA, type SelectOption, type SideEffects, type StoreConfig, type StoreInstance, type SyncPair, type ThrottleConfig, type ThrottleFieldInput, type TransformConfig, VALIDATED, type ValidatedAggregationPairs, type ValidatedComputationPairs, type ValidatedFlipPairs, type ValidatedListeners, type ValidatedSyncPairs, type ValidationError, type ValidationSchema, type ValidationStateConcern, type ValidationStateInput, type ValidationStateResult, _, aggregationPairs, applyChangesToObject, computationPairs, createGenericStore, deepClone, defaultConcerns, dot, evaluateBoolLogic, extractPlaceholders, findConcern, flipPairs, hashKey, interpolateTemplate, is, listeners, index as prebuilts, registerSideEffects, syncPairs, useBufferedField, useKeyboardSelect, useThrottledField, useTransformedField };