@logixjs/core 0.0.1 → 1.0.0

package/dist/{module-k7m3txak.d.ts → module-Zd1Gn-Nj.d.ts}

@@ -1,16 +1,9 @@
 import * as effect from 'effect';
-import { Schema, Cause, Effect, Stream, Context, SubscriptionRef, Layer } from 'effect';
+import { Schema, Cause, Effect, Stream, ServiceMap, Layer } from 'effect';
+import { v as SerializableErrorSummary, J as JsonValue, K as ReadQuery, z as ReadQueryInput } from './ReadQuery-DXLzCE0E.js';
 import { Draft as Draft$1 } from 'mutative';
-import { S as Service } from './Platform-C49Pv956.js';
-import { c as AnyActionToken, a as ActionToken } from './action-DiMDD_0v.js';
-import { d as ReadQuery, f as ReadQueryInput } from './ReadQuery-SinbStGF.js';
-
-interface SerializableErrorSummary {
-    readonly message: string;
-    readonly name?: string;
-    readonly code?: string;
-    readonly hint?: string;
-}
+import { S as Service } from './Platform-BV_0MW7g.js';
+import { c as AnyActionToken, a as ActionToken } from './action-BQxjPFEw.js';
 
 type Phase = 'init' | 'run' | 'destroy' | 'platform';
 type Hook = 'initRequired' | 'start' | 'destroy' | 'suspend' | 'resume' | 'reset' | 'unknown';
