@typeonce/ritmo 0.8.0 → 0.9.0

package/src/System.ts

@@ -461,7 +461,8 @@ export interface EventReadView<T> {
  * A writable event stream view.
  */
 export interface EventWriteView<T> {
-  emit(value: T): void
+  /** Publishes one event. Takes the readonly shape reads return, so a read event can be emitted again. */
+  emit(value: import("./Query.ts").ReadonlyValue<T>): void
 }
 
 /**
@@ -482,6 +483,13 @@ export interface NextMachineWriteView<M extends Machine.StateMachine.Any = Machi
    * Queues `value`, committed at the next `applyStateTransitions(...)`. For a
    * sub-state it returns a `Result` that fails with `SubStateInactive` (and
    * queues nothing) while the parent is in another state.
+   *
+   * One value is queued per machine: a later `set` before the marker
+   * replaces an earlier one. A `set` from a transition schedule (`onEnter`,
+   * `onExit`, `onTransition`) is committed at the following marker, while a
+   * value queued before the current marker still commits at it. A sub-state
+   * value set while its parent is still in its state but leaves it at the
+   * same marker returns ok and is dropped with the sub-state.
    */
   set(value: Machine.StateMachine.Value<M>): Machine.SetResult<M>
   /** Like `set`, but committing the current value again is skipped (no exit or enter schedules). */
@@ -661,10 +669,47 @@ export interface RelationFailureReadView<
  * A runtime query handle exposed to system implementations.
  *
  * The handle is already typed from the query spec, so iterating it returns
- * strongly typed entity proofs and cells.
+ * strongly typed entity proofs and cells. A query with `added` / `changed`
+ * filters only iterates (`each`, `singleOptional`): its lookups would fail
+ * for every entity that did not change since this system's previous run, so
+ * declare a second query without filters to resolve entities.
  */
-export interface QueryHandle<S extends Schema.Any, Q extends Query.Any> {
+export type QueryHandle<S extends Schema.Any, Q extends Query.Any> =
+  & QueryIteration<S, Q>
+  & (Q["filters"] extends readonly [] ? QueryLookups<S, Q> : FilteredQueryLookups)
+
+/** What every query handle has: iteration over its current matches. */
+export interface QueryIteration<S extends Schema.Any, Q extends Query.Any> {
   each(): ReadonlyArray<QueryMatch<S, Q>>
+  /**
+   * Returns a single match when zero or one entity satisfies the query.
+   *
+   * Use this when absence is acceptable but multiplicity is still a bug. Zero
+   * matches return `ok: true` with `value: undefined`; multiple matches remain
+   * an explicit `MultipleEntities` failure.
+   *
+   * @example
+   * ```ts
+   * const player = queries.player.singleOptional()
+   * if (!player.ok || !player.value) {
+   *   return
+   * }
+   *
+   * player.value.data.position.set({ x: 0, y: 0 })
+   * ```
+   */
+  singleOptional(): Result.Result<QueryMatch<S, Q> | undefined, Query.MultipleEntitiesError>
+}
+
+type FilteredLookupMessage = "lookups need a query without added/changed filters: declare a second query for resolving entities"
+
+/** The lookups of a query with filters, each replaced by the message naming the fix. */
+export type FilteredQueryLookups = {
+  readonly [K in keyof QueryLookups<Schema.Any, Query.Any>]: (this: FilteredLookupMessage, ...args: ReadonlyArray<unknown>) => never
+}
+
+/** Lookups of one entity or one hierarchy through a query without `added` / `changed` filters. */
+export interface QueryLookups<S extends Schema.Any, Q extends Query.Any> {
   /**
    * Retrieves the match for one specific entity id when it satisfies the query.
    *
@@ -711,24 +756,6 @@ export interface QueryHandle<S extends Schema.Any, Q extends Query.Any> {
    * Returns a single match when exactly one entity satisfies the query.
    */
   single(): Result.Result<QueryMatch<S, Q>, Query.SingleError>
-  /**
-   * Returns a single match when zero or one entity satisfies the query.
-   *
-   * Use this when absence is acceptable but multiplicity is still a bug. Zero
-   * matches return `ok: true` with `value: undefined`; multiple matches remain
-   * an explicit `MultipleEntities` failure.
-   *
-   * @example
-   * ```ts
-   * const player = queries.player.singleOptional()
-   * if (!player.ok || !player.value) {
-   *   return
-   * }
-   *
-   * player.value.data.position.set({ x: 0, y: 0 })
-   * ```
-   */
-  singleOptional(): Result.Result<QueryMatch<S, Q> | undefined, Query.MultipleEntitiesError>
 }
 
 /**
@@ -859,10 +886,36 @@ export interface SystemAccessInput {
  */
 export type SystemAccessSpec = SystemAccessInput
 
-/** Rejects unknown system access categories at a bound constructor. */
+/** Rejects unknown system access categories, and redundant resource and event slots, at a bound constructor. */
 export type ExactAccess<Access extends SystemAccessInput> = Access & {
   readonly [Key in Exclude<keyof Access, keyof SystemAccessInput>]: never
-}
+} & RedundantSlotsFix<Access, "resources", "read"> & RedundantSlotsFix<Access, "events", never>
+
+type SlotOf<A> = A extends { readonly mode: infer Mode extends string; readonly descriptor: { readonly name: infer Name extends string } } ? readonly [Mode, Name] : never
+
+/**
+ * Slots of `Record` that repeat another slot: the same descriptor in the same
+ * mode, or in `ReadMode` next to any other slot of it (a write or changed
+ * view already reads).
+ */
+type RedundantSlots<Record, ReadMode extends string> = {
+  readonly [K in keyof Record]: SlotOf<Record[K]> extends readonly [infer Mode, infer Name]
+    ? [Extract<SlotOf<Omit<Record, K>[keyof Omit<Record, K>]>, readonly [Mode extends ReadMode ? string : Mode, Name]>] extends [never] ? never : K
+    : never
+}[keyof Record]
+
+type RedundantSlotsFix<Access, Category extends "resources" | "events", ReadMode extends string> =
+  Access extends { readonly [C in Category]?: infer Record }
+    ? [RedundantSlots<Record, ReadMode>] extends [never]
+      ? unknown
+      : {
+        readonly [C in Category]: {
+          readonly [K in RedundantSlots<Record, ReadMode>]: {
+            readonly __fixSystem__: `${K & string} repeats ${Category extends "resources" ? "a resource" : "an event"} another slot of this system declares: keep one slot (a write or changed view reads too)`
+          }
+        }
+      }
+    : unknown
 
 type AccessField<
   Access,

package/src/index.ts

@@ -33,6 +33,10 @@ export * as Entity from "./Entity.ts"
  * Entity lifetime scopes used by scene and level ownership patterns.
  */
 export * as EntityScope from "./EntityScope.ts"
+/**
+ * Fixed-step timing for any host: clamping, catch-up limits, interpolation.
+ */
+export * as FixedLoop from "./FixedLoop.ts"
 /**
  * The host's wall clock as an injected contract (`standard`, `test()`).
  */

package/src/internal/cells.ts

@@ -63,38 +63,64 @@ const withTransition = (cell: WriteCellBase<unknown>, component: string) => Obje
   }
 })
 
