Add transition snapshots and structural metadata (#25)

Author: SandroMaglione

.changeset/rich-machines-inspect.md

@@ -0,0 +1,5 @@
+---
+"@typeonce/effect-machine": minor
+---
+
+Expose a captured full machine snapshot to event, eventless, and completion transition contexts; add serializable state-owned activity inspection for invokes, timers, and child machines; and surface resolved Effect Schema annotations plus descriptive pseudo-state annotations through state-node inspection.

README.md

@@ -379,6 +379,39 @@ Refresh: {
 keyed by full dotted paths, such as `parents["Form.Editing"]`; `context.parent`
 provides the immediate parent directly and is `undefined` at a root state.
 
+Event, eventless, and completion transition contexts also expose `snapshot`, a
+read-only view of the complete logical configuration captured at the beginning
+of that transition microstep. This lets one parallel region inspect a sibling
+without copying active-state facts into parent values:
+
+```ts
+BufferReady: ;
+;(({ snapshot, target }) =>
+  States.matches(snapshot, "Player.Network.Online")
+    ? target.local.Playing(State.cases.Playing.make({}))
+    : undefined)
+```
+
+All non-conflicting handlers selected together observe the same captured
+snapshot. An Effectful handler keeps that value; it does not read mutable live
+runtime state later. `snapshot` is intentionally absent from entry, exit,
+invoke, and choice contexts. In particular, startup and chained choices may run
+before a complete stable snapshot containing their pseudo-source exists.
+
+Effect Schema annotations are the metadata source for active states. Annotate
+the schema itself; `Machine.stateNodes` exposes the resolved annotation map:
+
+```ts
+const Saving = State.cases.Saving.annotate({
+  title: "Saving document",
+  description: "Persisting local changes to the server"
+})
+```
+
+Schema-less choice and history nodes accept only descriptive `title`,
+`description`, and `documentation` annotations. Titles may be used as display
+labels, but structural paths remain the only identity and targeting mechanism.
+
 ## Planning Effects and staged actions
 
 An Effect returned by a transition handler is part of planning. Use it to read
@@ -472,6 +505,14 @@ Descriptors are matched by id and machine identity, so independently created
 descriptors for the same pair address the same child without a global cache.
 Exporting one descriptor remains the clearest module boundary.
 
+`Machine.activityDefinitions(machine)` inspects state-owned work without
+executing it. Static descriptors report their source path, lifecycle id, and
+kind. Timers also report normalized duration and emitted event tag;
+`invokeEffect` mappings are described as dynamic; invoked machines expose only
+safe child identity. A function-valued `invoke` factory is reported as dynamic
+and is never evaluated during inspection. The result is serializable and does
+not contain Effects, closures, services, or child runtimes.
+
 ## Reactivity
 
 `AtomMachine.make` creates a lazy bridge backed by one running machine per

docs/agent-guide.md

@@ -347,6 +347,47 @@ parents["Route.Ready.Editing"]
 
 Do not guess short properties such as `parents.Ready`.
 
+### Inspecting the full transition configuration
+
+Event, `always`, and `onDone` transition contexts include a fully typed
+`snapshot`. It is the complete logical snapshot at the beginning of that
+microstep, before any selected transition is applied:
+
+```ts
+BufferReady: ({ snapshot, target }) =>
+  States.matches(snapshot, "Player.Network.Online")
+    ? target.local.Playing(new Playing({}))
+    : undefined
+```
+
+Use the existing `States.matches`, `States.get`, `States.getWithParents`, and
+`States.getSnapshot` helpers for cross-region reads. Parallel transitions
+selected in one microstep receive the same capture. Effectful handlers retain
+that captured value rather than consulting live runtime state.
+
+Do not expect `snapshot` in entry, exit, invoke, initializer, history-default,
+or choice contexts. Choice is an important soundness boundary: a startup or
+chained choice can run without a complete stable configuration containing the
+pseudo-source, so the API does not fabricate a partial `Machine.Snapshot`.
+
+### State annotations
+
+Attach active-state metadata through Effect Schema:
+
+```ts
+const Saving = State.cases.Saving.annotate({
+  title: "Saving document",
+  description: "Persisting local changes to the server",
+  documentation: "https://docs.example.test/saving"
+})
+```
+
+`Machine.stateNodes(machine)` returns the resolved annotation map. Choice and
+history definitions may declare an `annotations` object containing only
+`title`, `description`, and `documentation`. These values are descriptive;
+they cannot change behavior, identity, or targeting. Visualization may show a
+title, while the structural path remains authoritative.
+
 Use `Machine.retag(TargetCase, source, patch?)` when sibling state payloads
 share fields. It removes the source discriminator, reuses only compatible
 fields, and requires a patch for every missing or incompatible required field.
@@ -508,6 +549,25 @@ Use the separate
 `Machine.childAddress<Event>(id)` constructor only for lower-level process
 logic that does not have a complete machine descriptor.
 
+### Inspecting state-owned activities
+
+Use `Machine.activityDefinitions(machine)` to inspect invokes without running
+them. Static `Machine.invoke`, `Machine.invokeEffect`, `Machine.after`, and
+`Machine.invokeMachine` descriptors expose serializable ownership metadata:
+
+```ts
+Machine.activityDefinitions(machine)
+// [{ source: "Loading", id: "load-timeout", type: "timer",
+//    duration: "10s", event: "LoadTimedOut" }]
+```
+
+Effect success/failure mappers are closures and therefore appear as dynamic
+outcomes. Child machines expose descriptor identity, never their runtime or
+implementation. A function-valued `invoke` factory is represented as a dynamic
+activity because inspection must not evaluate user code. The existing invoke
+helpers remain the only execution API; this metadata does not add lifecycle
+configuration syntax or affect execution.
+
 ## AtomMachine and React
 
 `AtomMachine.make(machine, ...input)` works when the machine has no external

src/Machine.ts

@@ -5,7 +5,7 @@
  */
 
 import type * as Cause from "effect/Cause"
-import type * as Duration from "effect/Duration"
+import * as Duration from "effect/Duration"
 import * as Effect from "effect/Effect"
 import * as Inspectable from "effect/Inspectable"
 import * as Option from "effect/Option"
@@ -15,6 +15,7 @@ import type * as Schema from "effect/Schema"
 import type * as Scope from "effect/Scope"
 import type * as Stream from "effect/Stream"
 import type * as Types from "effect/Types"
+import * as Activities from "./internal/machineActivities.js"
 import type {
   ChildAlreadyExistsError,
   InfiniteTransitionError,
@@ -1868,6 +1869,28 @@ export declare namespace Machine {
    */
   export type TaggedSchema = Schema.Top & { readonly Type: { readonly _tag: PropertyKey } }
 
+  /**
+   * Descriptive annotations exposed for compiled state nodes.
+   *
+   * Schema-backed states resolve their complete Effect Schema annotation map.
+   * Pseudo-states accept only the descriptive fields below. Annotations never
+   * affect state identity, targeting, or runtime behavior.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface StateNodeAnnotations extends Schema.Annotations.Annotations {
+    readonly title?: string | undefined
+    readonly description?: string | undefined
+    readonly documentation?: string | undefined
+  }
+
+  /** Descriptive annotations accepted by schema-less pseudo-states. */
+  export type PseudoStateAnnotations = Pick<
+    StateNodeAnnotations,
+    "title" | "description" | "documentation"
+  >
+
   /**
    * Configuration accepted for an atomic object state node.
    *
@@ -1928,6 +1951,7 @@ export declare namespace Machine {
     readonly type: "history"
     /** Defaults to shallow history. */
     readonly history?: "shallow" | "deep"
+    readonly annotations?: PseudoStateAnnotations
   }
 
   /**
@@ -1942,6 +1966,7 @@ export declare namespace Machine {
    */
   export interface ChoiceStateNodeConfig {
     readonly type: "choice"
+    readonly annotations?: PseudoStateAnnotations
   }
 
   /**
@@ -2075,10 +2100,12 @@ export declare namespace Machine {
     readonly key: string
     readonly schema: TaggedSchema | undefined
     readonly output: Schema.Top | undefined
+    /** Resolved Effect Schema annotations, or descriptive pseudo-state annotations. */
+    readonly annotations: Readonly<StateNodeAnnotations> | undefined
     readonly type: "atomic" | "compound" | "parallel" | "final" | "history" | "choice"
     readonly history: "shallow" | "deep" | undefined
     readonly parent: Path | undefined
-    /** Active child paths. History pseudo-states are available through their `parent` relationship. */
+    /** Active child paths. Pseudo-states are available through their `parent` relationship. */
     readonly children: ReadonlyArray<Path>
     readonly initial: Path | undefined
     readonly order: number
@@ -2156,6 +2183,18 @@ export declare namespace Machine {
     readonly targets: TransitionTargets<TargetPath>
   }
 
+  /**
+   * Serializable description of state-owned work.
+   *
+   * Static invoke descriptors expose their lifecycle id and kind without
+   * retaining Effects, closures, services, or child runtimes. A function-valued
+   * invoke factory is reported as dynamic and is never evaluated by inspection.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export type ActivityDefinition<SourcePath extends string = string> = Activities.ActivityDefinition<SourcePath>
+
   /**
    * Transition retained after hierarchy precedence and conflict resolution for
    * one planned microstep.
@@ -3174,6 +3213,8 @@ export declare namespace Machine {
     readonly state: StateByIdentifier<States, StateId>
     readonly parent: ParentStateValue<States, StateId>
     readonly parents: ParentStateValues<States, StateId>
+    /** Complete logical configuration captured at the start of this microstep. */
+    readonly snapshot: Snapshot<States>
     readonly event: EventByTag<Events, EventTag>
     readonly runtime: RuntimeEffect<Events, Emits>
 
@@ -3261,6 +3302,8 @@ export declare namespace Machine {
     readonly state: StateByIdentifier<States, StateId>
     readonly parent: ParentStateValue<States, StateId>
     readonly parents: ParentStateValues<States, StateId>
+    /** Complete logical configuration captured at the start of this microstep. */
+    readonly snapshot: Snapshot<States>
     readonly event: LifecycleEvent<Events>
     readonly runtime: RuntimeEffect<Events, Emits>
 
@@ -3289,6 +3332,8 @@ export declare namespace Machine {
     readonly state: StateByIdentifier<States, StateId>
     readonly parent: ParentStateValue<States, StateId>
     readonly parents: ParentStateValues<States, StateId>
+    /** Complete logical configuration captured at the start of this microstep. */
+    readonly snapshot: Snapshot<States>
     readonly event: LifecycleEvent<Events>
     readonly output: CompletionOutputByIdentifier<States, StateId>
     readonly runtime: RuntimeEffect<Events, Emits>
@@ -3725,6 +3770,8 @@ export declare namespace Machine {
       readonly requirements: Types.Covariant<ChildRequirements>
       readonly initialError: Types.Covariant<ChildInitialError>
     }
+    /** @internal Serializable descriptor metadata used by inspection. */
+    readonly [Activities.ActivityMetadataTypeId]?: Activities.StaticActivityMetadata
     readonly id: string
     /**
      * Optional parent-local address for sending events to this invocation.
@@ -5948,7 +5995,11 @@ export const invoke = <
   ChildRequirements,
   ChildOutput,
   ChildInitialError
-> => ({ ...config, [InvokeTypeId]: undefined as any })
+> => ({
+  ...config,
+  [InvokeTypeId]: undefined as any,
+  [Activities.ActivityMetadataTypeId]: { type: "process" }
+})
 
 type InvokeEffectResult<Requirements, Event> = Machine.InvokeConfig<
   any,
@@ -6020,8 +6071,8 @@ export const invokeEffect = <
     readonly effect: Effect.Effect<unknown, unknown, unknown>
     readonly onSuccess: (value: unknown) => unknown
     readonly onFailure?: (error: unknown) => unknown
-  }) =>
-    invoke({
+  }) => ({
+    ...invoke({
       id: config.id,
       src: () =>
         effect(
@@ -6032,7 +6083,15 @@ export const invokeEffect = <
               onSuccess: (value) => Effect.succeed(config.onSuccess(value))
             })
         )
-    }))(config as any) as any
+    }),
+    [Activities.ActivityMetadataTypeId]: {
+      type: "effect",
+      outcomes: {
+        success: "dynamic",
+        failure: config.onFailure === undefined ? "none" : "dynamic"
+      }
+    }
+  }))(config as any) as any
 
 /**
  * Creates a cancellable state-scoped delayed event.
@@ -6048,11 +6107,17 @@ export const after = <Event extends { readonly _tag: PropertyKey }>(
   duration: Duration.Input,
   event: Event,
   options?: { readonly id?: InvokeLifecycleId }
-): InvokeEffectResult<never, Event> =>
-  invoke({
+): InvokeEffectResult<never, Event> => ({
+  ...invoke({
     id: options?.id ?? `Machine.after:${String(event._tag)}`,
     src: () => effect(Effect.as(Effect.sleep(duration), event))
-  })
+  }),
+  [Activities.ActivityMetadataTypeId]: {
+    type: "timer",
+    duration: Duration.format(Duration.fromInputUnsafe(duration)),
+    event: String(event._tag)
+  }
+})
 
 type RetagFields<Target extends Machine.TaggedSchema> = Omit<Target["~type.make.in"], "_tag">
 
@@ -6317,6 +6382,13 @@ export const invokeMachine: {
         : (internalProcess.toProcessLogic as any)(machine, config.input),
     snapshot: config.snapshot,
     onDone: config.onDone,
+    [Activities.ActivityMetadataTypeId]: {
+      type: "machine",
+      child: {
+        id: config.child.id,
+        machineId: machine.id ?? null
+      }
+    },
     [InvokeTypeId]: undefined as any
   }
 }) as any
@@ -6426,10 +6498,11 @@ export const planInitial: <
  *
  * **Details**
  *
- * The result includes atomic, compound, parallel, final, and history nodes.
- * Use each node's `parent` property to reconstruct the complete hierarchy.
- * History pseudo-states are intentionally omitted from `children` because they
- * can never appear in an active configuration.
+ * The result includes atomic, compound, parallel, final, history, and choice
+ * nodes together with their resolved descriptive annotations. Use each node's
+ * `parent` property to reconstruct the complete hierarchy. Pseudo-states are
+ * intentionally omitted from `children` because they can never appear in an
+ * active configuration.
  *
  * @category getters
  * @since 4.0.0
@@ -6472,14 +6545,34 @@ export const transitionDefinitions = <M extends Machine.Any>(
     >
   >
 
+/**
+ * Returns serializable descriptions of every state-owned activity.
+ *
+ * **Details**
+ *
+ * Static `invoke`, `invokeEffect`, `after`, and `invokeMachine` descriptors
+ * expose stable ownership and lifecycle metadata without serializing runtime
+ * values. Function-valued invoke factories are represented as dynamic and are
+ * never evaluated during inspection.
+ *
+ * @category getters
+ * @since 4.0.0
+ */
+export const activityDefinitions = <M extends Machine.Any>(
+  machine: M
+): ReadonlyArray<Machine.ActivityDefinition<Machine.StateIdentifier<Machine.States<M>>>> =>
+  Activities.activityDefinitions(machine) as ReadonlyArray<
+    Machine.ActivityDefinition<Machine.StateIdentifier<Machine.States<M>>>
+  >
+
 /**
  * Returns every state node active in a decoded snapshot, in definition order.
  *
  * **Details**
  *
  * Active compound ancestors and parallel regions are included together with
- * their active descendants. History pseudo-states are never active and are not
- * returned.
+ * their active descendants. History and choice pseudo-states are never active
+ * and are not returned.
  *
  * @category getters
  * @since 4.0.0