@logixjs/core 0.0.1 → 0.0.2

package/dist/{module-B8CBqIZ_.d.cts → module-doenaCsZ.d.cts}

@@ -3,7 +3,7 @@ import { Schema, Cause, Effect, Stream, Context, SubscriptionRef, Layer } from '
 import { Draft as Draft$1 } from 'mutative';
 import { S as Service } from './Platform-C49Pv956.cjs';
 import { c as AnyActionToken, a as ActionToken } from './action-DiMDD_0v.cjs';
-import { d as ReadQuery, f as ReadQueryInput } from './ReadQuery-SinbStGF.cjs';
+import { g as ReadQuery, a as ReadQueryInput } from './ReadQuery-CafjlJQo.cjs';
 
 interface SerializableErrorSummary {
     readonly message: string;
@@ -58,7 +58,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;
     /**
@@ -125,6 +125,16 @@ type StateFieldPath<S> = FieldPathInner<S, 4>;
  */
 type StateAtPath<S, P> = S extends object ? P extends `${infer K}.${infer Rest}` ? K extends keyof S ? StateAtPath<S[K], Rest> : never : P extends keyof S ? S[P] : never : never;
 
+type JsonValue = null | boolean | number | string | ReadonlyArray<JsonValue> | {
+    readonly [key: string]: JsonValue;
+};
+type DowngradeReason = 'non_serializable' | 'oversized' | 'unknown';
+interface JsonValueProjectionStats {
+    readonly dropped: number;
+    readonly oversized: number;
+    readonly nonSerializable: number;
+}
+
 type TraitMeta = Readonly<{
     readonly label?: string;
     readonly description?: string;
@@ -150,10 +160,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;
 /**
@@ -262,7 +268,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 +340,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 +395,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 +409,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 +442,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 +498,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;
@@ -676,8 +702,8 @@ interface TaskRunnerOrigins {
     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 +723,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 +823,10 @@ 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>;
+    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>;
 }
 
 /**
@@ -809,14 +835,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, any, any> ? Schema.Schema<A, any, any> : S;
+type NormalizeActionToken<T> = T extends ActionToken<infer Tag, infer Payload, any> ? ActionToken<Tag, Payload, Schema.Schema<any, any, 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 +855,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). */
@@ -908,7 +944,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> = Context.Tag<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 +953,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 +968,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>;
 }
@@ -977,9 +1013,59 @@ type ModuleExtOf<M> = M extends ModuleLike<any, any, infer Ext> ? Ext : never;
  * - After the runtime-logix L4 drafts converge, we will gradually adopt a real two-phase execution model.
  */
 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: Context.Tag<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): SubscriptionRef.SubscriptionRef<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: Context.Tag<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 +1073,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 +1087,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 +1116,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 +1126,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 +1134,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 Context.Tag<any, ModuleRuntimeOfShape<Sh>> {
     readonly _kind: 'ModuleTag';
     readonly id: Id;
     readonly shape: Sh;
@@ -1122,7 +1151,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 +1176,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>;
@@ -1188,4 +1217,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 StateTransactionTraitConvergeOverrides as $, type AnySchema as A, type BoundApi as B, type ConcurrencyLimit as C, type DirtyAllReason as D, type BoundApiDispatchApi as E, type FieldPath as F, type BoundApiLifecycleApi as G, type BoundApiUseApi as H, type BoundApiTraitsApi as I, type BoundApiReducerApi as J, type StateCommitMode as K, type LogicEffect as L, type ModuleTag as M, type StateChangeWithMeta as N, type ErrorContext as O, type PatchReason as P, type StateTxnOrigin as Q, type ReducersFromMap as R, type StateCommitPriority as S, type TraitContribution as T, type ModuleTraitsSnapshot as U, type Api as V, type ModuleLike as W, type ModuleHandleUnion as X, type JsonValue as Y, type TraitConvergeTimeSlicingPatch as Z, type TxnLanesPatch as _, type StateCommitMeta as a, type StateTransactionOverrides as a0, type ConvergeStaticIrExport as a1, type JsonValueProjectionStats as a2, type DowngradeReason as a3, type TraitProvenance as a4, type ModuleImplementStateTransactionOptions as a5, type Env as a6, type Of as a7, type Draft as a8, type IntentBuilder as a9, type FluentMatch as aa, type FluentMatchTag as ab, type LogicMeta as ac, type Middleware as ad, type OperationOptions as ae, type SerializableErrorSummary 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 StateTransactionInstrumentation as b, type StatePatchPath as c, type DirtySet as d, type FieldPathId as e, type ModuleRuntimeTag as f, type ConcurrencyPolicy as g, type ConcurrencyPolicyOverrides as h, type ConcurrencyPolicyPatch as i, type AnyModuleShape as j, type ModuleShape as k, type ModuleLogic as l, type ModuleImpl as m, normalizeFieldPath as n, type ModuleRuntime as o, type ModuleRuntimeOfShape as p, type ModuleHandle as q, type StateOf as r, type ActionOf as s, type ActionsFromMap as t, type MutatorsFromMap as u, type DispatchEffect as v, type ActionForTag as w, type BoundApiRootApi as x, type BoundApiStateApi as y, type BoundApiDispatchersApi as z };

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@logixjs/core",
-  "version": "0.0.1",
+  "version": "0.0.2",
+  "license": "Apache-2.0",
   "description": "The pure logic engine for Logix",
   "files": [
     "dist/**"
@@ -36,6 +37,11 @@
       "import": "./dist/EffectOp.js",
       "require": "./dist/EffectOp.cjs"
     },
