@logixjs/core 0.0.1

package/dist/module-B8CBqIZ_.d.cts

@@ -0,0 +1,1191 @@
+import * as effect from 'effect';
+import { Schema, Cause, Effect, Stream, Context, SubscriptionRef, Layer } from 'effect';
+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';
+
+interface SerializableErrorSummary {
+    readonly message: string;
+    readonly name?: string;
+    readonly code?: string;
+    readonly hint?: string;
+}
+
+type Phase = 'init' | 'run' | 'destroy' | 'platform';
+type Hook = 'initRequired' | 'start' | 'destroy' | 'suspend' | 'resume' | 'reset' | 'unknown';
+interface ErrorContext {
+    readonly phase: Phase;
+    readonly hook: Hook;
+    readonly moduleId: string;
+    readonly instanceId: string;
+    readonly taskId?: string;
+    readonly txnSeq?: number;
+    readonly opSeq?: number;
+    /**
+     * For diagnostics only: an implementation-side marker indicating where the error originated,
+     * e.g. "logic.fork" / "initRequired" / "start".
+     *
+     * Note: this field must be serializable and must not become a protocol anchor.
+     */
+    readonly origin?: string;
+}
+interface ModuleRuntimeIdentity {
+    readonly moduleId: string;
+    readonly instanceId: string;
+    readonly runtimeLabel?: string;
+}
+type InstanceStatus = 'creating' | 'initializing' | 'ready' | 'failed' | 'terminating' | 'terminated';
+interface InitProgress {
+    readonly total: number;
+    readonly completed: number;
+    readonly current?: number;
+    readonly startedAt?: number;
+}
+type LifecycleOutcome = {
+    readonly status: 'success';
+} | {
+    readonly status: 'failure';
+    readonly error: SerializableErrorSummary;
+};
+interface LifecycleStatus {
+    readonly identity: ModuleRuntimeIdentity;
+    readonly status: InstanceStatus;
+    readonly initOutcome?: LifecycleOutcome;
+    readonly initProgress?: InitProgress;
+}
+
+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';
+interface DirtySet {
+    readonly dirtyAll: boolean;
+    /**
+     * When dirtyAll=true, a stable reason code must be provided; when dirtyAll=false, it should be omitted.
+     */
+    readonly reason?: DirtyAllReason;
+    /**
+     * FieldPathId (Static IR table index).
+     * - When dirtyAll=true, must be an empty array;
+     * - When dirtyAll=false, roots are deduped / prefix-free / stably sorted.
+     */
+    readonly rootIds: ReadonlyArray<FieldPathId>;
+    readonly rootCount: number;
+    readonly keySize: number;
+    readonly keyHash: number;
+    /**
+     * Optional: mark when the output is TopK-truncated (light/full).
+     * Note: truncation does not affect the definition of keyHash/keySize/rootCount (they still refer to full roots).
+     */
+    readonly rootIdsTruncated?: boolean;
+}
+interface FieldPathTrieNode {
+    id?: FieldPathId;
+    children: Map<string, FieldPathTrieNode>;
+}
+interface FieldPathIdRegistry {
+    readonly fieldPaths: ReadonlyArray<FieldPath>;
+    readonly root: FieldPathTrieNode;
+    /**
+     * Fast path: direct lookup for common string inputs (e.g. 'a.b').
+     *
+     * Note: This map is only safe for "dot-separated" paths. If a schema key itself contains '.',
+     * it is ambiguous with nested paths and should not rely on string-path APIs.
+     */
+    readonly pathStringToId?: ReadonlyMap<string, FieldPathId>;
+}
+declare const normalizeFieldPath: (input: string | FieldPath) => FieldPath | undefined;
+
+type StatePatchPath = string | FieldPath | FieldPathId;
+interface StateTxnOrigin {
+    readonly kind: string;
+    readonly name?: string;
+    readonly details?: unknown;
+}
+
+type Primitive = string | number | boolean | bigint | symbol | null | undefined | Date | RegExp | Function;
+type NonNull<T> = Exclude<T, null | undefined>;
+type IsPlainObject<T> = [NonNull<T>] extends [Primitive] ? false : [NonNull<T>] extends [readonly any[]] ? false : [NonNull<T>] extends [Map<any, any> | Set<any> | WeakMap<any, any> | WeakSet<any>] ? false : [NonNull<T>] extends [object] ? true : false;
+type Join<K, P> = K extends string | number ? (P extends string ? `${K}.${P}` : never) : never;
+type PrevDepth<D extends number> = D extends 4 ? 3 : D extends 3 ? 2 : D extends 2 ? 1 : D extends 1 ? 0 : 0;
+type FieldPathInner<S, Depth extends number> = Depth extends 0 ? never : S extends object ? {
+    [K in keyof S & string]: K | (IsPlainObject<S[K]> extends true ? Join<K, FieldPathInner<S[K], PrevDepth<Depth>>> : never);
+}[keyof S & string] : never;
+/**
+ * StateFieldPath<S>：
+ * - Enumerate all field paths on S that can be annotated by Traits at the type level.
+ * - Uses a max recursion depth of 4 to avoid TS Server performance issues.
+ */
+type StateFieldPath<S> = FieldPathInner<S, 4>;
+/**
+ * StateAtPath<S, P>：
+ * - Given a State type S and path P, derive the field type at that path.
+ * - Returns never for non-existent paths, used to trigger type errors in tests.
+ */
+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 TraitMeta = Readonly<{
+    readonly label?: string;
+    readonly description?: string;
+    readonly tags?: ReadonlyArray<string>;
+    readonly group?: string;
+    readonly docsUrl?: string;
+    readonly cacheGroup?: string;
+    /**
+     * Extension annotations: only accepts `x-*` keys (anchors for capabilities like Phantom Source / Drift Detection).
+     *
+     * Constraints:
+     * - Must be serializable (JSON values).
+     * - Must be slim (keep only a few key hints; don't stuff large objects).
+     */
+    readonly annotations?: Readonly<Record<string, JsonValue>>;
+    /**
+     * Semantic hint: when the same entity (e.g. the same resourceId) has multiple inconsistent meta declarations,
+     * the one with canonical=true becomes the "display canonical", and others are recorded as conflicts.
+     */
+    readonly canonical?: boolean;
+}>;
+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;
+/**
+ * ConvergeStaticIrRegistry：
+ * - Converge-only static IR generated during build/load (stable within a generation).
+ * - Hot paths prefer integer-backed structures; keep only the necessary tables for evidence export and explainability.
+ */
+interface ConvergeStaticIrRegistry {
+    readonly generation: number;
+    /**
+     * writerKey/depsKey：
+     * - Used to determine "structural changes" of Converge Static IR (bump generation++ and invalidate strictly).
+     * - Does not include generation itself.
+     */
+    readonly writersKey: string;
+    readonly depsKey: string;
+    /**
+     * fieldPathsKey：
+     * - Incorporates FieldPathId semantics (fieldPaths table) into the stable definition of staticIrDigest;
+     * - Precomputed at build time to avoid repeatedly stringifying large tables at runtime.
+     */
+    readonly fieldPathsKey: string;
+    readonly fieldPaths: ReadonlyArray<FieldPath>;
+    readonly fieldPathIdRegistry: FieldPathIdRegistry;
+    readonly configError?: {
+        readonly code: 'CYCLE_DETECTED' | 'MULTIPLE_WRITERS';
+        readonly message: string;
+        readonly fields: ReadonlyArray<string>;
+    };
+    /**
+     * stepsById：
+     * - StepId -> writer entry (currently computed/link only).
+     * - Numbered by topo order by default (so topoOrder is usually 0..stepCount-1).
+     */
+    readonly stepsById: ReadonlyArray<StateTraitEntry<any, string>>;
+    readonly stepOutFieldPathIdByStepId: ReadonlyArray<FieldPathId>;
+    readonly stepDepsFieldPathIdsByStepId: ReadonlyArray<ReadonlyArray<FieldPathId>>;
+    readonly stepSchedulingByStepId: ReadonlyArray<TraitConvergeScheduling>;
+    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;
+    private readonly words;
+    private readonly touchedWords;
+    private readonly touchedFlags;
+    private touchedCount;
+    constructor(size: number, options?: {
+        readonly clearStrategy?: 'fill' | 'touched-words';
+    });
+    clear(): void;
+    has(id: number): boolean;
+    add(id: number): void;
+}
+
+interface ConvergeExecIr {
+    readonly generation: number;
+    readonly fieldPathsById: ReadonlyArray<FieldPath>;
+    readonly prefixFieldPathIdsByPathId: Int32Array;
+    readonly prefixOffsetsByPathId: Int32Array;
+    /**
+     * Reachability triggers (059):
+     * - prefixPathId -> stepIds that should run when this prefix becomes dirty
+     * - includes prefixes of step outPath and depsPaths
+     */
+    readonly triggerStepIdsByFieldPathId: Int32Array;
+    readonly triggerStepOffsetsByFieldPathId: Int32Array;
+    readonly topoOrderInt32: Int32Array;
+    readonly topoOrderImmediateInt32: Int32Array;
+    readonly topoOrderDeferredInt32: Int32Array;
+    /**
+     * 0=immediate, 1=deferred（043）
+     */
+    readonly stepSchedulingByStepId: Uint8Array;
+    readonly stepLabelByStepId: ReadonlyArray<string>;
+    readonly stepOutFieldPathIdByStepId: Int32Array;
+    readonly stepFromFieldPathIdByStepId: Int32Array;
+    readonly allOutPathsShallow: boolean;
+    readonly stepDepsFieldPathIds: Int32Array;
+    readonly stepDepsOffsetsByStepId: Int32Array;
+    readonly scratch: {
+        readonly dirtyPrefixBitSet: DenseIdBitSet;
+        readonly reachableStepBitSet: DenseIdBitSet;
+        readonly dirtyPrefixQueue: Int32Array;
+        readonly planStepIds: Int32Array;
+    };
+}
+
+/**
+ * StateTraitSpec<S>：
+ * - The standard shape for the `traits` slot in a Module blueprint.
+ * - Keys are constrained by StateFieldPath<S>; values are declarations for the corresponding scope (Entry / Node / List).
+ */
+type StateTraitSpec<S> = S extends object ? {
+    [Path in StateFieldPath<S> | '$root']?: StateTraitSpecValue<S, Path>;
+} : never;
+type StateTraitKind = 'computed' | 'source' | 'link' | 'check';
+/**
+ * TraitConvergeScheduling：
+ * - Scheduling semantics for converge/dirty-check (043): decides whether a step must converge within each transaction window.
+ * - Default `immediate` (keeps legacy behavior); `deferred` takes effect only with explicit declaration + time-slicing enabled.
+ */
+type TraitConvergeScheduling = 'immediate' | 'deferred';
+interface ComputedMeta<S, P> {
+    /**
+     * Explicit dependency field paths (required):
+     *
+     * - deps is the single source of truth for dependencies: Graph/ReverseClosure/incremental scheduling/perf optimizations rely on deps only.
+     * - In the DSL, `StateTrait.computed({ deps, get })` uses deps-as-args; it does not expose `(state) => ...`.
+     * - During build, `get(...depsValues)` is lowered into `derive(state)` for runtime execution, but the dependency read-set remains deps-based.
+     * - In dev-mode, if actual reads in `derive(state)` disagree with deps, a `deps_mismatch` diagnostic warning is emitted.
+     *
+     * - For root scope: deps are StateFieldPath<State>.
+     * - For list.item scope: deps are StateFieldPath<Item> (relative paths; build will prefix them).
+     */
+    readonly deps: ReadonlyArray<StateFieldPath<S>>;
+    readonly derive: (state: Readonly<S>) => StateAtPath<S, P>;
+    /**
+     * Optional: equality predicate (used to skip no-op writebacks).
+     */
+    readonly equals?: (prev: StateAtPath<S, P>, next: StateAtPath<S, P>) => boolean;
+    /**
+     * Converge scheduling (043): defaults to immediate.
+     */
+    readonly scheduling?: TraitConvergeScheduling;
+}
+interface SourceMeta<S, P> {
+    readonly deps: ReadonlyArray<StateFieldPath<S>>;
+    /**
+     * Logical resource identifier (e.g. "user/profile").
+     *
+     * - In the StateTrait.source DSL, `resource` is stored here during build.
+     * - data-model.md calls it resourceId; we keep the DSL naming here to avoid confusion.
+     */
+    readonly resource: string;
+    /**
+     * Rule for computing the key required to access the resource.
+     *
+     * - deps is the single source of truth for dependencies: Graph/ReverseClosure/incremental scheduling/perf optimizations rely on deps only.
+     * - In the DSL, `StateTrait.source({ deps, key })` uses deps-as-args; it does not expose `(state) => ...`.
+     * - During build, `key(...depsValues)` is lowered into `key(state)` for runtime execution, but the dependency read-set remains deps-based.
+     *
+     * - Returning undefined means the resource is inactive under the current state (should be recycled to idle).
+     */
+    readonly key: (state: Readonly<S>) => unknown;
+    readonly triggers?: ReadonlyArray<'onMount' | 'onKeyChange' | 'manual'>;
+    readonly debounceMs?: number;
+    readonly concurrency?: 'switch' | 'exhaust-trailing';
+    /**
+     * Serializable metadata for devtools/docs (whitelisted fields).
+     */
+    readonly meta?: TraitMeta;
+    /**
+     * Reserved: build may populate the field path this trait is attached to, for easier debugging.
+     */
+    readonly _fieldPath?: P;
+}
+interface LinkMeta<S> {
+    /**
+     * Source field path (also constrained by StateFieldPath<S>).
+     */
+    readonly from: StateFieldPath<S>;
+    /**
+     * Converge scheduling (043): defaults to immediate.
+     */
+    readonly scheduling?: TraitConvergeScheduling;
+}
+type CheckRule<Input = unknown, Ctx = unknown> = {
+    readonly deps: ReadonlyArray<string>;
+    /**
+     * validateOn：
+     * - Affects only auto validation phases (onChange/onBlur); submit/manual always run.
+     * - Empty array disables auto validation (only submit/manual run).
+     */
+    readonly validateOn?: ReadonlyArray<'onChange' | 'onBlur'>;
+    readonly validate: (input: Input, ctx: Ctx) => unknown;
+    readonly meta?: TraitMeta;
+};
+interface CheckMeta<Input = unknown, Ctx = unknown> {
+    /**
+     * Named rule set (used for deterministic merge and diagnostics display).
+     */
+    readonly rules: Readonly<Record<string, CheckRule<Input, Ctx>>>;
+    /**
+     * Error-tree writeback (Phase 2: structure only; concrete writeback semantics land in later phases).
+     */
+    readonly writeback?: {
+        readonly kind: 'errors';
+        readonly path?: string;
+    };
+}
+/**
+ * StateTraitEntry<S, P>：
+ * - A single Trait configuration attached to a field path P.
+ * - kind and meta always come together and are used to dispatch behavior during build/install.
+ */
+type StateTraitEntry<S = unknown, P extends string = StateFieldPath<S>> = {
+    readonly fieldPath: P;
+    readonly kind: 'computed';
+    readonly meta: ComputedMeta<S, P>;
+} | {
+    readonly fieldPath: P;
+    readonly kind: 'source';
+    readonly meta: SourceMeta<S, P>;
+} | {
+    readonly fieldPath: P;
+    readonly kind: 'link';
+    readonly meta: LinkMeta<S>;
+} | {
+    readonly fieldPath: P;
+    readonly kind: 'check';
+    readonly meta: CheckMeta<unknown, unknown>;
+};
+interface StateTraitNode<Input = unknown, Ctx = unknown> {
+    readonly _tag: 'StateTraitNode';
+    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 check?: Readonly<Record<string, CheckRule<Input, Ctx>>>;
+    readonly meta?: TraitMeta;
+}
+interface StateTraitList<Item = unknown> {
+    readonly _tag: 'StateTraitList';
+    readonly item?: StateTraitNode<Item, any>;
+    readonly list?: StateTraitNode<ReadonlyArray<Item>, any>;
+    readonly identityHint?: {
+        readonly trackBy?: string;
+    };
+}
+type StateTraitSpecValue<S, P extends string> = StateTraitEntry<S, P> | StateTraitNode<any, any> | StateTraitList<any>;
+/**
+ * StateTraitField：
+ * - Represents a field node in State (whether or not traits are attached).
+ * - Normalized from StateTraitSpec during build.
+ */
+interface StateTraitField {
+    readonly id: string;
+    readonly path: string;
+    readonly displayName?: string;
+    readonly valueType?: string;
+    readonly traits: ReadonlyArray<StateTraitFieldTrait>;
+}
+/**
+ * StateTraitFieldTrait：
+ * - A structured description of a field trait (computed / source / link).
+ * - meta matches StateTraitEntry.meta; deps is the set of field paths this trait depends on.
+ */
+interface StateTraitFieldTrait {
+    readonly fieldId: string;
+    readonly kind: StateTraitKind;
+    readonly meta: ComputedMeta<unknown, string> | SourceMeta<unknown, string> | LinkMeta<unknown> | CheckMeta<unknown, unknown>;
+    readonly deps: ReadonlyArray<string>;
+}
+/**
+ * StateTraitResource：
+ * - Describes the logical resource metadata that a source trait depends on.
+ * - Concrete ResourceSpec implementation lives in the Resource namespace; this keeps only trait-perspective dependency info.
+ */
+interface StateTraitResource {
+    readonly resourceId: string;
+    readonly keySelector: string;
+    readonly keyExample?: unknown;
+    readonly ownerFields: ReadonlyArray<string>;
+    readonly meta?: TraitMeta;
+    readonly metaOrigin?: string;
+    readonly metaConflicts?: ReadonlyArray<TraitMetaConflict>;
+}
+/**
+ * Graph Node / Edge：
+ * - Nodes typically correspond to fields.
+ * - Edges represent dependencies between fields, or between fields and resources.
+ */
+interface StateTraitGraphNode {
+    readonly id: string;
+    readonly field: StateTraitField;
+    readonly traits: ReadonlyArray<StateTraitFieldTrait>;
+    readonly meta?: TraitMeta;
+}
+interface StateTraitGraphEdge {
+    readonly id: string;
+    readonly from: string;
+    readonly to: string;
+    readonly kind: 'computed' | 'link' | 'source-dep' | 'check-dep';
+}
+/**
+ * StateTraitGraph：
+ * - Structural view of the StateTrait engine: a graph of nodes and dependency edges.
+ * - Used by Devtools / Studio / Runtime for structural analysis and visualization.
+ */
+interface StateTraitGraph {
+    readonly _tag: 'StateTraitGraph';
+    readonly nodes: ReadonlyArray<StateTraitGraphNode>;
+    readonly edges: ReadonlyArray<StateTraitGraphEdge>;
+    readonly resources: ReadonlyArray<StateTraitResource>;
+    readonly meta?: {
+        readonly moduleId?: string;
+        readonly version?: string;
+    };
+}
+/**
+ * StateTraitPlanStep：
+ * - The smallest instruction unit used by StateTrait.install / Runtime execution.
+ * - Derived from the graph; used at runtime to install watchers or trigger external calls.
+ */
+interface StateTraitPlanStep {
+    readonly id: string;
+    readonly kind: 'computed-update' | 'link-propagate' | 'source-refresh' | 'check-validate';
+    readonly targetFieldPath?: string;
+    readonly sourceFieldPaths?: ReadonlyArray<string>;
+    readonly resourceId?: string;
+    readonly keySelectorId?: string;
+    readonly debugInfo?: {
+        readonly graphNodeId?: string;
+        readonly graphEdgeId?: string;
+    };
+}
+/**
+ * StateTraitPlan：
+ * - Execution plan summarizing all trait behaviors for a module.
+ * - install mounts behaviors onto Bound API / EffectOp pipelines according to the plan.
+ */
+interface StateTraitPlan {
+    readonly _tag: 'StateTraitPlan';
+    readonly moduleId?: string;
+    readonly steps: ReadonlyArray<StateTraitPlanStep>;
+    readonly meta?: Record<string, unknown>;
+}
+type StateTraitSchemaPathKind = 'fieldPath' | 'dep' | 'link_from' | 'check_writeback';
+interface StateTraitSchemaPathRef {
+    readonly kind: StateTraitSchemaPathKind;
+    readonly entryKind: StateTraitKind;
+    readonly entryFieldPath: string;
+    readonly path: string;
+    readonly ruleName?: string;
+}
+/**
+ * StateTraitProgram<S>：
+ * - Program output of the StateTrait engine; the unified entrypoint for Runtime / Devtools.
+ * - stateSchema and spec preserve original inputs; graph/plan are internal IR.
+ */
+interface StateTraitProgram<S> {
+    readonly stateSchema: Schema.Schema<S, any>;
+    readonly spec: StateTraitSpec<S>;
+    /**
+     * Program.entries：
+     * - Minimal rule set normalized from spec (including node/list/$root) during build.
+     * - Phase 2 focuses on a readable/diagnosable structure; later phases add execution and converge semantics.
+     */
+    readonly entries: ReadonlyArray<StateTraitEntry<any, string>>;
+    readonly graph: StateTraitGraph;
+    readonly plan: StateTraitPlan;
+    readonly convergeIr?: ConvergeStaticIrRegistry;
+    readonly convergeExecIr?: ConvergeExecIr;
+    /**
+     * schemaPaths：
+     * - Path references that must exist in stateSchema, collected from entries during build; dev-only diagnostics (e.g. schema_mismatch).
+     * - When diagnostics=off, validation can be skipped entirely to keep near-zero cost.
+     */
+    readonly schemaPaths?: ReadonlyArray<StateTraitSchemaPathRef>;
+}
+type TraitConvergeRequestedMode = 'auto' | 'full' | 'dirty';
+
+type StateTransactionInstrumentation = 'full' | 'light';
+interface StateTransactionTraitConvergeOverrides {
+    readonly traitConvergeMode?: TraitConvergeRequestedMode;
+    readonly traitConvergeBudgetMs?: number;
+    readonly traitConvergeDecisionBudgetMs?: number;
+    readonly traitConvergeTimeSlicing?: TraitConvergeTimeSlicingPatch;
+}
+interface TxnLanesPatch {
+    /**
+     * enabled: whether Txn Lanes is enabled (default on since 062).
+     * - undefined: default enabled (when not explicitly configured)
+     * - false: disabled (returns to baseline behavior)
+     * - true: enabled (only affects scheduling of follow-up work outside the transaction; transactions remain synchronous)
+     */
+    readonly enabled?: boolean;
+    /**
+     * overrideMode: runtime temporary override (for debugging/rollback/comparison).
+     * - forced_off: forcibly disables Txn Lanes (returns to baseline behavior).
+     * - forced_sync: forces fully synchronous execution (ignores non-urgent deferral and time-slicing; used for comparisons).
+     *
+     * Notes:
+     * - Override precedence follows StateTransactionOverrides: provider > runtime_module > runtime_default > builtin.
+     * - Overrides must be explainable by evidence (see 060 LaneEvidence reasons).
+     */
+    readonly overrideMode?: 'forced_off' | 'forced_sync';
+    /** non-urgent work loop slice budget (ms). */
+    readonly budgetMs?: number;
+    /** Non-urgent backlog coalescing window (ms). */
+    readonly debounceMs?: number;
+    /** Max lag upper bound (ms): exceeding it triggers an explainable starvation protection (forced catch-up). */
+    readonly maxLagMs?: number;
+    /** Whether to allow coalescing/canceling intermediate non-urgent work (must preserve eventual consistency). */
+    readonly allowCoalesce?: boolean;
+    /**
+     * Yield strategy for the non-urgent work loop (progressive enhancement).
+     * - baseline: uses only time budget + hard upper bound
+     * - inputPending: when supported by browsers, also consults `navigator.scheduling.isInputPending`
+     */
+    readonly yieldStrategy?: 'baseline' | 'inputPending';
+}
+interface TraitConvergeTimeSlicingPatch {
+    /**
+     * enabled：
+     * - false/undefined: disabled (default)
+     * - true: enables time-slicing (only affects computed/link explicitly marked as deferred)
+     */
+    readonly enabled?: boolean;
+    /**
+     * debounceMs: coalescing interval (ms) for the deferral window; merges high-frequency inputs into one deferred flush.
+     */
+    readonly debounceMs?: number;
+    /**
+     * maxLagMs: max lag upper bound (ms); exceeding it triggers an explainable forced flush (starvation protection).
+     */
+    readonly maxLagMs?: number;
+}
+/**
+ * Provider-scoped StateTransactionOverrides (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 StateTransactionOverrides {
+    readonly traitConvergeMode?: TraitConvergeRequestedMode;
+    readonly traitConvergeBudgetMs?: number;
+    readonly traitConvergeDecisionBudgetMs?: number;
+    readonly traitConvergeTimeSlicing?: TraitConvergeTimeSlicingPatch;
+    readonly traitConvergeOverridesByModuleId?: Readonly<Record<string, StateTransactionTraitConvergeOverrides>>;
+    /** 060: Txn Lanes provider-level overrides (delta overrides). */
+    readonly txnLanes?: TxnLanesPatch;
+    /** 060: Txn Lanes provider_module overrides (by moduleId). */
+    readonly txnLanesOverridesByModuleId?: Readonly<Record<string, TxnLanesPatch>>;
+}
+type ConcurrencyLimit = number | 'unbounded';
+interface ConcurrencyPolicyPatch {
+    readonly concurrencyLimit?: ConcurrencyLimit;
+    readonly losslessBackpressureCapacity?: number;
+    readonly allowUnbounded?: boolean;
+    readonly pressureWarningThreshold?: {
+        readonly backlogCount?: number;
+        readonly backlogDurationMs?: number;
+    };
+    readonly warningCooldownMs?: number;
+}
+/**
+ * Runtime-level ConcurrencyPolicy:
+ * - 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>>;
+}
+/**
+ * Provider-scoped ConcurrencyPolicyOverrides (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>>;
+}
+
+type TraitId = string;
+type TraitOriginType = 'module' | 'logicUnit';
+type TraitOriginIdKind = 'explicit' | 'derived';
+interface TraitProvenance {
+    readonly originType: TraitOriginType;
+    readonly originId: string;
+    readonly originIdKind: TraitOriginIdKind;
+    /**
+     * Human-readable label for Devtools/error messages (e.g. "logicUnit:Profile#1").
+     */
+    readonly originLabel: string;
+    /**
+     * Optional location summary (e.g. file path / callsite); for navigation only and not used for semantic decisions.
+     */
+    readonly path?: string;
+}
+/**
+ * TraitSpec：
+ * - Minimal representation of "trait declarations": a record keyed by traitId.
+ * - The concrete value shape is defined by the specific trait system (e.g. StateTraitSpec).
+ * - Value serializability is not constrained here (runtime install may depend on functions), but snapshots/evidence exports
+ *   must only include serializable subsets.
+ */
+type TraitSpec = object;
+interface TraitContribution {
+    readonly traits: TraitSpec;
+    readonly provenance: TraitProvenance;
+}
+interface ModuleTraitItem {
+    readonly traitId: TraitId;
+    readonly name: string;
+    readonly description?: string;
+}
+interface ModuleTraitsSnapshot {
+    readonly moduleId: string;
+    readonly digest: string;
+    readonly traits: ReadonlyArray<ModuleTraitItem>;
+    readonly provenanceIndex: Record<TraitId, TraitProvenance>;
+}
+
+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>);
+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.
+     * - BoundApiRuntime may fill this in for onAction("xxx") / traits.source.refresh("field"), etc.
+     * - Other callers are not required to provide it.
+     */
+    readonly triggerName?: string;
+    /**
+     * pending: synchronous state writes (loading=true / clearing errors, etc.), always a separate transaction entry.
+     * - Only executed for tasks that are accepted and actually started (ignored triggers in runExhaustTask do not run pending).
+     */
+    readonly pending?: TaskHandler<Payload, Sh, R>;
+    /**
+     * effect: real IO / async work (must run outside the transaction window).
+     */
+    readonly effect: TaskEffect<Payload, Sh, R, A, E>;
+    /**
+     * success: success writeback (separate transaction entry).
+     */
+    readonly success?: (result: A, payload: Payload) => Of<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>;
+    /**
+     * origin: optional override for the three transaction origins.
+     * - Default: pending.kind="task:pending"; success/failure.kind="service-callback".
+     */
+    readonly origin?: TaskRunnerOrigins;
+    /**
+     * priority: reserved for future debugging/sorting; does not change transaction boundaries or concurrency semantics.
+     */
+    readonly priority?: number;
+}
+
+type Env<Sh extends AnyModuleShape, R> = ModuleRuntimeTag<Sh> | Service | R;
+type Of<Sh extends AnyModuleShape, R = never, A = void, E = never> = Effect.Effect<A, E, Env<Sh, R>>;
+type Draft<T> = Draft$1<T>;
+interface IntentBuilder<Payload, Sh extends AnyModuleShape, R = never> {
+    readonly debounce: (ms: number) => IntentBuilder<Payload, Sh, R>;
+    readonly throttle: (ms: number) => IntentBuilder<Payload, Sh, R>;
+    readonly filter: (predicate: (value: Payload) => boolean) => IntentBuilder<Payload, Sh, R>;
+    readonly map: <U>(f: (value: Payload) => U) => IntentBuilder<U, Sh, R>;
+    readonly run: <A = void, E = never, R2 = unknown>(effect: Of<Sh, R & R2, A, E> | ((p: Payload) => Of<Sh, R & R2, A, E>), options?: OperationOptions) => Of<Sh, R & R2, void, E>;
+    readonly runParallel: <A = void, E = never, R2 = unknown>(effect: Of<Sh, R & R2, A, E> | ((p: Payload) => Of<Sh, R & R2, A, E>), options?: OperationOptions) => Of<Sh, R & R2, void, E>;
+    readonly runLatest: <A = void, E = never, R2 = unknown>(effect: Of<Sh, R & R2, A, E> | ((p: Payload) => Of<Sh, R & R2, A, E>), options?: OperationOptions) => Of<Sh, R & R2, void, E>;
+    readonly runExhaust: <A = void, E = never, R2 = unknown>(effect: Of<Sh, R & R2, A, E> | ((p: Payload) => Of<Sh, R & R2, A, E>), options?: OperationOptions) => Of<Sh, R & R2, void, E>;
+    /**
+     * run*Task: long-chain TaskRunner sugar (pending → IO → success/failure), automatically split into multiple entries/transactions.
+     *
+     * Concurrency semantics mirror run/runLatest/runExhaust/runParallel.
+     */
+    readonly runTask: <A = void, E = never, R2 = unknown>(config: TaskRunnerConfig<Payload, Sh, R & R2, A, E>) => Of<Sh, R & R2, void, never>;
+    readonly runParallelTask: <A = void, E = never, R2 = unknown>(config: TaskRunnerConfig<Payload, Sh, R & R2, A, E>) => Of<Sh, R & R2, void, never>;
+    readonly runLatestTask: <A = void, E = never, R2 = unknown>(config: TaskRunnerConfig<Payload, Sh, R & R2, A, E>) => Of<Sh, R & R2, void, never>;
+    readonly runExhaustTask: <A = void, E = never, R2 = unknown>(config: TaskRunnerConfig<Payload, Sh, R & R2, A, E>) => Of<Sh, R & R2, void, never>;
+    /** Fork a watcher that runs in the ModuleRuntime Scope (equivalent to Effect.forkScoped + run) */
+    readonly runFork: <A = void, E = never, R2 = unknown>(effect: Of<Sh, R & R2, A, E> | ((p: Payload) => Of<Sh, R & R2, A, E>)) => Of<Sh, R & R2, void, E>;
+    /** Fork a watcher with parallel event processing (equivalent to Effect.forkScoped + runParallel) */
+    readonly runParallelFork: <A = void, E = never, R2 = unknown>(effect: Of<Sh, R & R2, A, E> | ((p: Payload) => Of<Sh, R & R2, A, E>)) => Of<Sh, R & R2, void, E>;
+    readonly update: (reducer: (prev: StateOf<Sh>, payload: Payload) => StateOf<Sh> | Effect.Effect<StateOf<Sh>, any, any>) => Of<Sh, R, void, never>;
+    readonly mutate: (reducer: (draft: Draft<StateOf<Sh>>, payload: Payload) => void) => Of<Sh, R, void, never>;
+    readonly pipe: (...fns: ReadonlyArray<(self: IntentBuilder<Payload, Sh, R>) => IntentBuilder<Payload, Sh, R>>) => IntentBuilder<Payload, Sh, R>;
+    readonly toStream: () => Stream.Stream<Payload>;
+}
+interface FluentMatch<V> {
+    readonly with: <A>(pattern: (value: V) => boolean, handler: (value: V) => A) => FluentMatch<V>;
+    readonly otherwise: <A>(handler: (value: V) => A) => A;
+    /**
+     * Requires at least one branch to match:
+     * - If a with branch matches, returns that branch's result (usually an Effect).
+     * - If no branch matches, returns a failing Effect.
+     *
+     * Convention: only use when handlers return an Effect.
+     */
+    readonly exhaustive: () => Effect.Effect<any, any, any>;
+}
+interface FluentMatchTag<V extends {
+    _tag: string;
+}> {
+    readonly with: <K extends V['_tag'], A>(tag: K, handler: (value: Extract<V, {
+        _tag: K;
+    }>) => A) => FluentMatchTag<V>;
+    readonly otherwise: <A>(handler: (value: V) => A) => A;
+    readonly exhaustive: () => Effect.Effect<any, any, any>;
+}
+interface LogicMeta {
+    readonly name: string;
+    readonly storeId?: string;
+    readonly action?: unknown;
+    readonly tags?: string[];
+    readonly [key: string]: unknown;
+}
+/**
+ * OperationOptions：
+ * - Attaches local annotations to a single boundary operation when running Flow/Intent.
+ * - Intent-only (e.g. disabling observation-only capabilities); does not carry rule logic itself.
+ */
+interface OperationOptions {
+    readonly policy?: {
+        readonly disableObservers?: boolean;
+    };
+    readonly tags?: ReadonlyArray<string>;
+    readonly trace?: ReadonlyArray<string>;
+    readonly meta?: Readonly<Record<string, unknown>>;
+}
+type Middleware<Sh extends AnyModuleShape, R, A, E> = (effect: Effect.Effect<A, E, Env<Sh, R>>, meta: LogicMeta) => Effect.Effect<A, E, Env<Sh, R>>;
+
+interface Api<Sh extends ModuleShape<any, any>, R = never> {
+    readonly fromAction: <T extends ActionOf<Sh>>(predicate: (a: ActionOf<Sh>) => a is T) => Stream.Stream<T>;
+    readonly fromState: {
+        <V>(selector: (s: StateOf<Sh>) => V): Stream.Stream<V>;
+        <V>(query: ReadQuery<StateOf<Sh>, V>): Stream.Stream<V>;
+    };
+    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>>;
+}
+
+/**
+ * Convenience constraint: any Effect Schema.
+ * We intentionally use `any` to bypass Schema invariance constraints, so that
+ * ModuleShape<SpecificSchema> can extend AnyModuleShape.
+ */
+type AnySchema = any;
+/**
+ * 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;
+}
+/**
+ * Convenience constraint: any ModuleShape.
+ */
+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 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;
+interface ModuleImplementStateTransactionOptions {
+    readonly instrumentation?: StateTransactionInstrumentation;
+    /** 060: Txn Lanes (instance-level opt-in / tuning). */
+    readonly txnLanes?: TxnLanesPatch;
+}
+type StateCommitMode = 'normal' | 'batch' | 'lowPriority';
+type StateCommitPriority = 'normal' | 'low';
+interface StateCommitMeta {
+    readonly txnSeq: number;
+    readonly txnId: string;
+    readonly commitMode: StateCommitMode;
+    readonly priority: StateCommitPriority;
+    readonly originKind?: string;
+    readonly originName?: string;
+}
+interface StateChangeWithMeta<V> {
+    readonly value: V;
+    readonly meta: StateCommitMeta;
+}
+/**
+ * The runtime interface of a Module (similar to "Store as Context" in docs),
+ * exposing read/write, subscription, and dispatch capabilities to Logic / Flow.
+ */
+interface ModuleRuntime<S, A> {
+    /**
+     * Associated module identifier:
+     * - Injected by ModuleRuntime.make from options.moduleId at construction time.
+     * - Primarily used by Devtools / debugging to align runtime instances with module-level information.
+     */
+    readonly moduleId: string;
+    /**
+     * Stable instance anchor (single source of truth), aligned with 009/011/016.
+     *
+     * - Must be injectable/derivable; never default to randomness/time.
+     * - Do not expose a "second anchor" field to avoid multiple sources of truth.
+     */
+    readonly instanceId: string;
+    /**
+     * Lifecycle status (serializable and consumable by Devtools/Sandbox).
+     * - initProgress is updated during initRequired.
+     * - initOutcome.failure is populated when initialization fails.
+     */
+    readonly lifecycleStatus?: Effect.Effect<LifecycleStatus>;
+    readonly getState: Effect.Effect<S>;
+    readonly setState: (next: S) => Effect.Effect<void>;
+    readonly dispatch: (action: A) => Effect.Effect<void>;
+    readonly dispatchBatch: (actions: ReadonlyArray<A>) => Effect.Effect<void>;
+    readonly dispatchLowPriority: (action: A) => Effect.Effect<void>;
+    readonly actions$: Stream.Stream<A>;
+    readonly actionsWithMeta$: Stream.Stream<StateChangeWithMeta<A>>;
+    /**
+     * Subscribe to changes of a selector.
+     * Note: an implementation may be based on state$ + distinctUntilChanged.
+     */
+    readonly changes: <V>(selector: (s: S) => V) => Stream.Stream<V>;
+    /**
+     * Subscribe to changes of a selector, including commit meta of the current commit (commitMode/priority, etc.).
+     */
+    readonly changesWithMeta: <V>(selector: (s: S) => V) => Stream.Stream<StateChangeWithMeta<V>>;
+    /**
+     * Subscribe to ReadQuery (SelectorSpec) changes, including commit meta of the current commit.
+     *
+     * - static lane: driven by SelectorGraph (precise recompute + cache + precise notifications)
+     * - dynamic lane: may fall back to per-commit recompute (legacy)
+     */
+    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.
+     */
+    readonly ref: {
+        <V = S>(selector?: (s: S) => V): SubscriptionRef.SubscriptionRef<V>;
+    };
+}
+/**
+ * v3: strongly-typed Module Tag for type-safe constraints in Logic.forShape / collaborative logic.
+ *
+ * Notes:
+ * - 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>>>;
+/**
+ * Module handle union:
+ * - Used by the React adapter / higher-level integrations to accept either a tag or a runtime instance.
+ * - As Env/DI: typically put ModuleTag<Sh> into Layer / Runtime environment.
+ * - As local ownership: typically pass a runtime instance directly in a component or a logic program.
+ *
+ * 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>;
+/**
+ * v3: a read-only handle view exposed to Logic for cross-module access.
+ *
+ * - read: read a snapshot value via selector.
+ * - changes: subscribe to changes of the selector view.
+ * - dispatch: dispatch an Action to the module.
+ *
+ * The runtime may wrap an implementation based on ModuleRuntime, but the type does not expose any direct State write API.
+ */
+interface ModuleHandle<Sh extends AnyModuleShape> {
+    readonly read: <V>(selector: (s: StateOf<Sh>) => V) => Effect.Effect<V, never, never>;
+    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>>;
+    };
+    readonly actions$: Stream.Stream<ActionOf<Sh>, never, never>;
+}
+/**
+ * ModuleLogic: a logic program that runs on a specific class of Module.
+ *
+ * - Convention: Env is Logic.Env<Sh, R>.
+ * - The return value is treated as void; errors and dependencies are expressed via E/R.
+ */
+type ModuleLogic<Sh extends AnyModuleShape, R = unknown, E = unknown> = Of<Sh, R, unknown, E> | LogicPlan<Sh, R, E>;
+declare const MODULE_EXT: unique symbol;
+/**
+ * ModuleLike: the minimal runtime/type contract for a Module (definition object / wrapped module),
+ * used by $.use(module).
+ *
+ * - Must be an explicit contract; no duck-typing / magic fields.
+ * - `tag` is the identity anchor (ModuleTag/Context.Tag) used for Env resolution.
+ * - Other reflection fields (schemas/meta/services/dev.source) are not strictly constrained here.
+ */
+interface ModuleLike<Id extends string, Sh extends AnyModuleShape, Ext extends object = {}> {
+    readonly _kind: 'ModuleDef' | 'Module';
+    readonly id: Id;
+    readonly tag: ModuleTag<Id, Sh>;
+    /**
+     * Type-only extension carrier for `$.use(module)` return typing.
+     * - Must not be required at runtime (optional + unique symbol).
+     * - Enables extracting `Ext` even though ModuleLike is otherwise structural.
+     */
+    readonly [MODULE_EXT]?: Ext;
+}
+type ModuleShapeOf<M> = M extends ModuleLike<any, infer Sh, any> ? Sh : never;
+type ModuleExtOf<M> = M extends ModuleLike<any, any, infer Ext> ? Ext : never;
+/**
+ * LogicPlan: an internal two-phase logic abstraction (setup + run).
+ *
+ * - 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.
+ */
+interface LogicPlan<Sh extends AnyModuleShape, R = unknown, E = unknown> {
+    readonly setup: Of<Sh, R, void, never>;
+    readonly run: Of<Sh, R, unknown, E>;
+}
+/**
+ * Bound API: creates pre-bound accessors for a given Store shape + Env.
+ *
+ * - The runtime implementation lives in internal/runtime/BoundApiRuntime.
+ * - 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 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>;
+    };
+    /**
+     * effect：
+     * - Register a side-effect handler for a specific Action token.
+     * - Setup registration is the primary path; run-phase dynamic registration is allowed but emits diagnostics and only affects future actions.
+     *
+     * Constraints:
+     * - 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 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 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>;
+        <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 in keyof Sh['actionMap']]: IntentBuilder<Extract<ActionOf<Sh>, {
+            _tag: K;
+        } | {
+            type: 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>;
+    /**
+     * traits: runtime entrypoints reserved for features like StateTrait.
+     *
+     * - 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>;
+        };
+    };
+    /**
+     * Primary reducer definition entrypoint:
+     * - Semantics: register a synchronous, pure state transform reducer for an Action tag.
+     * - Implementation: writes directly into the Runtime's `_tag -> (state, action) => state` map, not watcher / Flow.
+     *
+     * Constraints:
+     * - 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>;
+}
+/**
+ * ModuleTag: identity anchor (Context.Tag).
+ *
+ * - 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>>> {
+    readonly _kind: 'ModuleTag';
+    readonly id: Id;
+    readonly shape: Sh;
+    readonly stateSchema: Sh['stateSchema'];
+    readonly actionSchema: Sh['actionSchema'];
+    /**
+     * Raw ActionToken map (actionTag -> token).
+     * - Mainly for DX/reflection; runtime contract is still based on shape/actionSchema.
+     */
+    readonly actions: Sh['actionMap'];
+    /**
+     * Raw reducers (if provided by the definition).
+     * - Mainly for DX/reflection; runtime normalizes them into a `_tag -> (state, action) => state` map inside ModuleFactory.
+     */
+    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>;
+    /**
+     * implement: build a ModuleImpl blueprint from Module definition + initial state + a set of logics.
+     *
+     * - R represents the Env required by the logics.
+     * - The returned ModuleImpl.layer carries R as its input environment.
+     * - withLayer/withLayers can progressively narrow R to a more concrete Env (even `never`).
+     */
+    readonly implement: <R = never>(config: {
+        initial: StateOf<Sh>;
+        logics?: Array<ModuleLogic<Sh, R, any>>;
+        imports?: ReadonlyArray<Layer.Layer<any, any, any> | ModuleImpl<any, AnyModuleShape, any>>;
+        processes?: ReadonlyArray<Effect.Effect<void, any, any>>;
+        stateTransaction?: ModuleImplementStateTransactionOptions;
+    }) => ModuleImpl<Id, Sh, R>;
+}
+/**
+ * ModuleImpl: a concrete Module implementation unit (blueprint + initial state + mounted logics).
+ *
+ * - It's a "configured module" that can be consumed directly by React hooks or app composition.
+ * - It carries the Env dependency type R required by the implementation.
+ */
+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 processes?: ReadonlyArray<Effect.Effect<void, any, any>>;
+    readonly stateTransaction?: ModuleImplementStateTransactionOptions;
+    readonly withLayer: (layer: Layer.Layer<any, never, any>) => ModuleImpl<Id, Sh, REnv>;
+    readonly withLayers: (...layers: ReadonlyArray<Layer.Layer<any, never, any>>) => ModuleImpl<Id, Sh, REnv>;
+}
+/**
+ * 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 ActionsFromMap<M extends Record<string, AnySchema>> = {
+    [K in keyof M]: M[K] extends Schema.Schema<any, any, any> ? PayloadOfActionDef<M[K]> extends void ? {
+        readonly _tag: K;
+        readonly payload?: PayloadOfActionDef<M[K]>;
+    } : {
+        readonly _tag: K;
+        readonly payload: PayloadOfActionDef<M[K]>;
+    } : M[K] extends ActionToken<any, any, any> ? ReturnType<M[K]> : never;
+}[keyof M];
+/**
+ * Derive a tag-keyed "draft-style reducer (mutator) map" from an Action Map:
+ * - Each Action tag may optionally declare a `(draftState, payload) => void`.
+ * - Higher-level APIs wrap it into a pure reducer via `Module.Reducer.mutate` / `Module.Reducer.mutateMap`.
+ */
+type MutatorsFromMap<SSchema extends AnySchema, AMap extends Record<string, AnySchema>> = {
+    readonly [K in keyof AMap]?: (draft: Draft<Schema.Schema.Type<SSchema>>, payload: PayloadOfActionDef<AMap[K]>) => void;
+};
+/**
+ * Derive a tag-keyed reducer map from an Action Map:
+ * - Each Action tag may optionally declare a primary reducer `(state, actionOfThisTag) => nextState`.
+ */
+type ReducersFromMap<SSchema extends AnySchema, AMap extends Record<string, AnySchema>> = {
+    readonly [K in keyof AMap]?: (state: Schema.Schema.Type<SSchema>, action: AMap[K] extends ActionToken<any, any, any> ? ReturnType<AMap[K]> : PayloadOfActionDef<AMap[K]> extends void ? {
+        readonly _tag: K;
+        readonly payload?: PayloadOfActionDef<AMap[K]>;
+    } : {
+        readonly _tag: K;
+        readonly payload: PayloadOfActionDef<AMap[K]>;
+    }, 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 };