@@ -58,7 +51,7 @@ interface LifecycleStatus {
 type FieldPath = ReadonlyArray<string>;
 type FieldPathId = number;
 type DirtyAllReason = 'unknownWrite' | 'customMutation' | 'nonTrackablePatch' | 'fallbackPolicy';
-type PatchReason = 'reducer' | 'trait-computed' | 'trait-link' | 'source-refresh' | 'devtools' | 'perf' | 'unknown';
+type PatchReason = 'reducer' | 'trait-computed' | 'trait-link' | 'trait-external-store' | 'source-refresh' | 'devtools' | 'perf' | 'unknown';
 interface DirtySet {
     readonly dirtyAll: boolean;
     /**
@@ -150,10 +143,6 @@ type TraitMetaConflict = Readonly<{
     readonly origin: string;
     readonly meta: TraitMeta;
 }>;
-type JsonPrimitive = string | number | boolean | null;
-type JsonValue = JsonPrimitive | ReadonlyArray<JsonValue> | {
-    readonly [key: string]: JsonValue;
-};
 
 type ConvergeStepId = number;
 /**
@@ -176,6 +165,12 @@ interface ConvergeStaticIrRegistry {
      * - Precomputed at build time to avoid repeatedly stringifying large tables at runtime.
      */
     readonly fieldPathsKey: string;
+    /**
+     * staticIrDigest：
+     * - Stable digest for this converge IR shape;
+     * - Computed on cold build/register paths and reused by hot runtime paths.
+     */
+    readonly staticIrDigest: string;
     readonly fieldPaths: ReadonlyArray<FieldPath>;
     readonly fieldPathIdRegistry: FieldPathIdRegistry;
     readonly configError?: {
@@ -195,17 +190,6 @@ interface ConvergeStaticIrRegistry {
     readonly topoOrder: ReadonlyArray<ConvergeStepId>;
     readonly buildDurationMs: number;
 }
-interface ConvergeStaticIrExport {
-    readonly staticIrDigest: string;
-    readonly moduleId: string;
-    readonly instanceId: string;
-    readonly generation: number;
-    readonly fieldPaths: ReadonlyArray<FieldPath>;
-    readonly stepOutFieldPathIdByStepId: ReadonlyArray<number>;
-    readonly stepSchedulingByStepId: ReadonlyArray<TraitConvergeScheduling>;
-    readonly topoOrder?: ReadonlyArray<number>;
-    readonly buildDurationMs?: number;
-}
 
 declare class DenseIdBitSet {
     readonly size: number;
@@ -234,6 +218,13 @@ interface ConvergeExecIr {
     readonly triggerStepIdsByFieldPathId: Int32Array;
     readonly triggerStepOffsetsByFieldPathId: Int32Array;
     readonly topoOrderInt32: Int32Array;
+    /**
+     * stepId -> topo index in {@link topoOrderInt32}.
+     *
+     * Used by auto-plan computation to sort small reachable sets without scanning
+     * the entire topo slice every time (avoids O(totalSteps) tail cost).
+     */
+    readonly topoIndexByStepId: Int32Array;
     readonly topoOrderImmediateInt32: Int32Array;
     readonly topoOrderDeferredInt32: Int32Array;
     /**
@@ -246,10 +237,51 @@ interface ConvergeExecIr {
     readonly allOutPathsShallow: boolean;
     readonly stepDepsFieldPathIds: Int32Array;
     readonly stepDepsOffsetsByStepId: Int32Array;
+    /**
+     * Perf hints collected at runtime (per module instance, per generation).
+     * Mutated only in hot paths and must remain O(1).
+     */
+    readonly perf: {
+        /**
+         * EWMA of full converge execution duration (ms) under the "off-fast-path"
+         * (diagnostics=off, middleware stack empty).
+         *
+         * Used by auto mode to short-circuit planning when full is already cheap.
+         */
+        fullCommitEwmaOffMs?: number;
+        /**
+         * Last txnSeq (stable anchor) where we executed a full converge under off-fast-path.
+         * Used to periodically re-calibrate fullCommitEwmaOffMs after warmup/JIT effects.
+         */
+        fullCommitLastTxnSeqOff?: number;
+        /**
+         * Minimum observed full converge duration (ms) under off-fast-path.
+         * Helps auto mode quickly detect "full is already cheap" after warmup/JIT without getting stuck on cold-start outliers.
+         */
+        fullCommitMinOffMs?: number;
+        /**
+         * Number of full converge samples recorded under off-fast-path (best-effort; for tuning/debug only).
+         */
+        fullCommitSampleCountOff?: number;
+        /**
+         * "2-hit" admission control for plan computation under auto mode:
+         * - On cache miss, we only pay the cost to compute a plan after the same key repeats.
+         * - Prevents high-cardinality dirty patterns from turning auto into a negative optimization.
+         */
+        recentPlanMissHash1?: number;
+        recentPlanMissHash2?: number;
+    };
     readonly scratch: {
         readonly dirtyPrefixBitSet: DenseIdBitSet;
         readonly reachableStepBitSet: DenseIdBitSet;
         readonly dirtyPrefixQueue: Int32Array;
+        /**
+         * Scratch buffer for building canonical (sorted+deduped) dirty root ids in hot paths
+         * without allocating JS arrays on every txn window.
+         *
+         * Note: callers must treat it as ephemeral and must copy before storing into caches.
+         */
+        readonly dirtyRootIds: Int32Array;
         readonly planStepIds: Int32Array;
     };
 }
@@ -262,7 +294,8 @@ interface ConvergeExecIr {
 type StateTraitSpec<S> = S extends object ? {
     [Path in StateFieldPath<S> | '$root']?: StateTraitSpecValue<S, Path>;
 } : never;
-type StateTraitKind = 'computed' | 'source' | 'link' | 'check';
+type StateTraitKind = 'computed' | 'source' | 'link' | 'externalStore' | 'check';
+type TraitLane = 'urgent' | 'nonUrgent';
 /**
  * TraitConvergeScheduling：
  * - Scheduling semantics for converge/dirty-check (043): decides whether a step must converge within each transaction window.
@@ -333,6 +366,20 @@ interface LinkMeta<S> {
      */
     readonly scheduling?: TraitConvergeScheduling;
 }
+interface ExternalStoreLike<T> {
+    readonly getSnapshot: () => T;
+    readonly getServerSnapshot?: () => T;
+    readonly subscribe: (listener: () => void) => () => void;
+}
+interface ExternalStoreMeta<S, P, T = unknown> {
+    readonly store: ExternalStoreLike<T>;
+    readonly select?: (snapshot: T) => StateAtPath<S, P>;
+    readonly equals?: (prev: StateAtPath<S, P>, next: StateAtPath<S, P>) => boolean;
+    readonly coalesceWindowMs?: number;
+    readonly priority?: TraitLane;
+    readonly meta?: TraitMeta;
+    readonly _fieldPath?: P;
+}
 type CheckRule<Input = unknown, Ctx = unknown> = {
     readonly deps: ReadonlyArray<string>;
     /**
@@ -374,6 +421,10 @@ type StateTraitEntry<S = unknown, P extends string = StateFieldPath<S>> = {
     readonly fieldPath: P;
     readonly kind: 'link';
     readonly meta: LinkMeta<S>;
+} | {
+    readonly fieldPath: P;
+    readonly kind: 'externalStore';
+    readonly meta: ExternalStoreMeta<S, P>;
 } | {
     readonly fieldPath: P;
     readonly kind: 'check';
@@ -384,6 +435,7 @@ interface StateTraitNode<Input = unknown, Ctx = unknown> {
     readonly computed?: StateTraitEntry<Input, any> | Readonly<Record<string, StateTraitEntry<Input, any>>>;
     readonly source?: StateTraitEntry<Input, any> | Readonly<Record<string, StateTraitEntry<Input, any>>>;
     readonly link?: StateTraitEntry<Input, any> | Readonly<Record<string, StateTraitEntry<Input, any>>>;
+    readonly externalStore?: StateTraitEntry<Input, any> | Readonly<Record<string, StateTraitEntry<Input, any>>>;
     readonly check?: Readonly<Record<string, CheckRule<Input, Ctx>>>;
     readonly meta?: TraitMeta;
 }
@@ -416,7 +468,7 @@ interface StateTraitField {
 interface StateTraitFieldTrait {
     readonly fieldId: string;
     readonly kind: StateTraitKind;
-    readonly meta: ComputedMeta<unknown, string> | SourceMeta<unknown, string> | LinkMeta<unknown> | CheckMeta<unknown, unknown>;
+    readonly meta: ComputedMeta<unknown, string> | SourceMeta<unknown, string> | LinkMeta<unknown> | ExternalStoreMeta<unknown, string> | CheckMeta<unknown, unknown>;
     readonly deps: ReadonlyArray<string>;
 }
 /**
@@ -472,7 +524,7 @@ interface StateTraitGraph {
  */
 interface StateTraitPlanStep {
     readonly id: string;
-    readonly kind: 'computed-update' | 'link-propagate' | 'source-refresh' | 'check-validate';
+    readonly kind: 'computed-update' | 'link-propagate' | 'source-refresh' | 'external-store-sync' | 'check-validate';
     readonly targetFieldPath?: string;
     readonly sourceFieldPaths?: ReadonlyArray<string>;
     readonly resourceId?: string;
@@ -507,7 +559,7 @@ interface StateTraitSchemaPathRef {
  * - stateSchema and spec preserve original inputs; graph/plan are internal IR.
  */
 interface StateTraitProgram<S> {
-    readonly stateSchema: Schema.Schema<S, any>;
+    readonly stateSchema: Schema.Schema<S>;
     readonly spec: StateTraitSpec<S>;
     /**
      * Program.entries：
@@ -600,9 +652,10 @@ interface StateTransactionOverrides {
     /** 060: Txn Lanes provider_module overrides (by moduleId). */
     readonly txnLanesOverridesByModuleId?: Readonly<Record<string, TxnLanesPatch>>;
 }
-type ConcurrencyLimit = number | 'unbounded';
-interface ConcurrencyPolicyPatch {
-    readonly concurrencyLimit?: ConcurrencyLimit;
+type SchedulingPolicyLimit = number | 'unbounded';
+type ConcurrencyLimit = SchedulingPolicyLimit;
+interface SchedulingPolicySurfacePatch {
+    readonly concurrencyLimit?: SchedulingPolicyLimit;
     readonly losslessBackpressureCapacity?: number;
     readonly allowUnbounded?: boolean;
     readonly pressureWarningThreshold?: {
@@ -612,24 +665,32 @@ interface ConcurrencyPolicyPatch {
     readonly warningCooldownMs?: number;
 }
 /**
- * Runtime-level ConcurrencyPolicy:
+ * Runtime-level unified scheduling policy surface:
  * - Provided at the app layer by Logix.Runtime.make / AppRuntime.makeApp.
  * - ModuleRuntime merges sources via a resolver (builtin/runtime_module/provider, etc.).
  *
  * Notes:
  * - overridesByModuleId is used for runtime_module hot-switching (hotfix / gradual tuning) and is lower priority than provider overrides.
  */
-interface ConcurrencyPolicy extends ConcurrencyPolicyPatch {
-    readonly overridesByModuleId?: Readonly<Record<string, ConcurrencyPolicyPatch>>;
+interface SchedulingPolicySurface extends SchedulingPolicySurfacePatch {
+    readonly overridesByModuleId?: Readonly<Record<string, SchedulingPolicySurfacePatch>>;
 }
 /**
- * Provider-scoped ConcurrencyPolicyOverrides (delta overrides):
+ * Provider-scoped SchedulingPolicySurfaceOverrides (delta overrides):
  * - Used to inject more local overrides into a Provider subtree on top of inherited global runtime config.
  * - Override precedence: provider > runtime_module > runtime_default > builtin.
  */
-interface ConcurrencyPolicyOverrides extends ConcurrencyPolicyPatch {
-    readonly overridesByModuleId?: Readonly<Record<string, ConcurrencyPolicyPatch>>;
+interface SchedulingPolicySurfaceOverrides extends SchedulingPolicySurfacePatch {
+    readonly overridesByModuleId?: Readonly<Record<string, SchedulingPolicySurfacePatch>>;
 }
+/**
+ * Legacy aliases:
+ * - Keep old names as pure aliases to support migration without behavior drift.
+ * - Canonical naming for new code should use SchedulingPolicySurface*.
+ */
+type ConcurrencyPolicyPatch = SchedulingPolicySurfacePatch;
+type ConcurrencyPolicy = SchedulingPolicySurface;
+type ConcurrencyPolicyOverrides = SchedulingPolicySurfaceOverrides;
 
 type TraitId = string;
 type TraitOriginType = 'module' | 'logicUnit';
@@ -671,13 +732,15 @@ interface ModuleTraitsSnapshot {
     readonly provenanceIndex: Record<TraitId, TraitProvenance>;
 }
 
+type ModeRunnerMode = 'task' | 'parallel' | 'latest' | 'exhaust';
+
 interface TaskRunnerOrigins {
     readonly pending?: StateTxnOrigin;
     readonly success?: StateTxnOrigin;
     readonly failure?: StateTxnOrigin;
 }
-type TaskHandler<Payload, Sh extends AnyModuleShape, R> = Of<Sh, R, void, never> | ((payload: Payload) => Of<Sh, R, void, never>);
-type TaskEffect<Payload, Sh extends AnyModuleShape, R, A, E> = Of<Sh, R, A, E> | ((payload: Payload) => Of<Sh, R, A, E>);
+type TaskHandler<Payload, Sh extends AnyModuleShape, R> = LogicEffect<Sh, R, void, never> | ((payload: Payload) => LogicEffect<Sh, R, void, never>);
+type TaskEffect<Payload, Sh extends AnyModuleShape, R, A, E> = LogicEffect<Sh, R, A, E> | ((payload: Payload) => LogicEffect<Sh, R, A, E>);
 interface TaskRunnerConfig<Payload, Sh extends AnyModuleShape, R, A = void, E = never> {
     /**
      * Optional: trigger source name (e.g. actionTag / fieldPath), used as the default pending origin.name.
@@ -697,13 +760,13 @@ interface TaskRunnerConfig<Payload, Sh extends AnyModuleShape, R, A = void, E =
     /**
      * success: success writeback (separate transaction entry).
      */
-    readonly success?: (result: A, payload: Payload) => Of<Sh, R, void, never>;
+    readonly success?: (result: A, payload: Payload) => LogicEffect<Sh, R, void, never>;
     /**
      * failure: failure writeback (separate transaction entry).
      *
      * Note: takes a Cause to preserve defect/interrupt semantics; interrupts do not trigger failure writeback by default.
      */
-    readonly failure?: (cause: Cause.Cause<E>, payload: Payload) => Of<Sh, R, void, never>;
+    readonly failure?: (cause: Cause.Cause<E>, payload: Payload) => LogicEffect<Sh, R, void, never>;
     /**
      * origin: optional override for the three transaction origins.
      * - Default: pending.kind="task:pending"; success/failure.kind="service-callback".
@@ -797,10 +860,18 @@ interface Api<Sh extends ModuleShape<any, any>, R = never> {
     readonly debounce: <V>(ms: number) => (stream: Stream.Stream<V>) => Stream.Stream<V>;
     readonly throttle: <V>(ms: number) => (stream: Stream.Stream<V>) => Stream.Stream<V>;
     readonly filter: <V>(predicate: (value: V) => boolean) => (stream: Stream.Stream<V>) => Stream.Stream<V>;
-    readonly run: <V, A = void, E = never, R2 = unknown>(eff: Of<Sh, R & R2, A, E> | ((payload: V) => Of<Sh, R & R2, A, E>), options?: OperationOptions) => (stream: Stream.Stream<V>) => Effect.Effect<void, E, Env<Sh, R & R2>>;
-    readonly runParallel: <V, A = void, E = never, R2 = unknown>(eff: Of<Sh, R & R2, A, E> | ((payload: V) => Of<Sh, R & R2, A, E>), options?: OperationOptions) => (stream: Stream.Stream<V>) => Effect.Effect<void, E, Env<Sh, R & R2>>;
-    readonly runLatest: <V, A = void, E = never, R2 = unknown>(eff: Of<Sh, R & R2, A, E> | ((payload: V) => Of<Sh, R & R2, A, E>), options?: OperationOptions) => (stream: Stream.Stream<V>) => Effect.Effect<void, E, Env<Sh, R & R2>>;
-    readonly runExhaust: <V, A = void, E = never, R2 = unknown>(eff: Of<Sh, R & R2, A, E> | ((payload: V) => Of<Sh, R & R2, A, E>), options?: OperationOptions) => (stream: Stream.Stream<V>) => Effect.Effect<void, E, Env<Sh, R & R2>>;
+    readonly run: {
+        <V, A = void, E = never, R2 = unknown>(eff: LogicEffect<Sh, R & R2, A, E> | ((payload: V) => LogicEffect<Sh, R & R2, A, E>), options?: OperationOptions): (stream: Stream.Stream<V>) => LogicEffect<Sh, R & R2, void, E>;
+        <V, A = void, E = never, R2 = unknown>(config: RunConfig<Sh, R & R2, V, A, E>): (stream: Stream.Stream<V>) => LogicEffect<Sh, R & R2, void, E>;
+    };
+    readonly runParallel: <V, A = void, E = never, R2 = unknown>(eff: LogicEffect<Sh, R & R2, A, E> | ((payload: V) => LogicEffect<Sh, R & R2, A, E>), options?: OperationOptions) => (stream: Stream.Stream<V>) => LogicEffect<Sh, R & R2, void, E>;
+    readonly runLatest: <V, A = void, E = never, R2 = unknown>(eff: LogicEffect<Sh, R & R2, A, E> | ((payload: V) => LogicEffect<Sh, R & R2, A, E>), options?: OperationOptions) => (stream: Stream.Stream<V>) => LogicEffect<Sh, R & R2, void, E>;
+    readonly runExhaust: <V, A = void, E = never, R2 = unknown>(eff: LogicEffect<Sh, R & R2, A, E> | ((payload: V) => LogicEffect<Sh, R & R2, A, E>), options?: OperationOptions) => (stream: Stream.Stream<V>) => LogicEffect<Sh, R & R2, void, E>;
+}
+interface RunConfig<Sh extends AnyModuleShape, R, V, A = void, E = never> {
+    readonly effect: LogicEffect<Sh, R, A, E> | ((payload: V) => LogicEffect<Sh, R, A, E>);
+    readonly mode?: ModeRunnerMode;
+    readonly options?: OperationOptions;
 }
 
 /**
@@ -809,14 +880,19 @@ interface Api<Sh extends ModuleShape<any, any>, R = never> {
  * ModuleShape<SpecificSchema> can extend AnyModuleShape.
  */
 type AnySchema = any;
+type NormalizeSchema<S> = S extends Schema.Schema<infer A> ? Schema.Schema<A> : S;
+type NormalizeActionToken<T> = T extends ActionToken<infer Tag, infer Payload, any> ? ActionToken<Tag, Payload, Schema.Schema<any>> : T;
+type NormalizeActionMap<AMap extends Record<string, AnyActionToken>> = {
+    readonly [K in keyof AMap]: NormalizeActionToken<AMap[K]>;
+};
 /**
  * The "schema shape" of a Module: only cares about stateSchema / actionSchema,
  * not runtime configuration details (initialState / services / logic, etc.).
  */
 interface ModuleShape<SSchema extends AnySchema, ASchema extends AnySchema, AMap extends Record<string, AnyActionToken> = Record<string, never>> {
-    readonly stateSchema: SSchema;
-    readonly actionSchema: ASchema;
-    readonly actionMap: AMap;
+    readonly stateSchema: NormalizeSchema<SSchema>;
+    readonly actionSchema: NormalizeSchema<ASchema>;
+    readonly actionMap: NormalizeActionMap<AMap>;
 }
 /**
  * Convenience constraint: any ModuleShape.
@@ -824,9 +900,14 @@ interface ModuleShape<SSchema extends AnySchema, ASchema extends AnySchema, AMap
 type AnyModuleShape = ModuleShape<any, any, any>;
 type StateOf<Sh extends AnyModuleShape> = Schema.Schema.Type<Sh['stateSchema']>;
 type ActionOf<Sh extends AnyModuleShape> = Schema.Schema.Type<Sh['actionSchema']>;
+type ModuleRuntimeOfShape<Sh extends AnyModuleShape> = ModuleRuntime<StateOf<Sh>, ActionOf<Sh>>;
 type ActionArgs<P> = [P] extends [void] ? [] | [P] : [P];
-type ActionFn<P, Out> = (...args: ActionArgs<P>) => Out;
-type ActionPayload<T> = T extends ActionToken<any, infer P, any> ? P : never;
+type ActionPayloadOfToken<T> = T extends ActionToken<any, infer P, any> ? P : never;
+type ActionCallable<P, Out> = {
+    (payload: P): Out;
+} & ([P] extends [void] ? {
+    (): Out;
+} : {});
 interface ModuleImplementStateTransactionOptions {
     readonly instrumentation?: StateTransactionInstrumentation;
     /** 060: Txn Lanes (instance-level opt-in / tuning). */
@@ -846,6 +927,17 @@ interface StateChangeWithMeta<V> {
     readonly value: V;
     readonly meta: StateCommitMeta;
 }
+/**
+ * Read-only state ref exposed to business/logic code.
+ *
+ * - Provides pure snapshot read (`get`) and change stream (`changes`) only.
+ * - Does not expose write methods (`set`/`modify`/`update`); writes must go through controlled APIs
+ *   such as `runtime.setState` / `$.state.update` / `$.state.mutate`.
+ */
+interface ReadonlySubscriptionRef<V> {
+    readonly get: Effect.Effect<V, never, never>;
+    readonly changes: Stream.Stream<V, never, never>;
+}
 /**
  * The runtime interface of a Module (similar to "Store as Context" in docs),
  * exposing read/write, subscription, and dispatch capabilities to Logic / Flow.
@@ -876,6 +968,12 @@ interface ModuleRuntime<S, A> {
     readonly dispatchBatch: (actions: ReadonlyArray<A>) => Effect.Effect<void>;
     readonly dispatchLowPriority: (action: A) => Effect.Effect<void>;
     readonly actions$: Stream.Stream<A>;
+    /**
+     * Optional action-tag topic stream (hot-path optimization):
+     * - When provided, `$.onAction("tag")` can subscribe to a pre-routed stream instead of filtering `actions$`.
+     * - Missing tags may still fall back to `actions$` filtering at call sites.
+     */
+    readonly actionsByTag$?: (tag: string) => Stream.Stream<A>;
     readonly actionsWithMeta$: Stream.Stream<StateChangeWithMeta<A>>;
     /**
      * Subscribe to changes of a selector.
@@ -894,11 +992,11 @@ interface ModuleRuntime<S, A> {
      */
     readonly changesReadQueryWithMeta: <V>(readQuery: ReadQueryInput<S, V>) => Stream.Stream<StateChangeWithMeta<V>>;
     /**
-     * Provide a SubscriptionRef for long-running / fine-grained logic to borrow state directly.
-     * The current implementation only exposes a ref for the whole state; selector views are up to the caller to wrap.
+     * Provide a read-only state ref for long-running / fine-grained logic.
+     * Write access is intentionally blocked at this boundary; all writes must use controlled runtime APIs.
      */
     readonly ref: {
-        <V = S>(selector?: (s: S) => V): SubscriptionRef.SubscriptionRef<V>;
+        <V = S>(selector?: (s: S) => V): ReadonlySubscriptionRef<V>;
     };
 }
 /**
@@ -908,7 +1006,7 @@ interface ModuleRuntime<S, A> {
  * - The Id type is not important for this PoC, so we use `any`.
  * - The Service type is fixed to the Runtime for the current Shape.
  */
-type ModuleRuntimeTag<Sh extends AnyModuleShape> = Context.Tag<any, ModuleRuntime<StateOf<Sh>, ActionOf<Sh>>>;
+type ModuleRuntimeTag<Sh extends AnyModuleShape> = ServiceMap.Key<any, ModuleRuntimeOfShape<Sh>>;
 /**
  * Module handle union:
  * - Used by the React adapter / higher-level integrations to accept either a tag or a runtime instance.
@@ -917,7 +1015,7 @@ type ModuleRuntimeTag<Sh extends AnyModuleShape> = Context.Tag<any, ModuleRuntim
  *
  * Higher-level APIs may accept ModuleHandle<Sh> and branch internally on tag vs instance.
  */
-type ModuleHandleUnion<Sh extends AnyModuleShape> = ModuleRuntime<StateOf<Sh>, ActionOf<Sh>> | ModuleRuntimeTag<Sh>;
+type ModuleHandleUnion<Sh extends AnyModuleShape> = ModuleRuntimeOfShape<Sh> | ModuleRuntimeTag<Sh>;
 /**
  * v3: a read-only handle view exposed to Logic for cross-module access.
  *
@@ -932,7 +1030,7 @@ interface ModuleHandle<Sh extends AnyModuleShape> {
     readonly changes: <V>(selector: (s: StateOf<Sh>) => V) => Stream.Stream<V, never, never>;
     readonly dispatch: (action: ActionOf<Sh>) => Effect.Effect<void, never, never>;
     readonly actions: {
-        [K in keyof Sh['actionMap']]: ActionFn<ActionPayload<Sh['actionMap'][K]>, Effect.Effect<void, never, never>>;
+        [K in keyof Sh['actionMap']]: ActionCallable<ActionPayloadOfToken<Sh['actionMap'][K]>, Effect.Effect<void, never, never>>;
     };
     readonly actions$: Stream.Stream<ActionOf<Sh>, never, never>;
 }
@@ -971,15 +1069,64 @@ type ModuleExtOf<M> = M extends ModuleLike<any, any, infer Ext> ? Ext : never;
  * - setup: runs during Module instance startup, used to register reducers / lifecycle / Debug and other structural behavior.
  * - run: the main logic program, running as a long-lived fiber after Env is fully ready.
  *
- * Notes:
- * - In the current implementation, Runtime still treats Logic as a single-phase program, equivalent to
- *   `setup = Effect.void` and `run = Logic`.
- * - After the runtime-logix L4 drafts converge, we will gradually adopt a real two-phase execution model.
+ * Runtime canonicalization rule:
+ * - raw Logic inputs (single-phase / plan / marked plan effect) are normalized into LogicPlan before execution.
+ * - single-phase Logic is equivalent to `setup = Effect.void` and `run = Logic`.
  */
 interface LogicPlan<Sh extends AnyModuleShape, R = unknown, E = unknown> {
-    readonly setup: Of<Sh, R, void, never>;
-    readonly run: Of<Sh, R, unknown, E>;
+    readonly setup: DispatchEffect<Sh, R>;
+    readonly run: LogicEffect<Sh, R, unknown, E>;
 }
+type LogicEffect<Sh extends AnyModuleShape, R = never, A = void, E = never> = Of<Sh, R, A, E>;
+type DispatchEffect<Sh extends AnyModuleShape, R = never> = LogicEffect<Sh, R, void, never>;
+type ActionForTag<Sh extends AnyModuleShape, K extends keyof Sh['actionMap']> = Extract<ActionOf<Sh>, {
+    _tag: K;
+} | {
+    type: K;
+}>;
+type BoundApiRootApi<Sh extends AnyModuleShape, R = never> = {
+    readonly resolve: <Svc, Id = unknown>(tag: ServiceMap.Key<Id, Svc>) => LogicEffect<Sh, R, Svc, never>;
+};
+type BoundApiStateApi<Sh extends AnyModuleShape, R = never> = {
+    readonly read: LogicEffect<Sh, R, StateOf<Sh>, never>;
+    readonly update: (f: (prev: StateOf<Sh>) => StateOf<Sh>) => DispatchEffect<Sh, R>;
+    readonly mutate: (f: (draft: Draft<StateOf<Sh>>) => void) => DispatchEffect<Sh, R>;
+    readonly ref: {
+        <V = StateOf<Sh>>(selector?: (s: StateOf<Sh>) => V): ReadonlySubscriptionRef<V>;
+    };
+};
+type BoundApiDispatchersApi<Sh extends AnyModuleShape, R = never> = {
+    readonly [K in keyof Sh['actionMap']]: ActionCallable<ActionPayloadOfToken<Sh['actionMap'][K]>, DispatchEffect<Sh, R>>;
+};
+type BoundApiDispatchApi<Sh extends AnyModuleShape, R = never> = {
+    (action: ActionOf<Sh>): DispatchEffect<Sh, R>;
+    <K extends keyof Sh['actionMap']>(token: Sh['actionMap'][K], ...args: ActionArgs<ActionPayloadOfToken<Sh['actionMap'][K]>>): DispatchEffect<Sh, R>;
+    <K extends keyof Sh['actionMap']>(tag: K, ...args: ActionArgs<ActionPayloadOfToken<Sh['actionMap'][K]>>): DispatchEffect<Sh, R>;
+};
+type BoundApiLifecycleApi<Sh extends AnyModuleShape, R = never> = {
+    readonly onInitRequired: (eff: DispatchEffect<Sh, R>) => DispatchEffect<Sh, R>;
+    readonly onStart: (eff: DispatchEffect<Sh, R>) => DispatchEffect<Sh, R>;
+    readonly onInit: (eff: DispatchEffect<Sh, R>) => DispatchEffect<Sh, R>;
+    readonly onDestroy: (eff: DispatchEffect<Sh, R>) => DispatchEffect<Sh, R>;
+    readonly onError: (handler: (cause: effect.Cause.Cause<unknown>, context: ErrorContext) => Effect.Effect<void, never, R>) => DispatchEffect<Sh, R>;
+    readonly onSuspend: (eff: DispatchEffect<Sh, R>) => DispatchEffect<Sh, R>;
+    readonly onResume: (eff: DispatchEffect<Sh, R>) => DispatchEffect<Sh, R>;
+    readonly onReset: (eff: DispatchEffect<Sh, R>) => DispatchEffect<Sh, R>;
+};
+type BoundApiUseApi<Sh extends AnyModuleShape, R = never> = {
+    <M extends ModuleLike<string, AnyModuleShape, any>>(module: M): LogicEffect<Sh, R, ModuleHandle<ModuleShapeOf<M>> & ModuleExtOf<M>, never>;
+    <Sh2 extends AnyModuleShape>(module: ModuleTag<string, Sh2>): LogicEffect<Sh, R, ModuleHandle<Sh2>, never>;
+    <Svc, Id = unknown>(tag: ServiceMap.Key<Id, Svc>): LogicEffect<Sh, R, Svc, never>;
+};
+type BoundApiTraitsApi<Sh extends AnyModuleShape, R = never> = {
+    readonly declare: (traits: TraitSpec) => void;
+    readonly source: {
+        readonly refresh: (fieldPath: string, options?: {
+            readonly force?: boolean;
+        }) => DispatchEffect<Sh, R>;
+    };
+};
+type BoundApiReducerApi<Sh extends AnyModuleShape, R = never> = <K extends keyof Sh['actionMap']>(tag: K, reducer: (state: StateOf<Sh>, action: ActionForTag<Sh, K>) => StateOf<Sh>) => DispatchEffect<Sh, R>;
 /**
  * Bound API: creates pre-bound accessors for a given Store shape + Env.
  *
@@ -987,26 +1134,11 @@ interface LogicPlan<Sh extends AnyModuleShape, R = unknown, E = unknown> {
  * - The public Bound.ts exports a same-named type alias to keep the public API consistent.
  */
 interface BoundApi<Sh extends AnyModuleShape, R = never> {
-    readonly root: {
-        readonly resolve: <Svc, Id = unknown>(tag: Context.Tag<Id, Svc>) => Of<Sh, R, Svc, never>;
-    };
-    readonly state: {
-        readonly read: Of<Sh, R, StateOf<Sh>, never>;
-        readonly update: (f: (prev: StateOf<Sh>) => StateOf<Sh>) => Of<Sh, R, void, never>;
-        readonly mutate: (f: (draft: Draft<StateOf<Sh>>) => void) => Of<Sh, R, void, never>;
-        readonly ref: {
-            <V = StateOf<Sh>>(selector?: (s: StateOf<Sh>) => V): SubscriptionRef.SubscriptionRef<V>;
-        };
-    };
+    readonly root: BoundApiRootApi<Sh, R>;
+    readonly state: BoundApiStateApi<Sh, R>;
     readonly actions: Sh['actionMap'];
-    readonly dispatchers: {
-        readonly [K in keyof Sh['actionMap']]: ActionFn<ActionPayload<Sh['actionMap'][K]>, Of<Sh, R, void, never>>;
-    };
-    readonly dispatch: {
-        (action: ActionOf<Sh>): Of<Sh, R, void, never>;
-        <K extends keyof Sh['actionMap']>(token: Sh['actionMap'][K], ...args: ActionArgs<ActionPayload<Sh['actionMap'][K]>>): Of<Sh, R, void, never>;
-        <K extends keyof Sh['actionMap']>(tag: K, ...args: ActionArgs<ActionPayload<Sh['actionMap'][K]>>): Of<Sh, R, void, never>;
-    };
+    readonly dispatchers: BoundApiDispatchersApi<Sh, R>;
+    readonly dispatch: BoundApiDispatchApi<Sh, R>;
     /**
      * effect：
      * - Register a side-effect handler for a specific Action token.
@@ -1016,47 +1148,26 @@ interface BoundApi<Sh extends AnyModuleShape, R = never> {
      * - Handlers must run outside the transaction window (FR-012); never perform IO inside reducers/transactions.
      * - The runtime de-duplicates by `(actionTag, sourceKey)` (sourceKey is derived automatically).
      */
-    readonly effect: <K extends keyof Sh['actionMap']>(token: Sh['actionMap'][K], handler: (payload: ActionPayload<Sh['actionMap'][K]>) => Of<Sh, R, void, any>) => Of<Sh, R, void, never>;
+    readonly effect: <K extends keyof Sh['actionMap']>(token: Sh['actionMap'][K], handler: (payload: ActionPayloadOfToken<Sh['actionMap'][K]>) => LogicEffect<Sh, R, void, any>) => DispatchEffect<Sh, R>;
     readonly flow: Api<Sh, R>;
     readonly match: <V>(value: V) => FluentMatch<V>;
     readonly matchTag: <V extends {
         _tag: string;
     }>(value: V) => FluentMatchTag<V>;
-    readonly lifecycle: {
-        readonly onInitRequired: (eff: Of<Sh, R, void, never>) => Of<Sh, R, void, never>;
-        readonly onStart: (eff: Of<Sh, R, void, never>) => Of<Sh, R, void, never>;
-        readonly onInit: (eff: Of<Sh, R, void, never>) => Of<Sh, R, void, never>;
-        readonly onDestroy: (eff: Of<Sh, R, void, never>) => Of<Sh, R, void, never>;
-        readonly onError: (handler: (cause: effect.Cause.Cause<unknown>, context: ErrorContext) => Effect.Effect<void, never, R>) => Of<Sh, R, void, never>;
-        readonly onSuspend: (eff: Of<Sh, R, void, never>) => Of<Sh, R, void, never>;
-        readonly onResume: (eff: Of<Sh, R, void, never>) => Of<Sh, R, void, never>;
-        readonly onReset: (eff: Of<Sh, R, void, never>) => Of<Sh, R, void, never>;
-    };
-    readonly use: {
-        <M extends ModuleLike<string, AnyModuleShape, any>>(module: M): Of<Sh, R, ModuleHandle<ModuleShapeOf<M>> & ModuleExtOf<M>, never>;
-        <Sh2 extends AnyModuleShape>(module: ModuleTag<string, Sh2>): Of<Sh, R, ModuleHandle<Sh2>, never>;
-        <Svc, Id = unknown>(tag: Context.Tag<Id, Svc>): Of<Sh, R, Svc, never>;
-    };
+    readonly lifecycle: BoundApiLifecycleApi<Sh, R>;
+    readonly use: BoundApiUseApi<Sh, R>;
     readonly onAction: {
         <T extends ActionOf<Sh>>(predicate: (a: ActionOf<Sh>) => a is T): IntentBuilder<T, Sh, R>;
-        <K extends keyof Sh['actionMap']>(tag: K): IntentBuilder<Extract<ActionOf<Sh>, {
-            _tag: K;
-        } | {
-            type: K;
-        }>, Sh, R>;
+        <K extends keyof Sh['actionMap']>(tag: K): IntentBuilder<ActionForTag<Sh, K>, Sh, R>;
         <A extends ActionOf<Sh> & ({
             _tag: string;
         } | {
             type: string;
         })>(value: A): IntentBuilder<A, Sh, R>;
         <Sc extends AnySchema>(schema: Sc): IntentBuilder<Extract<ActionOf<Sh>, Schema.Schema.Type<Sc>>, Sh, R>;
-        <K extends keyof Sh['actionMap']>(token: Sh['actionMap'][K]): IntentBuilder<ActionPayload<Sh['actionMap'][K]>, Sh, R>;
+        <K extends keyof Sh['actionMap']>(token: Sh['actionMap'][K]): IntentBuilder<ActionPayloadOfToken<Sh['actionMap'][K]>, Sh, R>;
     } & {
-        [K in keyof Sh['actionMap']]: IntentBuilder<Extract<ActionOf<Sh>, {
-            _tag: K;
-        } | {
-            type: K;
-        }>, Sh, R>;
+        [K in keyof Sh['actionMap']]: IntentBuilder<ActionForTag<Sh, K>, Sh, R>;
     };
     readonly onState: <V>(selector: (s: StateOf<Sh>) => V) => IntentBuilder<V, Sh, R>;
     readonly on: <V>(source: Stream.Stream<V>) => IntentBuilder<V, Sh, R>;
@@ -1066,24 +1177,7 @@ interface BoundApi<Sh extends AnyModuleShape, R = never> {
      * - source.refresh(fieldPath): trigger an explicit refresh of a source field.
      * - Concrete behavior is mounted at runtime by StateTrait.install.
      */
-    readonly traits: {
-        /**
-         * declare：
-         * - setup-only: contributes trait declarations during the Logic setup phase (pure data/declarative).
-         * - Final merge / conflict detection / freezing is done during Runtime initialization (023).
-         */
-        readonly declare: (traits: TraitSpec) => void;
-        readonly source: {
-            readonly refresh: (fieldPath: string, options?: {
-                /**
-                 * Forced refresh: re-fetch even if keyHash is unchanged and a non-idle snapshot already exists.
-                 * - Used for explicit refresh / invalidate where "same key still re-fetch" is desired.
-                 * - Auto-trigger chains SHOULD keep the default (false/undefined) to avoid duplicate IO and meaningless writebacks.
-                 */
-                readonly force?: boolean;
-            }) => Of<Sh, R, void, never>;
-        };
-    };
+    readonly traits: BoundApiTraitsApi<Sh, R>;
     /**
      * Primary reducer definition entrypoint:
      * - Semantics: register a synchronous, pure state transform reducer for an Action tag.
@@ -1093,11 +1187,7 @@ interface BoundApi<Sh extends AnyModuleShape, R = never> {
      * - At most one primary reducer per Action tag; duplicate registration is an error.
      * - The reducer must be pure: no Env, no Effect.
      */
-    readonly reducer: <K extends keyof Sh['actionMap'], A extends Extract<ActionOf<Sh>, {
-        _tag: K;
-    } | {
-        type: K;
-    }>>(tag: K, reducer: (state: StateOf<Sh>, action: A) => StateOf<Sh>) => Of<Sh, R, void, never>;
+    readonly reducer: BoundApiReducerApi<Sh, R>;
 }
 /**
  * ModuleTag: identity anchor (Context.Tag).
@@ -1105,7 +1195,7 @@ interface BoundApi<Sh extends AnyModuleShape, R = never> {
  * - Also acts as a Context.Tag; usable as an argument to `$.use(Module)`.
  * - Exposes `logic` and `live` factories for mounting logic programs and building the live Layer.
  */
-interface ModuleTag<Id extends string, Sh extends AnyModuleShape> extends Context.Tag<any, ModuleRuntime<StateOf<Sh>, ActionOf<Sh>>> {
+interface ModuleTag<Id extends string, Sh extends AnyModuleShape> extends ServiceMap.Key<any, ModuleRuntimeOfShape<Sh>> {
     readonly _kind: 'ModuleTag';
     readonly id: Id;
     readonly shape: Sh;
@@ -1122,7 +1212,7 @@ interface ModuleTag<Id extends string, Sh extends AnyModuleShape> extends Contex
      */
     readonly reducers?: ReducersFromMap<Sh['stateSchema'], Sh['actionMap']>;
     readonly logic: <R = never, E = unknown>(build: (api: BoundApi<Sh, R>) => ModuleLogic<Sh, R, E>) => ModuleLogic<Sh, R, E>;
-    readonly live: <R = never, E = never>(initial: StateOf<Sh>, ...logics: Array<ModuleLogic<Sh, R, E>>) => Layer.Layer<ModuleRuntime<StateOf<Sh>, ActionOf<Sh>>, E, R>;
+    readonly live: <R = never, E = never>(initial: StateOf<Sh>, ...logics: Array<ModuleLogic<Sh, R, E>>) => Layer.Layer<ModuleRuntimeOfShape<Sh>, E, R>;
     /**
      * implement: build a ModuleImpl blueprint from Module definition + initial state + a set of logics.
      *
@@ -1147,7 +1237,7 @@ interface ModuleTag<Id extends string, Sh extends AnyModuleShape> extends Contex
 interface ModuleImpl<Id extends string, Sh extends AnyModuleShape, REnv = any> {
     readonly _tag: 'ModuleImpl';
     readonly module: ModuleTag<Id, Sh>;
-    readonly layer: Layer.Layer<ModuleRuntime<StateOf<Sh>, ActionOf<Sh>>, never, REnv>;
+    readonly layer: Layer.Layer<ModuleRuntimeOfShape<Sh>, never, REnv>;
     readonly processes?: ReadonlyArray<Effect.Effect<void, any, any>>;
     readonly stateTransaction?: ModuleImplementStateTransactionOptions;
     readonly withLayer: (layer: Layer.Layer<any, never, any>) => ModuleImpl<Id, Sh, REnv>;
@@ -1156,9 +1246,9 @@ interface ModuleImpl<Id extends string, Sh extends AnyModuleShape, REnv = any> {
 /**
  * Helper type: convert an Action Map into a union type.
  */
-type PayloadOfActionDef<V> = V extends Schema.Schema<any, any, any> ? Schema.Schema.Type<V> : V extends ActionToken<any, infer P, any> ? P : never;
+type PayloadOfActionDef<V> = V extends Schema.Schema<any> ? Schema.Schema.Type<V> : V extends ActionToken<any, infer P, any> ? P : never;
 type ActionsFromMap<M extends Record<string, AnySchema>> = {
-    [K in keyof M]: M[K] extends Schema.Schema<any, any, any> ? PayloadOfActionDef<M[K]> extends void ? {
+    [K in keyof M]: M[K] extends Schema.Schema<any> ? PayloadOfActionDef<M[K]> extends void ? {
         readonly _tag: K;
         readonly payload?: PayloadOfActionDef<M[K]>;
     } : {
@@ -1188,4 +1278,4 @@ type ReducersFromMap<SSchema extends AnySchema, AMap extends Record<string, AnyS
     }, sink?: (path: string | FieldPath) => void) => Schema.Schema.Type<SSchema>;
 };
 
-export { type OperationOptions as $, type AnySchema as A, type BoundApi as B, type ConcurrencyLimit as C, type DirtyAllReason as D, type ErrorContext as E, type FieldPath as F, type ModuleHandleUnion as G, type TraitConvergeTimeSlicingPatch as H, type TxnLanesPatch as I, type StateTransactionTraitConvergeOverrides as J, type StateTransactionOverrides as K, type ConvergeStaticIrExport as L, type ModuleTag as M, type TraitProvenance as N, type ModuleImplementStateTransactionOptions as O, type PatchReason as P, type Env as Q, type ReducersFromMap as R, type StateTransactionInstrumentation as S, type TraitContribution as T, type Of as U, type Draft as V, type IntentBuilder as W, type FluentMatch as X, type FluentMatchTag as Y, type LogicMeta as Z, type Middleware as _, type StatePatchPath as a, type SerializableErrorSummary as a0, type StateTraitProgram as a1, type StateTraitGraph as a2, type StateTraitPlan as a3, type StateTraitSpec as a4, type StateTraitEntry as a5, type StateTraitNode as a6, type StateTraitList as a7, type CheckRule as a8, type StateFieldPath as a9, type StateAtPath as aa, type TraitConvergeScheduling as ab, type DirtySet as b, type FieldPathId as c, type ModuleRuntimeTag as d, type ConcurrencyPolicy as e, type ConcurrencyPolicyOverrides as f, type ConcurrencyPolicyPatch as g, type AnyModuleShape as h, type ModuleShape as i, type ModuleLogic as j, type ModuleImpl as k, type ModuleRuntime as l, type ModuleHandle as m, normalizeFieldPath as n, type StateOf as o, type ActionOf as p, type ActionsFromMap as q, type MutatorsFromMap as r, type StateCommitMode as s, type StateCommitPriority as t, type StateCommitMeta as u, type StateChangeWithMeta as v, type StateTxnOrigin as w, type ModuleTraitsSnapshot as x, type Api as y, type ModuleLike as z };
+export { type ModuleLike as $, type AnySchema as A, type BoundApi as B, type ConcurrencyLimit as C, type DirtyAllReason as D, type ActionForTag as E, type FieldPath as F, type BoundApiRootApi as G, type BoundApiStateApi as H, type BoundApiDispatchersApi as I, type BoundApiDispatchApi as J, type BoundApiLifecycleApi as K, type LogicEffect as L, type ModuleTag as M, type BoundApiUseApi as N, type BoundApiTraitsApi as O, type PatchReason as P, type BoundApiReducerApi as Q, type ReducersFromMap as R, type StateCommitPriority as S, type StateCommitMode as T, type StateChangeWithMeta as U, type ReadonlySubscriptionRef as V, type ErrorContext as W, type StateTxnOrigin as X, type TraitContribution as Y, type ModuleTraitsSnapshot as Z, type Api as _, type StateCommitMeta as a, type ModuleHandleUnion as a0, type TraitConvergeTimeSlicingPatch as a1, type TxnLanesPatch as a2, type StateTransactionTraitConvergeOverrides as a3, type StateTransactionOverrides as a4, type TraitProvenance as a5, type ModuleImplementStateTransactionOptions as a6, type Env as a7, type Of as a8, type Draft as a9, type IntentBuilder as aa, type FluentMatch as ab, type FluentMatchTag as ac, type LogicMeta as ad, type Middleware as ae, type OperationOptions as af, type StateTraitProgram as ag, type StateTraitGraph as ah, type StateTraitPlan as ai, type StateTraitSpec as aj, type StateTraitEntry as ak, type StateTraitNode as al, type StateTraitList as am, type CheckRule as an, type TraitMeta as ao, type StateFieldPath as ap, type StateAtPath as aq, type TraitConvergeScheduling as ar, type TraitLane as as, type SchedulingPolicyLimit as b, type StateTransactionInstrumentation as c, type StatePatchPath as d, type DirtySet as e, type FieldPathId as f, type ModuleRuntimeTag as g, type SchedulingPolicySurface as h, type SchedulingPolicySurfaceOverrides as i, type SchedulingPolicySurfacePatch as j, type ConcurrencyPolicy as k, type ConcurrencyPolicyOverrides as l, type ConcurrencyPolicyPatch as m, normalizeFieldPath as n, type AnyModuleShape as o, type ModuleShape as p, type ModuleLogic as q, type ModuleImpl as r, type ModuleRuntime as s, type ModuleRuntimeOfShape as t, type ModuleHandle as u, type StateOf as v, type ActionOf as w, type ActionsFromMap as x, type MutatorsFromMap as y, type DispatchEffect as z };