@typeonce/effect-machine 0.6.1 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/README.md +25 -3
  2. package/dist/Machine.d.ts +181 -144
  3. package/dist/Machine.d.ts.map +1 -1
  4. package/dist/Machine.js +3 -1
  5. package/dist/Machine.js.map +1 -1
  6. package/dist/internal/machine/atom.d.ts +13 -2
  7. package/dist/internal/machine/atom.d.ts.map +1 -1
  8. package/dist/internal/machine/atom.js +6 -3
  9. package/dist/internal/machine/atom.js.map +1 -1
  10. package/dist/internal/machine/configuration.d.ts.map +1 -1
  11. package/dist/internal/machine/configuration.js +103 -20
  12. package/dist/internal/machine/configuration.js.map +1 -1
  13. package/dist/internal/machine/executionPlan.d.ts.map +1 -1
  14. package/dist/internal/machine/executionPlan.js +6 -0
  15. package/dist/internal/machine/executionPlan.js.map +1 -1
  16. package/dist/internal/machine/invocation.js +1 -1
  17. package/dist/internal/machine/invocation.js.map +1 -1
  18. package/dist/internal/machine/machine.d.ts.map +1 -1
  19. package/dist/internal/machine/machine.js +23 -17
  20. package/dist/internal/machine/machine.js.map +1 -1
  21. package/dist/internal/machine/planner.d.ts +10 -0
  22. package/dist/internal/machine/planner.d.ts.map +1 -1
  23. package/dist/internal/machine/planner.js +45 -35
  24. package/dist/internal/machine/planner.js.map +1 -1
  25. package/dist/internal/machine/serialization.d.ts.map +1 -1
  26. package/dist/internal/machine/serialization.js +53 -21
  27. package/dist/internal/machine/serialization.js.map +1 -1
  28. package/dist/internal/machine/stateDefinition.d.ts +4 -4
  29. package/dist/internal/machine/stateDefinition.d.ts.map +1 -1
  30. package/dist/internal/machine/stateDefinition.js +18 -11
  31. package/dist/internal/machine/stateDefinition.js.map +1 -1
  32. package/dist/internal/machine/topology.d.ts +5 -5
  33. package/dist/internal/machine/topology.d.ts.map +1 -1
  34. package/dist/internal/machine/topology.js +16 -13
  35. package/dist/internal/machine/topology.js.map +1 -1
  36. package/dist/internal/testing/machine/verification.d.ts.map +1 -1
  37. package/dist/internal/testing/machine/verification.js +10 -3
  38. package/dist/internal/testing/machine/verification.js.map +1 -1
  39. package/dist/unstable/reactivity/AtomMachine.d.ts +34 -2
  40. package/dist/unstable/reactivity/AtomMachine.d.ts.map +1 -1
  41. package/dist/unstable/reactivity/AtomMachine.js +23 -0
  42. package/dist/unstable/reactivity/AtomMachine.js.map +1 -1
  43. package/docs/agent-guide.md +70 -28
  44. package/package.json +2 -2
  45. package/src/Machine.ts +420 -309
  46. package/src/internal/machine/atom.ts +61 -6
  47. package/src/internal/machine/configuration.ts +102 -23
  48. package/src/internal/machine/executionPlan.ts +6 -0
  49. package/src/internal/machine/invocation.ts +1 -1
  50. package/src/internal/machine/machine.ts +93 -62
  51. package/src/internal/machine/planner.ts +49 -38
  52. package/src/internal/machine/serialization.ts +56 -31
  53. package/src/internal/machine/stateDefinition.ts +22 -11
  54. package/src/internal/machine/topology.ts +21 -18
  55. package/src/internal/testing/machine/verification.ts +13 -3
  56. package/src/unstable/reactivity/AtomMachine.ts +56 -2
package/src/Machine.ts CHANGED
@@ -558,7 +558,7 @@ type ValidateStateNode<Node, AllowHistory extends boolean, Path extends Property
558
558
  & ValidatePseudoStateAnnotations<Node, Path>
559
559
  & (AllowHistory extends true ? ValidateChoiceStateNode<Node>
560
560
  : StateDefinitionError<"Choice states must be declared below an active parent state", Path>)
561
- : Node extends { readonly schema: Machine.TaggedSchema } ? ValidateStateNodeConfig<Node, Path>
561
+ : Node extends Machine.StateNodeConfig ? ValidateStateNodeConfig<Node, Path>
562
562
  : StateDefinitionError<"State nodes must be tagged schemas or state node configs", Path>
563
563
 
