@sladg/apex-state 3.11.4 → 4.0.0

package/dist/index.d.ts

@@ -284,6 +284,269 @@ type BoolLogic<STATE, Depth extends number = DefaultDepth> = {
     CONTAINS_ALL: PathArrayElementsPair<STATE, Depth>;
 } | PathValuePair<STATE, Depth>;
 
+type Stage = "input" | "aggregation_write" | "diff" | "sync" | "flip" | "clear_path" | "aggregation_read" | "computation" | "bool_logic" | "value_logic" | "listeners" | "apply";
+type ChangeKind = "real" | "redundant" | "breakdown" | "consumed";
+type ChangeContext = "Initial" | "Mutation";
+type Lineage = "Input" | {
+    "Derived": {
+        parent_id: number;
+        via: Stage;
+        context: ChangeContext;
+    };
+};
+type SkipReason = "wrong_kind" | "guard_failed" | "redundant" | "anchor_missing";
+type SkippedChange = {
+    path: string;
+    kind: ChangeKind;
+    reason: SkipReason;
+    /**
+     * Human-readable explanation of why this change was skipped.
+     */
+    detail: string;
+    /**
+     * Which registration owns the resource that was skipped (if applicable).
+     */
+    registration_id: string | null;
+    /**
+     * Anchor path that caused the skip (if applicable).
+     */
+    anchor_path: string | null;
+};
+type ProducedChange = {
+    path: string;
+    /**
+     * JSON-encoded value.
+     */
+    value: string;
+    /**
+     * Which registration produced this change (if traceable).
+     */
+    registration_id: string | null;
+    /**
+     * What input path caused this (e.g. sync source path).
+     */
+    source_path: string | null;
+};
+type ChangeAudit = {
+    source_path: string | null;
+    logic_id: number | null;
+};
+type Change$1 = {
+    path: string;
+    value_json: string;
+    /**
+     * Opaque JS meta object — carried through the pipeline unchanged.
+     * WASM never inspects the contents. Returned on listener_changes so JS
+     * meta survives the boundary without any stringify/parse.
+     */
+    meta: unknown | null;
+    /**
+     * Coarse classification: Real | Redundant | Breakdown | Consumed.
+     */
+    kind: ChangeKind;
+    /**
+     * Causal chain. Always set. Carries ChangeContext for stage routing.
+     */
+    lineage: Lineage;
+    /**
+     * Debug-mode only. None in production.
+     */
+    audit: ChangeAudit | null;
+};
+type StageTrace = {
+    stage: Stage;
+    duration_us: number;
+    /**
+     * Paths (with JSON-encoded values) that this stage processed.
+     */
+    matched: Array<[string, string]>;
+    skipped: Array<SkippedChange>;
+    /**
+     * Changes produced by this stage.
+     */
+    produced: Array<ProducedChange>;
+    followup: Array<StageTrace>;
+};
+type PipelineTrace = {
+    total_duration_us: number;
+    stages: Array<StageTrace>;
+    /**
+     * Anchor path → present? Gives display layer full context on anchor-dependent resources.
+     */
+    anchor_states: Record<string, boolean>;
+};
+type ValidatorDispatch = {
+    validator_id: number;
+    output_path: string;
+    dependency_values: Record<string, string>;
+};
+type GraphSnapshot = {
+    sync_pairs: Array<[string, string]>;
+    directed_sync_pairs: Array<[string, string]>;
+    flip_pairs: Array<[string, string]>;
+    listeners: Array<{
+        id: number;
+        topic: string;
+        scope: string;
+    }>;
+    bool_logics: Array<{
+        id: number;
+        output_path: string;
+        definition: {
+            "IS_EQUAL": [string, unknown];
+        } | {
+            "EXISTS": string;
+        } | {
+            "IS_EMPTY": string;
+        } | {
+            "AND": Array<BoolLogicNode>;
+        } | {
+            "OR": Array<BoolLogicNode>;
+        } | {
+            "NOT": BoolLogicNode;
+        } | {
+            "GT": [string, number];
+        } | {
+            "LT": [string, number];
+        } | {
+            "GTE": [string, number];
+        } | {
+            "LTE": [string, number];
+        } | {
+            "IN": [string, Array<unknown>];
+        } | {
+            "CONTAINS_ANY": [string, Array<unknown>];
+        } | {
+            "CONTAINS_ALL": [string, Array<unknown>];
+        };
+    }>;
+    value_logics: Array<{
+        id: number;
+        output_path: string;
+    }>;
+    aggregations: Array<{
+        target: string;
+        sources: Array<string>;
+    }>;
+    computations: Array<{
+        target: string;
+        op: string;
+        sources: Array<string>;
+    }>;
+};
+type SideEffectsResult$1 = {
+    sync_changes: Array<Change$1>;
+    aggregation_changes: Array<Change$1>;
+    computation_changes: Array<Change$1>;
+    registered_listener_ids: Array<number>;
+};
+type ListenerRegistration$1 = {
+    subscriber_id: number;
+    topic_paths: Array<string>;
+    scope_path: string;
+    anchor_path?: string;
+};
+type SideEffectsRegistration = {
+    registration_id: string;
+    sync_pairs: Array<[string, string]>;
+    /**
+     * One-way sync pairs: source → target only. Changes to target do NOT propagate back to source.
+     */
+    directed_sync_pairs: Array<[string, string]>;
+    flip_pairs: Array<[string, string]>;
+    aggregation_pairs: Array<[string, string] | [string, string, string]>;
+    clear_paths: Array<{
+        triggers: Array<string>;
+        targets: Array<string>;
+    }>;
+    computation_pairs: Array<[string, string, string] | [string, string, string, string]>;
+    listeners: Array<ListenerRegistration$1>;
+    anchor_path?: string;
+};
+type BoolLogicRegistration = {
+    output_path: string;
+    tree_json: string;
+};
+type ValueLogicRegistration = {
+    output_path: string;
+    tree_json: string;
+};
+type ValidatorRegistration = {
+    validator_id: number;
+    output_path: string;
+    dependency_paths: Array<string>;
+};
+type ConcernsRegistration = {
+    /**
+     * Used by JS for unregister tracking; not consumed by Rust pipeline logic.
+     */
+    registration_id: string;
+    bool_logics: Array<BoolLogicRegistration>;
+    validators: Array<ValidatorRegistration>;
+    value_logics: Array<ValueLogicRegistration>;
+    anchor_path?: string;
+};
+type FullExecutionPlan = {
+    /**
+     * Sequential groups of dispatches (flattened from depth levels + batches).
+     */
+    groups: Array<{
+        dispatches: Array<{
+            dispatch_id: number;
+            subscriber_id: number;
+            scope_path: string;
+            topic_path: string;
+            /**
+             * Indexes into the PrepareResult.listener_changes array.
+             */
+            input_change_ids: Array<number>;
+        }>;
+    }>;
+    /**
+     * propagation_map[dispatch_id] = targets to forward produced changes to.
+     * Flat array indexed by dispatch_id, empty vec = no propagation.
+     */
+    propagation_map: Array<Array<{
+        target_dispatch_id: number;
+        /**
+         * Prefix to prepend to child's relative paths for the target's scope.
+         */
+        remap_prefix: string;
+    }>>;
+    /**
+     * cascade_map[dispatch_id] = sibling dispatch_ids (same group, later position)
+     * that should receive this dispatch's produced changes.
+     */
+    cascade_map: Array<Array<number>>;
+};
+type BoolLogicNode = {
+    "IS_EQUAL": [string, unknown];
+} | {
+    "EXISTS": string;
+} | {
+    "IS_EMPTY": string;
+} | {
+    "AND": Array<BoolLogicNode>;
+} | {
+    "OR": Array<BoolLogicNode>;
+} | {
+    "NOT": BoolLogicNode;
+} | {
+    "GT": [string, number];
+} | {
+    "LT": [string, number];
+} | {
+    "GTE": [string, number];
+} | {
+    "LTE": [string, number];
+} | {
+    "IN": [string, Array<unknown>];
+} | {
+    "CONTAINS_ANY": [string, Array<unknown>];
+} | {
+    "CONTAINS_ALL": [string, Array<unknown>];
+};
+
 /**
  * GenericMeta interface
  *
@@ -336,9 +599,14 @@ interface GenericMeta {
     isComputationChange?: 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;
 }
 
 /**
@@ -371,6 +639,13 @@ interface GenericMeta {
 type ArrayOfChanges<DATA, META extends GenericMeta = GenericMeta> = {
     [K in DeepKey<DATA>]: [K, DeepValue<DATA, K>, META] | [K, DeepValue<DATA, K>];
 }[DeepKey<DATA>][];
+/** A single state change in internal pipeline form. */
+interface Change {
+    path: string;
+    value: unknown;
+    /** Meta object threaded through the pipeline. Lineage is merged in by the bridge on WASM→JS conversion. */
+    meta: GenericMeta;
+}
 
 /**
  * Concern type utilities
@@ -669,16 +944,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 +973,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 +991,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 +1074,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 +1157,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;
 };
@@ -905,57 +1210,6 @@ interface ConcernRegistration {
     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;
-    name: string;
-}
-interface Timing {
-    run: <T>(type: TimingType, fn: () => T, meta: TimingMeta) => T;
-    reportBatch: (type: TimingType) => void;
-}
-
 /**
  * WASM Bridge — Thin namespace over Rust/WASM exports.
  *
@@ -970,211 +1224,132 @@ interface Timing {
  * @module wasm/bridge
  */
 
