@typeonce/ritmo 0.7.0 → 0.9.0

package/src/Schema.ts

@@ -54,7 +54,7 @@ import type { ConstructedDescriptor, Descriptor } from "./Descriptor.ts"
 import type * as Entity from "./Entity.ts"
 import type * as EntityScope from "./EntityScope.ts"
 import { buildSchema, emptySchema, mergeSchemas } from "./internal/fragments.ts"
-import { makeGame } from "./internal/game.ts"
+import { type exitApplyDeferredMessage, makeGame } from "./internal/game.ts"
 import type * as Condition from "./Condition.ts"
 import type * as Inspector from "./Inspector.ts"
 import type * as Machine from "./Machine.ts"
@@ -66,6 +66,7 @@ import type * as Result from "./Result.ts"
 import type * as Debug from "./Debug.ts"
 import type * as Runtime from "./Runtime.ts"
 import type * as Schedule from "./Schedule.ts"
+import type * as Snapshot from "./Snapshot.ts"
 import type * as System from "./System.ts"
 
 /**
@@ -73,22 +74,107 @@ import type * as System from "./System.ts"
  */
 export type Registry = Record<string, Descriptor.Any>
 
+/** At least one: a permission that names nothing allows nothing. */
+type NonEmpty<T> = readonly [T, ...ReadonlyArray<T>]
+
+type Article<Kind extends string> = Kind extends "event" ? "an" : "a"
+
+/**
+ * Rejects descriptors of another kind in a fragment's `components`,
+ * `resources`, or `events`, naming where each belongs.
+ */
+type RegistryOfKind<R, Expected extends string> = {
+  readonly [K in keyof R]: R[K] extends { readonly kind: Expected }
+    ? unknown
+    : R[K] extends { readonly kind: infer Actual extends string }
+      ? {
+        readonly __fixSchema__: Actual extends "service"
+          ? `${K & string} is a service, not ${Article<Expected>} ${Expected}: provide services to Game.Runtime.make({ services }) instead of registering them`
+          : `${K & string} is ${Article<Actual>} ${Actual}, not ${Article<Expected>} ${Expected}: move it to ${Actual}s: { ... }`
+      }
+      : unknown
+}
+
 /**
  * A closed schema: the components, resources, events, and relations a world
- * may contain.
+ * may contain, and the component requirements (`Schema.requires`) every
+ * entity of it keeps.
  */
 export interface SchemaDefinition<
   out Components extends Registry = {},
   out Resources extends Registry = {},
   out Events extends Registry = {},
-  out Relations extends Record<string, Relation.Relation.Any> = {}
+  out Relations extends Record<string, Relation.Relation.Any> = {},
+  out Requires extends RequirementPair = never
 > {
   readonly components: Components
   readonly resources: Resources
   readonly events: Events
   readonly relations: Relations
+  /** Component requirements declared with `Schema.requires(...)`. */
+  readonly requires: ReadonlyArray<ComponentRequirement<Requires>>
+}
+
+/**
+ * One requirement carried in a schema type, by component name:
+ * `[requirer, required]`. One pair per required component, so lookups by
+ * either end stay exact.
+ */
+export type RequirementPair = readonly [string, string]
+
+/**
+ * One `Schema.requires(...)` declaration: every entity holding `component`
+ * also holds each of `required`.
+ */
+export interface ComponentRequirement<out Pairs extends RequirementPair = RequirementPair> {
+  readonly kind: "requires"
+  readonly component: Descriptor<"component", string, any>
+  readonly required: ReadonlyArray<Descriptor<"component", string, any>>
+  readonly __pairs?: (_: never) => Pairs
 }
 