+    "./ExternalStore": {
+      "types": "./dist/ExternalStore.d.ts",
+      "import": "./dist/ExternalStore.js",
+      "require": "./dist/ExternalStore.cjs"
+    },
     "./Env": {
       "types": "./dist/Env.d.ts",
       "import": "./dist/Env.js",
@@ -46,6 +52,11 @@
       "import": "./dist/Flow.js",
       "require": "./dist/Flow.cjs"
     },
+    "./Workflow": {
+      "types": "./dist/Workflow.d.ts",
+      "import": "./dist/Workflow.js",
+      "require": "./dist/Workflow.cjs"
+    },
     "./Kernel": {
       "types": "./dist/Kernel.d.ts",
       "import": "./dist/Kernel.js",

package/dist/ModuleTag-C8FHY_sY.d.ts

@@ -1,93 +0,0 @@
-import { Schema } from 'effect';
-import { D as Draft } from './Logic-BRjEMr-W.js';
-import { N as NormalizedActionTokens, b as ActionDefs } from './action-DiMDD_0v.js';
-import { F as FieldPath, A as AnySchema, i as ModuleShape, q as ActionsFromMap, R as ReducersFromMap, M as ModuleTag$1, p as ActionOf, h as AnyModuleShape, B as BoundApi, m as ModuleHandle, G as ModuleHandleUnion, k as ModuleImpl, j as ModuleLogic, l as ModuleRuntime, v as StateChangeWithMeta, u as StateCommitMeta, s as StateCommitMode, t as StateCommitPriority, o as StateOf } from './module-k7m3txak.js';
-
-type NoInfer_<T> = [T][T extends any ? 0 : never];
-
-/**
- * Reducer helper:
- * - `Reducer.mutate` provides the same mutative style as `$.state.mutate`.
- * - Internally uses mutative-based immutable updates to map "in-place draft mutation" into a pure `(state, action) => state`.
- *
- * @example
- *
- *   const Counter = Logix.ModuleTag.make("Counter", {
- *     state: CounterState,
- *     actions: CounterActions,
- *     reducers: {
- *       inc: Logix.ModuleTag.Reducer.mutate((draft, _payload) => {
- *         draft.count += 1
- *       }),
- *     },
- *   })
- *
- *   yield* $.reducer(
- *     "setValue",
- *     Logix.ModuleTag.Reducer.mutate((draft, payload) => {
- *       draft.value = payload
- *     }),
- *   )
- */
-declare const Reducer: {
-    mutate: <S, A extends {
-        readonly payload?: any;
-    }>(mutator: (draft: Draft<S>, payload: A["payload"]) => void) => ((state: S, action: A, sink?: (path: string | FieldPath) => void) => S);
-    mutateMap: <R extends Readonly<Record<string, ((state: any, action: any, sink?: (path: string | FieldPath) => void) => any) | undefined>>>(mutators: { readonly [K in keyof NoInfer_<R>]?: (draft: Draft<Parameters<NonNullable<NoInfer_<R>[K]>>[0]>, payload: Parameters<NonNullable<NoInfer_<R>[K]>>[1] extends {
-        readonly payload: infer P;
-    } ? P : Parameters<NonNullable<NoInfer_<R>[K]>>[1] extends {
-        readonly payload?: infer P;
-    } ? P | undefined : never) => void; }) => R;
-};
-/**
- * A simplified Shape definition helper, designed for Action Maps.
- * @example type MyShape = Shape<typeof MyState, typeof MyActionMap>
- */
-type Shape<S extends AnySchema, M extends Record<string, AnySchema>> = ModuleShape<S, Schema.Schema<ActionsFromMap<NormalizedActionTokens<M & ActionDefs>>>, NormalizedActionTokens<M & ActionDefs>>;
-/**
- * ModuleTag.make：
- * - Defines a domain module Tag using the given id and state/actions/reducers.
- * - The returned ModuleTag is both a Context.Tag and a factory carrying its Shape.
- *
- * Note: since 022, the old `Module` (Tag identity) was renamed to `ModuleTag`; use `Logix.Module` for module definition objects.
- */
-declare const make: <Id extends string, SSchema extends AnySchema, ADefs extends ActionDefs>(id: Id, def: {
-    readonly state: SSchema;
-    readonly actions: ADefs;
-    readonly reducers?: ReducersFromMap<SSchema, ADefs>;
-    /**
-     * traits：
-     * - Used to attach a StateTraitSpec (see specs/000-module-traits-runtime).
-     * - The current implementation builds a Program during ModuleTag.make, and injects a setup-only Logic in `ModuleTag.implement`
-     *   to call `StateTrait.install`.
-     *   (Note: if you use `ModuleTag.live` to export a Layer and want trait behavior, call `StateTrait.install` explicitly in logics,
-     *   or use `ModuleTag.implement` instead.)
-     */
-    readonly traits?: unknown;
-}) => ModuleTag$1<Id, ModuleShape<SSchema, Schema.Schema<ActionsFromMap<NormalizedActionTokens<ADefs>>>, NormalizedActionTokens<ADefs>>>;
-
-declare const ModuleTag_ActionOf: typeof ActionOf;
-declare const ModuleTag_ActionsFromMap: typeof ActionsFromMap;
-declare const ModuleTag_AnyModuleShape: typeof AnyModuleShape;
-declare const ModuleTag_AnySchema: typeof AnySchema;
-declare const ModuleTag_BoundApi: typeof BoundApi;
-declare const ModuleTag_ModuleHandle: typeof ModuleHandle;
-declare const ModuleTag_ModuleHandleUnion: typeof ModuleHandleUnion;
-declare const ModuleTag_ModuleImpl: typeof ModuleImpl;
-declare const ModuleTag_ModuleLogic: typeof ModuleLogic;
-declare const ModuleTag_ModuleRuntime: typeof ModuleRuntime;
-declare const ModuleTag_ModuleShape: typeof ModuleShape;
-declare const ModuleTag_Reducer: typeof Reducer;
-declare const ModuleTag_ReducersFromMap: typeof ReducersFromMap;
-type ModuleTag_Shape<S extends AnySchema, M extends Record<string, AnySchema>> = Shape<S, M>;
-declare const ModuleTag_StateChangeWithMeta: typeof StateChangeWithMeta;
-declare const ModuleTag_StateCommitMeta: typeof StateCommitMeta;
-declare const ModuleTag_StateCommitMode: typeof StateCommitMode;
-declare const ModuleTag_StateCommitPriority: typeof StateCommitPriority;
-declare const ModuleTag_StateOf: typeof StateOf;
-declare const ModuleTag_make: typeof make;
-declare namespace ModuleTag {
-  export { ModuleTag_ActionOf as ActionOf, ModuleTag_ActionsFromMap as ActionsFromMap, ModuleTag_AnyModuleShape as AnyModuleShape, ModuleTag_AnySchema as AnySchema, ModuleTag_BoundApi as BoundApi, ModuleTag_ModuleHandle as ModuleHandle, ModuleTag_ModuleHandleUnion as ModuleHandleUnion, ModuleTag_ModuleImpl as ModuleImpl, ModuleTag_ModuleLogic as ModuleLogic, ModuleTag_ModuleRuntime as ModuleRuntime, ModuleTag_ModuleShape as ModuleShape, ModuleTag$1 as ModuleTag, ModuleTag_Reducer as Reducer, ModuleTag_ReducersFromMap as ReducersFromMap, type ModuleTag_Shape as Shape, ModuleTag_StateChangeWithMeta as StateChangeWithMeta, ModuleTag_StateCommitMeta as StateCommitMeta, ModuleTag_StateCommitMode as StateCommitMode, ModuleTag_StateCommitPriority as StateCommitPriority, ModuleTag_StateOf as StateOf, ModuleTag_make as make };
-}
-
-export { ModuleTag as M, Reducer as R, type Shape as S, make as m };