@typeonce/ritmo 0.8.0 → 0.9.0

package/src/Schedule.ts

@@ -147,10 +147,12 @@ export type CompositionOrder<Entries extends ReadonlyArray<unknown>> = ScheduleO
 // walks back from the reader to the nearest marker, which is usually close.
 
 /** An event or resource read. */
-interface DataRead<Kind, Key, Reader> {
+interface DataRead<Kind, Key, Reader, ReaderSystem> {
   readonly kind: Kind
   readonly key: Key
   readonly reader: Reader
+  /** The reader itself: systems may share a display name, so writers are told apart by type. */
+  readonly readerSystem: ReaderSystem
 }
 
 /**
@@ -158,19 +160,24 @@ interface DataRead<Kind, Key, Reader> {
  * component it names (`Named`: selection slots, optional ones included,
  * `with`, `without`, and filters).
  */
-interface QueryRead<Slot, Required, Named, Reader> {
+interface QueryRead<Slot, Required, Named, Reader, ReaderSystem> {
   readonly kind: "query"
   readonly slot: Slot
   readonly required: Required
   readonly named: Named
   readonly reader: Reader
+  readonly readerSystem: ReaderSystem
 }
 
 type DescriptorKind<D> = D extends { readonly kind: infer Kind } ? Kind : never
 
 type Names<D> = D extends { readonly name: infer Name extends string } ? Name : never
 
-type DescriptorsOf<Access> = Access extends { readonly descriptor: infer D } ? D : never
+type DescriptorsOf<Access> =
+  Access extends { readonly descriptor: infer D } ? D
+  // A Query.anyOf filter names the components of its member filters.
+  : Access extends { readonly kind: "anyOf"; readonly filters: ReadonlyArray<infer Member> } ? DescriptorsOf<Member>
+  : never
 
 /** Every system an entry runs, nested schedules and transition bundles included, as a union. */
 type SystemsIn<Entry> =
@@ -179,13 +186,14 @@ type SystemsIn<Entry> =
     ? [Order] extends [never] ? never : SystemsIn<Order["entries"][number]>
     : never
 
-type QueryReadOf<Slot, Q, Reader> =
+type QueryReadOf<Slot, Q, Reader, ReaderSystem> =
   Q extends { readonly selection: infer Selection; readonly with: infer With extends ReadonlyArray<unknown>; readonly without: infer Without extends ReadonlyArray<unknown>; readonly filters: infer Filters extends ReadonlyArray<unknown> }
     ? QueryRead<
         Slot,
         Names<{ readonly [K in keyof Selection]: Selection[K] extends { readonly mode: "read" | "write"; readonly descriptor: infer D } ? D : never }[keyof Selection] | With[number]>,
         Names<DescriptorsOf<Selection[keyof Selection]> | With[number] | Without[number] | DescriptorsOf<Filters[number]>>,
-        Reader
+        Reader,
+        ReaderSystem
       >
     : never
 
@@ -195,19 +203,22 @@ type SystemReads<Sys> =
       :
         | (Extract<SpecAccessValues<Sys["spec"]>, ThisTick> extends infer Access
           ? Access extends { readonly descriptor: infer D extends { readonly name: string } }
-            ? DataRead<DescriptorKind<D>, D["name"], Sys["name"]>
+            ? DataRead<DescriptorKind<D>, D["name"], Sys["name"], Sys>
             : never
           : never)
         | (Sys["spec"] extends { readonly queries: infer Queries }
-          ? { readonly [K in keyof Queries]: Queries[K] extends ThisTick ? QueryReadOf<K, Queries[K], Sys["name"]> : never }[keyof Queries]
+          ? { readonly [K in keyof Queries]: Queries[K] extends ThisTick ? QueryReadOf<K, Queries[K], Sys["name"], Sys> : never }[keyof Queries]
           : never)
     : never
 
-/** Names of the systems among `Systems` that write `Key` (other than `Reader`). */
-type WritersOf<Systems, Kind, Key, Reader> =
+/** Whether two system types are the same system (mutually assignable): a shared display name is not enough. */
+type SameSystem<A, B> = [A] extends [B] ? [B] extends [A] ? true : false : false
+
+/** Names of the systems among `Systems` that write `Key` (other than the reader itself). */
+type WritersOf<Systems, Kind, Key, ReaderSystem> =
   Systems extends AnySystem
     ? IsErased<Systems["spec"]> extends true ? never
-      : Systems["name"] extends Reader ? never
+      : SameSystem<Systems, ReaderSystem> extends true ? never
       : [Extract<SpecAccessValues<Systems["spec"]>, { readonly mode: "write"; readonly descriptor: { readonly kind: Kind; readonly name: Key } }>] extends [never]
         ? never
         : Systems["name"]
@@ -233,18 +244,18 @@ type CommandNames<Commands> =
     : readonly [never, never]
 
 /** Names of the systems among `Systems` whose commands count for a query read (other than its reader). */
-type CommandWritersOf<Systems, Required, Named, Reader> =
+type CommandWritersOf<Systems, Required, Named, ReaderSystem> =
   Systems extends AnySystem
     ? IsErased<Systems["spec"]> extends true ? never
-      : Systems["name"] extends Reader ? never
+      : SameSystem<Systems, ReaderSystem> extends true ? never
       : Systems["spec"] extends { readonly commands: infer Commands }
         ? CommandsCount<Commands, Required, Named> extends true ? Systems["name"] : never
         : never
     : never
 
 type WritersFor<Systems, R> =
-  R extends QueryRead<any, infer Required, infer Named, infer Reader> ? CommandWritersOf<Systems, Required, Named, Reader>
-  : R extends DataRead<infer Kind, infer Key, infer Reader> ? WritersOf<Systems, Kind, Key, Reader>
+  R extends QueryRead<any, infer Required, infer Named, any, infer ReaderSystem> ? CommandWritersOf<Systems, Required, Named, ReaderSystem>
+  : R extends DataRead<infer Kind, infer Key, any, infer ReaderSystem> ? WritersOf<Systems, Kind, Key, ReaderSystem>
   : never
 
 /**
@@ -288,16 +299,16 @@ type ReaderIndices<Entries extends ReadonlyArray<unknown>, Reader> = {
 
 type LateWriterError<R, Writer> =
   Writer extends string
-    ? R extends QueryRead<infer Slot extends string, any, any, infer Reader extends string>
+    ? R extends QueryRead<infer Slot extends string, any, any, infer Reader extends string, any>
       ? `${Writer} queues commands that ${Reader} needs this tick (queries.${Slot}), but it runs after ${Reader}: move ${Writer} before the applyDeferred() that precedes ${Reader}, or read queries.${Slot} without thisTick`
-      : R extends DataRead<any, infer Key extends string, infer Reader extends string>
+      : R extends DataRead<any, infer Key extends string, infer Reader extends string, any>
         ? `${Reader} needs ${Key} from this tick, but its writer ${Writer} runs after it: move ${Writer} before ${Reader}, or read ${Key} without thisTick`
         : never
     : never
 
 type UnflushedWriterError<R, Writer> =
   Writer extends string
-    ? R extends QueryRead<infer Slot extends string, any, any, infer Reader extends string>
+    ? R extends QueryRead<infer Slot extends string, any, any, infer Reader extends string, any>
       ? `${Reader} needs this tick's commands for queries.${Slot}, but ${Writer} queues them with no applyDeferred() in between: add Game.Schedule.applyDeferred() after ${Writer}`
       : never
     : never
@@ -371,7 +382,7 @@ type TailSegment<Entries, Acc = never> =
     : readonly [Acc, false]
 
 type UnflushedWriters<Entries, R, Reader extends string> =
-  R extends QueryRead<any, any, any, any>
+  R extends QueryRead<any, any, any, any, any>
     ? Segment<Entries, Reader> extends infer Found
       ? Found extends readonly [infer Systems, any] ? UnflushedWriterError<R, WritersFor<Systems, R>> : never
       : never
@@ -656,7 +667,8 @@ export const make = <S extends Schema.Any, const Entries extends ReadonlyArray<S
  *
  * Conditions gate every system in `entries`, nested schedules included.
  * Marker steps (`applyDeferred`, `applyStateTransitions`) in the group still
- * run. A gated system is the same system as far as the runtime is concerned:
+ * run, and so do the transition schedules an `applyStateTransitions(bundle)`
+ * in the group runs: gate those systems in their own specs. A gated system is the same system as far as the runtime is concerned:
  * it shares change detection and event cursors with the original and with
  * any other gated copy, so using one system in two groups of one schedule is
  * a duplicate like any other.

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,6 +74,27 @@ 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, and the component requirements (`Schema.requires`) every
@@ -133,6 +155,10 @@ type PairsOf<R> = R extends ComponentRequirement<infer Pairs> ? Pairs : never
  * 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({
@@ -250,17 +276,33 @@ export type ValidateFragments<Fragments extends ReadonlyArray<Schema.Any>> =
 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. Erased schemas (`Schema.Any`) are checked by `bind` at
- * runtime instead.
+ * 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> =
-  [UnregisteredRequirements<S>] extends [never]
-    ? unknown
-    : string extends Schema.Requires<S>[1]
+  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`
       }
@@ -288,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.
  *
@@ -316,9 +353,9 @@ export const fragment = <
   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
   readonly requires?: Requires
 } & ValidateFragments<[SchemaDefinition<Components, Resources, Events, Relations>]>): SchemaDefinition<Components, Resources, Events, Relations, PairsOf<Requires[number]>> =>
@@ -420,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,
@@ -428,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>
@@ -610,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: {
       <
@@ -624,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
@@ -658,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
@@ -694,6 +754,12 @@ export namespace Schema {
        * 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).
        *
@@ -775,17 +841,20 @@ export namespace Schema {
        */
       commands: typeof Command.commands
       /** Allows spawning drafts whose components are all among these and what they require (`Schema.requires`); see `Command.spawns`. */
-      spawns: <const Components extends ReadonlyArray<ComponentDescriptor<S>>>(...components: Components) => Command.Permission<"spawns", Components[number] | Command.RequiredDescriptors<S, Components[number]["name"]>>
+      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: {
       /**
@@ -803,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.
        */
@@ -848,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>,
@@ -858,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

package/src/Snapshot.ts

@@ -24,10 +24,17 @@
  *
  * Restoring despawns every current entity and spawns the saved ones with their
  * original ids, so change detection and renderer sync see a restore as normal
- * despawns and spawns. Pending commands and events are dropped. Transient
+ * despawns and spawns. Pending commands and events emitted by systems are
+ * dropped; events the host sent with `runtime.send` and no system has read
+ * yet are kept, since they are input that has not been handled. Transient
  * components are absent from restored entities; transient resources keep their
  * current value.
  *
+ * When the game's save format changes, give the runtime its migrations
+ * (`Game.Runtime.make({ saves: Snapshot.migrations(...) })`): saves carry a
+ * `gameVersion`, and `restore` upgrades older ones step by step before
+ * validating them.
+ *
  * @module Snapshot
  * @docGroup runtime
  *
@@ -90,6 +97,12 @@ export const version = 2
 
 export interface WorldSnapshot {
   readonly version: typeof version
+  /**
+   * The game's own save version: the last `Snapshot.migration` the runtime
+   * that wrote it was given (0 without migrations, and for saves written
+   * before game versions existed).
+   */
+  readonly gameVersion: number
   /** The next id the runtime will allocate. */
   readonly nextEntity: number
   readonly entities: ReadonlyArray<EntitySnapshot>
@@ -113,6 +126,8 @@ export interface WorldSnapshot {
 export type RestoreError =
   | { readonly _tag: "InvalidSnapshot"; readonly path: string }
   | { readonly _tag: "UnsupportedVersion"; readonly version: unknown }
+  /** A save written by a newer game than this runtime's migrations reach. */
+  | { readonly _tag: "NewerGameVersion"; readonly gameVersion: number; readonly latest: number }
   | { readonly _tag: "UnknownComponent"; readonly entityId: number; readonly name: string }
   | { readonly _tag: "InvalidComponent"; readonly entityId: number; readonly name: string; readonly error: unknown }
   /** A saved entity holds `requiredBy` but lacks `name`, which `Schema.requires` says it needs. */
@@ -126,6 +141,8 @@ export type RestoreError =
   /** A saved sub-state value while its parent machine is not in the state the sub-state exists in. */
   | { readonly _tag: "InactiveSubState"; readonly name: string; readonly parent: string; readonly requires: unknown }
   | { readonly _tag: "DuplicateEntity"; readonly entityId: number }
+  /** A scope name that no `Game.EntityScope(...)` of this game defines. */
+  | { readonly _tag: "UnknownScope"; readonly name: string }
   /** A scope member that is not a saved entity, or is already in another scope. */
   | { readonly _tag: "InvalidScope"; readonly name: string; readonly entityId: number }
   | { readonly _tag: "UnvalidatedDescriptor"; readonly name: string }
@@ -145,6 +162,8 @@ const invalid = (path: string) => Result.failure<RestoreError>({ _tag: "InvalidS
 export const parse = (data: unknown): Result.Result<WorldSnapshot, RestoreError> => {
   if (!isRecord(data)) return invalid("$")
   if (data["version"] !== version) return Result.failure({ _tag: "UnsupportedVersion", version: data["version"] })
+  const gameVersion = data["gameVersion"] ?? 0
+  if (typeof gameVersion !== "number" || !Number.isSafeInteger(gameVersion) || gameVersion < 0) return invalid("$.gameVersion")
   if (!isEntityId(data["nextEntity"])) return invalid("$.nextEntity")
   const entities = data["entities"]
   if (!Array.isArray(entities)) return invalid("$.entities")
@@ -176,5 +195,74 @@ export const parse = (data: unknown): Result.Result<WorldSnapshot, RestoreError>
   for (const [name, members] of Object.entries(scopes)) {
     if (!Array.isArray(members) || !members.every(isEntityId)) return invalid(`$.scopes.${name}`)
   }
-  return Result.success(data as unknown as WorldSnapshot)
+  return Result.success({ ...data, gameVersion } as unknown as WorldSnapshot)
+}
+
+/**
+ * One step of a game's save format: turns a save of version `to - 1` into
+ * version `to`. A pure function on the save's plain data, tested like one.
+ */
+export interface Migration<To extends number = number> {
+  readonly to: To
+  readonly migrate: (save: WorldSnapshot) => WorldSnapshot
+}
+
+/** A game's save migrations, given to `Game.Runtime.make({ saves })`. Built with {@link migrations}. */
+export interface Migrations<Latest extends number = number> {
+  readonly kind: "SnapshotMigrations"
+  /** The game version `snapshot()` writes. */
+  readonly latest: Latest
+  readonly steps: ReadonlyArray<Migration>
+}
+
+/**
+ * Declares the step that upgrades saves to game version `to` (from `to - 1`).
+ *
+ * @example
+ * ```ts
+ * Snapshot.migration(2, (save) => ({ ...save, resources: { ...save.resources, "Town/Gold": 0 } }))
+ * ```
+ */
+export const migration = <const To extends number>(to: To, migrate: (save: WorldSnapshot) => WorldSnapshot): Migration<To> => ({ to, migrate })
+
+type Last<Steps> = Steps extends readonly [...Array<unknown>, infer L extends Migration] ? L["to"] : number
+
+/** `unknown` when the steps are numbered 1, 2, 3, ... in order; otherwise the message naming the misplaced one. */
+type Consecutive<Steps, Count extends Array<0> = []> =
+  Steps extends readonly [infer Head extends Migration, ...infer Tail]
+    ? number extends Head["to"] ? unknown
+    : Head["to"] extends [...Count, 0]["length"] ? Consecutive<Tail, [...Count, 0]>
+    : { readonly __fixMigrations__: `migration ${Head["to"]} is listed where migration ${[...Count, 0]["length"]} belongs: number migrations 1, 2, 3, ... in order` }
+    : unknown
+
+/**
+ * A game's save migrations, numbered 1, 2, 3, ... in order (checked at
+ * compile time for literal numbers, and at runtime). Pass them to
+ * `Game.Runtime.make({ saves })`: `snapshot()` then writes the last number as
+ * the save's `gameVersion`, and `restore(data)` runs every step after the
+ * save's version, in order, before validating it as usual. A save newer than
+ * the last step fails with `NewerGameVersion`. Use it instead of editing raw
+ * save data before `restore`.
+ *
+ * @example
+ * ```ts
+ * const runtime = Game.Runtime.make({
+ *   services,
+ *   saves: Snapshot.migrations(
+ *     Snapshot.migration(1, (save) => ({ ...save, scopes: {} })),
+ *     Snapshot.migration(2, renameGold)
+ *   )
+ * }).value
+ * runtime.restore(raw)
+ * ```
+ */
+export const migrations = <const Steps extends readonly [Migration, ...Array<Migration>]>(
+  ...steps: Steps & Consecutive<Steps>
+): Migrations<Last<Steps>> => {
+  steps.forEach((step, index) => {
+    if (step.to !== index + 1) {
+      throw new Error(`migration ${step.to} is listed where migration ${index + 1} belongs: number migrations 1, 2, 3, ... in order`)
+    }
+  })
+  return { kind: "SnapshotMigrations", latest: steps.length as Last<Steps>, steps }
 }