+/**
+ * A required slot is empty only when its match outlived the run that produced
+ * it: the entity was despawned, or lost the component. Reading would hand out
+ * the internal marker as a value, and writing would put the component back
+ * without the insert path, so both fail loudly instead.
+ */
+const staleMatch = (record: EntityRecord, ordinal: number): Error =>
+  new Error(
+    `${record.nameAt(ordinal)} was used through a query match after ${record.alive ? "its entity lost it" : "its entity was despawned"}: `
+    + "a match is valid during the system run that produced it; keep the entity id or a handle and resolve it again with queries.x.get(id) or queries.x.getHandle(handle)"
+  )
+
+
+/** Kept out of `get` so the hot read stays small enough to inline. */
+const staleRead = (record: EntityRecord, ordinal: number): never => {
+  throw staleMatch(record, ordinal)
+}
+
 class ComponentReadCell {
-  readonly record: EntityRecord
+  // The record's values array, held directly: one load per read instead of
+  // two pays for the stale check. Records never replace their array.
+  readonly values: Array<unknown>
   readonly ordinal: number
+  readonly record: EntityRecord
 
   constructor(record: EntityRecord, ordinal: number) {
-    this.record = record
+    this.values = record.values
     this.ordinal = ordinal
+    this.record = record
   }
 
   get(): unknown {
-    return this.record.values[this.ordinal]
+    const value = this.values[this.ordinal]
+    return value === ABSENT ? staleRead(this.record, this.ordinal) : value
   }
 }
 
 class ComponentWriteCell extends WriteCellBase<unknown> {
-  readonly record: EntityRecord
+  readonly values: Array<unknown>
   readonly ordinal: number
+  readonly record: EntityRecord
   readonly world: World
 
   constructor(record: EntityRecord, ordinal: number, world: World) {
     super()
-    this.record = record
+    this.values = record.values
     this.ordinal = ordinal
+    this.record = record
     this.world = world
   }
 
   get(): unknown {
-    return this.record.values[this.ordinal]
+    const value = this.values[this.ordinal]
+    return value === ABSENT ? staleRead(this.record, this.ordinal) : value
   }
 
   set(value: unknown): void {
-    this.world.setComponentValue(this.record, this.ordinal, value)
+    if (!this.world.setComponentValue(this.record, this.ordinal, value)) staleRead(this.record, this.ordinal)
   }
 }
 
