@typeonce/ritmo 0.7.0 → 0.9.0

package/dist/Schema.d.ts

@@ -53,6 +53,7 @@ import type * as Command from "./Command.ts";
 import type { ConstructedDescriptor, Descriptor } from "./Descriptor.ts";
 import type * as Entity from "./Entity.ts";
 import type * as EntityScope from "./EntityScope.ts";
+import { type exitApplyDeferredMessage } 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";
@@ -64,21 +65,89 @@ 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";
 /**
  * A mapping from schema keys to nominal descriptors.
  */
 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> = {}> {
+export interface SchemaDefinition<out Components extends Registry = {}, out Resources extends Registry = {}, out Events extends Registry = {}, 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 declare const requires: <D extends AnyComponentDescriptor, const Required extends readonly [AnyComponentDescriptor, ...Array<AnyComponentDescriptor>]>(component: D, ...required: Required) => ComponentRequirement<RequirementPairs<D["name"], Required[number]["name"]>>;
 declare const schemaRootTypeId: "~ritmo/SchemaRoot";
 export type RootToken<Name extends string = string> = {
     readonly kind: "SchemaRoot";
@@ -87,7 +156,7 @@ export type RootToken<Name extends string = string> = {
         readonly _Name: (_: never) => Name;
     };
 };
-export type MergeSchemaDefinitions<A extends Schema.Any, B extends Schema.Any> = SchemaDefinition<Schema.Components<A> & Schema.Components<B>, Schema.Resources<A> & Schema.Resources<B>, Schema.Events<A> & Schema.Events<B>, Schema.Relations<A> & Schema.Relations<B>>;
+export type MergeSchemaDefinitions<A extends Schema.Any, B extends Schema.Any> = SchemaDefinition<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.Requires<A> | Schema.Requires<B>>;
 /**
  * Type-level fold for fragment composition.
  */
@@ -135,6 +204,24 @@ export type ValidateFragments<Fragments extends ReadonlyArray<Schema.Any>> = [
 ] extends [never] ? unknown : {
     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.
  *
@@ -151,10 +238,6 @@ export type ValidateFragments<Fragments extends ReadonlyArray<Schema.Any>> = [
  * ```
  */
 export declare const defineRoot: <const Name extends string>(name: Name) => RootToken<Name>;
-/**
- * Creates an empty schema.
- */
-export declare const empty: () => SchemaDefinition;
 /**
  * Creates a schema fragment.
  *
@@ -165,17 +248,19 @@ export declare const empty: () => SchemaDefinition;
  * @example
  * ```ts
  * const Combat = Schema.fragment({
- *   components: { Health, Damage },
- *   events: { Hit }
+ *   components: { Health, Damage, Enemy },
+ *   events: { Hit },
+ *   requires: [Schema.requires(Enemy, Health)]
  * })
  * ```
  */
-export declare const fragment: <const Components extends Registry = {}, const Resources extends Registry = {}, const Events extends Registry = {}, const Relations extends Record<string, Relation.Relation.Any> = {}>(definition: {
-    readonly components?: Components;
-    readonly resources?: Resources;
-    readonly events?: Events;
+export declare const fragment: <const Components extends Registry = {}, const Resources extends Registry = {}, const Events extends Registry = {}, const Relations extends Record<string, Relation.Relation.Any> = {}, const Requires extends ReadonlyArray<ComponentRequirement> = readonly []>(definition: {
+    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]>>;
 /**
  * Composes one or more fragments and returns one bound `Game` surface.
  *
@@ -189,10 +274,10 @@ export declare const fragment: <const Components extends Registry = {}, const Re
  * const Game = Schema.bind(Core, Combat, Root)
  * ```
  */
-export declare function bind<S extends Schema.Any>(schema: S & ValidateFragments<[S]>): Schema.Game<S, S>;
-export declare function bind<S extends Schema.Any, const Name extends string>(schema: S & ValidateFragments<[S]>, root: RootToken<Name>): Schema.Game<S, RootToken<Name>>;
-export declare function bind<const Fragments extends readonly [Schema.Any, Schema.Any, ...Array<Schema.Any>]>(...fragments: Fragments & ValidateFragments<Fragments>): Schema.Game<BuildFragments<Fragments>, BuildFragments<Fragments>>;
-export declare 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>>;
+export declare function bind<S extends Schema.Any>(schema: S & ValidateFragments<[S]> & ValidateRequires<S>): Schema.Game<S, S>;
+export declare function bind<S extends Schema.Any, const Name extends string>(schema: S & ValidateFragments<[S]> & ValidateRequires<S>, root: RootToken<Name>): Schema.Game<S, RootToken<Name>>;
+export declare function bind<const Fragments extends readonly [Schema.Any, Schema.Any, ...Array<Schema.Any>]>(...fragments: Fragments & ValidateFragments<Fragments> & ValidateRequires<BuildFragments<Fragments>>): Schema.Game<BuildFragments<Fragments>, BuildFragments<Fragments>>;
+export declare function bind<const Fragments extends readonly [Schema.Any, Schema.Any, ...Array<Schema.Any>], const Name extends string>(...args: [...Fragments, RootToken<Name>] & ValidateFragments<Fragments> & ValidateRequires<BuildFragments<Fragments>>): Schema.Game<BuildFragments<Fragments>, RootToken<Name>>;
 type RuntimeServicesOf<Provided extends Runtime.RuntimeServices<any>> = [
     Provided
 ] extends [Runtime.RuntimeServices<infer Services>] ? Services : never;
@@ -206,7 +291,7 @@ type RelationDescriptor<S extends Schema.Any> = Schema.RelationDescriptor<S>;
 type QuerySelectionAccess<S extends Schema.Any, Root> = QueryModule.Access<ComponentDescriptor<S>> | Relation.SelectionAccess<S, 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>>>;
@@ -221,7 +306,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>>>;
 }
 interface BoundInspectorAccess<S extends Schema.Any, Root> extends Inspector.InspectorAccessInput {
@@ -235,7 +320,17 @@ interface BoundInspectorAccess<S extends Schema.Any, Root> extends Inspector.Ins
 }
 type BoundScheduleEntry<S extends Schema.Any, Root> = Schema.BoundSystem<S, Root, any, any> | Schedule.ApplyDeferredStep | Schedule.ApplyStateTransitionsStep<any, Root> | Schedule.ScheduleDefinition<S, any, Root, any, any, Schedule.AnyScheduleOrder>;
 type BoundTransitionEntry<S extends Schema.Any, Root> = Exclude<BoundScheduleEntry<S, Root>, Schedule.ApplyStateTransitionsStep<any, Root>>;
-type BoundTransitionScheduleResult<S extends Schema.Any, Root, M extends Schema.BoundStateMachine<Root>, Entries extends ReadonlyArray<BoundTransitionEntry<S, Root>>> = Machine.TransitionScheduleDefinition<S, M, Schedule.CompositionExactRequirements<Entries>, Root, Schedule.CompositionFailure<Entries>, Schedule.CompositionOrder<Entries>>;
+/**
+ * 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, M extends Schema.BoundStateMachine<Root>, Entries extends ReadonlyArray<BoundTransitionEntry<S, Root>>> = Machine.TransitionScheduleDefinition<S, M, Schedule.CompositionExactRequirements<Entries> | M, Root, Schedule.CompositionFailure<Entries>, Schedule.CompositionOrder<Entries>>;
 type BoundTransitionBundleInput<S extends Schema.Any, Root> = Schema.BoundTransitionSchedule<S, Root, any, any, any> | Schema.BoundTransitionBundle<S, Root, any, any, any>;
 type BoundTransitionBundleResult<S extends Schema.Any, Root, Entries extends ReadonlyArray<BoundTransitionBundleInput<S, Root>>> = Schedule.TransitionBundleDefinition<S, ReadonlyArray<Schedule.FlattenTransitionEntries<Entries>[number]>, Schedule.TransitionBundleRequirements<Schedule.FlattenTransitionEntries<Entries>>, Root, Schedule.TransitionBundleRequirements<Schedule.FlattenTransitionEntries<Entries>>, Schedule.TransitionBundleFailure<Schedule.FlattenTransitionEntries<Entries>>, Schedule.CompositionOrder<Entries>>;
 /**
@@ -245,11 +340,13 @@ export declare namespace Schema {
     /**
      * Any complete schema definition.
      */
-    type Any = SchemaDefinition<Registry, Registry, Registry, Record<string, Relation.Relation.Any>>;
+    type Any = SchemaDefinition<Registry, Registry, Registry, Record<string, Relation.Relation.Any>, RequirementPair>;
     type Components<T extends Any> = T["components"];
     type Resources<T extends Any> = T["resources"];
     type Events<T extends Any> = T["events"];
     type Relations<T extends Any> = T["relations"];
+    /** The component requirements of a schema, as `[requirer, required]` name pairs (`Schema.requires`). */
+    type Requires<T extends Any> = T extends SchemaDefinition<any, any, any, any, infer Pairs> ? Pairs : never;
     type ComponentValue<T extends Any, K extends keyof Components<T>> = Descriptor.Value<Components<T>[K]>;
     type ResourceValue<T extends Any, K extends keyof Resources<T>> = Descriptor.Value<Resources<T>[K]>;
     type EventValue<T extends Any, K extends keyof Events<T>> = Descriptor.Value<Events<T>[K]>;
@@ -278,7 +375,7 @@ export declare namespace Schema {
     /**
      * A schema-bound finite-state machine.
      */
-    type BoundStateMachine<Root, Name extends string = string, Values extends readonly [Machine.StateValue, ...Machine.StateValue[]] = readonly [Machine.StateValue, ...Machine.StateValue[]]> = Machine.StateMachineDefinition<Name, Values, Root>;
+    type BoundStateMachine<Root, Name extends string = string, Values extends readonly [Machine.StateValue, ...Machine.StateValue[]] = readonly [Machine.StateValue, ...Machine.StateValue[]], Parent = unknown> = Machine.StateMachineDefinition<Name, Values, Root, Parent>;
     type BoundTransitionSchedule<S extends Any, Root, M extends BoundStateMachine<Root> = BoundStateMachine<Root>, Needs extends Requirement.Requirement = Requirement.Requirement, Failure extends System.SystemFailure = never, Order extends Schedule.AnyScheduleOrder = Schedule.AnyScheduleOrder> = Machine.TransitionScheduleDefinition<S, M, Needs, Root, Failure, Order>;
     type BoundTransitionBundle<S extends Any, Root, Entries extends ReadonlyArray<BoundTransitionSchedule<S, Root, any, any, any>> = ReadonlyArray<BoundTransitionSchedule<S, Root, any, any, any>>, Needs extends Requirement.Requirement = Requirement.Requirement, Failure extends System.SystemFailure = never, Order extends Schedule.AnyScheduleOrder = Schedule.AnyScheduleOrder> = Schedule.TransitionBundleDefinition<S, Entries, Needs, Root, Needs, Failure, Order>;
     /**
@@ -292,11 +389,31 @@ export declare 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, const Access extends BoundInspectorAccess<S, Root>, Value>(name: Name, spec: Inspector.ExactInspectorAccess<Access>, read: (context: Inspector.InspectorContext<System.SystemSpec<S, Access, Root>>) => Value) => BoundInspector<S, Root, System.SystemSpec<S, Access, Root>, Value, Name, System.SystemAccessNeeds<Access>>;
         readonly Entity: {
@@ -305,12 +422,19 @@ export declare namespace Schema {
              * with an intent component that later resolution must prove.
              */
             handle: <const D extends ComponentDescriptor<S> | undefined = undefined>(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: {
             <const Selection extends Record<string, QuerySelectionAccess<S, Root>>, const With extends ReadonlyArray<ComponentDescriptor<S>> = [], const Without extends ReadonlyArray<ComponentDescriptor<S>> = [], const Filters extends ReadonlyArray<QueryModule.Filter<ComponentDescriptor<S>>> = [], const WithRelations extends ReadonlyArray<RelationDescriptor<S>> = [], const WithoutRelations extends ReadonlyArray<RelationDescriptor<S>> = [], const WithRelated extends ReadonlyArray<RelationDescriptor<S>> = [], const WithoutRelated extends ReadonlyArray<RelationDescriptor<S>> = []>(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;
@@ -318,10 +442,15 @@ export declare namespace Schema {
                 readonly withoutRelated?: WithoutRelated;
             }): 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>;
@@ -334,10 +463,15 @@ export declare 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>, ...entries: Entries) => Command.DraftFor<S, Entries, P, Root>;
-            entry: <D extends ComponentDescriptor<S>>(descriptor: D, value: Descriptor.Value<D>) => Command.Entry<D>;
+            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, 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>, relation: R, target: Entity.EntityId<S, Root>) => 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, Relates | R>;
         };
         /**
          * Declares one game-wide mode (menu, playing, paused): queued with
@@ -347,10 +481,43 @@ export declare namespace Schema {
          */
         readonly StateMachine: {
             <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;
@@ -365,6 +532,7 @@ export declare namespace Schema {
             <const Name extends string, const Access extends BoundSystemAccess<S, Root>, E = never>(name: Name, spec: System.ExactAccess<Access>, run: System.SystemRun<System.SystemSpec<S, Access, Root>, E>): 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>;
             /**
@@ -372,7 +540,7 @@ export declare 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>>(read: Read) => Read & System.ThisTick;
+            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;
             machine: <M extends BoundStateMachine<Root>>(machine: M) => Machine.MachineRead<M>;
             nextState: <M extends BoundStateMachine<Root>>(machine: M) => Machine.NextMachineWrite<M>;
@@ -386,18 +554,21 @@ export declare 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: {
             /**
@@ -407,12 +578,23 @@ export declare namespace Schema {
             <const Entries extends ReadonlyArray<BoundScheduleEntry<S, Root>>>(...entries: Entries): Schedule.AnonymousScheduleBuildFor<S, Entries, Root>;
             transitions: <const Entries extends ReadonlyArray<BoundTransitionBundleInput<S, Root>>>(...entries: Entries) => BoundTransitionBundleResult<S, Root, Entries>;
             onEnter: <M extends BoundStateMachine<Root>, const Entries extends ReadonlyArray<BoundTransitionEntry<S, Root>>>(machine: M, state: Machine.StateMachine.Value<M>, plan: readonly [...Entries]) => BoundTransitionScheduleResult<S, Root, M, Entries>;
-            onExit: <M extends BoundStateMachine<Root>, const Entries extends ReadonlyArray<BoundTransitionEntry<S, Root>>>(machine: M, state: Machine.StateMachine.Value<M>, plan: readonly [...Entries]) => BoundTransitionScheduleResult<S, Root, M, Entries>;
-            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]) => 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] & 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] & 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.
              */
@@ -430,15 +612,18 @@ export declare 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>, const Resources extends Runtime.RuntimeResources<S> = {}, const ProvidedMachines extends Runtime.RuntimeMachines<any> = Runtime.RuntimeMachines<{}>, 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;