+type AnyComponentDescriptor = Descriptor<"component", string, any>
+
+/** One `[from, to]` pair per required name. */
+type RequirementPairs<From extends string, To extends string> = To extends string ? readonly [From, To] : never
+
+type PairsOf<R> = R extends ComponentRequirement<infer Pairs> ? Pairs : never
+
+/**
+ * Declares that every entity holding `component` also holds each of
+ * `required`. List it in a fragment's `requires`.
+ *
+ * The compiler then rejects every command that would break it:
+ * `commands.spawn` / `spawnIn` of a draft missing a required entry,
+ * `commands.insert` of `component` on an entity not proven to hold the
+ * rest, and `commands.remove` of a required component while a requirer may
+ * stay. `Game.System.spawns(component)` also allows spawning what it
+ * requires. Nothing is ever filled in with a default: the draft must carry
+ * every value.
+ *
+ * Requirements chain (`A` requires `B`, `B` requires `C`) and may name
+ * components of other fragments of the same `Schema.bind`.
+ *
+ * A saved component cannot require a transient one (`Schema.bind` rejects
+ * it): a restore would bring the requirer back without it. A transient
+ * requirer may require a transient component.
+ *
+ * @example
+ * ```ts
+ * const Gameplay = Schema.fragment({
+ *   components: { Player, Position, Velocity },
+ *   requires: [Schema.requires(Player, Position, Velocity)]
+ * })
+ * ```
+ */
+export const requires = <
+  D extends AnyComponentDescriptor,
+  const Required extends readonly [AnyComponentDescriptor, ...Array<AnyComponentDescriptor>]
+>(
+  component: D,
+  ...required: Required
+): ComponentRequirement<RequirementPairs<D["name"], Required[number]["name"]>> => ({ kind: "requires", component, required })
+
 const schemaRootTypeId = "~ritmo/SchemaRoot" as const
 
 export type RootToken<Name extends string = string> = {
@@ -112,7 +198,8 @@ export type MergeSchemaDefinitions<
   Schema.Components<A> & Schema.Components<B>,
   Schema.Resources<A> & Schema.Resources<B>,
   Schema.Events<A> & Schema.Events<B>,
-  Schema.Relations<A> & Schema.Relations<B>
+  Schema.Relations<A> & Schema.Relations<B>,
+  Schema.Requires<A> | Schema.Requires<B>
 >
 
 /**
@@ -186,6 +273,40 @@ export type ValidateFragments<Fragments extends ReadonlyArray<Schema.Any>> =
         readonly __schemaConflicts__: FragmentConflicts<Fragments>
       }
 
+type UnregisteredRequirements<S extends Schema.Any> =
+  Exclude<Schema.Requires<S>[0] | Schema.Requires<S>[1], Schema.ComponentDescriptor<S>["name"]>
+
+type TransientComponentName<S extends Schema.Any> = Extract<Schema.ComponentDescriptor<S>, { readonly transient: true }>["name"]
+
+/** One message per saved requirer that requires a transient component. */
+type TransientRequirements<S extends Schema.Any, Pairs = Schema.Requires<S>> =
+  Pairs extends readonly [infer From extends string, infer To extends string]
+    ? To extends TransientComponentName<S>
+      ? From extends TransientComponentName<S> ? never
+      : `${From} requires ${To}, which is transient and not saved: make ${From} transient too, or give ${To} a constructor`
+    : never
+    : never
+
+/**
+ * Rejects requirements naming a component the bound schema does not
+ * register. Checked at `bind`, so a fragment may require a component another
+ * fragment registers. Also rejects a saved component requiring a transient
+ * one (a restore would bring the requirer back without it). Erased schemas
+ * (`Schema.Any`) are checked by `bind` at runtime instead.
+ */
+export type ValidateRequires<S extends Schema.Any> =
+  string extends Schema.Requires<S>[1]
+    ? unknown
+    : [UnregisteredRequirements<S>] extends [never]
+    ? [TransientRequirements<S>] extends [never]
+      ? unknown
+      : {
+          readonly __schemaRequires__: TransientRequirements<S>
+        }
+    : {
+        readonly __schemaRequires__: `${UnregisteredRequirements<S>} is named in Schema.requires(...) but no fragment registers it: add it to a fragment's components`
+      }
+
 /**
  * Creates one explicit root token for schema-bound long-lived references.
  *
@@ -209,11 +330,6 @@ export const defineRoot = <const Name extends string>(name: Name): RootToken<Nam
   }
 }) as RootToken<Name>
 
-/**
- * Creates an empty schema.
- */
-export const empty = (): SchemaDefinition => emptySchema()
-
 /**
  * Creates a schema fragment.
  *
@@ -224,8 +340,9 @@ export const empty = (): SchemaDefinition => emptySchema()
  * @example
  * ```ts
  * const Combat = Schema.fragment({
- *   components: { Health, Damage },
- *   events: { Hit }
+ *   components: { Health, Damage, Enemy },
+ *   events: { Hit },
+ *   requires: [Schema.requires(Enemy, Health)]
  * })
  * ```
  */
@@ -233,19 +350,22 @@ export const fragment = <
   const Components extends Registry = {},
   const Resources extends Registry = {},
   const Events extends Registry = {},
-  const Relations extends Record<string, Relation.Relation.Any> = {}
+  const Relations extends Record<string, Relation.Relation.Any> = {},
+  const Requires extends ReadonlyArray<ComponentRequirement> = readonly []
 >(definition: {
-  readonly components?: Components
-  readonly resources?: Resources
-  readonly events?: Events
+  readonly components?: Components & RegistryOfKind<Components, "component">
+  readonly resources?: Resources & RegistryOfKind<Resources, "resource">
+  readonly events?: Events & RegistryOfKind<Events, "event">
   readonly relations?: Relations
-} & ValidateFragments<[SchemaDefinition<Components, Resources, Events, Relations>]>): SchemaDefinition<Components, Resources, Events, Relations> =>
+  readonly requires?: Requires
+} & ValidateFragments<[SchemaDefinition<Components, Resources, Events, Relations>]>): SchemaDefinition<Components, Resources, Events, Relations, PairsOf<Requires[number]>> =>
   mergeSchemas(emptySchema(), {
     components: definition.components ?? {},
     resources: definition.resources ?? {},
     events: definition.events ?? {},
-    relations: definition.relations ?? {}
-  }) as SchemaDefinition<Components, Resources, Events, Relations>
+    relations: definition.relations ?? {},
+    requires: definition.requires ?? []
+  }) as SchemaDefinition<Components, Resources, Events, Relations, PairsOf<Requires[number]>>
 
 /**
  * Composes one or more fragments and returns one bound `Game` surface.
@@ -262,18 +382,18 @@ export const fragment = <
  */
 export function bind<
   S extends Schema.Any
