@lite-fsm/core 2.0.4 → 2.1.0-alpha.0

package/dist/runtime/kernel/storage.d.cts

@@ -0,0 +1,226 @@
+import type { MachineManagerOptions } from "../../interfaces";
+import type { ManagerRuntimeContext as PublicManagerRuntimeContext, ScopedInvocationContext } from "../../plugin";
+import type { StorageActionStageResult as PublicStorageActionStageResult, StorageDehydrateResult as PublicStorageDehydrateResult, StorageHydrateResult as PublicStorageHydrateResult, StoragePrepareActionResult as PublicStoragePrepareActionResult, StorageReduceResult as PublicStorageReduceResult, StorageRuntimeExtension as PublicStorageRuntimeExtension } from "../../pluginStorageTypes";
+import type { AnyEvent, DehydrateOptions, HydrateStrategy, MachinesState, MachineStore, ManagerAction, ReadonlyManagerAction } from "../../types";
+import type { RouteConstraint, RoutingRuntime } from "./routing";
+export type StorageRuntimeState = unknown;
+export type RuntimeIdentity = Readonly<Record<string, unknown>>;
+export type StorageEffectInvocation = unknown;
+export type StorageActionStageResult = PublicStorageActionStageResult;
+export type StorageReduceResult = PublicStorageReduceResult;
+export type ValidateTemplateContext = {
+    readonly key: string;
+    readonly machine: MachineStore[string];
+    readonly storageKind: string;
+};
+export type CompileTemplateContext = ValidateTemplateContext;
+export type CompiledStorageTemplate = {
+    readonly key: string;
+    readonly kind: string;
+    readonly data?: unknown;
+};
+export type CreateRuntimeStateContext = {
+    readonly templates: readonly CompiledStorageTemplate[];
+    readonly manager: ManagerRuntimeContext;
+};
+export type CreatePublicInitialStateContext = {
+    readonly template: CompiledStorageTemplate;
+    readonly state: StorageRuntimeState;
+};
+export type AcceptsEventContext = {
+    readonly template: CompiledStorageTemplate;
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageReduceContext = {
+    readonly template: CompiledStorageTemplate;
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageBeforeReduceContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageReduceBucketContext = {
+    readonly templates: readonly CompiledStorageTemplate[];
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageCommitContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type ResolveEffectInvocationsContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageEffectInvocationContext = {
+    readonly invocation: StorageEffectInvocation;
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageConditionContext = {
+    readonly predicate: (action: ReadonlyManagerAction<AnyEvent>) => boolean;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+};
+export type StorageDehydrateContext = {
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly rootState: Record<string, unknown>;
+    readonly options: DehydrateOptions<MachineStore> | undefined;
+};
+export type StorageHydrateContext = {
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly machines: Readonly<Record<string, unknown>>;
+    readonly snapshot: unknown | undefined;
+    readonly baseState: Record<string, unknown>;
+    readonly strategy: HydrateStrategy;
+    readonly source: "hydrate" | "opts.snapshot";
+    readonly mode: "preview" | "commit" | "init";
+};
+export type ResolveIdentityContext = {
+    readonly state: StorageRuntimeState;
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+};
+export type StorageReactionContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StoragePrepareActionContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly options: unknown;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StoragePrepareActionResult = PublicStoragePrepareActionResult;
+export type StorageHydrateResult = PublicStorageHydrateResult;
+export type StorageDehydrateResult = PublicStorageDehydrateResult<PublicStorageRuntimeExtension>;
+export type StorageDispatchContext = {
+    readonly options: unknown;
+    readonly runtime: Map<string, unknown>;
+    readonly route: RouteConstraint;
+    readonly prevState: Record<string, unknown>;
+    nextState: Record<string, unknown>;
+    readonly skipDelivery: boolean;
+    reportError(error: unknown): void;
+};
+export type StorageDispatchOutcome = {
+    readonly type: "active";
+} | {
+    readonly type: "drop";
+    readonly action: ManagerAction<AnyEvent>;
+};
+export type StorageDispatchLifecycleContext = {
+    readonly originalAction: ManagerAction<AnyEvent>;
+    action: ManagerAction<AnyEvent>;
+    skipDelivery: boolean;
+    route: RouteConstraint;
+    prevState: Record<string, unknown>;
+    nextState: Record<string, unknown>;
+    nextCalled: boolean;
+    outcome: StorageDispatchOutcome;
+    touched: Set<string>;
+    readonly dispatch: StorageDispatchContext;
+};
+export type DispatchSlot<T> = {
+    readonly key: string;
+    get(dispatch: StorageDispatchContext): T | undefined;
+    set(dispatch: StorageDispatchContext, value: T): void;
+};
+export declare const createDispatchSlot: <T>(key: string) => DispatchSlot<T>;
+export type ManagerRuntimeContext<Events extends AnyEvent = AnyEvent, S extends MachineStore = MachineStore> = PublicManagerRuntimeContext<Events, S> & {
+    readonly config: S;
+    readonly options: MachineManagerOptions<any, any, any> | undefined;
+    readonly schemaVersion: number | undefined;
+    readonly routing: RoutingRuntime;
+    getState(): MachinesState<S>;
+    transition(action: ManagerAction<Events>, options?: unknown): ManagerAction<Events>;
+    onTransition(cb: (prevState: MachinesState<S>, currentState: MachinesState<S>, action: ReadonlyManagerAction<Events> | {
+        readonly type: string;
+        readonly payload?: unknown;
+    }) => void): () => void;
+    getDependencies(): Record<string, unknown>;
+    createScopedDeps(baseDeps: Record<string, unknown>, ctx: ScopedInvocationContext): Record<string, unknown>;
+};
+export type StorageRouteMetaDependencyKeys = readonly string[];
+export type StorageRuntimeBase = {
+    readonly kind: string;
+    readonly routeMetaKeys?: StorageRouteMetaDependencyKeys;
+    validateTemplate(ctx: ValidateTemplateContext): void;
+    compileTemplate(ctx: CompileTemplateContext): CompiledStorageTemplate;
+    createRuntimeState(ctx: CreateRuntimeStateContext): StorageRuntimeState;
+    createPublicInitialState(ctx: CreatePublicInitialStateContext): unknown;
+    prepareAction?(ctx: StoragePrepareActionContext): StoragePrepareActionResult;
+    beforeReduce?(ctx: StorageBeforeReduceContext): StorageActionStageResult;
+    commit(ctx: StorageCommitContext): void;
+};
+export type TemplateStorageRuntime = StorageRuntimeBase & {
+    readonly reduceScope?: "template";
+    acceptsEvent(ctx: AcceptsEventContext): boolean;
+    reduce(ctx: StorageReduceContext): StorageReduceResult;
+    readonly reduceBucket?: never;
+};
+export type BucketStorageRuntime = StorageRuntimeBase & {
+    readonly reduceScope: "bucket";
+    reduceBucket(ctx: StorageReduceBucketContext): StorageReduceResult;
+    readonly acceptsEvent?: never;
+    readonly reduce?: never;
+};
+export type StorageEffectsRuntime = {
+    condition?(ctx: StorageConditionContext): Promise<boolean>;
+    resolveInvocations(ctx: ResolveEffectInvocationsContext): readonly StorageEffectInvocation[];
+    invoke(ctx: StorageEffectInvocationContext): void;
+};
+export type StorageSnapshotRuntime = {
+    dehydrate(ctx: StorageDehydrateContext): StorageDehydrateResult;
+    hydrate(ctx: StorageHydrateContext): StorageHydrateResult;
+};
+export type StorageIdentityRuntime = {
+    resolve(ctx: ResolveIdentityContext): RuntimeIdentity | undefined;
+};
+export type StorageReactionRuntime = {
+    run(ctx: StorageReactionContext): void;
+};
+export type StorageRuntime = (TemplateStorageRuntime | BucketStorageRuntime) & {
+    readonly effects?: StorageEffectsRuntime;
+    readonly snapshot?: StorageSnapshotRuntime;
+    readonly identity?: StorageIdentityRuntime;
+    readonly reactions?: StorageReactionRuntime;
+};
+export type StorageRegistry = {
+    register(kind: string, runtime: StorageRuntime, owner: string): void;
+    get(kind: string): StorageRuntime | undefined;
+};
+export type RuntimeStorageEntry = {
+    readonly kind: string;
+    readonly runtime: StorageRuntime;
+};
+export declare const compileStorageTemplates: (machines: MachineStore, machineKeys: readonly string[], storage: StorageRegistry, defaultStorageKind: string) => CompiledStorageTemplate[];

package/dist/runtime/kernel/storage.d.ts

@@ -0,0 +1,226 @@
+import type { MachineManagerOptions } from "../../interfaces";
+import type { ManagerRuntimeContext as PublicManagerRuntimeContext, ScopedInvocationContext } from "../../plugin";
+import type { StorageActionStageResult as PublicStorageActionStageResult, StorageDehydrateResult as PublicStorageDehydrateResult, StorageHydrateResult as PublicStorageHydrateResult, StoragePrepareActionResult as PublicStoragePrepareActionResult, StorageReduceResult as PublicStorageReduceResult, StorageRuntimeExtension as PublicStorageRuntimeExtension } from "../../pluginStorageTypes";
+import type { AnyEvent, DehydrateOptions, HydrateStrategy, MachinesState, MachineStore, ManagerAction, ReadonlyManagerAction } from "../../types";
+import type { RouteConstraint, RoutingRuntime } from "./routing";
+export type StorageRuntimeState = unknown;
+export type RuntimeIdentity = Readonly<Record<string, unknown>>;
+export type StorageEffectInvocation = unknown;
+export type StorageActionStageResult = PublicStorageActionStageResult;
+export type StorageReduceResult = PublicStorageReduceResult;
+export type ValidateTemplateContext = {
+    readonly key: string;
+    readonly machine: MachineStore[string];
+    readonly storageKind: string;
+};
+export type CompileTemplateContext = ValidateTemplateContext;
+export type CompiledStorageTemplate = {
+    readonly key: string;
+    readonly kind: string;
+    readonly data?: unknown;
+};
+export type CreateRuntimeStateContext = {
+    readonly templates: readonly CompiledStorageTemplate[];
+    readonly manager: ManagerRuntimeContext;
+};
+export type CreatePublicInitialStateContext = {
+    readonly template: CompiledStorageTemplate;
+    readonly state: StorageRuntimeState;
+};
+export type AcceptsEventContext = {
+    readonly template: CompiledStorageTemplate;
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageReduceContext = {
+    readonly template: CompiledStorageTemplate;
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageBeforeReduceContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageReduceBucketContext = {
+    readonly templates: readonly CompiledStorageTemplate[];
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageCommitContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type ResolveEffectInvocationsContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageEffectInvocationContext = {
+    readonly invocation: StorageEffectInvocation;
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageConditionContext = {
+    readonly predicate: (action: ReadonlyManagerAction<AnyEvent>) => boolean;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+};
+export type StorageDehydrateContext = {
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly rootState: Record<string, unknown>;
+    readonly options: DehydrateOptions<MachineStore> | undefined;
+};
+export type StorageHydrateContext = {
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly machines: Readonly<Record<string, unknown>>;
+    readonly snapshot: unknown | undefined;
+    readonly baseState: Record<string, unknown>;
+    readonly strategy: HydrateStrategy;
+    readonly source: "hydrate" | "opts.snapshot";
+    readonly mode: "preview" | "commit" | "init";
+};
+export type ResolveIdentityContext = {
+    readonly state: StorageRuntimeState;
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+};
+export type StorageReactionContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StoragePrepareActionContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly options: unknown;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StoragePrepareActionResult = PublicStoragePrepareActionResult;
+export type StorageHydrateResult = PublicStorageHydrateResult;
+export type StorageDehydrateResult = PublicStorageDehydrateResult<PublicStorageRuntimeExtension>;
+export type StorageDispatchContext = {
+    readonly options: unknown;
+    readonly runtime: Map<string, unknown>;
+    readonly route: RouteConstraint;
+    readonly prevState: Record<string, unknown>;
+    nextState: Record<string, unknown>;
+    readonly skipDelivery: boolean;
+    reportError(error: unknown): void;
+};
+export type StorageDispatchOutcome = {
+    readonly type: "active";
+} | {
+    readonly type: "drop";
+    readonly action: ManagerAction<AnyEvent>;
+};
+export type StorageDispatchLifecycleContext = {
+    readonly originalAction: ManagerAction<AnyEvent>;
+    action: ManagerAction<AnyEvent>;
+    skipDelivery: boolean;
+    route: RouteConstraint;
+    prevState: Record<string, unknown>;
+    nextState: Record<string, unknown>;
+    nextCalled: boolean;
+    outcome: StorageDispatchOutcome;
+    touched: Set<string>;
+    readonly dispatch: StorageDispatchContext;
+};
+export type DispatchSlot<T> = {
+    readonly key: string;
+    get(dispatch: StorageDispatchContext): T | undefined;
+    set(dispatch: StorageDispatchContext, value: T): void;
+};
+export declare const createDispatchSlot: <T>(key: string) => DispatchSlot<T>;
+export type ManagerRuntimeContext<Events extends AnyEvent = AnyEvent, S extends MachineStore = MachineStore> = PublicManagerRuntimeContext<Events, S> & {
+    readonly config: S;
+    readonly options: MachineManagerOptions<any, any, any> | undefined;
+    readonly schemaVersion: number | undefined;
+    readonly routing: RoutingRuntime;
+    getState(): MachinesState<S>;
+    transition(action: ManagerAction<Events>, options?: unknown): ManagerAction<Events>;
+    onTransition(cb: (prevState: MachinesState<S>, currentState: MachinesState<S>, action: ReadonlyManagerAction<Events> | {
+        readonly type: string;
+        readonly payload?: unknown;
+    }) => void): () => void;
+    getDependencies(): Record<string, unknown>;
+    createScopedDeps(baseDeps: Record<string, unknown>, ctx: ScopedInvocationContext): Record<string, unknown>;
+};
+export type StorageRouteMetaDependencyKeys = readonly string[];
+export type StorageRuntimeBase = {
+    readonly kind: string;
+    readonly routeMetaKeys?: StorageRouteMetaDependencyKeys;
+    validateTemplate(ctx: ValidateTemplateContext): void;
+    compileTemplate(ctx: CompileTemplateContext): CompiledStorageTemplate;
+    createRuntimeState(ctx: CreateRuntimeStateContext): StorageRuntimeState;
+    createPublicInitialState(ctx: CreatePublicInitialStateContext): unknown;
+    prepareAction?(ctx: StoragePrepareActionContext): StoragePrepareActionResult;
+    beforeReduce?(ctx: StorageBeforeReduceContext): StorageActionStageResult;
+    commit(ctx: StorageCommitContext): void;
+};
+export type TemplateStorageRuntime = StorageRuntimeBase & {
+    readonly reduceScope?: "template";
+    acceptsEvent(ctx: AcceptsEventContext): boolean;
+    reduce(ctx: StorageReduceContext): StorageReduceResult;
+    readonly reduceBucket?: never;
+};
+export type BucketStorageRuntime = StorageRuntimeBase & {
+    readonly reduceScope: "bucket";
+    reduceBucket(ctx: StorageReduceBucketContext): StorageReduceResult;
+    readonly acceptsEvent?: never;
+    readonly reduce?: never;
+};
+export type StorageEffectsRuntime = {
+    condition?(ctx: StorageConditionContext): Promise<boolean>;
+    resolveInvocations(ctx: ResolveEffectInvocationsContext): readonly StorageEffectInvocation[];
+    invoke(ctx: StorageEffectInvocationContext): void;
+};
+export type StorageSnapshotRuntime = {
+    dehydrate(ctx: StorageDehydrateContext): StorageDehydrateResult;
+    hydrate(ctx: StorageHydrateContext): StorageHydrateResult;
+};
+export type StorageIdentityRuntime = {
+    resolve(ctx: ResolveIdentityContext): RuntimeIdentity | undefined;
+};
+export type StorageReactionRuntime = {
+    run(ctx: StorageReactionContext): void;
+};
+export type StorageRuntime = (TemplateStorageRuntime | BucketStorageRuntime) & {
+    readonly effects?: StorageEffectsRuntime;
+    readonly snapshot?: StorageSnapshotRuntime;
+    readonly identity?: StorageIdentityRuntime;
+    readonly reactions?: StorageReactionRuntime;
+};
+export type StorageRegistry = {
+    register(kind: string, runtime: StorageRuntime, owner: string): void;
+    get(kind: string): StorageRuntime | undefined;
+};
+export type RuntimeStorageEntry = {
+    readonly kind: string;
+    readonly runtime: StorageRuntime;
+};
+export declare const compileStorageTemplates: (machines: MachineStore, machineKeys: readonly string[], storage: StorageRegistry, defaultStorageKind: string) => CompiledStorageTemplate[];

package/dist/runtime/kernel/transitionGuard.d.cts

@@ -0,0 +1,4 @@
+import type { DispatchHookPhase } from "../../pluginTypes";
+export type TransitionGuardPhase = "storage.prepareAction" | "storage.beforeReduce" | "storage.acceptsEvent" | "storage.reduce" | "storage.reduceBucket" | "storage.commit" | "storage.reactions" | "plugin.intercept" | `hook.${DispatchHookPhase}`;
+export type GuardedCallbackRunner = <Result>(phase: TransitionGuardPhase, run: () => Result) => Result;
+export declare const throwTransitionGuardError: (phase: TransitionGuardPhase) => never;

package/dist/runtime/kernel/transitionGuard.d.ts

@@ -0,0 +1,4 @@
+import type { DispatchHookPhase } from "../../pluginTypes";
+export type TransitionGuardPhase = "storage.prepareAction" | "storage.beforeReduce" | "storage.acceptsEvent" | "storage.reduce" | "storage.reduceBucket" | "storage.commit" | "storage.reactions" | "plugin.intercept" | `hook.${DispatchHookPhase}`;
+export type GuardedCallbackRunner = <Result>(phase: TransitionGuardPhase, run: () => Result) => Result;
+export declare const throwTransitionGuardError: (phase: TransitionGuardPhase) => never;

package/dist/runtime/kernel/transitionTrace.d.cts

@@ -0,0 +1,40 @@
+import type { StorageDispatchContext } from "./storage";
+export declare const TRANSITION_TRACE_COLLECTOR_SYMBOL: unique symbol;
+export declare const TRANSITION_TRACE_RUNTIME_KEY = "@lite-fsm/core/transition-trace";
+export type TransitionTraceStatus = "ok" | "error";
+export type TransitionTracePhaseMetadata = {
+    readonly runtimeKind?: string;
+};
+export type TransitionTracePhaseRecord = {
+    readonly key: string;
+    readonly durationMs: number;
+    readonly runtimeKind?: string;
+};
+export type TransitionTraceCounterRecord = {
+    readonly key: string;
+    readonly value: number;
+};
+export type TransitionTraceRecord = {
+    readonly actionType: string | undefined;
+    readonly depth: number;
+    readonly status: TransitionTraceStatus;
+    readonly phases: readonly TransitionTracePhaseRecord[];
+    readonly counters: readonly TransitionTraceCounterRecord[];
+};
+export type TransitionTraceCollector = {
+    readonly records: TransitionTraceRecord[];
+};
+export type TransitionTraceSession = {
+    readonly depth: number;
+    now(): number;
+    record(key: string, startedAt: number, metadata?: TransitionTracePhaseMetadata): void;
+    count(key: string, value?: number): void;
+    finish(status: TransitionTraceStatus): void;
+};
+export declare const createTransitionTraceSession: (actionType: string | undefined) => TransitionTraceSession | undefined;
+export type TraceSpanRunner = <T>(key: string, run: () => T) => T;
+export declare const createTraceSpanRunner: (session: TransitionTraceSession | undefined) => TraceSpanRunner;
+export type BucketTraceRunner = <T>(phase: string, runtimeKind: string, run: () => T) => T;
+export declare const createBucketTraceRunner: (session: TransitionTraceSession | undefined) => BucketTraceRunner;
+export declare const attachTransitionTraceSession: (dispatch: StorageDispatchContext, session: TransitionTraceSession | undefined) => void;
+export declare const readTransitionTraceSession: (dispatch: StorageDispatchContext) => TransitionTraceSession | undefined;

package/dist/runtime/kernel/transitionTrace.d.ts

@@ -0,0 +1,40 @@
+import type { StorageDispatchContext } from "./storage";
+export declare const TRANSITION_TRACE_COLLECTOR_SYMBOL: unique symbol;
+export declare const TRANSITION_TRACE_RUNTIME_KEY = "@lite-fsm/core/transition-trace";
+export type TransitionTraceStatus = "ok" | "error";
+export type TransitionTracePhaseMetadata = {
+    readonly runtimeKind?: string;
+};
+export type TransitionTracePhaseRecord = {
+    readonly key: string;
+    readonly durationMs: number;
+    readonly runtimeKind?: string;
+};
+export type TransitionTraceCounterRecord = {
+    readonly key: string;
+    readonly value: number;
+};
+export type TransitionTraceRecord = {
+    readonly actionType: string | undefined;
+    readonly depth: number;
+    readonly status: TransitionTraceStatus;
+    readonly phases: readonly TransitionTracePhaseRecord[];
+    readonly counters: readonly TransitionTraceCounterRecord[];
+};
+export type TransitionTraceCollector = {
+    readonly records: TransitionTraceRecord[];
+};
+export type TransitionTraceSession = {
+    readonly depth: number;
+    now(): number;
+    record(key: string, startedAt: number, metadata?: TransitionTracePhaseMetadata): void;
+    count(key: string, value?: number): void;
+    finish(status: TransitionTraceStatus): void;
+};
+export declare const createTransitionTraceSession: (actionType: string | undefined) => TransitionTraceSession | undefined;
+export type TraceSpanRunner = <T>(key: string, run: () => T) => T;
+export declare const createTraceSpanRunner: (session: TransitionTraceSession | undefined) => TraceSpanRunner;
+export type BucketTraceRunner = <T>(phase: string, runtimeKind: string, run: () => T) => T;
+export declare const createBucketTraceRunner: (session: TransitionTraceSession | undefined) => BucketTraceRunner;
+export declare const attachTransitionTraceSession: (dispatch: StorageDispatchContext, session: TransitionTraceSession | undefined) => void;
+export declare const readTransitionTraceSession: (dispatch: StorageDispatchContext) => TransitionTraceSession | undefined;

package/dist/sidecar.d.cts

@@ -15,7 +15,7 @@ export type ReplacementReconcilePlan = {
     nextCounters: Counters;
     canonicalActorRecords: Map<string, ActorRecord>;
     actorsToCleanup: ActorRuntime[];
-    touchedTemplateKeys: string[];
+    touchedTemplateKeys: readonly string[];
 };
 export type SidecarValidationDeps = {
     actorTemplateKeys: readonly string[];
@@ -34,7 +34,7 @@ type IndexBundle = {
 export declare const addActorToGroupIndexes: (indexes: IndexBundle, actor: ActorRuntime) => void;
 export declare const removeActorFromGroupIndexes: (sidecar: SidecarState, actor: ActorRuntime) => void;
 export declare const cleanupDisposedActor: (actor: ActorRuntime) => void;
-export declare const buildReplacementReconcilePlan: (sidecar: SidecarState, deps: SidecarValidationDeps, changedTemplateKeys: string[], nextRoot: RootStateView) => ReplacementReconcilePlan;
+export declare const buildReplacementReconcilePlan: (sidecar: SidecarState, deps: SidecarValidationDeps, changedTemplateKeys: readonly string[], nextRoot: RootStateView) => ReplacementReconcilePlan;
 export declare const canonicalizeEmptyActorRecords: <S extends RootStateView>(state: S, templateKeys: Iterable<string>) => S;
 export declare const commitDispatchSidecar: <S extends RootStateView>(sidecar: SidecarState, ctx: DispatchContext, nextState: S) => S;
 export declare const commitReplacementSidecar: <S extends RootStateView>(sidecar: SidecarState, plan: ReplacementReconcilePlan, nextState: S) => S;

package/dist/sidecar.d.ts

@@ -15,7 +15,7 @@ export type ReplacementReconcilePlan = {
     nextCounters: Counters;
     canonicalActorRecords: Map<string, ActorRecord>;
     actorsToCleanup: ActorRuntime[];
-    touchedTemplateKeys: string[];
+    touchedTemplateKeys: readonly string[];
 };
 export type SidecarValidationDeps = {
     actorTemplateKeys: readonly string[];
@@ -34,7 +34,7 @@ type IndexBundle = {
 export declare const addActorToGroupIndexes: (indexes: IndexBundle, actor: ActorRuntime) => void;
 export declare const removeActorFromGroupIndexes: (sidecar: SidecarState, actor: ActorRuntime) => void;
 export declare const cleanupDisposedActor: (actor: ActorRuntime) => void;
-export declare const buildReplacementReconcilePlan: (sidecar: SidecarState, deps: SidecarValidationDeps, changedTemplateKeys: string[], nextRoot: RootStateView) => ReplacementReconcilePlan;
+export declare const buildReplacementReconcilePlan: (sidecar: SidecarState, deps: SidecarValidationDeps, changedTemplateKeys: readonly string[], nextRoot: RootStateView) => ReplacementReconcilePlan;
 export declare const canonicalizeEmptyActorRecords: <S extends RootStateView>(state: S, templateKeys: Iterable<string>) => S;
 export declare const commitDispatchSidecar: <S extends RootStateView>(sidecar: SidecarState, ctx: DispatchContext, nextState: S) => S;
 export declare const commitReplacementSidecar: <S extends RootStateView>(sidecar: SidecarState, plan: ReplacementReconcilePlan, nextState: S) => S;