-/** A single state change (input or output). */
-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;
-}
-/**
- * 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.
- */
-interface WasmPipeline {
-    readonly id: number;
+/** Map a Wasm wire result type to JS-facing type: Wasm.Change[] → Change[], rest untouched. */
+type WireToJs<T> = {
+    [K in keyof T]: T[K] extends Change$1[] ? Change[] : T[K];
+};
+/** JS-facing side effects result — same shape as Wasm wire type but with parsed Change values. */
+type SideEffectsResult = WireToJs<SideEffectsResult$1>;
+/**
+ * Create a new isolated WASM pipeline instance.
+ * Each store should call this once and store the result.
+ * Call pipeline.destroy() on cleanup.
+ */
+declare const createWasmPipeline: (options?: {
+    debug?: boolean;
+}) => {
+    id: number;
+    readonly destroyed: boolean;
     shadowInit: (state: object) => void;
     shadowDump: () => unknown;
-    processChanges: (changes: Change[]) => ProcessChangesResult;
-    pipelineFinalize: (jsChanges: Change[]) => {
+    processChanges: (changes: Change[]) => {
+        listener_changes: Change[];
+        validators_to_run: ValidatorDispatch[];
+        execution_plan: FullExecutionPlan | null;
+        has_work: boolean;
+    };
+    pipelineFinalize: (changes: Change[]) => {
         state_changes: Change[];
+        trace: PipelineTrace | null;
+    };
+    registerSideEffects: (reg: Partial<SideEffectsRegistration>) => {
+        sync_changes: Change[];
+        aggregation_changes: Change[];
+        computation_changes: Change[];
+        registered_listener_ids: number[];
     };
-    registerSideEffects: (reg: SideEffectsRegistration) => SideEffectsResult;
     unregisterSideEffects: (registrationId: string) => void;
-    registerConcerns: (reg: ConcernsRegistration) => ConcernsResult;
+    registerConcerns: (reg: Partial<ConcernsRegistration>) => {
+        bool_logic_changes: Change[];
+        registered_logic_ids: number[];
+        registered_validator_ids: number[];
+        value_logic_changes: Change[];
+        registered_value_logic_ids: number[];
+    };
     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>;
-}
+    getGraphSnapshot: () => GraphSnapshot;
+    validatorSchemas: Map<number, ValidationSchema<unknown>>;
+};
+type WasmPipeline = ReturnType<typeof createWasmPipeline>;
 
 /**
- * PathGroups Data Structure
- *
- * A custom data structure that provides O(1) connected component lookups
- * instead of O(V+E) recomputation on every change like graphology's connectedComponents.
+ * Apex State Logger — Simplified debug logging with colored console output.
  *
- * When wasmGraphType is set ('sync' | 'flip'), addEdge/removeEdge automatically
- * mirror registrations to WASM bridge for pipeline processing.
- *
- * 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.
+ * Two log functions:
+ * 1. logPipeline — called once per processChanges with unified trace
+ * 2. logRegistration — called once per register/unregister with graph snapshot
  *
- * 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
+ * Zero runtime cost when log flag is false (returns no-op logger).
  */
-interface PathGroups {
-    pathToGroup: Map<string, number>;
-    groupToPaths: Map<number, Set<string>>;
-    edges: Set<string>;
-    adjacency: Map<string, Set<string>>;
-    nextGroupId: number;
-    wasmGraphType?: WasmGraphType;
+
+/** Per-listener dispatch trace (JS-measured). */
+interface ListenerDispatchTrace {
+    dispatchId: number;
+    subscriberId: number;
+    fnName: string;
+    scope: string;
+    topic: string;
+    registrationId: string;
+    input: [string, unknown, unknown][];
+    output: Change[];
+    currentState: unknown;
+    durationMs: number;
+    slow: boolean;
+}
+/** Universal trace — single object for console, devtools, any observability tool. */
+interface UnifiedPipelineTrace {
+    wasm: PipelineTrace;
+    listeners: ListenerDispatchTrace[];
+    totalDurationMs: number;
+    wasmDurationMs: number;
+    listenerDurationMs: number;
+    /** True when listener timing was actually measured (debug.timing: true). False → show N/A. */
+    listenerTimingEnabled: boolean;
+}
+interface PipelineLogData {
+    initialChanges: Change[];
+    trace: UnifiedPipelineTrace | null;
+    /** Pre-finalize changes: listener output + validator output before WASM merge/dedup. */
+    preFinalizableChanges?: Change[];
+    /** Final applied changes: after WASM finalization, partitioned to state + concerns. */
+    appliedChanges?: Change[];
+    /** Frozen valtio snapshot of state after all changes applied. */
+    stateSnapshot?: unknown;
+}
+interface RegistrationLogData {
+    result?: SideEffectsResult;
+    appliedChanges?: Change[];
+    stateSnapshot?: unknown;
+    durationMs?: number;
+    /** subscriber_id → function name, for enriching listener entries in the log. */
+    listenerNames?: Map<number, string>;
+}
+interface ApexLogger {
+    logPipeline: (data: PipelineLogData) => void;
+    logRegistration: (type: 'register' | 'unregister', id: string, snapshot: GraphSnapshot, data?: RegistrationLogData) => 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.
+ *
+ * Uses valtio/utils devtools() to expose both proxies as separate DevTools instances:
+ * - '{prefix}:state' — application state proxy
+ * - '{prefix}:concerns' — computed concern values proxy
  *
- * Type aliases for the PathGroups data structure used in sync and flip operations.
- * These aliases maintain backward compatibility with the previous graphology-based API.
+ * 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;
+interface DevToolsNotifier {
+    notifyPipeline: (data: PipelineLogData) => void;
+    notifyRegistration: (type: 'register' | 'unregister', id: string, snapshot: GraphSnapshot) => void;
+    destroy: () => void;
+}
 
 /**
  * Core Store Types
@@ -1187,18 +1362,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 +1411,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 +1475,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,48 +1498,55 @@ interface ListenerRegistration<DATA extends object = object, META extends Generi
     scope?: DeepKey<DATA, Depth> | null;
     fn: OnStateListener<DATA, any, META>;
 }
+/**
+ * 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 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>;
+    fn: (...args: any[]) => unknown;
+    name: string;
+    registrationId: string;
 }
 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>;
+    /** O(1) lookup: subscriber_id -> handler ref. Populated by registerListener. */
+    listenerHandlers: Map<number, ListenerHandlerRef>;
 }
 /** 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;
 }
@@ -1701,6 +1883,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 +1924,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 +2180,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 +2245,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 +2545,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 };