->(schema: S & ValidateFragments<[S]>): Schema.Game<S, S>
+>(schema: S & ValidateFragments<[S]> & ValidateRequires<S>): Schema.Game<S, S>
 export function bind<
   S extends Schema.Any,
   const Name extends string
->(schema: S & ValidateFragments<[S]>, root: RootToken<Name>): Schema.Game<S, RootToken<Name>>
+>(schema: S & ValidateFragments<[S]> & ValidateRequires<S>, root: RootToken<Name>): Schema.Game<S, RootToken<Name>>
 export function bind<
   const Fragments extends readonly [Schema.Any, Schema.Any, ...Array<Schema.Any>]
->(...fragments: Fragments & ValidateFragments<Fragments>): Schema.Game<BuildFragments<Fragments>, BuildFragments<Fragments>>
+>(...fragments: Fragments & ValidateFragments<Fragments> & ValidateRequires<BuildFragments<Fragments>>): Schema.Game<BuildFragments<Fragments>, BuildFragments<Fragments>>
 export function bind<
   const Fragments extends readonly [Schema.Any, Schema.Any, ...Array<Schema.Any>],
   const Name extends string
->(...args: [...Fragments, RootToken<Name>] & ValidateFragments<Fragments>): Schema.Game<BuildFragments<Fragments>, RootToken<Name>>
+>(...args: [...Fragments, RootToken<Name>] & ValidateFragments<Fragments> & ValidateRequires<BuildFragments<Fragments>>): Schema.Game<BuildFragments<Fragments>, RootToken<Name>>
 export function bind(...args: ReadonlyArray<Schema.Any | RootToken>) {
   const maybeRoot = args[args.length - 1]
   const fragments = (isRootToken(maybeRoot) ? args.slice(0, -1) : args) as Array<Schema.Any>
@@ -298,7 +418,7 @@ type QuerySelectionAccess<S extends Schema.Any, Root> =
 
 interface BoundSystemAccess<S extends Schema.Any, Root> extends System.SystemAccessInput {
   readonly queries?: Record<string, Query.Any<Root>>
-  readonly resources?: Record<string, System.ResourceRead<ResourceDescriptor<S>> | System.ResourceWrite<ResourceDescriptor<S>>>
+  readonly resources?: Record<string, System.ResourceRead<ResourceDescriptor<S>> | System.ResourceChanged<ResourceDescriptor<S>> | System.ResourceWrite<ResourceDescriptor<S>>>
   readonly events?: Record<string, System.EventRead<EventDescriptor<S>> | System.EventWrite<EventDescriptor<S>>>
   readonly machines?: Record<string, Machine.MachineRead<Schema.BoundStateMachine<Root>>>
   readonly nextMachines?: Record<string, Machine.NextMachineWrite<Schema.BoundStateMachine<Root>>>
@@ -314,7 +434,7 @@ interface BoundSystemAccess<S extends Schema.Any, Root> extends System.SystemAcc
 
 interface BoundCheckAccess<S extends Schema.Any, Root> extends Condition.CheckAccessInput {
   readonly queries?: Record<string, Query.Any<Root>>
-  readonly resources?: Record<string, System.ResourceRead<ResourceDescriptor<S>>>
+  readonly resources?: Record<string, System.ResourceRead<ResourceDescriptor<S>> | System.ResourceChanged<ResourceDescriptor<S>> | System.ResourceWrite<ResourceDescriptor<S>>>
   readonly machines?: Record<string, Machine.MachineRead<Schema.BoundStateMachine<Root>>>
 }
 
@@ -337,6 +457,16 @@ type BoundScheduleEntry<S extends Schema.Any, Root> =
 type BoundTransitionEntry<S extends Schema.Any, Root> =
   Exclude<BoundScheduleEntry<S, Root>, Schedule.ApplyStateTransitionsStep<any, Root>>
 
+/**
+ * Rejects `applyDeferred()` in an exit phase (`onExit`, `onTransition`): the
+ * phase rolls back as one when a system in it fails, which applied commands
+ * could not. Nested schedules are checked when the schedule is built.
+ */
+type NoApplyDeferredInExit<Entries extends ReadonlyArray<unknown>> =
+  [Extract<Entries[number], Schedule.ApplyDeferredStep>] extends [never]
+    ? unknown
+    : { readonly __fixTransition__: typeof exitApplyDeferredMessage }
+
 type BoundTransitionScheduleResult<
   S extends Schema.Any,
   Root,
@@ -345,7 +475,8 @@ type BoundTransitionScheduleResult<
 > = Machine.TransitionScheduleDefinition<
   S,
   M,
-  Schedule.CompositionExactRequirements<Entries>,
+  // The machine itself: a transition schedule on a machine the runtime does not provide could never run.
+  Schedule.CompositionExactRequirements<Entries> | M,
   Root,
   Schedule.CompositionFailure<Entries>,
   Schedule.CompositionOrder<Entries>
@@ -376,12 +507,14 @@ export namespace Schema {
   /**
    * Any complete schema definition.
    */
-  export type Any = SchemaDefinition<Registry, Registry, Registry, Record<string, Relation.Relation.Any>>
+  export type Any = SchemaDefinition<Registry, Registry, Registry, Record<string, Relation.Relation.Any>, RequirementPair>
 
   export type Components<T extends Any> = T["components"]
   export type Resources<T extends Any> = T["resources"]
   export type Events<T extends Any> = T["events"]
   export type Relations<T extends Any> = T["relations"]
+  /** The component requirements of a schema, as `[requirer, required]` name pairs (`Schema.requires`). */
+  export type Requires<T extends Any> = T extends SchemaDefinition<any, any, any, any, infer Pairs> ? Pairs : never
 
   export type ComponentValue<T extends Any, K extends keyof Components<T>> = Descriptor.Value<Components<T>[K]>
   export type ResourceValue<T extends Any, K extends keyof Resources<T>> = Descriptor.Value<Resources<T>[K]>
@@ -434,8 +567,9 @@ export namespace Schema {
   export type BoundStateMachine<
     Root,
     Name extends string = string,
-    Values extends readonly [Machine.StateValue, ...Machine.StateValue[]] = readonly [Machine.StateValue, ...Machine.StateValue[]]
-  > = Machine.StateMachineDefinition<Name, Values, Root>
+    Values extends readonly [Machine.StateValue, ...Machine.StateValue[]] = readonly [Machine.StateValue, ...Machine.StateValue[]],
+    Parent = unknown
+  > = Machine.StateMachineDefinition<Name, Values, Root, Parent>
 
   export type BoundTransitionSchedule<
     S extends Any,
@@ -473,11 +607,38 @@ export namespace Schema {
     readonly schema: S
     /**
      * Creates a typed ownership scope for scene or level entities: a flat
-     * group despawned together with `commands.despawnScope(...)`. Use
-     * `Descriptor.Hierarchy` instead for a parent-child tree with ordered
-     * children, traversal, and recursive despawn.
+     * group whose members are spawned with `commands.spawnIn(...)` and
+     * despawned together. Use `Descriptor.Hierarchy` instead for a
+     * parent-child tree with ordered children, traversal, and recursive
+     * despawn.
+     *
+     * When the group lives exactly as long as a state, name the state change
+     * that ends it: `despawnOnExit: [Flow, "Playing"]` despawns every member
+     * when `applyStateTransitions(...)` commits leaving `Playing` (after its
+     * `onExit` schedules, which still see the members), and
+     * `despawnOnEnter: [Flow, "Playing"]` when it commits entering it (before
+     * its `onEnter` schedules, so what they spawn survives). Use
+     * `commands.despawnScope(...)` instead when the wipe is not tied to a
+     * state change. Scope names are unique per game.
+     *
+     * @example
+     * ```ts
+     * const RunScope = Game.EntityScope("Shooter/Run", { despawnOnExit: [Flow, "Playing"] })
+     * ```
      */
-    readonly EntityScope: <const Name extends string>(name: Name) => EntityScope.EntityScope<Name, Root>
+    readonly EntityScope: <
+      const Name extends string,
+      Enter extends Machine.StateMachine.Any = never,
+      Exit extends Machine.StateMachine.Any = never
+    >(
+      name: Name,
+      options?: {
+        /** Despawns every member when the machine enters this state, before its `onEnter` schedules run. */
+        readonly despawnOnEnter?: readonly [Enter & Machine.SameGame<Enter, Root>, Machine.StateMachine.Value<Enter>]
+        /** Despawns every member when the machine leaves this state, after its `onExit` schedules run. */
+        readonly despawnOnExit?: readonly [Exit & Machine.SameGame<Exit, Root>, Machine.StateMachine.Value<Exit>]
+      }
+    ) => EntityScope.EntityScope<Name, Root>
     /** Declares a reusable, requirement-checked read-only world projection. */
     readonly Inspector: <
       const Name extends string,
@@ -497,6 +658,13 @@ export namespace Schema {
         target: Entity.HandleTarget<S, Root>,
         intent?: D
       ) => Entity.Handle<Root, D>
+      /**
+       * The entity id a handle names, to compare with ids or pass where an id
+       * is expected (`queries.x.get(id)`), instead of storing the id beside
+       * the handle. Like the handle, it proves nothing about liveness:
+       * resolve it through a query. Two handles of the same entity are `===`.
+       */
+      id: (handle: Entity.Handle<Root, ComponentDescriptor<S> | undefined>) => Entity.EntityId<S, Root>
     }
     readonly Query: {
       <
@@ -511,7 +679,7 @@ export namespace Schema {
       >(spec: {
         readonly selection: Selection
         readonly with?: With
-        readonly without?: Without
+        readonly without?: Without & QueryModule.ExclusionsPossible<Selection, With, Without, Filters>
         readonly filters?: Filters
         readonly withRelations?: WithRelations
         readonly withoutRelations?: WithoutRelations
@@ -520,10 +688,17 @@ export namespace Schema {
         // Uninferred: an omitted list is `[]`, never inferred from the spec it is written in (`queries: { ... }`).
       }): QueryModule.QuerySpec<Selection, QueryModule.Uninferred<With, ReadonlyArray<ComponentDescriptor<S>>>, QueryModule.Uninferred<Without, ReadonlyArray<ComponentDescriptor<S>>>, QueryModule.Uninferred<Filters, ReadonlyArray<QueryModule.Filter<ComponentDescriptor<S>>>>, QueryModule.Uninferred<WithRelations, ReadonlyArray<Relation.Relation.Any>>, QueryModule.Uninferred<WithoutRelations, ReadonlyArray<Relation.Relation.Any>>, QueryModule.Uninferred<WithRelated, ReadonlyArray<Relation.Relation.Any>>, QueryModule.Uninferred<WithoutRelated, ReadonlyArray<Relation.Relation.Any>>, Root>
       read: <D extends ComponentDescriptor<S>>(descriptor: D) => QueryModule.ReadAccess<D>
-      write: <D extends ComponentDescriptor<S>>(descriptor: D) => QueryModule.WriteAccess<D>
+      write: <D extends ComponentDescriptor<S>>(descriptor: D & QueryModule.Writable<D>) => QueryModule.WriteAccess<D>
       optional: <D extends ComponentDescriptor<S>>(descriptor: D) => QueryModule.OptionalReadAccess<D>
       added: <D extends ComponentDescriptor<S>>(descriptor: D) => QueryModule.AddedFilter<D>
       changed: <D extends ComponentDescriptor<S>>(descriptor: D) => QueryModule.ChangedFilter<D>
+      anyOf: <
+        const Filters extends readonly [
+          QueryModule.LifecycleFilter<ComponentDescriptor<S>>,
+          QueryModule.LifecycleFilter<ComponentDescriptor<S>>,
+          ...ReadonlyArray<QueryModule.LifecycleFilter<ComponentDescriptor<S>>>
+        ]
+      >(...filters: Filters) => QueryModule.AnyOfFilter<Filters[number]["descriptor"]>
       readRelation: <R extends RelationDescriptor<S>>(descriptor: R) => Relation.RelationReadAccess<R, S, Root>
       optionalRelation: <R extends RelationDescriptor<S>>(descriptor: R) => Relation.OptionalRelationReadAccess<R, S, Root>
       readRelated: <R extends RelationDescriptor<S>>(descriptor: R) => Relation.RelatedReadAccess<R, S, Root>
@@ -538,20 +713,25 @@ export namespace Schema {
        * Adds entries to a draft (a value not yet spawned). Use
        * `commands.insert` for an entity that already exists.
        */
-      extend: <P extends Entity.ComponentProof, const Entries extends ReadonlyArray<Command.SpawnEntry<S>>>(
-        draft: Entity.EntityDraft<S, P, Root>,
+      extend: <P extends Entity.ComponentProof, const Entries extends ReadonlyArray<Command.SpawnEntry<S>>, Relates = never>(
+        draft: Entity.EntityDraft<S, P, Root, Relates>,
         ...entries: Entries
-      ) => Command.DraftFor<S, Entries, P, Root>
-      entry: <D extends ComponentDescriptor<S>>(descriptor: D, value: Descriptor.Value<D>) => Command.Entry<D>
+      ) => Command.DraftFor<S, Entries, P, Root, Relates>
+      entry: <D extends ComponentDescriptor<S>>(descriptor: D, value: QueryModule.ReadonlyValue<Descriptor.Value<D>>) => Command.Entry<D>
       entryRaw: <D extends Extract<ComponentDescriptor<S>, ConstructedDescriptor<"component", string, any, any, any>>>(
         descriptor: D,
         raw: Descriptor.Raw<D>
       ) => Result.Result<Command.Entry<D>, Descriptor.ConstructionError<D>>
-      relate: <P extends Entity.ComponentProof, R extends RelationDescriptor<S>>(
-        draft: Entity.EntityDraft<S, P, Root>,
+      /**
+       * Stages a relation on a draft, created with the spawn. Spawning the
+       * draft needs the relation in `Game.System.relates(...)`, like
+       * `commands.relate`.
+       */
+      relate: <P extends Entity.ComponentProof, R extends RelationDescriptor<S>, Relates = never>(
+        draft: Entity.EntityDraft<S, P, Root, Relates>,
         relation: R,
         target: Entity.EntityId<S, Root>
-      ) => Entity.EntityDraft<S, P, Root>
+      ) => Entity.EntityDraft<S, P, Root, Relates | R>
     }
     /**
      * Declares one game-wide mode (menu, playing, paused): queued with
@@ -564,10 +744,52 @@ export namespace Schema {
         const Name extends string,
         const Values extends readonly [Machine.StateValue, ...Machine.StateValue[]]
       >(name: Name, values: Values): Schema.BoundStateMachine<Root, Name, Values>
+      /**
+       * Declares a sub-state: a machine that exists only while `within[0]` is
+       * in state `within[1]` (a battle phase that only means something while
+       * playing). Whenever the parent enters that state, the sub-state enters
+       * the value given to `Game.Runtime.machine(...)`; when the parent leaves
+       * it, the sub-state exits and has no value: `get()` is `undefined`,
+       * `Game.Condition.inState(Sub, x)` is false, and `nextMachines.sub.set(...)`
+       * returns a `SubStateInactive` failure. So `inState(Sub, x)` alone
+       * implies the parent's state.
+       *
+       * The sub-state enters together with the parent's commit, before any
+       * `onEnter` schedule runs: the parent's `onEnter` systems already see its
+       * value, its `despawnOnEnter` scopes are cleared before they spawn, and
+       * a failing `onEnter` leaves it entered. Its own `onEnter` schedules
+       * run after the parent's.
+       *
+       * Use a second top-level machine instead when the two modes are
+       * independent (each keeps its value whatever the other does).
+       *
+       * @example
+       * ```ts
+       * const Phase = Game.StateMachine("Phase", ["Setup", "Battle"], { within: [Session, "Playing"] })
+       * ```
+       */
+      <
+        const Name extends string,
+        const Values extends readonly [Machine.StateValue, ...Machine.StateValue[]],
+        Parent extends Machine.StateMachine.Any
+      >(
+        name: Name,
+        values: Values,
+        options: { readonly within: readonly [Parent & Machine.SameGame<Parent, Root>, Machine.StateMachine.Value<Parent>] }
+      ): Schema.BoundStateMachine<Root, Name, Values, Parent>
     }
     readonly Condition: {
-      inState: typeof Machine.inState
-      stateChanged: typeof Machine.stateChanged
+      /**
+       * Passes while the machine's committed value is `value`. For a
+       * sub-state it fails while the parent is in another state. A machine
+       * of another game fails to compile with a message naming the fix.
+       */
+      inState: <M extends Machine.StateMachine.Any>(
+        machine: M & Machine.SameGame<M, Root>,
+        value: Machine.StateMachine.Value<M>
+      ) => Machine.InStateCondition<M>
+      /** Passes in the schedule run where `applyStateTransitions(...)` changed the machine. */
+      stateChanged: <M extends Machine.StateMachine.Any>(machine: M & Machine.SameGame<M, Root>) => Machine.StateChangedCondition<M>
       not: typeof Machine.not
       and: typeof Machine.and
       or: typeof Machine.or
@@ -594,6 +816,7 @@ export namespace Schema {
       ): BoundSystem<S, Root, System.SystemSpec<S, Access, Root>, E, Name, System.SystemAccessNeeds<Access>>
       readResource: <D extends ResourceDescriptor<S>>(descriptor: D) => System.ResourceRead<D>
       writeResource: <D extends ResourceDescriptor<S>>(descriptor: D) => System.ResourceWrite<D>
+      changedResource: <D extends ResourceDescriptor<S>>(descriptor: D) => System.ResourceChanged<D>
       readEvent: <D extends EventDescriptor<S>>(descriptor: D) => System.EventRead<D>
       writeEvent: <D extends EventDescriptor<S>>(descriptor: D) => System.EventWrite<D>
       /**
@@ -601,7 +824,7 @@ export namespace Schema {
        * same `runtime.tick(...)` call; checked at compile time by `tick`.
        * Accepts `readEvent(...)`, `readResource(...)`, or a query.
        */
-      thisTick: <Read extends System.EventRead<EventDescriptor<S>> | System.ResourceRead<ResourceDescriptor<S>> | Query.Any<Root>>(
+      thisTick: <Read extends System.EventRead<EventDescriptor<S>> | System.ResourceRead<ResourceDescriptor<S>> | System.ResourceChanged<ResourceDescriptor<S>> | Query.Any<Root>>(
         read: Read
       ) => Read & System.ThisTick
       service: typeof System.service
@@ -617,18 +840,21 @@ export namespace Schema {
        * `Game.System.commands(Game.System.spawns(Enemy, Position), Game.System.despawns(Enemy))`.
        */
       commands: typeof Command.commands
-      /** Allows spawning drafts whose components are all among these; see `Command.spawns`. */
-      spawns: <const Components extends ReadonlyArray<ComponentDescriptor<S>>>(...components: Components) => Command.Permission<"spawns", Components[number]>
+      /** Allows spawning drafts whose components are all among these and what they require (`Schema.requires`); see `Command.spawns`. */
+      spawns: <const Components extends NonEmpty<ComponentDescriptor<S>>>(...components: Components) => Command.Permission<"spawns", Components[number] | Command.RequiredDescriptors<S, Components[number]["name"]>>
       /** Allows `insert` (add or replace at the next `applyDeferred()`) of these; see `Command.inserts`. */
-      inserts: <const Components extends ReadonlyArray<ComponentDescriptor<S>>>(...components: Components) => Command.Permission<"inserts", Components[number]>
+      inserts: <const Components extends NonEmpty<ComponentDescriptor<S>>>(...components: Components) => Command.Permission<"inserts", Components[number]>
       /** Allows `remove` of these. */
-      removes: <const Components extends ReadonlyArray<ComponentDescriptor<S>>>(...components: Components) => Command.Permission<"removes", Components[number]>
+      removes: <const Components extends NonEmpty<ComponentDescriptor<S>>>(...components: Components) => Command.Permission<"removes", Components[number]>
       /** Allows `despawn` of entities a query proves have one of these; see `Command.despawns`. */
-      despawns: <const Components extends ReadonlyArray<ComponentDescriptor<S>>>(...components: Components) => Command.Permission<"despawns", Components[number]>
+      despawns: <const Components extends NonEmpty<ComponentDescriptor<S>>>(...components: Components) => Command.Permission<"despawns", Components[number]>
       /** Allows `despawnScope` of this scope. */
       despawnsScope: <const Scope extends EntityScope.EntityScope<string, Root>>(scope: Scope) => Command.Permission<"despawnsScope", Scope>
-      /** Allows `relate`, `unrelate`, and `reorderChildren` of these relations. */
-      relates: <const Relations extends ReadonlyArray<RelationDescriptor<S>>>(...relations: Relations) => Command.Permission<"relates", Relations[number]>
+      /**
+       * Allows `relate`, `unrelate`, and `reorderChildren` of these relations,
+       * and spawning drafts that stage them with `Game.Command.relate(...)`.
+       */
+      relates: <const Relations extends NonEmpty<RelationDescriptor<S>>>(...relations: Relations) => Command.Permission<"relates", Relations[number]>
     }
     readonly Schedule: {
       /**
@@ -646,20 +872,31 @@ export namespace Schema {
         state: Machine.StateMachine.Value<M>,
         plan: readonly [...Entries]
       ) => BoundTransitionScheduleResult<S, Root, M, Entries>
+      /**
+       * Systems run when `machine` leaves `state`. The exit phase of one
+       * transition (the exit schedules of the sub-states it ends, then of
+       * `state`, then `onTransition`) is one transaction: when a system in it
+       * fails, everything the phase did is undone (except `local`) and the
+       * transition stays queued, so the next attempt starts from the same
+       * state. Its commands are applied at the next `applyDeferred()` after
+       * the marker, so it cannot contain `applyDeferred()` itself.
+       */
       onExit: <M extends BoundStateMachine<Root>, const Entries extends ReadonlyArray<BoundTransitionEntry<S, Root>>>(
         machine: M,
         state: Machine.StateMachine.Value<M>,
-        plan: readonly [...Entries]
+        plan: readonly [...Entries] & NoApplyDeferredInExit<Entries>
       ) => BoundTransitionScheduleResult<S, Root, M, Entries>
+      /** Systems run on one `[from, to]` transition, last in its exit phase (see `onExit`). */
       onTransition: <M extends BoundStateMachine<Root>, const Entries extends ReadonlyArray<BoundTransitionEntry<S, Root>>>(
         machine: M,
         transition: readonly [Machine.StateMachine.Value<M>, Machine.StateMachine.Value<M>],
-        plan: readonly [...Entries]
+        plan: readonly [...Entries] & NoApplyDeferredInExit<Entries>
       ) => BoundTransitionScheduleResult<S, Root, M, Entries>
       /**
        * Builds a schedule whose systems run only while every condition
        * passes (in addition to their own `when`). Nested schedules are
-       * gated too; marker steps still run. Gated systems drop the events
+       * gated too; marker steps still run, and so do the transition schedules
+       * an `applyStateTransitions(bundle)` in the group runs. Gated systems drop the events
        * published while gated; use `pauseWhen` to keep them. For one system,
        * use `when` in its spec.
        */
@@ -691,8 +928,9 @@ export namespace Schema {
     }
     readonly Runtime: {
       /**
-       * Builds a runtime. Returns a `Result` exactly when a provided resource
-       * goes through a constructed descriptor and can fail validation.
+       * Builds a runtime. Always returns a `Result`: a `Success` (read
+       * `.value`) when nothing provided can fail, and a `Result` to check
+       * when a provided resource goes through a constructed descriptor.
        */
       make: <
         const ProvidedServices extends Runtime.RuntimeServices<any>,
@@ -701,10 +939,12 @@ export namespace Schema {
         const Enabled extends Debug.Option | undefined = undefined
       >(options: {
         readonly services: ProvidedServices
-        readonly resources?: Resources
+        readonly resources?: Resources & Runtime.ExactResources<S, Resources>
         readonly machines?: ProvidedMachines
         /** Attaches a `debug` handle to the runtime; see the `Debug` module. */
         readonly debug?: Enabled
+        /** The game's save migrations (`Snapshot.migrations`): `restore` upgrades older saves with them. */
+        readonly saves?: Snapshot.Migrations
       }) => Runtime.MakeRuntimeResult<S, RuntimeServicesOf<ProvidedServices>, Resources, Root, RuntimeMachinesOf<ProvidedMachines>, Enabled>
       service: typeof Runtime.service
       services: typeof Runtime.services