@sladg/apex-state 4.0.0 → 4.6.0

package/dist/index.d.ts

@@ -284,269 +284,6 @@ 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
  *
@@ -597,6 +334,16 @@ 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, listener function name, or any identifier string.
@@ -639,13 +386,6 @@ 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
@@ -1190,25 +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;
-}
+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;
+    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.
@@ -1224,12 +1044,21 @@ interface ConcernRegistration {
  * @module wasm/bridge
  */
 
-/** 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>;
+/**
+ * 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;
+    meta: GenericMeta;
+    kind?: ChangeKind;
+    lineage?: Lineage;
+    audit?: ChangeAudit;
+}
 /**
  * Create a new isolated WASM pipeline instance.
  * Each store should call this once and store the result.
@@ -1243,36 +1072,33 @@ declare const createWasmPipeline: (options?: {
     shadowInit: (state: object) => void;
     shadowDump: () => unknown;
     processChanges: (changes: Change[]) => {
-        listener_changes: Change[];
-        validators_to_run: ValidatorDispatch[];
-        execution_plan: FullExecutionPlan | null;
-        has_work: boolean;
+        changes: Change[];
+        listener_errors: ListenerError[];
+        trace: PipelineTrace | undefined;
     };
-    pipelineFinalize: (changes: Change[]) => {
-        state_changes: Change[];
-        trace: PipelineTrace | null;
+    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[]>;
     };
-    registerSideEffects: (reg: Partial<SideEffectsRegistration>) => {
+    unregisterSideEffects: (registrationId: string) => {
         sync_changes: Change[];
         aggregation_changes: Change[];
         computation_changes: Change[];
-        registered_listener_ids: number[];
+        registered_side_effects: Record<string, ListenerRegistration$1[]>;
     };
-    unregisterSideEffects: (registrationId: string) => void;
-    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[];
+    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[];
     };
     unregisterConcerns: (registrationId: string) => void;
     registerBoolLogic: (outputPath: string, tree: unknown) => number;
     unregisterBoolLogic: (logicId: number) => void;
     pipelineReset: () => void;
     destroy: () => void;
-    getGraphSnapshot: () => GraphSnapshot;
-    validatorSchemas: Map<number, ValidationSchema<unknown>>;
 };
 type WasmPipeline = ReturnType<typeof createWasmPipeline>;
 
@@ -1280,57 +1106,47 @@ type WasmPipeline = ReturnType<typeof createWasmPipeline>;
  * Apex State Logger — Simplified debug logging with colored console output.
  *
  * Two log functions:
- * 1. logPipeline — called once per processChanges with unified trace
+ * 1. logPipeline — called once per processChanges with WASM pipeline trace
  * 2. logRegistration — called once per register/unregister with graph snapshot
  *
  * Zero runtime cost when log flag is false (returns no-op logger).
+ *
+ * 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
+ *
+ * Out of scope:
+ *   - Trace collection (handled by Rust pipeline_trace.rs)
+ *   - DevTools integration (handled by store/devtools.ts)
  */
 
-/** 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;
-}
+type GraphSnapshot$1 = Record<string, unknown>;
+type SideEffectsResult = ReturnType<WasmPipeline['registerSideEffects']>;
 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;
+    /** 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;
-    appliedChanges?: Change[];
-    stateSnapshot?: unknown;
-    durationMs?: number;
-    /** subscriber_id → function name, for enriching listener entries in the log. */
-    listenerNames?: Map<number, string>;
+    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: (type: 'register' | 'unregister', id: string, snapshot: GraphSnapshot, data?: RegistrationLogData) => void;
+    logRegistration: (params: RegistrationLogParams) => void;
     destroy: () => void;
 }
 
@@ -1345,6 +1161,7 @@ interface ApexLogger {
  * Singleton connections per proxy — survives StrictMode remounts and HMR reloads.
  */
 
+type GraphSnapshot = Record<string, unknown>;
 interface DevToolsNotifier {
     notifyPipeline: (data: PipelineLogData) => void;
     notifyRegistration: (type: 'register' | 'unregister', id: string, snapshot: GraphSnapshot) => void;
@@ -1518,18 +1335,9 @@ interface MultiPathListener<DATA extends object = object, META extends GenericMe
 }
 /** 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: any[]) => unknown;
-    name: string;
-    registrationId: string;
-}
 interface Registrations {
-    concerns: Map<string, ConcernType[]>;
-    effectCleanups: Set<() => void>;
-    sideEffectCleanups: Map<string, () => void>;
-    /** O(1) lookup: subscriber_id -> handler ref. Populated by registerListener. */
-    listenerHandlers: Map<number, ListenerHandlerRef>;
+    /** 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 {
@@ -1551,6 +1359,26 @@ interface StoreInstance<DATA extends object> {
     _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;