@@ -115,6 +141,11 @@ class OptionalComponentCell {
   get(): unknown {
     return this.record.values[this.ordinal]
   }
+
+  value(): unknown {
+    const value = this.record.values[this.ordinal]
+    return value === ABSENT ? undefined : value
+  }
 }
 
 class StoreReadCell {
@@ -167,7 +198,7 @@ export const componentWrite = (
   return entityState === undefined ? constructed : withTransition(constructed, entityState)
 }
 
-export const componentOptional = (record: EntityRecord, ordinal: number): { readonly present: boolean; get(): unknown } =>
+export const componentOptional = (record: EntityRecord, ordinal: number): { readonly present: boolean; get(): unknown; value(): unknown } =>
   new OptionalComponentCell(record, ordinal)
 
 export const storeRead = (store: Map<symbol, unknown>, key: symbol): { get(): unknown } =>
@@ -198,9 +229,10 @@ export const derivedRead = <T>(read: () => T): { get(): T } => ({ get: read })
 export const derivedOptional = <T>(
   isPresent: () => boolean,
   read: () => T
-): { readonly present: boolean; get(): T } => ({
+): { readonly present: boolean; get(): T; value(): T | undefined } => ({
   get present() {
     return isPresent()
   },
-  get: read
+  get: read,
+  value: () => (isPresent() ? read() : undefined)
 })

package/src/internal/debug.ts

@@ -282,6 +282,9 @@ export interface DescribeInput {
   readonly ranSystems: ReadonlySet<string>
   /** Commands skipped because they would have broken a `Schema.requires` requirement. */
   readonly requirementViolations: ReadonlyArray<Debug.RequirementViolation>
+  readonly nextStateReplacements: ReadonlyArray<Debug.NextStateReplacement>
+  readonly staleTargets: ReadonlyArray<Debug.StaleTarget>
+  readonly streamLosses: ReadonlyArray<Debug.StreamLoss>
   readonly hasResource: (descriptor: Descriptor.Any) => boolean
   readonly schedules: ReadonlyArray<readonly [string, AnySchedule]>
 }
@@ -293,19 +296,38 @@ export const describe = (input: DescribeInput): Debug.Description => {
   const relations = Object.values(input.schema.relations) as ReadonlyArray<Relation.Relation.Any>
 
   const schedules = collectSchedules(input.schedules)
+  // A system gated by Schedule.when / pauseWhen is a copy pointing at its
+  // base: both are one system, described once with every placement.
+  const baseOf = (system: AnySystem): AnySystem => (system as { readonly base?: AnySystem }).base ?? system
   const placements = new Map<AnySystem, Array<string>>()
+  const steps = new Set<AnySystem>()
   for (const [name, schedule] of schedules) {
     schedule.steps.forEach((step, index) => {
       if (!Schedule.isSystemStep(step)) return
-      const system = step as AnySystem
+      const system = baseOf(step as AnySystem)
+      steps.add(step as AnySystem)
       const list = placements.get(system)
       const placement = `${name}#${index}`
       if (list) list.push(placement)
       else placements.set(system, [placement])
     })
   }
-  const described = new Map([...placements].map(([system, where]) => [system, describeSystem(system, where)] as const))
-  const systems = [...described.values()]
+  // Gates differ per placement: the description lists the conditions of all of them.
+  const gatesOf = new Map<AnySystem, { when: Set<unknown>; pauseWhen: Set<unknown> }>()
+  for (const step of steps) {
+    const base = baseOf(step)
+    const gates = gatesOf.get(base) ?? { when: new Set(), pauseWhen: new Set() }
+    for (const condition of step.spec.when as ReadonlyArray<unknown>) gates.when.add(condition)
+    for (const condition of step.spec.pauseWhen as ReadonlyArray<unknown>) gates.pauseWhen.add(condition)
+    gatesOf.set(base, gates)
+  }
+  const byBase = new Map([...placements].map(([system, where]) => {
+    const gates = gatesOf.get(system)!
+    const merged = { ...system, spec: { ...system.spec, when: [...gates.when], pauseWhen: [...gates.pauseWhen] } } as AnySystem
+    return [system, describeSystem(merged, where)] as const
+  }))
+  const described = new Map<AnySystem, Debug.SystemDescription>([...steps].map((step) => [step, byBase.get(baseOf(step))!] as const))
+  const systems = [...byBase.values()]
 
   const components = new Index(componentDescriptors.map((descriptor) => descriptor.name))
   const resources = new Index(resourceDescriptors.map((descriptor) => descriptor.name))
@@ -314,7 +336,7 @@ export const describe = (input: DescribeInput): Debug.Description => {
   for (const name of input.externallyWrittenEvents) events.write(name, "runtime.send")
   for (const system of systems) {
     for (const query of system.queries) {
-      for (const name of [...query.reads, ...query.optional, ...query.with, ...query.added, ...query.changed]) {
+      for (const name of [...query.reads, ...query.optional, ...query.with, ...query.added, ...query.changed, ...anyOfNames(query)]) {
         components.read(name, system.name)
       }
       for (const name of query.writes) {
@@ -401,7 +423,7 @@ export const describe = (input: DescribeInput): Debug.Description => {
       }
     }
     const failureReaders = new Set(systems.flatMap((system) => system.relationFailures))
-    // Declared `relates` permissions, and relations that commands were seen to relate (drafts relate without one).
+    // Declared `relates` permissions, and relations that commands were seen to relate (erased types can relate without one).
     const relaters = new Map<string, Set<string>>()
     for (const system of systems) {
       for (const name of system.commands.relates) relaters.set(name, new Set([...(relaters.get(name) ?? []), system.name]))
@@ -452,15 +474,6 @@ export const describe = (input: DescribeInput): Debug.Description => {
         })
       }
     }
-    for (const violation of input.requirementViolations) {
-      const times = violation.count === 1 ? "once" : `${violation.count} times`
-      lints.push({
-        severity: "warning",
-        code: "requirement-violated",
-        subject: violation.system,
-        message: `${violation.system} queued ${violation.command === "insert" ? "an" : "a"} ${violation.command} that would have left ${violation.component} without ${violation.missing} (last on entity ${violation.entity}), so it was skipped ${times}`
-      })
-    }
     for (const entry of components.list()) {
       if (entry.writers.length > 0 && entry.readers.every((reader) => entry.writers.includes(reader))) {
         lints.push({
@@ -472,6 +485,52 @@ export const describe = (input: DescribeInput): Debug.Description => {
       }
     }
   }
+  // Observed with debug, whether or not schedules are named.
+  for (const violation of input.requirementViolations) {
+    const times = violation.count === 1 ? "once" : `${violation.count} times`
+    lints.push({
+      severity: "warning",
+      code: "requirement-violated",
+      subject: violation.system,
+      message: `${violation.system} queued ${violation.command === "insert" ? "an" : "a"} ${violation.command} that would have left ${violation.component} without ${violation.missing} (last on entity ${violation.entity}), so it was skipped ${times}`
+    })
+  }
+  for (const replacement of input.nextStateReplacements) {
+    const times = replacement.count === 1 ? "" : `, ${replacement.count} times`
+    lints.push({
+      severity: "warning",
+      code: "next-state-replaced",
+      subject: replacement.machine,
+      message: `${replacement.by.system} queued ${replacement.machine}=${String(replacement.by.value)}, replacing ${String(replacement.replaced.value)} queued by ${replacement.replaced.system} before the same applyStateTransitions()${times}: the last value wins`
+    })
+  }
+  for (const stale of input.staleTargets) {
+    const times = stale.count === 1 ? "once" : `${stale.count} times`
+    lints.push({
+      severity: "warning",
+      code: "stale-target",
+      subject: stale.system,
+      message: `${stale.system} passed ${stale.command} an id spawned in an earlier run (last entity ${stale.entity}), so it was skipped ${times}`
+    })
+  }
+  for (const loss of input.streamLosses) {
+    if (loss.checksLagged) continue
+    if (loss.lostRuns > 0) {
+      lints.push({
+        severity: "warning",
+        code: "stream-loss-unread",
+        subject: loss.system,
+        message: `${loss.system} read ${loss.stream} after entries were dropped before it read them (${loss.lostRuns === 1 ? "once" : `${loss.lostRuns} runs`}), and never checks lagged()`
+      })
+    } else if (loss.paused) {
+      lints.push({
+        severity: "info",
+        code: "stream-loss-unread",
+        subject: loss.system,
+        message: `${loss.system} reads ${loss.stream} under pauseWhen and never checks lagged(): a long pause drops entries past the stream's capacity`
+      })
+    }
+  }
 
   return {
     version: 1,
@@ -548,6 +607,12 @@ const fixFor = (code: Debug.Lint["code"], subject: string): string => {
       return `fine if ${subject} is read outside the described schedules (rendering, inspectors); otherwise stop writing it`
     case "requirement-violated":
       return `keep what ${subject} spawns or inserts complete (every component its components require), and remove a required component only together with its requirers; a query proof can go stale when another system's command is applied first in the same applyDeferred()`
+    case "stream-loss-unread":
+      return `check lagged() in ${subject} where a missed entry matters (a node never destroyed, a count off), and rebuild from queries when it is true; fine if a missed entry is harmless`
+    case "stale-target":
+      return `an id spawn returns is valid only in the run that spawned it; in ${subject}, keep the entity id or a handle and resolve it again with a query (queries.x.get(id) / lookup.getHandle(handle, query)) and pass match.entity`
+    case "next-state-replaced":
+      return "decide between the values in one system, or check whether a next state is already queued (nextMachines.x.getPending()) before setting another"
     case "command-permission-unused":
       return `fine if the session did not reach the case where ${subject} uses it; otherwise drop the permission from its Game.System.commands(...)`
     case "read-before-write":
@@ -558,9 +623,13 @@ const fixFor = (code: Debug.Lint["code"], subject: string): string => {
 type Accesses = { readonly reads: ReadonlyArray<string>; readonly writes: ReadonlyArray<string> }
 
 /** What a system reads and writes, per kind. `with`/`without` filters test presence and are not reads. */
+/** The components named by a query's `anyOf` filters. */
+const anyOfNames = (query: Debug.QueryDescription): ReadonlyArray<string> =>
+  query.anyOf.flatMap((filter) => [...filter.added, ...filter.changed])
+
 const accessesOf = (system: Debug.SystemDescription): Record<"component" | "resource" | "event", Accesses> => ({
   component: {
-    reads: system.queries.flatMap((query) => [...query.reads, ...query.optional, ...query.added, ...query.changed]),
+    reads: system.queries.flatMap((query) => [...query.reads, ...query.optional, ...query.added, ...query.changed, ...anyOfNames(query)]),
     writes: system.queries.flatMap((query) => query.writes)
   },
   resource: { reads: system.resources.reads, writes: system.resources.writes },

package/src/internal/fragments.ts

@@ -4,9 +4,14 @@
  * The compile-time counterpart is `ValidateFragments` in `Schema.ts`; these
  * guards cover schemas assembled from erased types.
  */
+import { isTransient } from "../Descriptor.ts"
 import type { Schema, SchemaDefinition } from "../Schema.ts"
 
-type NamedRegistry = Record<string, { readonly name: string }>
+type NamedRegistry = Record<string, { readonly name: string; readonly kind?: string }>
+
+/** The descriptor kind each registry holds (relations carry their own shape). */
+const expectedKind: Partial<Record<(typeof kinds)[number], string>> = { components: "component", resources: "resource", events: "event" }
+const article = (kind: string) => kind === "event" ? "an" : "a"
 
 const kinds = ["components", "resources", "events", "relations"] as const
 
@@ -21,9 +26,15 @@ export const emptySchema = (): SchemaDefinition => ({
 /**
  * Merges two registries after checking for duplicate keys and descriptor names.
  */
-const mergeRegistry = (left: NamedRegistry, right: NamedRegistry): NamedRegistry => {
+const mergeRegistry = (left: NamedRegistry, right: NamedRegistry, expected: string | undefined): NamedRegistry => {
   const names = new Set(Object.values(left).map((entry) => entry.name))
   for (const [key, entry] of Object.entries(right)) {
+    if (expected !== undefined && entry.kind !== expected) {
+      const actual = String(entry.kind)
+      throw new Error(actual === "service"
+        ? `${key} is a service, not ${article(expected)} ${expected}: provide services to Game.Runtime.make({ services }) instead of registering them`
+        : `${key} is ${article(actual)} ${actual}, not ${article(expected)} ${expected}: move it to ${actual}s: { ... }`)
+    }
     if (key in left) {
       throw new Error(`Duplicate schema key: ${key}`)
     }
@@ -38,7 +49,7 @@ const mergeRegistry = (left: NamedRegistry, right: NamedRegistry): NamedRegistry
 export const mergeSchemas = (left: Schema.Any, right: Schema.Any): Schema.Any => {
   const merged: Record<string, unknown> = {}
   for (const kind of kinds) {
-    merged[kind] = mergeRegistry(left[kind], right[kind])
+    merged[kind] = mergeRegistry(left[kind], right[kind], expectedKind[kind])
   }
   merged["requires"] = [...left.requires, ...right.requires]
   return merged as unknown as Schema.Any
@@ -56,6 +67,15 @@ export const buildSchema = (fragments: ReadonlyArray<Schema.Any>): Schema.Any =>
         throw new Error(`${descriptor.name} is named in Schema.requires(...) but no fragment registers it: add it to a fragment's components`)
       }
     }
+    for (const required of requirement.required) {
+      if (isTransient(required) && !isTransient(requirement.component)) {
+        throw new Error(transientRequirementMessage(requirement.component.name, required.name))
+      }
+    }
   }
   return current
 }
+
+/** Why a saved component cannot require a transient one: a restore would bring it back without it. */
+export const transientRequirementMessage = (requirer: string, required: string): string =>
+  `${requirer} requires ${required}, which is transient and not saved: make ${requirer} transient too, or give ${required} a constructor`

package/src/internal/game.ts

@@ -6,6 +6,7 @@
  */
 import * as Command from "../Command.ts"
 import type * as Debug from "../Debug.ts"
+import type * as Snapshot from "../Snapshot.ts"
 import type { Descriptor } from "../Descriptor.ts"
 import * as Condition from "../Condition.ts"
 import * as Entity from "../Entity.ts"
@@ -15,11 +16,16 @@ import * as Machine from "../Machine.ts"
 import * as QueryModule from "../Query.ts"
 import * as Relation from "../Relation.ts"
 import * as Runtime from "../Runtime.ts"
+import * as Requirement from "../Requirement.ts"
 import * as Schedule from "../Schedule.ts"
 import type { Schema } from "../Schema.ts"
 import * as System from "../System.ts"
 import { requirementIndex, withRequired } from "./requirements.ts"
 
+/** Why an exit phase (`onExit`, `onTransition`) cannot contain `applyDeferred()`. */
+export const exitApplyDeferredMessage =
+  "onExit and onTransition schedules cannot contain applyDeferred(): the exit phase rolls back as one when a system in it fails, so its commands are applied at the next applyDeferred() after the marker" as const
+
 export const makeGame = <S extends Schema.Any, Root>(schema: S, _root: Root): Schema.Game<S, Root> => {
   const requirements = requirementIndex(schema)
   const definedMachines: Array<Machine.StateMachine.Any> = []
@@ -77,7 +83,14 @@ export const makeGame = <S extends Schema.Any, Root>(schema: S, _root: Root): Sc
   const transitionSchedule = (
     transition: Machine.TransitionScheduleDefinition["transition"],
     plan: ReadonlyArray<Schedule.ScheduleEntry>
-  ) => ({ ...Schedule.make(schema, plan), transition })
+  ) => {
+    const schedule = Schedule.make(schema, plan)
+    if (transition.phase !== "enter" && schedule.steps.some((step) => !Schedule.isSystemStep(step) && step.kind === "applyDeferred")) {
+      throw new Error(exitApplyDeferredMessage)
+    }
+    // The machine is a requirement: a runtime without it could never run the schedule.
+    return { ...schedule, requirements: Requirement.collect([...schedule.requirements, transition.machine]), transition }
+  }
 
   const game = {
     schema,
@@ -85,7 +98,8 @@ export const makeGame = <S extends Schema.Any, Root>(schema: S, _root: Root): Sc
     Inspector: (name: string, spec: object, read: (context: any) => unknown) =>
       Inspector.make(name, { schema, ...spec } as never, read),
     Entity: {
-      handle: Entity.handle
+      handle: Entity.handle,
+      id: (handle: number) => Entity.makeEntityId(handle)
     },
     Query: Object.assign((spec: never) => QueryModule.Query(spec), {
       read: QueryModule.read,
@@ -129,7 +143,8 @@ export const makeGame = <S extends Schema.Any, Root>(schema: S, _root: Root): Sc
         commands: Command.commands,
         // `spawns(Player)` also allows what `Player` requires (`Schema.requires`), matching its type.
         spawns: (...components: ReadonlyArray<Descriptor<"component", string, any>>) =>
-          Command.spawns(...withRequired(requirements, components)),
+          // Internally erased: the bound signature already requires at least one component.
+          Command.spawns(...(withRequired(requirements, components) as unknown as readonly [Descriptor<"component", string, any>])),
         inserts: Command.inserts,
         removes: Command.removes,
         despawns: Command.despawns,
@@ -172,6 +187,7 @@ export const makeGame = <S extends Schema.Any, Root>(schema: S, _root: Root): Sc
         readonly resources?: object
         readonly machines?: Runtime.RuntimeMachines<any>
         readonly debug?: Debug.Option
+        readonly saves?: Snapshot.Migrations
       }) => Runtime.make({ schema, ...options, machineDefinitions: definedMachines, scopeDefinitions: definedScopes } as never),
       service: Runtime.service,
       services: Runtime.services,

package/src/internal/queries.ts

@@ -14,6 +14,7 @@
  * Matches are always returned in ascending entity id order, which is spawn
  * order, so iteration is deterministic.
  */
+import type { Descriptor } from "../Descriptor.ts"
 import * as DescriptorModule from "../Descriptor.ts"
 import type * as Entity from "../Entity.ts"
 import * as Query from "../Query.ts"
@@ -124,6 +125,31 @@ export const makeQueryEngine = (world: World) => {
   const states = new WeakMap<AnyQuery, QueryState>()
   let nextOrdinal = 0
 
+  /**
+   * The ordinal of a selected component, checking that the descriptor the
+   * query names behaves like the one the schema registers under that name:
+   * identity is (kind, name), so a look-alike built elsewhere must not add
+   * or drop behaviour (entity-state transitions, a constructor, immutability,
+   * transience) the schema does not declare.
+   */
+  const registeredOrdinal = (descriptor: Descriptor.Any): number => {
+    const ordinal = world.ordinalOf(descriptor as never)
+    const registered = world.descriptorAt(ordinal) as Descriptor.Any
+    if (registered === descriptor) return ordinal
+    const traits = (candidate: Descriptor.Any) => [
+      DescriptorModule.isEntityState(candidate as never) ? "an entity state" : undefined,
+      DescriptorModule.hasConstructor(candidate) ? "constructed" : undefined,
+      DescriptorModule.isImmutable(candidate) ? "immutable" : undefined,
+      DescriptorModule.isTransient(candidate) ? "transient" : undefined
+    ].filter((trait) => trait !== undefined).join(", ") || "plain"
+    const expected = traits(registered)
+    const actual = traits(descriptor)
+    if (expected !== actual) {
+      throw new Error(`${descriptor.name} is ${expected} in this schema, but this query names a descriptor that is ${actual}: use the descriptor the schema registers`)
+    }
+    return ordinal
+  }
+
   const compile = (query: AnyQuery): QueryState => {
     const required: Array<number> = query.with.map((descriptor) => world.ordinalOf(descriptor))
     const withRelations: Array<Relation.Relation.Any> = [...query.withRelations]
@@ -136,7 +162,7 @@ export const makeQueryEngine = (world: World) => {
       switch (access.mode) {
         case "read":
         case "write": {
-          const ordinal = world.ordinalOf(access.descriptor)
+          const ordinal = registeredOrdinal(access.descriptor)
           required.push(ordinal)
           proofSlots.push([slot, ordinal])
           if (access.mode === "write") {
@@ -154,7 +180,7 @@ export const makeQueryEngine = (world: World) => {
           break
         }
         case "optional":
-          slots.push({ slot, mode: "optional", ordinal: world.ordinalOf(access.descriptor) })
+          slots.push({ slot, mode: "optional", ordinal: registeredOrdinal(access.descriptor) })
           break
         case "readRelation":
           withRelations.push(access.descriptor)

package/src/internal/relations.ts

@@ -0,0 +1,52 @@
+/**
+ * Builds relation pairs for `Descriptor.Hierarchy` and `Descriptor.Relation`,
+ * the one public way to define a relation.
+ */
+import type { PairBrand, RelatedDefinition, RelationDefinition, RelationKind } from "../Relation.ts"
+
+const relationTypeId = "~ritmo/Relation"
+
+export const makePair = <
+  const Name extends string,
+  const RelatedName extends string,
+  const Kind extends RelationKind
+>(
+  kind: Kind,
+  name: Name,
+  relatedName: RelatedName
+): {
+  readonly relation: RelationDefinition<Name, RelatedName, Kind, PairBrand<Name, RelatedName, Kind>>
+  readonly related: RelatedDefinition<RelatedName, Name, Kind, PairBrand<Name, RelatedName, Kind>>
+} => {
+  type Pair = PairBrand<Name, RelatedName, Kind>
+  const related = {
+    kind: "related",
+    relatedName,
+    relationName: name,
+    key: Symbol.for(`ritmo/related/${name}`),
+    relationKind: kind,
+    [relationTypeId]: {
+      _Pair: (_: never) => undefined as unknown as Pair
+    }
+  } as RelatedDefinition<RelatedName, Name, Kind, Pair>
+
+  const relation = {
+    kind: "relation",
+    name,
+    relatedName,
+    key: Symbol.for(`ritmo/relation/${name}`),
+    relationKind: kind,
+    linkedDespawn: kind === "hierarchy",
+    allowSelf: false,
+    ordered: kind === "hierarchy",
+    related,
+    [relationTypeId]: {
+      _Pair: (_: never) => undefined as unknown as Pair
+    }
+  } as RelationDefinition<Name, RelatedName, Kind, Pair>
+
+  return {
+    relation,
+    related
+  }
+}