564
564
  type ValidateHistoryStateNode<Node extends Machine.HistoryStateNodeConfig> = [
@@ -572,27 +572,31 @@ type ValidateChoiceStateNode<Node extends Machine.ChoiceStateNodeConfig> = [
572
572
  : StateDefinitionError<"Choice states cannot declare schemas, children, initial states, output, or history">
573
573
 
574
574
  type ValidateStateNodeConfig<
575
- Node extends { readonly schema: Machine.TaggedSchema },
575
+ Node extends Machine.StateNodeConfig,
576
576
  Path extends PropertyKey
577
577
  > = Node extends { readonly type: "parallel" } ?
578
578
  & ValidateExactStateNodeProperties<Node, "parallel", Path>
579
579
  & ValidateStateNodeWithChildren<Node, Node extends { readonly states: infer Children } ? Children : never, Path>
580
+ & ValidatePseudoStateAnnotations<Node, Path>
580
581
  : Node extends { readonly type: "final" } ?
581
582
  & ValidateExactStateNodeProperties<Node, "final", Path>
582
583
  & ValidateStateNodeWithoutChildren<Node>
584
+ & ValidatePseudoStateAnnotations<Node, Path>
583
585
  : Node extends { readonly states: infer Children } ?
584
586
  & ValidateExactStateNodeProperties<Node, "compound", Path>
585
587
  & ValidateStateNodeWithChildren<Node, Children, Path>
588
+ & ValidatePseudoStateAnnotations<Node, Path>
586
589
  :
587
590
  & ValidateExactStateNodeProperties<Node, "atomic", Path>
588
591
  & ValidateStateNodeWithoutChildren<Node>
592
+ & ValidatePseudoStateAnnotations<Node, Path>
589
593
 
590
594
  type ValidateOutputSchema<Node> = "output" extends keyof Node ? Node extends { readonly output: Schema.Top } ? unknown
591
595
  : StateDefinitionError<"State output must be a schema">
592
596
  : unknown
593
597
 
594
598
  type ValidateStateNodeWithChildren<
595
- Node extends { readonly schema: Machine.TaggedSchema },
599
+ Node extends Machine.StateNodeConfig,
596
600
  Children,
597
601
  Path extends PropertyKey
598
602
  > = Children extends Machine.StateSchemas ?
@@ -605,7 +609,7 @@ type ValidateStateNodeWithChildren<
605
609
  : StateDefinitionError<"Child states must be a state tree">
606
610
 
607
611
  type ValidateCompoundStateNode<
608
- Node extends { readonly schema: Machine.TaggedSchema },
612
+ Node extends Machine.StateNodeConfig,
609
613
  Children extends Machine.StateSchemas,
610
614
  Path extends PropertyKey
611
615
  > = Node extends { readonly initial: infer Initial } ?
@@ -615,8 +619,8 @@ type ValidateCompoundStateNode<
615
619
  : StateDefinitionError<"Compound initial must be one of its direct child keys">
616
620
  : StateDefinitionError<"Compound states must declare an initial child">
617
621
 
618
- type ValidateStateNodeWithoutChildren<Node extends { readonly schema: Machine.TaggedSchema }> = "initial" extends
619
- keyof Node ? StateDefinitionError<"Atomic states cannot declare an initial child">
622
+ type ValidateStateNodeWithoutChildren<Node extends Machine.StateNodeConfig> = "initial" extends keyof Node ?
623
+ StateDefinitionError<"Atomic states cannot declare an initial child">
620
624
  : Node extends { readonly type: infer Type } ? Type extends "final" ? ValidateOutputSchema<Node>
621
625
  : Type extends "active" | undefined ?
622
626
  "output" extends keyof Node ? StateDefinitionError<"Only final and parallel states can declare output">
@@ -722,6 +726,56 @@ type ConstructionResult<Result> = Result | Machine.StateConstruction<Result>
722
726
 
723
727
  type UnwrapConstruction<Result> = Result extends Machine.StateConstruction<infer Value> ? Value : Result
724
728
 
729
+ type NodeValue<Node> = [Machine.NodeSchema<Node>] extends [never] ? undefined
730
+ : Machine.NodeSchema<Node>["Type"]
731
+
732
+ type NodeMakeInput<Node> = [Machine.NodeSchema<Node>] extends [never] ? never
733
+ : Machine.NodeSchema<Node>["~type.make.in"]
734
+
735
+ type WithNodeValue<Node, Rest extends ReadonlyArray<unknown>> = Machine.NodeSchema<Node> extends never ? Rest
736
+ : readonly [value: NodeValue<Node>, ...Rest]
737
+
738
+ type WithNodeInput<Node, Rest extends ReadonlyArray<unknown>> = Machine.NodeSchema<Node> extends never ? Rest
739
+ : readonly [input: NodeMakeInput<Node>, ...Rest]
740
+
741
+ type NodeBuilderMethod<
742
+ Node,
743
+ Arguments extends ReadonlyArray<unknown>,
744
+ Result,
745
+ FromArguments extends ReadonlyArray<unknown>,
746
+ FromResult
747
+ > = Machine.NodeSchema<Node> extends never ? {
748
+ readonly from: FromCallable<FromArguments, FromResult>
749
+ }
750
+ :
751
+ & ((...args: Arguments) => Result)
752
+ & { readonly from: FromCallable<FromArguments, FromResult> }
753
+
754
+ type NodeMethod<
755
+ Node,
756
+ Arguments extends ReadonlyArray<unknown>,
757
+ Result,
758
+ FromArguments extends ReadonlyArray<unknown>
759
+ > = Machine.NodeSchema<Node> extends never ? FromMethod<FromArguments, Result>
760
+ : ((...args: Arguments) => Result) & FromMethod<FromArguments, Result>
761
+
762
+ type NodeConstructionSelectorFromCallable<Node, Builder, Result> = Machine.NodeSchema<Node> extends never ? {
763
+ <Selected extends ConstructionResult<Result>>(
764
+ state: (builder: Builder) => Selected
765
+ ): Machine.StateConstruction<UnwrapConstruction<Selected>>
766
+ }
767
+ : ConstructionSelectorFromCallable<NodeMakeInput<Node>, Builder, Result>
768
+
769
+ type NestedTargetMethod<Node, Builder, Result> = Machine.NodeSchema<Node> extends never ? {
770
+ readonly from: NodeConstructionSelectorFromCallable<Node, Builder, Result>
771
+ }
772
+ :
773
+ & (<Selected extends ConstructionResult<Result>>(
774
+ value: NodeValue<Node>,
775
+ state: (builder: Builder) => Selected
776
+ ) => Selected)
777
+ & { readonly from: NodeConstructionSelectorFromCallable<Node, Builder, Result> }
778
+
725
779
  type ConstructionSelectorFromCallable<Input, Builder, Result> = {} extends Input ? {
726
780
  <Selected extends ConstructionResult<Result>>(
727
781
  state: (builder: Builder) => Selected
@@ -751,14 +805,18 @@ type InitialSnapshotMethod<
751
805
  States extends Machine.StateSchemas,
752
806
  StateId extends ActiveStateKey<States>,
753
807
  Prefix extends string
754
- > =
755
- & ((
756
- ...args: InitialSnapshotArguments<States, StateId, Prefix>
757
- ) => InitialSnapshotResult<States, StateId, Prefix>)
758
- & FromMethod<
808
+ > = Machine.NodeSchema<States[StateId]> extends never ? FromMethod<
759
809
  InitialSnapshotFromArguments<States, StateId, Prefix>,
760
810
  InitialSnapshotResult<States, StateId, Prefix>
761
811
  >
812
+ :
813
+ & ((
814
+ ...args: InitialSnapshotArguments<States, StateId, Prefix>
815
+ ) => InitialSnapshotResult<States, StateId, Prefix>)
816
+ & FromMethod<
817
+ InitialSnapshotFromArguments<States, StateId, Prefix>,
818
+ InitialSnapshotResult<States, StateId, Prefix>
819
+ >
762
820
 
763
821
  type InitialSnapshotArguments<
764
822
  States extends Machine.StateSchemas,
@@ -766,21 +824,21 @@ type InitialSnapshotArguments<
766
824
  Prefix extends string,
767
825
  Path extends string = Machine.JoinPath<Prefix, StateId>
768
826
  > = States[StateId] extends infer Node ?
769
- Node extends { readonly type: "parallel"; readonly states: infer Children extends Machine.StateSchemas } ? [
770
- value: Machine.NodeSchema<Node>["Type"],
827
+ Node extends { readonly type: "parallel"; readonly states: infer Children extends Machine.StateSchemas } ?
828
+ WithNodeValue<Node, [
771
829
  states: (
772
830
  builder: InitialParallelBuilder<Children, Path>
773
831
  ) => SnapshotBuilderComplete<InitialSnapshotRegionsWithPrefix<Children, Path>>
774
- ]
832
+ ]>
775
833
  : Node extends { readonly states: infer Children extends Machine.StateSchemas } ?
776
- Node extends { readonly initial: infer Initial extends ActiveStateKey<Children> | ChoiceStateKey<Children> } ? [
777
- value: Machine.NodeSchema<Node>["Type"],
834
+ Node extends { readonly initial: infer Initial extends ActiveStateKey<Children> | ChoiceStateKey<Children> } ?
835
+ WithNodeValue<Node, [
778
836
  state: (
779
837
  builder: Pick<InitialSnapshotBuilderWithPrefix<Children, Path>, Initial>
780
838
  ) => InitialSelectableResult<Children, Initial, Path>
781
- ]
839
+ ]>
782
840
  : never
783
- : [value: Machine.NodeSchema<Node>["Type"]]
841
+ : WithNodeValue<Node, []>
784
842
  : never
785
843
 
786
844
  type InitialSnapshotFromArguments<
@@ -789,21 +847,21 @@ type InitialSnapshotFromArguments<
789
847
  Prefix extends string,
790
848
  Path extends string = Machine.JoinPath<Prefix, StateId>
791
849
  > = States[StateId] extends infer Node ?
792
- Node extends { readonly type: "parallel"; readonly states: infer Children extends Machine.StateSchemas } ? [
793
- input: Machine.NodeSchema<Node>["~type.make.in"],
850
+ Node extends { readonly type: "parallel"; readonly states: infer Children extends Machine.StateSchemas } ?
851
+ WithNodeInput<Node, [
794
852
  states: (
795
853
  builder: InitialParallelBuilder<Children, Path>
796
854
  ) => SnapshotBuilderComplete<InitialSnapshotRegionsWithPrefix<Children, Path>, boolean>
797
- ]
855
+ ]>
798
856
  : Node extends { readonly states: infer Children extends Machine.StateSchemas } ?
799
- Node extends { readonly initial: infer Initial extends ActiveStateKey<Children> | ChoiceStateKey<Children> } ? [
800
- input: Machine.NodeSchema<Node>["~type.make.in"],
857
+ Node extends { readonly initial: infer Initial extends ActiveStateKey<Children> | ChoiceStateKey<Children> } ?
858
+ WithNodeInput<Node, [
801
859
  state: (
802
860
  builder: Pick<InitialSnapshotBuilderWithPrefix<Children, Path>, Initial>
803
861
  ) => ConstructionResult<InitialSelectableResult<Children, Initial, Path>>
804
- ]
862
+ ]>
805
863
  : never
806
- : [input: Machine.NodeSchema<Node>["~type.make.in"]]
864
+ : WithNodeInput<Node, []>
807
865
  : never
808
866
 
809
867
  type InitialSnapshotResult<
@@ -815,18 +873,18 @@ type InitialSnapshotResult<
815
873
  Node extends { readonly type: "parallel"; readonly states: infer Children extends Machine.StateSchemas } ?
816
874
  Machine.ParallelSnapshot<
817
875
  Path,
818
- Machine.NodeSchema<Node>["Type"],
876
+ NodeValue<Node>,
819
877
  InitialSnapshotRegionsWithPrefix<Children, Path>
820
878
  >
821
879
  : Node extends { readonly states: infer Children extends Machine.StateSchemas } ?
822
880
  Node extends { readonly initial: infer Initial extends ActiveStateKey<Children> | ChoiceStateKey<Children> } ?
823
881
  Machine.CompoundSnapshot<
824
882
  Path,
825
- Machine.NodeSchema<Node>["Type"],
883
+ NodeValue<Node>,
826
884
  InitialSelectableResult<Children, Initial, Path>
827
885
  >
828
886
  : never
829
- : Machine.AtomicSnapshot<Path, Machine.NodeSchema<Node>["Type"]>
887
+ : Machine.AtomicSnapshot<Path, NodeValue<Node>>
830
888
  : never
831
889
 
832
890
  type InitialSelectableResult<
@@ -853,28 +911,25 @@ type InitialParallelBuilder<
853
911
  > =
854
912
  & SnapshotBuilderComplete<Regions, Constructed>
855
913
  & {
856
- readonly [Key in Remaining]:
857
- & ((
858
- ...args: InitialSnapshotArguments<States, Key, Prefix>
859
- ) => InitialParallelBuilder<
914
+ readonly [Key in Remaining]: NodeBuilderMethod<
915
+ States[Key],
916
+ InitialSnapshotArguments<States, Key, Prefix>,
917
+ InitialParallelBuilder<
860
918
  States,
861
919
  Prefix,
862
920
  Exclude<Remaining, Key>,
863
921
  Regions & { readonly [Region in Key]: InitialSnapshotResult<States, Key, Prefix> },
864
922
  Constructed
865
- >)
866
- & {
867
- readonly from: FromCallable<
868
- InitialSnapshotFromArguments<States, Key, Prefix>,
869
- InitialParallelBuilder<
870
- States,
871
- Prefix,
872
- Exclude<Remaining, Key>,
873
- Regions & { readonly [Region in Key]: InitialSnapshotResult<States, Key, Prefix> },
874
- true
875
- >
876
- >
877
- }
923
+ >,
924
+ InitialSnapshotFromArguments<States, Key, Prefix>,
925
+ InitialParallelBuilder<
926
+ States,
927
+ Prefix,
928
+ Exclude<Remaining, Key>,
929
+ Regions & { readonly [Region in Key]: InitialSnapshotResult<States, Key, Prefix> },
930
+ true
931
+ >
932
+ >
878
933
  }
879
934
 
880
935
  type FullSnapshotBuilderWithPrefix<
@@ -892,14 +947,18 @@ type FullSnapshotMethod<
892
947
  States extends Machine.StateSchemas,
893
948
  StateId extends ActiveStateKey<States>,
894
949
  Prefix extends string
895
- > =
896
- & ((
897
- ...args: FullSnapshotArguments<States, StateId, Prefix>
898
- ) => FullSnapshotResult<States, StateId, Prefix>)
899
- & FromMethod<
950
+ > = Machine.NodeSchema<States[StateId]> extends never ? FromMethod<
900
951
  FullSnapshotFromArguments<States, StateId, Prefix>,
901
952
  FullSnapshotResult<States, StateId, Prefix>
902
953
  >
954
+ :
955
+ & ((
956
+ ...args: FullSnapshotArguments<States, StateId, Prefix>
957
+ ) => FullSnapshotResult<States, StateId, Prefix>)
958
+ & FromMethod<
959
+ FullSnapshotFromArguments<States, StateId, Prefix>,
960
+ FullSnapshotResult<States, StateId, Prefix>
961
+ >
903
962
 
904
963
  type FullSnapshotArguments<
905
964
  States extends Machine.StateSchemas,
@@ -907,21 +966,20 @@ type FullSnapshotArguments<
907
966
  Prefix extends string,
908
967
  Path extends string = Machine.JoinPath<Prefix, StateId>
909
968
  > = States[StateId] extends infer Node ?
910
- Node extends { readonly type: "parallel"; readonly states: infer Children extends Machine.StateSchemas } ? [
911
- value: Machine.NodeSchema<Node>["Type"],
969
+ Node extends { readonly type: "parallel"; readonly states: infer Children extends Machine.StateSchemas } ?
970
+ WithNodeValue<Node, [
912
971
  states: (
913
972
  builder: FullParallelBuilder<Children, Path>
914
973
  ) => SnapshotBuilderComplete<Machine.SnapshotRegionsWithPrefix<Children, Path>>
915
- ]
916
- : Node extends { readonly states: infer Children extends Machine.StateSchemas } ? [
917
- value: Machine.NodeSchema<Node>["Type"],
974
+ ]>
975
+ : Node extends { readonly states: infer Children extends Machine.StateSchemas } ? WithNodeValue<Node, [
918
976
  state: (
919
977
  builder: FullSnapshotBuilderWithPrefix<Children, Path>
920
978
  ) =>
921
979
  | Machine.SnapshotWithPrefix<Children, Path>
922
980
  | Machine.ChoiceTargetInstruction<Machine.ChoiceIdentifierWithPrefix<Children, Path>>
923
- ]
924
- : [value: Machine.NodeSchema<Node>["Type"]]
981
+ ]>
982
+ : WithNodeValue<Node, []>
925
983
  : never
926
984
 
927
985
  type FullSnapshotFromArguments<
@@ -930,22 +988,21 @@ type FullSnapshotFromArguments<
930
988
  Prefix extends string,
931
989
  Path extends string = Machine.JoinPath<Prefix, StateId>
932
990
  > = States[StateId] extends infer Node ?
933
- Node extends { readonly type: "parallel"; readonly states: infer Children extends Machine.StateSchemas } ? [
934
- input: Machine.NodeSchema<Node>["~type.make.in"],
991
+ Node extends { readonly type: "parallel"; readonly states: infer Children extends Machine.StateSchemas } ?
992
+ WithNodeInput<Node, [
935
993
  states: (
936
994
  builder: FullParallelBuilder<Children, Path>
937
995
  ) => SnapshotBuilderComplete<Machine.SnapshotRegionsWithPrefix<Children, Path>, boolean>
938
- ]
939
- : Node extends { readonly states: infer Children extends Machine.StateSchemas } ? [
940
- input: Machine.NodeSchema<Node>["~type.make.in"],
996
+ ]>
997
+ : Node extends { readonly states: infer Children extends Machine.StateSchemas } ? WithNodeInput<Node, [
941
998
  state: (
942
999
  builder: FullSnapshotBuilderWithPrefix<Children, Path>
943
1000
  ) => ConstructionResult<
944
1001
  | Machine.SnapshotWithPrefix<Children, Path>
945
1002
  | Machine.ChoiceTargetInstruction<Machine.ChoiceIdentifierWithPrefix<Children, Path>>
946
1003
  >
947
- ]
948
- : [input: Machine.NodeSchema<Node>["~type.make.in"]]
1004
+ ]>
1005
+ : WithNodeInput<Node, []>
949
1006
  : never
950
1007
 
951
1008
  type FullSnapshotResult<
@@ -964,28 +1021,25 @@ type FullParallelBuilder<
964
1021
  > =
965
1022
  & SnapshotBuilderComplete<Regions, Constructed>
966
1023
  & {
967
- readonly [Key in Remaining]:
968
- & ((
969
- ...args: FullSnapshotArguments<States, Key, Prefix>
970
- ) => FullParallelBuilder<
1024
+ readonly [Key in Remaining]: NodeBuilderMethod<
1025
+ States[Key],
1026
+ FullSnapshotArguments<States, Key, Prefix>,
1027
+ FullParallelBuilder<
971
1028
  States,
972
1029
  Prefix,
973
1030
  Exclude<Remaining, Key>,
974
1031
  Regions & { readonly [Region in Key]: FullSnapshotResult<States, Key, Prefix> },
975
1032
  Constructed
976
- >)
977
- & {
978
- readonly from: FromCallable<
979
- FullSnapshotFromArguments<States, Key, Prefix>,
980
- FullParallelBuilder<
981
- States,
982
- Prefix,
983
- Exclude<Remaining, Key>,
984
- Regions & { readonly [Region in Key]: FullSnapshotResult<States, Key, Prefix> },
985
- true
986
- >
987
- >
988
- }
1033
+ >,
1034
+ FullSnapshotFromArguments<States, Key, Prefix>,
1035
+ FullParallelBuilder<
1036
+ States,
1037
+ Prefix,
1038
+ Exclude<Remaining, Key>,
1039
+ Regions & { readonly [Region in Key]: FullSnapshotResult<States, Key, Prefix> },
1040
+ true
1041
+ >
1042
+ >
989
1043
  }
990
1044
 
991
1045
  type HistorySnapshotArguments<
@@ -996,18 +1050,17 @@ type HistorySnapshotArguments<
996
1050
  Path extends string = Machine.JoinPath<Prefix, StateId>
997
1051
  > = Path extends Owner ? FullSnapshotArguments<States, StateId, Prefix>
998
1052
  : States[StateId] extends infer Node ?
999
- Node extends { readonly type: "parallel"; readonly states: infer Children extends Machine.StateSchemas } ? [
1000
- value: Machine.NodeSchema<Node>["Type"],
1053
+ Node extends { readonly type: "parallel"; readonly states: infer Children extends Machine.StateSchemas } ?
1054
+ WithNodeValue<Node, [
1001
1055
  states: (
1002
1056
  builder: HistoryParallelBuilder<Children, Path, Owner>
1003
1057
  ) => SnapshotBuilderComplete<HistorySnapshotRegions<Children, Path, Owner>>
1004
- ]
1005
- : Node extends { readonly states: infer Children extends Machine.StateSchemas } ? [
1006
- value: Machine.NodeSchema<Node>["Type"],
1058
+ ]>
1059
+ : Node extends { readonly states: infer Children extends Machine.StateSchemas } ? WithNodeValue<Node, [
1007
1060
  state: (
1008
1061
  builder: HistorySnapshotBuilderWithPrefix<Children, Owner, Path>
1009
1062
  ) => ConstructionResult<HistorySnapshotWithPrefix<Children, Owner, Path>>
1010
- ]
1063
+ ]>
1011
1064
  : never
1012
1065
  : never
1013
1066
 
@@ -1019,18 +1072,17 @@ type HistorySnapshotFromArguments<
1019
1072
  Path extends string = Machine.JoinPath<Prefix, StateId>
1020
1073
  > = Path extends Owner ? FullSnapshotFromArguments<States, StateId, Prefix>
1021
1074
  : States[StateId] extends infer Node ?
1022
- Node extends { readonly type: "parallel"; readonly states: infer Children extends Machine.StateSchemas } ? [
1023
- input: Machine.NodeSchema<Node>["~type.make.in"],
1075
+ Node extends { readonly type: "parallel"; readonly states: infer Children extends Machine.StateSchemas } ?
1076
+ WithNodeInput<Node, [
1024
1077
  states: (
1025
1078
  builder: HistoryParallelBuilder<Children, Path, Owner>
1026
1079
  ) => SnapshotBuilderComplete<HistorySnapshotRegions<Children, Path, Owner>, boolean>
1027
- ]
1028
- : Node extends { readonly states: infer Children extends Machine.StateSchemas } ? [
1029
- input: Machine.NodeSchema<Node>["~type.make.in"],
1080
+ ]>
1081
+ : Node extends { readonly states: infer Children extends Machine.StateSchemas } ? WithNodeInput<Node, [
1030
1082
  state: (
1031
1083
  builder: HistorySnapshotBuilderWithPrefix<Children, Owner, Path>
1032
1084
  ) => ConstructionResult<HistorySnapshotWithPrefix<Children, Owner, Path>>
1033
- ]
1085
+ ]>
1034
1086
  : never
1035
1087
  : never
1036
1088
 
@@ -1045,12 +1097,12 @@ type HistorySnapshotResult<
1045
1097
  Node extends { readonly type: "parallel"; readonly states: infer Children extends Machine.StateSchemas } ?
1046
1098
  Machine.ParallelSnapshot<
1047
1099
  Path,
1048
- Machine.NodeSchema<Node>["Type"],
1100
+ NodeValue<Node>,
1049
1101
  HistorySnapshotRegions<Children, Path, Owner>
1050
1102
  >
1051
1103
  : Node extends { readonly states: infer Children extends Machine.StateSchemas } ? Machine.CompoundSnapshot<
1052
1104
  Path,
1053
- Machine.NodeSchema<Node>["Type"],
1105
+ NodeValue<Node>,
1054
1106
  HistorySnapshotWithPrefix<Children, Owner, Path>
1055
1107
  >
1056
1108
  : never
@@ -1061,14 +1113,18 @@ type HistorySnapshotMethod<
1061
1113
  StateId extends ActiveStateKey<States>,
1062
1114
  Prefix extends string,
1063
1115
  Owner extends string
1064
- > =
1065
- & ((
1066
- ...args: HistorySnapshotArguments<States, StateId, Prefix, Owner>
1067
- ) => HistorySnapshotResult<States, StateId, Prefix, Owner>)
1068
- & FromMethod<
1116
+ > = Machine.NodeSchema<States[StateId]> extends never ? FromMethod<
1069
1117
  HistorySnapshotFromArguments<States, StateId, Prefix, Owner>,
1070
1118
  HistorySnapshotResult<States, StateId, Prefix, Owner>
1071
1119
  >
1120
+ :
1121
+ & ((
1122
+ ...args: HistorySnapshotArguments<States, StateId, Prefix, Owner>
1123
+ ) => HistorySnapshotResult<States, StateId, Prefix, Owner>)
1124
+ & FromMethod<
1125
+ HistorySnapshotFromArguments<States, StateId, Prefix, Owner>,
1126
+ HistorySnapshotResult<States, StateId, Prefix, Owner>
1127
+ >
1072
1128
 
1073
1129
  type HistorySnapshotWithPrefix<
1074
1130
  States extends Machine.StateSchemas,
@@ -1117,50 +1173,48 @@ type HistoryParallelBuilder<
1117
1173
  & {
1118
1174
  readonly [Key in Remaining]: Owner extends
1119
1175
  | Machine.JoinPath<Prefix, Key>
1120
- | `${Machine.JoinPath<Prefix, Key>}.${string}` ?
1121
- & ((...args: HistorySnapshotArguments<States, Key, Prefix, Owner>) => HistoryParallelBuilder<
1176
+ | `${Machine.JoinPath<Prefix, Key>}.${string}` ? NodeBuilderMethod<
1177
+ States[Key],
1178
+ HistorySnapshotArguments<States, Key, Prefix, Owner>,
1179
+ HistoryParallelBuilder<
1122
1180
  States,
1123
1181
  Prefix,
1124
1182
  Owner,
1125
1183
  Exclude<Remaining, Key>,
1126
1184
  Regions & { readonly [Region in Key]: HistorySnapshotResult<States, Key, Prefix, Owner> },
1127
1185
  Constructed
1128
- >)
1129
- & {
1130
- readonly from: FromCallable<
1131
- HistorySnapshotFromArguments<States, Key, Prefix, Owner>,
1132
- HistoryParallelBuilder<
1133
- States,
1134
- Prefix,
1135
- Owner,
1136
- Exclude<Remaining, Key>,
1137
- Regions & { readonly [Region in Key]: HistorySnapshotResult<States, Key, Prefix, Owner> },
1138
- true
1139
- >
1140
- >
1141
- }
1142
- :
1143
- & ((...args: FullSnapshotArguments<States, Key, Prefix>) => HistoryParallelBuilder<
1186
+ >,
1187
+ HistorySnapshotFromArguments<States, Key, Prefix, Owner>,
1188
+ HistoryParallelBuilder<
1189
+ States,
1190
+ Prefix,
1191
+ Owner,
1192
+ Exclude<Remaining, Key>,
1193
+ Regions & { readonly [Region in Key]: HistorySnapshotResult<States, Key, Prefix, Owner> },
1194
+ true
1195
+ >
1196
+ >
1197
+ : NodeBuilderMethod<
1198
+ States[Key],
1199
+ FullSnapshotArguments<States, Key, Prefix>,
1200
+ HistoryParallelBuilder<
1144
1201
  States,
1145
1202
  Prefix,
1146
1203
  Owner,
1147
1204
  Exclude<Remaining, Key>,
1148
1205
  Regions & { readonly [Region in Key]: FullSnapshotResult<States, Key, Prefix> },
1149
1206
  Constructed
1150
- >)
1151
- & {
1152
- readonly from: FromCallable<
1153
- FullSnapshotFromArguments<States, Key, Prefix>,
1154
- HistoryParallelBuilder<
1155
- States,
1156
- Prefix,
1157
- Owner,
1158
- Exclude<Remaining, Key>,
1159
- Regions & { readonly [Region in Key]: FullSnapshotResult<States, Key, Prefix> },
1160
- true
1161
- >
1162
- >
1163
- }
1207
+ >,
1208
+ FullSnapshotFromArguments<States, Key, Prefix>,
1209
+ HistoryParallelBuilder<
1210
+ States,
1211
+ Prefix,
1212
+ Owner,
1213
+ Exclude<Remaining, Key>,
1214
+ Regions & { readonly [Region in Key]: FullSnapshotResult<States, Key, Prefix> },
1215
+ true
1216
+ >
1217
+ >
1164
1218
  }
1165
1219
 
1166
1220
  type ParentPath<Path extends string> = Path extends `${infer Parent}.${infer Child}`
@@ -1245,59 +1299,36 @@ type LocalTargetMethod<
1245
1299
  Path extends string = Machine.JoinPath<Prefix, StateId>
1246
1300
  > = States[StateId] extends infer Node ?
1247
1301
  Node extends { readonly type: "parallel"; readonly states: infer Children extends Machine.StateSchemas } ?
1248
- Source extends Path | `${Path}.${string}` ?
1249
- & (<Result extends ConstructionResult<LocalTargetResultWithPrefix<AllStates, Children, Path>>>(
1250
- value: Machine.NodeSchema<Node>["Type"],
1251
- state: (
1252
- builder: LocalTargetBuilderWithPrefix<AllStates, Children, Path, Source>
1253
- ) => Result
1254
- ) => Result)
1255
- & {
1256
- readonly from: ConstructionSelectorFromCallable<
1257
- Machine.NodeSchema<Node>["~type.make.in"],
1258
- LocalTargetBuilderWithPrefix<AllStates, Children, Path, Source>,
1259
- LocalTargetResultWithPrefix<AllStates, Children, Path>
1260
- >
1261
- }
1262
- :
1263
- & ((
1264
- value: Machine.NodeSchema<Node>["Type"],
1302
+ Source extends Path | `${Path}.${string}` ? NestedTargetMethod<
1303
+ Node,
1304
+ LocalTargetBuilderWithPrefix<AllStates, Children, Path, Source>,
1305
+ LocalTargetResultWithPrefix<AllStates, Children, Path>
1306
+ >
1307
+ : NodeMethod<
1308
+ Node,
1309
+ WithNodeValue<Node, [
1265
1310
  states: (
1266
1311
  builder: FullParallelBuilder<Children, Path>
1267
1312
  ) => SnapshotBuilderComplete<Machine.SnapshotRegionsWithPrefix<Children, Path>>
1268
- ) => Machine.Target<AllStates, StateIdentifierFromPath<AllStates, Path>>)
1269
- & FromMethod<
1270
- [
1271
- input: Machine.NodeSchema<Node>["~type.make.in"],
1272
- states: (
1273
- builder: FullParallelBuilder<Children, Path>
1274
- ) => SnapshotBuilderComplete<Machine.SnapshotRegionsWithPrefix<Children, Path>, boolean>
1275
- ],
1276
- Machine.Target<AllStates, StateIdentifierFromPath<AllStates, Path>>
1277
- >
1278
- : Node extends { readonly states: infer Children extends Machine.StateSchemas } ?
1279
- & (<Result extends ConstructionResult<LocalTargetResultWithPrefix<AllStates, Children, Path>>>(
1280
- value: Machine.NodeSchema<Node>["Type"],
1281
- state: (
1282
- builder: LocalTargetBuilderWithPrefix<AllStates, Children, Path, Source>
1283
- ) => Result
1284
- ) => Result)
1285
- & {
1286
- readonly from: ConstructionSelectorFromCallable<
1287
- Machine.NodeSchema<Node>["~type.make.in"],
1288
- LocalTargetBuilderWithPrefix<AllStates, Children, Path, Source>,
1289
- LocalTargetResultWithPrefix<AllStates, Children, Path>
1290
- >
1291
- }
1292
- :
1293
- & ((value: Machine.NodeSchema<Node>["Type"]) => Machine.Target<
1294
- AllStates,
1295
- StateIdentifierFromPath<AllStates, Path>
1296
- >)
1297
- & FromMethod<
1298
- [input: Machine.NodeSchema<Node>["~type.make.in"]],
1299
- Machine.Target<AllStates, StateIdentifierFromPath<AllStates, Path>>
1313
+ ]>,
1314
+ Machine.Target<AllStates, StateIdentifierFromPath<AllStates, Path>>,
1315
+ WithNodeInput<Node, [
1316
+ states: (
1317
+ builder: FullParallelBuilder<Children, Path>
1318
+ ) => SnapshotBuilderComplete<Machine.SnapshotRegionsWithPrefix<Children, Path>, boolean>
1319
+ ]>
1300
1320
  >
1321
+ : Node extends { readonly states: infer Children extends Machine.StateSchemas } ? NestedTargetMethod<
1322
+ Node,
1323
+ LocalTargetBuilderWithPrefix<AllStates, Children, Path, Source>,
1324
+ LocalTargetResultWithPrefix<AllStates, Children, Path>
1325
+ >
1326
+ : NodeMethod<
1327
+ Node,
1328
+ WithNodeValue<Node, []>,
1329
+ Machine.Target<AllStates, StateIdentifierFromPath<AllStates, Path>>,
1330
+ WithNodeInput<Node, []>
1331
+ >
1301
1332
  : never
1302
1333
 
1303
1334
  type LocalTargetBuilderForScope<
@@ -1306,28 +1337,29 @@ type LocalTargetBuilderForScope<
1306
1337
  Source extends Machine.StateNodeIdentifier<States>
1307
1338
  > = ChildrenOf<States, Scope> extends infer Children extends Machine.StateSchemas ?
1308
1339
  & LocalTargetBuilderWithPrefix<States, Children, Scope, Source>
1309
- & {
1310
- /**
1311
- * Updates the value of the state containing the local group and moves to
1312
- * one of the states inside it. Values in other active branches are kept.
1313
- *
1314
- * @since 0.4.0
1315
- */
1316
- readonly with:
1317
- & (<Result extends ConstructionResult<LocalTargetResultWithPrefix<States, Children, Scope>>>(
1318
- value: Machine.StateByIdentifier<States, Scope>,
1319
- state: (
1320
- builder: LocalTargetBuilderWithPrefix<States, Children, Scope, Source>
1321
- ) => Result
1322
- ) => Result)
1323
- & {
1324
- readonly from: ConstructionSelectorFromCallable<
1325
- Machine.SchemaByIdentifier<States, Scope>["~type.make.in"],
1326
- LocalTargetBuilderWithPrefix<States, Children, Scope, Source>,
1327
- LocalTargetResultWithPrefix<States, Children, Scope>
1328
- >
1329
- }
1330
- }
1340
+ & (Scope extends Machine.ValuedStateIdentifier<States> ? {
1341
+ /**
1342
+ * Updates the value of the state containing the local group and moves to
1343
+ * one of the states inside it. Values in other active branches are kept.
1344
+ *
1345
+ * @since 0.4.0
1346
+ */
1347
+ readonly with:
1348
+ & (<Result extends ConstructionResult<LocalTargetResultWithPrefix<States, Children, Scope>>>(
1349
+ value: Machine.StateByIdentifier<States, Scope>,
1350
+ state: (
1351
+ builder: LocalTargetBuilderWithPrefix<States, Children, Scope, Source>
1352
+ ) => Result
1353
+ ) => Result)
1354
+ & {
1355
+ readonly from: ConstructionSelectorFromCallable<
1356
+ Machine.SchemaByIdentifier<States, Scope>["~type.make.in"],
1357
+ LocalTargetBuilderWithPrefix<States, Children, Scope, Source>,
1358
+ LocalTargetResultWithPrefix<States, Children, Scope>
1359
+ >
1360
+ }
1361
+ } :
1362
+ {})
1331
1363
  : {}
1332
1364
 
1333
1365
  type BranchTargetResult<
@@ -1381,60 +1413,39 @@ type BranchTargetMethod<
1381
1413
  > = States[StateId] extends infer Node ?
1382
1414
  Node extends { readonly type: "parallel"; readonly states: infer Children extends Machine.StateSchemas } ?
1383
1415
  Source extends Path | `${Path}.${string}` ?
1384
- & (<Result extends ConstructionResult<BranchTargetResultWithPrefix<AllStates, Children, Path>>>(
1385
- value: Machine.NodeSchema<Node>["Type"],
1386
- state: (
1387
- builder: BranchTargetBuilderWithPrefix<AllStates, Children, Path, Source>
1388
- ) => Result
1389
- ) => Result)
1390
- & {
1391
- readonly from: ConstructionSelectorFromCallable<
1392
- Machine.NodeSchema<Node>["~type.make.in"],
1393
- BranchTargetBuilderWithPrefix<AllStates, Children, Path, Source>,
1394
- BranchTargetResultWithPrefix<AllStates, Children, Path>
1395
- >
1396
- }
1416
+ & NestedTargetMethod<
1417
+ Node,
1418
+ BranchTargetBuilderWithPrefix<AllStates, Children, Path, Source>,
1419
+ BranchTargetResultWithPrefix<AllStates, Children, Path>
1420
+ >
1397
1421
  & BranchTargetBuilderWithPrefix<AllStates, Children, Path, Source>
1398
- :
1399
- & ((
1400
- value: Machine.NodeSchema<Node>["Type"],
1422
+ : NodeMethod<
1423
+ Node,
1424
+ WithNodeValue<Node, [
1401
1425
  states: (
1402
1426
  builder: FullParallelBuilder<Children, Path>
1403
1427
  ) => SnapshotBuilderComplete<Machine.SnapshotRegionsWithPrefix<Children, Path>>
1404
- ) => Machine.Target<AllStates, StateIdentifierFromPath<AllStates, Path>>)
1405
- & FromMethod<
1406
- [
1407
- input: Machine.NodeSchema<Node>["~type.make.in"],
1408
- states: (
1409
- builder: FullParallelBuilder<Children, Path>
1410
- ) => SnapshotBuilderComplete<Machine.SnapshotRegionsWithPrefix<Children, Path>, boolean>
1411
- ],
1412
- Machine.Target<AllStates, StateIdentifierFromPath<AllStates, Path>>
1413
- >
1428
+ ]>,
1429
+ Machine.Target<AllStates, StateIdentifierFromPath<AllStates, Path>>,
1430
+ WithNodeInput<Node, [
1431
+ states: (
1432
+ builder: FullParallelBuilder<Children, Path>
1433
+ ) => SnapshotBuilderComplete<Machine.SnapshotRegionsWithPrefix<Children, Path>, boolean>
1434
+ ]>
1435
+ >
1414
1436
  : Node extends { readonly states: infer Children extends Machine.StateSchemas } ?
1415
- & (<Result extends ConstructionResult<BranchTargetResultWithPrefix<AllStates, Children, Path>>>(
1416
- value: Machine.NodeSchema<Node>["Type"],
1417
- state: (
1418
- builder: BranchTargetBuilderWithPrefix<AllStates, Children, Path, Source>
1419
- ) => Result
1420
- ) => Result)
1421
- & {
1422
- readonly from: ConstructionSelectorFromCallable<
1423
- Machine.NodeSchema<Node>["~type.make.in"],
1424
- BranchTargetBuilderWithPrefix<AllStates, Children, Path, Source>,
1425
- BranchTargetResultWithPrefix<AllStates, Children, Path>
1426
- >
1427
- }
1437
+ & NestedTargetMethod<
1438
+ Node,
1439
+ BranchTargetBuilderWithPrefix<AllStates, Children, Path, Source>,
1440
+ BranchTargetResultWithPrefix<AllStates, Children, Path>
1441
+ >
1428
1442
  & BranchTargetBuilderWithPrefix<AllStates, Children, Path, Source>
1429
- :
1430
- & ((value: Machine.NodeSchema<Node>["Type"]) => Machine.Target<
1431
- AllStates,
1432
- StateIdentifierFromPath<AllStates, Path>
1433
- >)
1434
- & FromMethod<
1435
- [input: Machine.NodeSchema<Node>["~type.make.in"]],
1436
- Machine.Target<AllStates, StateIdentifierFromPath<AllStates, Path>>
1437
- >
1443
+ : NodeMethod<
1444
+ Node,
1445
+ WithNodeValue<Node, []>,
1446
+ Machine.Target<AllStates, StateIdentifierFromPath<AllStates, Path>>,
1447
+ WithNodeInput<Node, []>
1448
+ >
1438
1449
  : never
1439
1450
 
1440
1451
  type BranchTargetBuilderForRoot<
@@ -1471,15 +1482,21 @@ type HasDirectShallowHistory<States extends Machine.StateSchemas> = {
1471
1482
  readonly [Key in HistoryStateKey<States>]: States[Key] extends { readonly history: "deep" } ? never : Key
1472
1483
  }[HistoryStateKey<States>] extends never ? false : true
1473
1484
 
1485
+ type HasValuedActiveChild<States extends Machine.StateSchemas> = {
1486
+ readonly [Key in ActiveStateKey<States>]: Machine.NodeSchema<States[Key]> extends never ? never : Key
1487
+ }[ActiveStateKey<States>] extends never ? false : true
1488
+
1474
1489
  type InitializerClosureForNode<
1475
1490
  AllStates extends Machine.StateSchemas,
1476
1491
  Node,
1477
1492
  Path extends string
1478
1493
  > = Node extends { readonly type: "parallel"; readonly states: infer Children extends Machine.StateSchemas } ?
1479
- | Extract<Path, Machine.StateIdentifier<AllStates>>
1494
+ | (HasValuedActiveChild<Children> extends true ? Extract<Path, Machine.StateIdentifier<AllStates>> : never)
1480
1495
  | InitializerClosuresForChildren<AllStates, Children, Path>
1481
1496
  : Node extends { readonly states: infer Children extends Machine.StateSchemas; readonly initial: infer Initial } ?
1482
- | Extract<Path, Machine.StateIdentifier<AllStates>>
1497
+ | (Initial extends ActiveStateKey<Children> ? Machine.NodeSchema<Children[Initial]> extends never ? never
1498
+ : Extract<Path, Machine.StateIdentifier<AllStates>>
1499
+ : never)
1483
1500
  | (Initial extends ActiveStateKey<Children> ? InitializerClosureForNode<
1484
1501
  AllStates,
1485
1502
  Children[Initial],
@@ -2175,8 +2192,9 @@ export declare namespace Machine {
2175
2192
  * Descriptive annotations exposed for compiled state nodes.
2176
2193
  *
2177
2194
  * Schema-backed states resolve their complete Effect Schema annotation map.
2178
- * Pseudo-states accept only the descriptive fields below. Annotations never
2179
- * affect state identity, targeting, or runtime behavior.
2195
+ * Schema-less active states and pseudo-states accept only the descriptive
2196
+ * fields below. Annotations never affect state identity, targeting, or
2197
+ * runtime behavior.
2180
2198
  *
2181
2199
  * @category models
2182
2200
  * @since 0.4.0
@@ -2187,14 +2205,18 @@ export declare namespace Machine {
2187
2205
  readonly documentation?: string | undefined
2188
2206
  }
2189
2207
 
2190
- /** Descriptive annotations accepted by schema-less pseudo-states. */
2191
- export type PseudoStateAnnotations = Pick<
2208
+ /** Descriptive annotations accepted by schema-less active and pseudo-states. */
2209
+ export type SchemaLessStateAnnotations = Pick<
2192
2210
  StateNodeAnnotations,
2193
2211
  "title" | "description" | "documentation"
2194
2212
  >
2195
2213
 
2214
+ /** @deprecated Use {@link SchemaLessStateAnnotations}. */
2215
+ export type PseudoStateAnnotations = SchemaLessStateAnnotations
2216
+
2196
2217
  /**
2197
- * Configuration accepted for an atomic object state node.
2218
+ * Configuration accepted for an atomic object state node. Omit `schema` when
2219
+ * the state owns no value; a schema-less final may still declare `output`.
2198
2220
  *
2199
2221
  * @category models
2200
2222
  * @since 0.4.0
@@ -2204,38 +2226,72 @@ export declare namespace Machine {
2204
2226
  readonly schema: TaggedSchema
2205
2227
  readonly type?: "active"
2206
2228
  readonly output?: never
2229
+ readonly annotations?: never
2207
2230
  }
2208
2231
  | {
2209
2232
  readonly schema: TaggedSchema
2210
2233
  readonly type: "final"
2211
2234
  readonly output?: Schema.Top
2235
+ readonly annotations?: never
2236
+ }
2237
+ | {
2238
+ readonly schema?: never
2239
+ readonly type?: "active"
2240
+ readonly output?: never
2241
+ readonly annotations?: SchemaLessStateAnnotations
2242
+ }
2243
+ | {
2244
+ readonly schema?: never
2245
+ readonly type: "final"
2246
+ readonly output?: Schema.Top
2247
+ readonly annotations?: SchemaLessStateAnnotations
2212
2248
  }
2213
2249
 
2214
2250
  /**
2215
- * Configuration accepted for a compound object state node.
2251
+ * Configuration accepted for a compound object state node. Omit `schema`
2252
+ * when the compound state exists only to own control topology.
2216
2253
  *
2217
2254
  * @category models
2218
2255
  * @since 0.4.0
2219
2256
  */
2220
- export interface CompoundStateNodeConfig {
2221
- readonly schema: TaggedSchema
2222
- readonly type?: "active"
2223
- readonly initial: string
2224
- readonly states: StateTree
2225
- }
2257
+ export type CompoundStateNodeConfig =
2258
+ | {
2259
+ readonly schema: TaggedSchema
2260
+ readonly type?: "active"
2261
+ readonly initial: string
2262
+ readonly states: StateTree
2263
+ readonly annotations?: never
2264
+ }
2265
+ | {
2266
+ readonly schema?: never
2267
+ readonly type?: "active"
2268
+ readonly initial: string
2269
+ readonly states: StateTree
2270
+ readonly annotations?: SchemaLessStateAnnotations
2271
+ }
2226
2272
 
2227
2273
  /**
2228
- * Configuration accepted for a parallel object state node.
2274
+ * Configuration accepted for a parallel object state node. Omit `schema`
2275
+ * when the parallel state exists only to own its regions.
2229
2276
  *
2230
2277
  * @category models
2231
2278
  * @since 0.4.0
2232
2279
  */
2233
- export interface ParallelStateNodeConfig {
2234
- readonly schema: TaggedSchema
2235
- readonly type: "parallel"
2236
- readonly output?: Schema.Top
2237
- readonly states: StateTree
2238
- }
2280
+ export type ParallelStateNodeConfig =
2281
+ | {
2282
+ readonly schema: TaggedSchema
2283
+ readonly type: "parallel"
2284
+ readonly output?: Schema.Top
2285
+ readonly states: StateTree
2286
+ readonly annotations?: never
2287
+ }
2288
+ | {
2289
+ readonly schema?: never
2290
+ readonly type: "parallel"
2291
+ readonly output?: Schema.Top
2292
+ readonly states: StateTree
2293
+ readonly annotations?: SchemaLessStateAnnotations
2294
+ }
2239
2295
 
2240
2296
  /**
2241
2297
  * Pseudo-state that restores the last active configuration of its parent.
@@ -2253,7 +2309,7 @@ export declare namespace Machine {
2253
2309
  readonly type: "history"
2254
2310
  /** Defaults to shallow history. */
2255
2311
  readonly history?: "shallow" | "deep"
2256
- readonly annotations?: PseudoStateAnnotations
2312
+ readonly annotations?: SchemaLessStateAnnotations
2257
2313
  }
2258
2314
 
2259
2315
  /**
@@ -2268,7 +2324,7 @@ export declare namespace Machine {
2268
2324
  */
2269
2325
  export interface ChoiceStateNodeConfig {
2270
2326
  readonly type: "choice"
2271
- readonly annotations?: PseudoStateAnnotations
2327
+ readonly annotations?: SchemaLessStateAnnotations
2272
2328
  }
2273
2329
 
2274
2330
  /**
@@ -2341,14 +2397,26 @@ export declare namespace Machine {
2341
2397
  readonly initial: InitialBuilder<States>
2342
2398
 
2343
2399
  /**
2344
- * Returns the decoded value for an active state path.
2400
+ * Returns the decoded value for an active state path. The supplied
2401
+ * snapshot may be a complete root snapshot or a snapshot previously
2402
+ * extracted from this definition. Extracted snapshots accept only their
2403
+ * own absolute path and descendant paths.
2345
2404
  *
2346
2405
  * @since 0.4.0
2347
2406
  */
2348
- readonly get: <Path extends StateIdentifier<States>>(
2349
- snapshot: Snapshot<States>,
2350
- path: Path
2351
- ) => Option.Option<StateByIdentifier<States, Path>>
2407
+ readonly get: {
2408
+ <Path extends ValuedStateIdentifier<States>>(
2409
+ snapshot: Snapshot<States>,
2410
+ path: Path
2411
+ ): Option.Option<StateByIdentifier<States, Path>>
2412
+ <
2413
+ const From extends StateIdentifier<States>,
2414
+ const Path extends ValuedStateIdentifier<States>
2415
+ >(
2416
+ snapshot: SnapshotByIdentifier<States, From>,
2417
+ path: Path & (Path extends NoInfer<From> | `${NoInfer<From>}.${string}` ? unknown : never)
2418
+ ): Option.Option<StateByIdentifier<States, Path>>
2419
+ }
2352
2420
 
2353
2421
  /**
2354
2422
  * Returns the decoded value for an active state path together with all of
@@ -2360,30 +2428,54 @@ export declare namespace Machine {
2360
2428
  *
2361
2429
  * @since 0.4.0
2362
2430
  */
2363
- readonly getWithParents: <Path extends StateIdentifier<States>>(
2431
+ readonly getWithParents: <Path extends ValuedStateIdentifier<States>>(
2364
2432
  snapshot: Snapshot<States>,
2365
2433
  path: Path
2366
2434
  ) => Option.Option<StateWithParents<States, Path>>
2367
2435
 
2368
2436
  /**
2369
- * Returns the snapshot for an active state path.
2437
+ * Returns the snapshot for an active state path. The supplied snapshot may
2438
+ * be a complete root snapshot or a snapshot previously extracted from this
2439
+ * definition. Extracted snapshots accept only their own absolute path and
2440
+ * descendant paths.
2370
2441
  *
2371
2442
  * @since 0.4.0
2372
2443
  */
2373
- readonly getSnapshot: <Path extends StateIdentifier<States>>(
2374
- snapshot: Snapshot<States>,
2375
- path: Path
2376
- ) => Option.Option<SnapshotByIdentifier<States, Path>>
2444
+ readonly getSnapshot: {
2445
+ <Path extends StateIdentifier<States>>(
2446
+ snapshot: Snapshot<States>,
2447
+ path: Path
2448
+ ): Option.Option<SnapshotByIdentifier<States, Path>>
2449
+ <
2450
+ const From extends StateIdentifier<States>,
2451
+ const Path extends StateIdentifier<States>
2452
+ >(
2453
+ snapshot: SnapshotByIdentifier<States, From>,
2454
+ path: Path & (Path extends NoInfer<From> | `${NoInfer<From>}.${string}` ? unknown : never)
2455
+ ): Option.Option<SnapshotByIdentifier<States, Path>>
2456
+ }
2377
2457
 
2378
2458
  /**
2379
- * Returns whether a state path is active in the snapshot.
2459
+ * Returns whether a state path is active in the snapshot. The supplied
2460
+ * snapshot may be a complete root snapshot or a snapshot previously
2461
+ * extracted from this definition. Extracted snapshots accept only their
2462
+ * own absolute path and descendant paths.
2380
2463
  *
2381
2464
  * @since 0.4.0
2382
2465
  */
2383
- readonly matches: <Path extends StateIdentifier<States>>(
2384
- snapshot: Snapshot<States>,
2385
- path: Path
2386
- ) => boolean
2466
+ readonly matches: {
2467
+ <Path extends StateIdentifier<States>>(
2468
+ snapshot: Snapshot<States>,
2469
+ path: Path
2470
+ ): boolean
2471
+ <
2472
+ const From extends StateIdentifier<States>,
2473
+ const Path extends StateIdentifier<States>
2474
+ >(
2475
+ snapshot: SnapshotByIdentifier<States, From>,
2476
+ path: Path & (Path extends NoInfer<From> | `${NoInfer<From>}.${string}` ? unknown : never)
2477
+ ): boolean
2478
+ }
2387
2479
  }
2388
2480
 
2389
2481
  /**
@@ -2398,7 +2490,7 @@ export declare namespace Machine {
2398
2490
  export interface StateNodeBase<Path extends string = string> {
2399
2491
  readonly path: Path
2400
2492
  readonly key: string
2401
- /** Resolved Effect Schema annotations, or descriptive pseudo-state annotations. */
2493
+ /** Resolved schema annotations, or descriptive schema-less-state annotations. */
2402
2494
  readonly annotations: Readonly<StateNodeAnnotations> | undefined
2403
2495
  readonly order: number
2404
2496
  }
@@ -2408,7 +2500,7 @@ export declare namespace Machine {
2408
2500
  extends StateNodeBase<OwnPath>
2409
2501
  {
2410
2502
  readonly type: "atomic"
2411
- readonly schema: TaggedSchema
2503
+ readonly schema: TaggedSchema | undefined
2412
2504
  readonly output: undefined
2413
2505
  readonly history: undefined
2414
2506
  readonly parent: ActivePath | undefined
@@ -2423,7 +2515,7 @@ export declare namespace Machine {
2423
2515
  ChoicePath extends string = ActivePath
2424
2516
  > extends StateNodeBase<OwnPath> {
2425
2517
  readonly type: "compound"
2426
- readonly schema: TaggedSchema
2518
+ readonly schema: TaggedSchema | undefined
2427
2519
  readonly output: undefined
2428
2520
  readonly history: undefined
2429
2521
  readonly parent: ActivePath | undefined
@@ -2437,7 +2529,7 @@ export declare namespace Machine {
2437
2529
  extends StateNodeBase<OwnPath>
2438
2530
  {
2439
2531
  readonly type: "parallel"
2440
- readonly schema: TaggedSchema
2532
+ readonly schema: TaggedSchema | undefined
2441
2533
  readonly output: Schema.Top | undefined
2442
2534
  readonly history: undefined
2443
2535
  readonly parent: ActivePath | undefined
@@ -2451,7 +2543,7 @@ export declare namespace Machine {
2451
2543
  extends StateNodeBase<OwnPath>
2452
2544
  {
2453
2545
  readonly type: "final"
2454
- readonly schema: TaggedSchema
2546
+ readonly schema: TaggedSchema | undefined
2455
2547
  readonly output: Schema.Top | undefined
2456
2548
  readonly history: undefined
2457
2549
  readonly parent: ActivePath | undefined
@@ -2661,6 +2753,19 @@ export declare namespace Machine {
2661
2753
  */
2662
2754
  export type StateIdentifier<States extends StateSchemas> = StateIdentifierWithPrefix<States>
2663
2755
 
2756
+ /** Extracts active state paths whose definitions declare a state value schema. */
2757
+ export type ValuedStateIdentifier<States extends StateSchemas> = StateIdentifier<States> extends infer StateId
2758
+ ? StateId extends StateIdentifier<States> ? NodeSchema<NodeByIdentifier<States, StateId>> extends never ? never
2759
+ : StateId
2760
+ : never
2761
+ : never
2762
+
2763
+ /** Extracts active state paths whose definitions intentionally omit a state value schema. */
2764
+ export type StructuralStateIdentifier<States extends StateSchemas> = Exclude<
2765
+ StateIdentifier<States>,
2766
+ ValuedStateIdentifier<States>
2767
+ >
2768
+
2664
2769
  /**
2665
2770
  * Extracts the state path values represented by a state definition under a
2666
2771
  * parent path prefix.
@@ -2871,7 +2976,7 @@ export declare namespace Machine {
2871
2976
  export type StateByIdentifier<
2872
2977
  States extends StateSchemas,
2873
2978
  StateId extends StateIdentifier<States>
2874
- > = Extract<StateOf<States>, SchemaByIdentifier<States, StateId>["Type"]>
2979
+ > = StateId extends ValuedStateIdentifier<States> ? SchemaByIdentifier<States, StateId>["Type"] : undefined
2875
2980
 
2876
2981
  /**
2877
2982
  * Extracts every parent state path from a state identifier.
@@ -2904,7 +3009,7 @@ export declare namespace Machine {
2904
3009
  States extends StateSchemas,
2905
3010
  StateId extends StateIdentifier<States>
2906
3011
  > = StateId extends StateIdentifier<States> ? {
2907
- readonly [Parent in Extract<ParentStateIdentifier<StateId>, StateIdentifier<States>>]: StateByIdentifier<
3012
+ readonly [Parent in Extract<ParentStateIdentifier<StateId>, ValuedStateIdentifier<States>>]: StateByIdentifier<
2908
3013
  States,
2909
3014
  Parent
2910
3015
  >
@@ -2923,7 +3028,7 @@ export declare namespace Machine {
2923
3028
  > = StateId extends StateIdentifier<States> ?
2924
3029
  Extract<ImmediateParentStateIdentifier<StateId>, StateIdentifier<States>> extends infer Parent
2925
3030
  ? [Parent] extends [never] ? undefined
2926
- : Parent extends StateIdentifier<States> ? StateByIdentifier<States, Parent>
3031
+ : Parent extends ValuedStateIdentifier<States> ? StateByIdentifier<States, Parent>
2927
3032
  : undefined
2928
3033
  : undefined
2929
3034
  : never
@@ -3108,7 +3213,7 @@ export declare namespace Machine {
3108
3213
  */
3109
3214
  export interface EncodedSnapshotState {
3110
3215
  readonly path: string
3111
- readonly value: unknown
3216
+ readonly value?: unknown
3112
3217
  }
3113
3218
 
3114
3219
  /**
@@ -3293,17 +3398,17 @@ export declare namespace Machine {
3293
3398
  > = States[StateId] extends { readonly type: "parallel"; readonly states: infer Children }
3294
3399
  ? Children extends StateSchemas ? ParallelSnapshot<
3295
3400
  Path,
3296
- NodeSchema<States[StateId]>["Type"],
3401
+ NodeValue<States[StateId]>,
3297
3402
  SnapshotRegionsWithPrefix<Children, Path>
3298
3403
  >
3299
- : AtomicSnapshot<Path, NodeSchema<States[StateId]>["Type"]>
3404
+ : AtomicSnapshot<Path, NodeValue<States[StateId]>>
3300
3405
  : States[StateId] extends { readonly states: infer Children } ? Children extends StateSchemas ? CompoundSnapshot<
3301
3406
  Path,
3302
- NodeSchema<States[StateId]>["Type"],
3407
+ NodeValue<States[StateId]>,
3303
3408
  SnapshotWithPrefix<Children, Path>
3304
3409
  >
3305
- : AtomicSnapshot<Path, NodeSchema<States[StateId]>["Type"]>
3306
- : AtomicSnapshot<Path, NodeSchema<States[StateId]>["Type"]>
3410
+ : AtomicSnapshot<Path, NodeValue<States[StateId]>>
3411
+ : AtomicSnapshot<Path, NodeValue<States[StateId]>>
3307
3412
 
3308
3413
  /**
3309
3414
  * Extracts a complete root snapshot whose selected configuration contains a
@@ -3419,7 +3524,7 @@ export declare namespace Machine {
3419
3524
  readonly value: StateByIdentifier<States, StateId>
3420
3525
  readonly values?: Partial<
3421
3526
  {
3422
- readonly [AncestorStateId in StateIdentifier<States>]: StateByIdentifier<States, AncestorStateId>
3527
+ readonly [AncestorStateId in ValuedStateIdentifier<States>]: StateByIdentifier<States, AncestorStateId>
3423
3528
  }
3424
3529
  >
3425
3530
  }
@@ -3743,7 +3848,7 @@ export declare namespace Machine {
3743
3848
  Extract<ImmediateParentStateIdentifier<ChoiceId>, StateIdentifier<States>>
3744
3849
  >
3745
3850
  readonly parents: {
3746
- readonly [Parent in Extract<ParentStateIdentifier<ChoiceId>, StateIdentifier<States>>]: StateByIdentifier<
3851
+ readonly [Parent in Extract<ParentStateIdentifier<ChoiceId>, ValuedStateIdentifier<States>>]: StateByIdentifier<
3747
3852
  States,
3748
3853
  Parent
3749
3854
  >
@@ -4292,10 +4397,14 @@ export declare namespace Machine {
4292
4397
  StateId extends StateIdentifier<States>
4293
4398
  > = NodeByIdentifier<States, StateId> extends infer Node ?
4294
4399
  Node extends { readonly type: "parallel"; readonly states: infer Children extends StateSchemas } ? {
4295
- readonly [Key in ActiveStateKey<Children>]: NodeSchema<Children[Key]>["Type"]
4400
+ readonly [Key in ActiveStateKey<Children> as NodeSchema<Children[Key]> extends never ? never : Key]: NodeValue<
4401
+ Children[Key]
4402
+ >
4296
4403
  }
4297
4404
  : Node extends { readonly states: infer Children extends StateSchemas; readonly initial: infer Initial } ?
4298
- Initial extends ActiveStateKey<Children> ? NodeSchema<Children[Initial]>["Type"] : never
4405
+ Initial extends ActiveStateKey<Children> ? NodeSchema<Children[Initial]> extends never ? never
4406
+ : NodeValue<Children[Initial]>
4407
+ : never
4299
4408
  : never
4300
4409
  : never
4301
4410
 
@@ -5267,7 +5376,9 @@ export const isFinal: <
5267
5376
  *
5268
5377
  * The returned `states` property is the same object passed to `defineStates`.
5269
5378
  * The returned `initial` builder creates snapshots without user-authored path
5270
- * strings and enforces compound and parallel initial-state rules.
5379
+ * strings and enforces compound and parallel initial-state rules. Active nodes
5380
+ * may omit `schema` when they own no value; those builders expose `.from(...)`
5381
+ * and still participate fully in targeting, matching, and snapshots.
5271
5382
  *
5272
5383
  * **Example** (Atomic initial snapshot)
5273
5384
  *